@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
Make hidden and locked configuration even more explicit
Summary:
A user in IRC seemed very confused by this, and worked extremely hard to shoot themsevles in the foot by manually writing locked configuration to the database.
Try to explain why configuration is locked better.
Test Plan:
Mostly reading.
{F1078905}
{F1078906}
Reviewers: chad
Reviewed By: chad
Differential Revision: https://secure.phabricator.com/D15128
+161
-19
+56
-16
src/applications/config/controller/PhabricatorConfigEditController.php
+56
-16
src/applications/config/controller/PhabricatorConfigEditController.php
···
104
104
if ($errors) {
105
105
$error_view = id(new PHUIInfoView())
106
106
->setErrors($errors);
107
-
} else if ($option->getHidden()) {
108
-
$msg = pht(
107
+
}
108
+
109
+
$status_items = array();
110
+
if ($option->getHidden()) {
111
+
$message = pht(
109
112
'This configuration is hidden and can not be edited or viewed from '.
110
113
'the web interface.');
111
114
112
-
$error_view = id(new PHUIInfoView())
113
-
->setTitle(pht('Configuration Hidden'))
114
-
->setSeverity(PHUIInfoView::SEVERITY_WARNING)
115
-
->appendChild(phutil_tag('p', array(), $msg));
115
+
$status_items[] = id(new PHUIStatusItemView())
116
+
->setIcon('fa-eye-slash red')
117
+
->setTarget(phutil_tag('strong', array(), pht('Configuration Hidden')))
118
+
->setNote($message);
116
119
} else if ($option->getLocked()) {
120
+
$message = $option->getLockedMessage();
117
121
118
-
$msg = $option->getLockedMessage();
119
-
$error_view = id(new PHUIInfoView())
120
-
->setTitle(pht('Configuration Locked'))
121
-
->setSeverity(PHUIInfoView::SEVERITY_NOTICE)
122
-
->appendChild(phutil_tag('p', array(), $msg));
122
+
$status_items[] = id(new PHUIStatusItemView())
123
+
->setIcon('fa-lock red')
124
+
->setTarget(phutil_tag('strong', array(), pht('Configuration Locked')))
125
+
->setNote($message);
126
+
}
127
+
128
+
if ($status_items) {
129
+
$doc_href = PhabricatorEnv::getDoclink(
130
+
'Configuration Guide: Locked and Hidden Configuration');
131
+
132
+
$doc_link = phutil_tag(
133
+
'a',
134
+
array(
135
+
'href' => $doc_href,
136
+
'target' => '_blank',
137
+
),
138
+
pht('Configuration Guide: Locked and Hidden Configuration'));
139
+
140
+
$status_items[] = id(new PHUIStatusItemView())
141
+
->setIcon('fa-book')
142
+
->setTarget(phutil_tag('strong', array(), pht('Learn More')))
143
+
->setNote($doc_link);
123
144
}
124
145
125
146
if ($option->getHidden() || $option->getLocked()) {
···
144
165
145
166
$form
146
167
->setUser($viewer)
147
-
->addHiddenInput('issue', $request->getStr('issue'))
148
-
->appendChild(
168
+
->addHiddenInput('issue', $request->getStr('issue'));
169
+
170
+
if ($status_items) {
171
+
$status_view = id(new PHUIStatusListView());
172
+
173
+
foreach ($status_items as $status_item) {
174
+
$status_view->addItem($status_item);
175
+
}
176
+
177
+
$form->appendControl(
149
178
id(new AphrontFormMarkupControl())
150
-
->setLabel(pht('Description'))
151
-
->setValue($description));
179
+
->setValue($status_view));
180
+
}
181
+
182
+
$description = $option->getDescription();
183
+
if (strlen($description)) {
184
+
$description_view = new PHUIRemarkupView($viewer, $description);
185
+
186
+
$form
187
+
->appendChild(
188
+
id(new AphrontFormMarkupControl())
189
+
->setLabel(pht('Description'))
190
+
->setValue($description_view));
191
+
}
152
192
153
193
if ($group) {
154
194
$extra = $group->renderContextualDescription(
···
195
235
->setForm($form);
196
236
197
237
if ($error_view) {
198
-
$form_box->setInfoView($error_view);
238
+
$form_box->setInfoView($error_view);
199
239
}
200
240
201
241
$crumbs = $this->buildApplicationCrumbs();
+4
-3
src/applications/config/management/PhabricatorConfigManagementSetWorkflow.php
+4
-3
src/applications/config/management/PhabricatorConfigManagementSetWorkflow.php
···
141
141
if ($option->getLocked() && $use_database) {
142
142
throw new PhutilArgumentUsageException(
143
143
pht(
144
-
"Config key '%s' is locked and can only be set in local ".
145
-
"configuration.",
146
-
$key));
144
+
'Config key "%s" is locked and can only be set in local '.
145
+
'configuration. To learn more, see "%s" in the documentation.',
146
+
$key,
147
+
pht('Configuration Guide: Locked and Hidden Configuration')));
147
148
}
148
149
149
150
try {
+101
src/docs/user/configuration/configuration_locked.diviner
+101
src/docs/user/configuration/configuration_locked.diviner
···
1
+
@title Configuration Guide: Locked and Hidden Configuration
2
+
@group config
3
+
4
+
Details about locked and hidden configuration.
5
+
6
+
7
+
Overview
8
+
========
9
+
10
+
Some configuration options are **Locked** or **Hidden**. If an option has one
11
+
of 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
+
17
+
This document explains these attributes in more detail.
18
+
19
+
20
+
Locked Configuration
21
+
====================
22
+
23
+
**Locked Configuration** can not be edited from the web UI. In general, you
24
+
can edit it from the CLI instead, with `bin/config`:
25
+
26
+
```
27
+
phabricator/ $ ./bin/config set <key> <value>
28
+
```
29
+
30
+
A few settings have alternate CLI tools. Refer to the setting page for
31
+
details.
32
+
33
+
Note that these settings can not be written to the database, even from the
34
+
CLI.
35
+
36
+
Locked values can not be unlocked: they are locked because of what the setting
37
+
does or how the setting operates. Some of the reasons configuration options are
38
+
locked include:
39
+
40
+
41
+
**Required for bootstrapping**: Some options, like `mysql.host`, must be
42
+
available before Phabricator can read configuration from the database.
43
+
44
+
If you stored `mysql.host` only in the database, Phabricator would not know how
45
+
to connect to the database in order to read the value in the first place.
46
+
47
+
These options must be provided in a configuration source which is read earlier
48
+
in the bootstrapping process, before Phabricator connects to the database.
49
+
50
+
51
+
**Errors could not be fixed from the web UI**: Some options, like
52
+
`phabricator.base-uri`, can effectively disable the web UI if they are
53
+
configured incorrectly.
54
+
55
+
If these options could be configured from the web UI, you could not fix them if
56
+
you made a mistake (because the web UI would no longer work, so you could not
57
+
load the page to change the value).
58
+
59
+
We require these options to be edited from the CLI to make sure the editor has
60
+
access to fix any mistakes.
61
+
62
+
63
+
**Attackers could gain greater access**: Some options could be modified by an
64
+
attacker who has gained access to an administrator account in order to gain
65
+
greater access.
66
+
67
+
For example, an attacker who could modify `metamta.mail-adapter` (and other
68
+
similar options), could potentially reconfigure Phabricator to send mail
69
+
through an evil server they controlled, then trigger password resets on other
70
+
user accounts to compromise them.
71
+
72
+
We require these options to be edited from the CLI to make sure the editor
73
+
has full access to the install.
74
+
75
+
76
+
Hidden Configuration
77
+
====================
78
+
79
+
**Hidden Configuration** is similar to locked configuration, but also can not
80
+
be //read// from the web UI.
81
+
82
+
In almost all cases, configuration is hidden because it is some sort of secret
83
+
key or access token for an external service. These values are hidden from the
84
+
web UI to prevent administrators (or attackers who have compromised
85
+
administrator accounts) from reading them.
86
+
87
+
You can review (and edit) hidden configuration from the CLI:
88
+
89
+
```
90
+
phabricator/ $ ./bin/config get <key>
91
+
phabricator/ $ ./bin/config set <key> <value>
92
+
93
+
```
94
+
95
+
96
+
Next Steps
97
+
==========
98
+
99
+
Continue by:
100
+
101
+
- returning to the @{article: Configuration Guide}.