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