Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/configuration/configuration_locked.diviner
| Show All 18 Lines | ||||||||||
| Locked Configuration | Locked Configuration | |||||||||
| ==================== | ==================== | |||||||||
| **Locked Configuration** can not be edited from the web UI. In general, you | **Locked Configuration** can not be edited from the web UI. In general, you | |||||||||
| can edit it from the CLI instead, with `bin/config`: | can edit it from the CLI instead, with `bin/config`: | |||||||||
| ``` | ``` | |||||||||
| phabricator/ $ ./bin/config set <key> <value> | phorge/ $ ./bin/config set <key> <value> | |||||||||
| ``` | ``` | |||||||||
| Some configuration options take complicated values which can be difficult | Some configuration options take complicated values which can be difficult | |||||||||
| to escape properly for the shell. The easiest way to set these options is | to escape properly for the shell. The easiest way to set these options is | |||||||||
| to use the `--stdin` flag. First, put your desired value in a `config.json` | to use the `--stdin` flag. First, put your desired value in a `config.json` | |||||||||
| file: | file: | |||||||||
| ```name=config.json, lang=json | ```name=config.json, lang=json | |||||||||
| { | { | |||||||||
| "duck": "quack", | "duck": "quack", | |||||||||
| "cow": "moo" | "cow": "moo" | |||||||||
| } | } | |||||||||
| ``` | ``` | |||||||||
| Then, set it with `--stdin` like this: | Then, set it with `--stdin` like this: | |||||||||
| ``` | ``` | |||||||||
| phabricator/ $ ./bin/config set <key> --stdin < config.json | phorge/ $ ./bin/config set <key> --stdin < config.json | |||||||||
| ``` | ``` | |||||||||
| A few settings have alternate CLI tools. Refer to the setting page for | A few settings have alternate CLI tools. Refer to the setting page for | |||||||||
| details. | details. | |||||||||
| Note that these settings can not be written to the database, even from the | Note that these settings can not be written to the database, even from the | |||||||||
| CLI. | CLI. | |||||||||
| Locked values can not be unlocked: they are locked because of what the setting | Locked values can not be unlocked: they are locked because of what the setting | |||||||||
| does or how the setting operates. Some of the reasons configuration options are | does or how the setting operates. Some of the reasons configuration options are | |||||||||
| locked include: | locked include: | |||||||||
| **Required for bootstrapping**: Some options, like `mysql.host`, must be | **Required for bootstrapping**: Some options, like `mysql.host`, must be | |||||||||
| available before Phabricator can read configuration from the database. | available before Phorge can read configuration from the database. | |||||||||
chrisUnsubmitted Done Inline Actions
chris: | ||||||||||
| If you stored `mysql.host` only in the database, Phabricator would not know how | If you stored `mysql.host` only in the database, Phorge would not know how | |||||||||
| to connect to the database in order to read the value in the first place. | to connect to the database in order to read the value in the first place. | |||||||||
| These options must be provided in a configuration source which is read earlier | These options must be provided in a configuration source which is read earlier | |||||||||
| in the bootstrapping process, before Phabricator connects to the database. | in the bootstrapping process, before Phorge connects to the database. | |||||||||
| **Errors could not be fixed from the web UI**: Some options, like | **Errors could not be fixed from the web UI**: Some options, like | |||||||||
| `phabricator.base-uri`, can effectively disable the web UI if they are | `phabricator.base-uri`, can effectively disable the web UI if they are | |||||||||
| configured incorrectly. | configured incorrectly. | |||||||||
| If these options could be configured from the web UI, you could not fix them if | If these options could be configured from the web UI, you could not fix them if | |||||||||
| you made a mistake (because the web UI would no longer work, so you could not | you made a mistake (because the web UI would no longer work, so you could not | |||||||||
| load the page to change the value). | load the page to change the value). | |||||||||
| We require these options to be edited from the CLI to make sure the editor has | We require these options to be edited from the CLI to make sure the editor has | |||||||||
| access to fix any mistakes. | access to fix any mistakes. | |||||||||
| **Attackers could gain greater access**: Some options could be modified by an | **Attackers could gain greater access**: Some options could be modified by an | |||||||||
| attacker who has gained access to an administrator account in order to gain | attacker who has gained access to an administrator account in order to gain | |||||||||
| greater access. | greater access. | |||||||||
| For example, an attacker who could modify `cluster.mailers` (and other | For example, an attacker who could modify `cluster.mailers` (and other | |||||||||
| similar options), could potentially reconfigure Phabricator to send mail | similar options), could potentially reconfigure Phorge to send mail | |||||||||
| through an evil server they controlled, then trigger password resets on other | through an evil server they controlled, then trigger password resets on other | |||||||||
| user accounts to compromise them. | user accounts to compromise them. | |||||||||
| We require these options to be edited from the CLI to make sure the editor | We require these options to be edited from the CLI to make sure the editor | |||||||||
| has full access to the install. | has full access to the install. | |||||||||
| Hidden Configuration | Hidden Configuration | |||||||||
| ==================== | ==================== | |||||||||
| **Hidden Configuration** is similar to locked configuration, but also can not | **Hidden Configuration** is similar to locked configuration, but also can not | |||||||||
| be //read// from the web UI. | be //read// from the web UI. | |||||||||
| In almost all cases, configuration is hidden because it is some sort of secret | In almost all cases, configuration is hidden because it is some sort of secret | |||||||||
| key or access token for an external service. These values are hidden from the | key or access token for an external service. These values are hidden from the | |||||||||
| web UI to prevent administrators (or attackers who have compromised | web UI to prevent administrators (or attackers who have compromised | |||||||||
| administrator accounts) from reading them. | administrator accounts) from reading them. | |||||||||
| You can review (and edit) hidden configuration from the CLI: | You can review (and edit) hidden configuration from the CLI: | |||||||||
| ``` | ``` | |||||||||
| phabricator/ $ ./bin/config get <key> | phorge/ $ ./bin/config get <key> | |||||||||
| phabricator/ $ ./bin/config set <key> <value> | phorge/ $ ./bin/config set <key> <value> | |||||||||
| ``` | ``` | |||||||||
| Locked Configuration With Database Values | Locked Configuration With Database Values | |||||||||
| ========================================= | ========================================= | |||||||||
| You may receive a setup issue warning you that a locked configuration key has a | You may receive a setup issue warning you that a locked configuration key has a | |||||||||
| value set in the database. Most commonly, this is because: | value set in the database. Most commonly, this is because: | |||||||||
| - In some earlier version of Phabricator, this configuration was not locked. | - In some earlier version of Phorge, this configuration was not locked. | |||||||||
| - In the past, you or some other administrator used the web UI to set a | - In the past, you or some other administrator used the web UI to set a | |||||||||
| value. This value was written to the database. | value. This value was written to the database. | |||||||||
| - In a later version of the software, the value became locked. | - In a later version of the software, the value became locked. | |||||||||
| When Phabricator was originally released, locked configuration did not yet | When Phorge was originally released, locked configuration did not yet | |||||||||
| exist. Locked configuration was introduced later, and then configuration options | exist. Locked configuration was introduced later, and then configuration options | |||||||||
| were gradually locked for a long time after that. | were gradually locked for a long time after that. | |||||||||
| In some cases the meaning of a value changed and it became possible to use it | In some cases the meaning of a value changed and it became possible to use it | |||||||||
| to break an install or the configuration became a security risk. In other | to break an install or the configuration became a security risk. In other | |||||||||
| cases, we identified an existing security risk or arrived at some other reason | cases, we identified an existing security risk or arrived at some other reason | |||||||||
| to lock the value. | to lock the value. | |||||||||
| Locking values was more common in the past, and it is now relatively rare for | Locking values was more common in the past, and it is now relatively rare for | |||||||||
| an unlocked value to become locked: when new values are introduced, they are | an unlocked value to become locked: when new values are introduced, they are | |||||||||
| generally locked or hidden appropriately. In most cases, this setup issue only | generally locked or hidden appropriately. In most cases, this setup issue only | |||||||||
| affects installs that have used Phabricator for a long time. | affects installs that have used Phorge for a long time. | |||||||||
Done Inline Actions
chris: | ||||||||||
| At time of writing (February 2019), Phabricator currently respects these old | At time of writing (February 2019), Phorge currently respects these old | |||||||||
| database values. However, some future version of Phabricator will refuse to | database values. However, some future version of Phorge will refuse to | |||||||||
| read locked configuration from the database, because this improves security if | read locked configuration from the database, because this improves security if | |||||||||
| an attacker manages to find a way to bypass restrictions on editing locked | an attacker manages to find a way to bypass restrictions on editing locked | |||||||||
| configuration from the web UI. | configuration from the web UI. | |||||||||
| To clear this setup warning and avoid surprise behavioral changes in the future, | To clear this setup warning and avoid surprise behavioral changes in the future, | |||||||||
| you should move these configuration values from the database to a local config | you should move these configuration values from the database to a local config | |||||||||
| file. Usually, you'll do this by first copying the value from the database: | file. Usually, you'll do this by first copying the value from the database: | |||||||||
| ``` | ``` | |||||||||
| phabricator/ $ ./bin/config get <key> | phorge/ $ ./bin/config get <key> | |||||||||
| ``` | ``` | |||||||||
| ...into local configuration: | ...into local configuration: | |||||||||
| ``` | ``` | |||||||||
| phabricator/ $ ./bin/config set <key> <value> | phorge/ $ ./bin/config set <key> <value> | |||||||||
| ``` | ``` | |||||||||
| ...and then removing the database value: | ...and then removing the database value: | |||||||||
| ``` | ``` | |||||||||
| phabricator/ $ ./bin/config delete --database <key> | phorge/ $ ./bin/config delete --database <key> | |||||||||
| ``` | ``` | |||||||||
| See @{Configuration User Guide: Advanced Configuration} for some more detailed | See @{Configuration User Guide: Advanced Configuration} for some more detailed | |||||||||
| discussion of different configuration sources. | discussion of different configuration sources. | |||||||||
| Next Steps | Next Steps | |||||||||
| ========== | ========== | |||||||||
| Continue by: | Continue by: | |||||||||
| - learning more about advanced options with | - learning more about advanced options with | |||||||||
| @{Configuration User Guide: Advanced Configuration}; or | @{Configuration User Guide: Advanced Configuration}; or | |||||||||
| - returning to the @{article: Configuration Guide}. | - returning to the @{article: Configuration Guide}. | |||||||||
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0