@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Configuration Guide: Locked and Hidden Configuration
2@group config
3
4Details about locked and hidden configuration.
5
6
7Overview
8========
9
10Some configuration options are **Locked** or **Hidden**. If an option has one
11of these attributes, it means:
12
13 - **Locked Configuration**: This setting can not be written from the web UI.
14 - **Hidden Configuration**: This setting can not be read or written from
15 the web UI.
16
17This document explains these attributes in more detail.
18
19
20Locked Configuration
21====================
22
23**Locked Configuration** can not be edited from the web UI. In general, you
24can edit it from the CLI instead, with `bin/config`:
25
26```
27phorge/ $ ./bin/config set <key> <value>
28```
29
30Some configuration options take complicated values which can be difficult
31to escape properly for the shell. The easiest way to set these options is
32to use the `--stdin` flag. First, put your desired value in a `config.json`
33file:
34
35```name=config.json, lang=json
36{
37 "duck": "quack",
38 "cow": "moo"
39}
40```
41
42Then, set it with `--stdin` like this:
43
44```
45phorge/ $ ./bin/config set <key> --stdin < config.json
46```
47
48A few settings have alternate CLI tools. Refer to the setting page for
49details.
50
51Note that these settings can not be written to the database, even from the
52CLI.
53
54Locked values can not be unlocked: they are locked because of what the setting
55does or how the setting operates. Some of the reasons configuration options are
56locked include:
57
58
59**Required for bootstrapping**: Some options, like `mysql.host`, must be
60available before Phorge can read configuration from the database.
61
62If you stored `mysql.host` only in the database, Phorge would not know how
63to connect to the database in order to read the value in the first place.
64
65These options must be provided in a configuration source which is read earlier
66in the bootstrapping process, before Phorge connects to the database.
67
68
69**Errors could not be fixed from the web UI**: Some options, like
70`phabricator.base-uri`, can effectively disable the web UI if they are
71configured incorrectly.
72
73If these options could be configured from the web UI, you could not fix them if
74you made a mistake (because the web UI would no longer work, so you could not
75load the page to change the value).
76
77We require these options to be edited from the CLI to make sure the editor has
78access to fix any mistakes.
79
80
81**Attackers could gain greater access**: Some options could be modified by an
82attacker who has gained access to an administrator account in order to gain
83greater access.
84
85For example, an attacker who could modify `cluster.mailers` (and other
86similar options), could potentially reconfigure Phorge to send mail
87through an evil server they controlled, then trigger password resets on other
88user accounts to compromise them.
89
90We require these options to be edited from the CLI to make sure the editor
91has full access to the install.
92
93
94Hidden Configuration
95====================
96
97**Hidden Configuration** is similar to locked configuration, but also can not
98be //read// from the web UI.
99
100In almost all cases, configuration is hidden because it is some sort of secret
101key or access token for an external service. These values are hidden from the
102web UI to prevent administrators (or attackers who have compromised
103administrator accounts) from reading them.
104
105You can review (and edit) hidden configuration from the CLI:
106
107```
108phorge/ $ ./bin/config get <key>
109phorge/ $ ./bin/config set <key> <value>
110
111```
112
113
114Locked Configuration With Database Values
115=========================================
116
117You may receive a setup issue warning you that a locked configuration key has a
118value set in the database. Most commonly, this is because:
119
120 - In some earlier version of Phorge, this configuration was not locked.
121 - In the past, you or some other administrator used the web UI to set a
122 value. This value was written to the database.
123 - In a later version of the software, the value became locked.
124
125When Phorge was originally released, locked configuration did not yet
126exist. Locked configuration was introduced later, and then configuration options
127were gradually locked for a long time after that.
128
129In some cases the meaning of a value changed and it became possible to use it
130to break an install or the configuration became a security risk. In other
131cases, we identified an existing security risk or arrived at some other reason
132to lock the value.
133
134Locking values was more common in the past, and it is now relatively rare for
135an unlocked value to become locked: when new values are introduced, they are
136generally locked or hidden appropriately. In most cases, this setup issue only
137affects installs that have used Phorge for a long time.
138
139At time of writing (February 2019), Phorge currently respects these old
140database values. However, some future version of Phorge will refuse to
141read locked configuration from the database, because this improves security if
142an attacker manages to find a way to bypass restrictions on editing locked
143configuration from the web UI.
144
145To clear this setup warning and avoid surprise behavioral changes in the future,
146you should move these configuration values from the database to a local config
147file. Usually, you'll do this by first copying the value from the database:
148
149```
150phorge/ $ ./bin/config get <key>
151```
152
153...into local configuration:
154
155```
156phorge/ $ ./bin/config set <key> <value>
157```
158
159...and then removing the database value:
160
161```
162phorge/ $ ./bin/config delete --database <key>
163```
164
165See @{Configuration User Guide: Advanced Configuration} for some more detailed
166discussion of different configuration sources.
167
168
169Next Steps
170==========
171
172Continue by:
173
174 - learning more about advanced options with
175 @{Configuration User Guide: Advanced Configuration}; or
176 - returning to the @{article: Configuration Guide}.