configuration_locked.diviner

@title Configuration Guide: Locked and Hidden Configuration
@group config

Details about locked and hidden configuration.


Overview
========

Some configuration options are **Locked** or **Hidden**. If an option has one
of these attributes, it means:

  - **Locked Configuration**: This setting can not be written from the web UI.
  - **Hidden Configuration**: This setting can not be read or written from
    the web UI.

This document explains these attributes in more detail.


Locked Configuration
====================

**Locked Configuration** can not be edited from the web UI. In general, you
can edit it from the CLI instead, with `bin/config`:

```
phabricator/ $ ./bin/config set <key> <value>
```

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 use the `--stdin` flag. First, put your desired value in a `config.json`
file:

```name=config.json, lang=json
{
  "duck": "quack",
  "cow": "moo"
}
```

Then, set it with `--stdin` like this:

```
phabricator/ $ ./bin/config set <key> --stdin < config.json
```

A few settings have alternate CLI tools. Refer to the setting page for
details.

Note that these settings can not be written to the database, even from the
CLI.

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
locked include:


**Required for bootstrapping**: Some options, like `mysql.host`, must be
available before Phabricator can read configuration from the database.

If you stored `mysql.host` only in the database, Phabricator would not know how
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
in the bootstrapping process, before Phabricator connects to the database.


**Errors could not be fixed from the web UI**: Some options, like
`phabricator.base-uri`, can effectively disable the web UI if they are
configured incorrectly.

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
load the page to change the value).

We require these options to be edited from the CLI to make sure the editor has
access to fix any mistakes.


**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
greater access.

For example, an attacker who could modify `cluster.mailers` (and other
similar options), could potentially reconfigure Phabricator to send mail
through an evil server they controlled, then trigger password resets on other
user accounts to compromise them.

We require these options to be edited from the CLI to make sure the editor
has full access to the install.


Hidden Configuration
====================

**Hidden Configuration** is similar to locked configuration, but also can not
be //read// from the web UI.

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
web UI to prevent administrators (or attackers who have compromised
administrator accounts) from reading them.

You can review (and edit) hidden configuration from the CLI:

```
phabricator/ $ ./bin/config get <key>
phabricator/ $ ./bin/config set <key> <value>

```


Locked Configuration With Database Values
=========================================

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:

  - In some earlier version of Phabricator, this configuration was not locked.
  - In the past, you or some other administrator used the web UI to set a
    value. This value was written to the database.
  - In a later version of the software, the value became locked.

When Phabricator was originally released, locked configuration did not yet
exist. Locked configuration was introduced later, and then configuration options
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
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
to lock the value.

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
generally locked or hidden appropriately. In most cases, this setup issue only
affects installs that have used Phabricator for a long time.

At time of writing (February 2019), Phabricator currently respects these old
database values. However, some future version of Phabricator will refuse to
read locked configuration from the database, because this improves security if
an attacker manages to find a way to bypass restrictions on editing locked
configuration from the web UI.

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
file. Usually, you'll do this by first copying the value from the database:

```
phabricator/ $ ./bin/config get <key>
```

...into local configuration:

```
phabricator/ $ ./bin/config set <key> <value>
```

...and then removing the database value:

```
phabricator/ $ ./bin/config delete --database <key>
```

See @{Configuration User Guide: Advanced Configuration} for some more detailed
discussion of different configuration sources.


Next Steps
==========

Continue by:

  - learning more about advanced options with
    @{Configuration User Guide: Advanced Configuration}; or
  - returning to the @{article: Configuration Guide}.