Configuration Guide: Locked and Hidden Configuration

Phorge Administrator and User Documentation (Configuration)

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:

phorge/ $ ./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:

{
  "duck": "quack",
  "cow": "moo"
}

Then, set it with --stdin like this:

phorge/ $ ./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 Phorge can read configuration from the database.

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.

These options must be provided in a configuration source which is read earlier in the bootstrapping process, before Phorge 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 Phorge 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:

phorge/ $ ./bin/config get <key>
phorge/ $ ./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 Phorge, 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 Phorge 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 Phorge for a long time.

At time of writing (February 2019), Phorge currently respects these old database values. However, some future version of Phorge 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:

phorge/ $ ./bin/config get <key>

...into local configuration:

phorge/ $ ./bin/config set <key> <value>

...and then removing the database value:

phorge/ $ ./bin/config delete --database <key>

See Advanced Configuration for some more detailed discussion of different configuration sources.

Next Steps

Continue by:

• learning more about advanced options with Advanced Configuration; or
• returning to the Configuration Guide.