Fossil SCM

fossil-scm / www / caps / admin-v-setup.md
1
# Differences Between Setup and Admin Users
2
3
This document explains the distinction between [Setup users][caps] and
4
[Admin users][capa]. For other information about use types, see:
5
6
* [Administering User Capabilities](./)
7
* [How Moderation Works](../forum.wiki#moderation)
8
* [Users vs Subscribers](../alerts.md#uvs)
9
* [Defense Against Spiders](../antibot.wiki)
10
11
12
## <a id="philosophy"></a>Philosophical Core
13
14
The Setup user "owns" the Fossil repository and may delegate a subset of
15
that power to one or more Admin users.
16
17
The Setup user can grant Admin capability and take it away, but Admin
18
users cannot grant themselves Setup capability, either directly via the
19
Admin → Users UI page or via any indirect means. (If you discover
20
indirect means to elevate Admin privilege to Setup, it's a bug, so
21
please [report it][forum]!)
22
23
It is common for the Setup user to have administrative control over the
24
host system running the Fossil repository, whereas it makes no sense for
25
Admin users to have that ability. If an Admin-only user had `root`
26
access on a Linux box running the Fossil instance they are an Admin on,
27
they could elevate their capability to Setup in several ways. (The
28
`fossil user` command, the `fossil sql` command, editing the repository
29
DB file directly, etc.) Therefore, if you wish to grant someone
30
Setup-like capability on a Fossil repository but you're unwilling to
31
give them a login on the host system, you probably want to grant
32
them Admin capability instead.
33
34
Admin power is delegated from Setup. When a Setup user grants Admin
35
capability, it is an expression of trust in that user's judgement.
36
37
Admin-only users must not fight against the policies of the Setup user.
38
Such a rift would be just cause for the Setup user to strip the Admin
39
user's capabilities. This may then create a fork in the project’s
40
development effort as the ex-Admin takes their clone and stands it up
41
elsewhere, so they may become that fork’s Setup user.
42
43
A useful rule of thumb here is that Admin users should only change
44
things that the Setup user has not changed from the stock configuration.
45
In this way, an Admin-only user can avoid overriding the Setup user's
46
choices.
47
48
You can also look at the role of Admin from the other direction, up
49
through the [user power hierarchy][ucap] rather than down from Setup. An
50
Admin user is usually a “super-developer” role, given full control over
51
the repository’s managed content: versioned artifacts in [the hash tree][bc],
52
[unversioned content][uv], forum posts, wiki articles,
53
tickets, etc.
54
55
We’ll explore these distinctions in the rest of this document.
56
57
[bc]: ../blockchain.md
58
[ucap]: ./index.md#ucap
59
[uv]: ../unvers.wiki
60
61
62
## <a id="binary"></a>No Granularity
63
64
Fossil doesn’t make any distinction between these two user types beyond
65
this binary choice: Setup or Admin.
66
67
A few features of Fossil are broken down so that only part of the
68
feature is accessible to Admin, with the rest left only to Setup users,
69
but for the most part each feature affected by this distinction is
70
either Admin + Setup or Setup-only.
71
72
We could add more capability letters to break down individual
73
sub-features, but we’d run out of ASCII alphanumerics pretty quickly,
74
and we might even run out of ASCII punctuation and symbols. Then would
75
we need to shift to Unicode?
76
77
Consider the Admin → Settings page, which is currently restricted to
78
Setup users only: you might imagine breaking this up into several
79
subsets so that some settings can be changed by Admin users. Is that a
80
good idea? Maybe, but it should be done only after due consideration. It
81
would definitely be wrong to assign a user capability bit to *each*
82
setting on that page.
83
84
Now consider the opposite sort of case, Admin → Skins. Fossil grants
85
Admin users full access to this page so that the Admins can maintain and
86
extend the skin as the repository evolves, not so Admins can switch the
87
entire skin to another without consulting with the Setup user first. How
88
would Fossil decide, using user capabilities only, which skin changes
89
the Admin user is allowed to do, and which must be left to Setup? Do we
90
assign a separate capability letter to each step in `/setup_skin`? Do we
91
assign one more each to the five sections of a skin? (Header, Footer,
92
CSS, JavaScript, and Details.) It quickly becomes unmanageable.
93
94
95
96
## <a id="capgroups"></a>Capability Groups
97
98
We can break up the set of powers the Admin user capability grants into
99
several groups, then defend each group as a coherent whole.
100
101
102
### <a id="security"></a>Security
103
104
While establishing the Fossil repository's security policy is a task for
105
the Setup user, *maintaining* that policy is something that Fossil
106
allows a Setup user to delegate to trustworthy users via the Admin user
107
capability:
108
109
* **Manage users**: The only thing an Admin-only user cannot do on the
110
Admin → Users page is grant Setup capability, either to themselves
111
or to other users. The intent is that Admin users be able to take
112
some of the load of routine user management tasks off the shoulders
113
of the Setup user: delete accounts created by spammers, fix email
114
alert subscriptions, reset passwords, etc.
115
116
* **Security audit**: The Admin → Security-Audit page runs several
117
tests on the Fossil repository's configuration, then reports
118
potential problems it found and offers canned solutions. Those
119
canned solutions do not do anything that an Admin-user could not do
120
via other means, so this page offers the Admin-only user no more
121
power than they otherwise had. For example, this page's "Take it
122
Private" feature can also be done manually via Admin → Users. This
123
page is a convenience, not a grant of new power to the Admin-only
124
user.
125
126
* **Logging**:<a id="log"></a> Admin-only users get to see the various
127
Fossil logs in case they need to use them to understand a problem
128
they're empowered to solve. An obvious example is a spam attack: the
129
Admin might want to find the user's last-used IP, see if they cloned
130
the repository, see if they attempted to brute-force an existing
131
login before self-registering, etc.
132
133
Some security-conscious people might be bothered by the fact that
134
Admin-only users have these abilities. Think of a large IT organization:
135
if the CIO hires a [tiger team][tt] to test the company's internal IT
136
defenses, the line grunts fix the reported problems, not the CIO.
137
138
139
### <a id="administrivia"></a>Administrivia
140
141
It is perfectly fine for a Fossil repository to only have Setup users,
142
no Admin users. The smaller the repository, the more likely the
143
repository has no Admin-only users. If the Setup user neither needs nor
144
wants to grant Admin power to others, there is no requirement in Fossil
145
to do so. [Setup capability is a pure superset of Admin capability.][sia]
146
147
As the number of users on a Fossil repository grows, the value in
148
delegating administrivia also grows, because the Setup user typically
149
has other time sinks they consider more important.
150
151
Admin users can take over the following routine tasks on behalf of the
152
Setup user:
153
154
* **Shunning**: After user management, this is one of the greatest
155
powers of an Admin-only user. Fossil grants access to the Admin →
156
Shunned page to Admin users rather than reserve it to Setup users
157
because one of the primary purposes of [the Fossil shunning
158
system][shun] is to clean up after a spammer, and that's
159
exactly the sort of administrivia we wish to delegate to Admin users.
160
161
Coupled with the Rebuild button on the same page, an Admin user has
162
the power to delete the repository's entire
163
[hash tree][bc]! This makes this feature a pretty good
164
razor in deciding whether to grant someone Admin capability: do you
165
trust that user to shun Fossil artifacts responsibly?
166
167
Realize that shunning is cooperative in Fossil. As long as there are
168
surviving repository clones, an Admin-only user who deletes the
169
whole hash tree has merely caused a nuisance. An Admin-only user
170
cannot permanently destroy the repository unless the Setup user has
171
been so silly as to have no up-to-date clones.
172
173
* **Moderation**: According to [the user power hierarchy][ucap],
174
Admins are greater than Moderators, so control over
175
what Moderators can do clearly belongs to both Admins and to the
176
Setup user(s).
177
178
* **Status**: Although the Fossil `/stat` page is visible to every
179
user with Read capability, there are several additional things this
180
page gives access to when a user also has the Admin capability:
181
182
* <p>[Email alerts][ale] and [backoffice](../backoffice.md)
183
status. Admin-only users cannot modify the email alerts setup,
184
but they can see some details about its configuration and
185
current status.</p>
186
187
* <p>The `/urllist` page, which is a read-only page showing the
188
ways the repository can be accessed and how it has been accessed
189
in the past. Logically, this is an extension to logging,
190
[covered above](#log).</p>
191
192
* <p>The Fossil repository SQL schema. This is not particularly
193
sensitive information, since you get more or less the same
194
information when you clone the repository. It's restricted to
195
Admin because it's primarily useful in debugging SQL errors,
196
which happen most often when Fossil itself is in flux and the
197
schema isn't being automatically updated correctly. That puts
198
this squarely into the "administrivia" category.</p>
199
200
* <p>Web cache status, environment, and logging: more
201
administrivia meant to help the Admin debug problems.</p>
202
203
* **Configure search**
204
205
[ale]: ../alerts.md
206
[shun]: ../shunning.wiki
207
208
209
### <a id="cosmetics"></a>Cosmetics
210
211
While the Setup user is responsible for setting up the initial "look" of
212
a Fossil repository, the Setup user entrusts Admin users with
213
*maintaining* that look. An Admin-only user therefore has the following
214
special abilities:
215
216
* Modify the repository skin
217
218
* Create and modify URL aliases
219
220
* Manage the "ad units" feature, if enabled.
221
222
* Adjust the `/timeline` display preferences.
223
224
* Change the "logo" element displayed by some skins.
225
226
These capabilities allow an Admin-only user to affect the branding and
227
possibly even the back-end finances of a project. This is why we began
228
this document with a philosophical discussion: if you cannot entrust a
229
user with these powers, you should not grant that user Admin capability.
230
231
232
## <a id="clones"></a>Clones and Backups
233
234
Fossil is a *distributed* version control system, which has direct
235
effects on the “Setup user” concept in the face of clones. When you
236
clone a repository, your local user becomes a Setup user on the local
237
clone even if you are not one on the remote repository. This may be
238
surprising to you, but it should also be sensible once you realize that
239
your operating system will generally give you full control over the
240
local repository file. What use trying to apply remote restrictions on
241
the local file, then?
242
243
The distinctions above therefore are intransitive: they apply only
244
within a single repository instance.
245
246
Fossil behaves differently when you do a clone as a user with Setup
247
capability on the remote repository, which primarily has effects on the
248
fidelity of clone-as-backup, which we cover [elsewhere](../backup.md).
249
We strongly encourage you to read that document if you expect to use a
250
clone as a complete replacement for the remote repository.
251
252
253
## <a id="apsu"></a>The All-Powerful Setup User
254
255
Setup users get [every user capability](./ref.html) of Fossil except for
256
[two exceptionally dangerous capabilities](#dcap), which they can later
257
grant to themselves or to others.
258
259
In addition, Setup users can use every feature of the Fossil UI. If Fossil can do a
260
thing, a Setup user on that repo can make Fossil do it.
261
262
Setup users can do many things that Admin users cannot. They may not
263
only use all of the Admin UI features, they may also:
264
265
* See record IDs (RIDs) on screens that show them
266
* See the MIME type of attachments on [`/ainfo` pages](/help/www/ainfo)
267
* See a remote repo’s HTTP [cache status](/help/www/cachestat)
268
and [pull cache entries](/help/www/cacheget)
269
* Edit a Setup user’s account!
270
271
The “Admin” feature of Fossil UI is so-named because Admin users can use
272
about half of its functions, but only Setup can use these pages:
273
274
* **Access**: This page falls under the [Security](#security)
275
category above, but like Configuration, it's generally something set
276
up once and never touched, so only Setup users should change it.
277
278
* **Configuration**: This page nominally falls
279
under [Cosmetics](#cosmetics) above, but it's such a core part of the Fossil
280
configuration — something every Setup user is expected to fully
281
specify on initial repository setup — that we have trouble
282
justifying any case where an Admin-only user would have good cause
283
to modify any of it. This page is generally set up once and then
284
never touched again.
285
286
* **Email-Server**: This is an experimental SMTP server feature which
287
is currently unused in Fossil. Should we get it working, it will
288
likely remain Setup-only, since it will likely be used as a
289
replacement for the platform’s default SMTP server, a powerful
290
position for a piece of software to take.
291
292
* **Login-Group**: [Login groups][lg] allow one Fossil repository to
293
delegate user access to another. Since an Admin-only user on one
294
repo might not have such access to another repo on the same host
295
system, this must be a Setup-only task.
296
297
* **Notification**: This is the main UI for setting up integration
298
with a platform’s SMTP service, for use in sending out [email
299
notifications][ale]. Because this screen can set commands to execute
300
on the host, and because finishing the configuration requires a
301
login on the Fossil host system, it is not appropriate to give Admin
302
users access to it.
303
304
* **Settings**: The [repository settings][rs] available via Admin →
305
Settings have too wide a range of power to allow modification by
306
Admin-only users:
307
308
* <p><b>Harmless</b>: Admin-only users on a repository may well
309
have checkin rights on the repository, so the fact that
310
versionable settings like `crlf-glob` can also be set at the
311
repository level seems like a thing we might want to allow
312
Admin-only users the ability to change. Since Fossil currently
313
has no way to allow only some settings to be changed by
314
Admin-only users and some not, we can't just show these harmless
315
settings to Admin-only users.</p>
316
317
* <p><b>Low-Risk</b>: The <tt>admin-log</tt> setting controls
318
whether the Fossil admin log is generated. Since we've <a
319
href="#log">already decided</a> that Admin-only users can see
320
this log, it seems fine that the Admin users can choose whether
321
this log gets generated in the first place.</p>
322
323
<p>There's a small risk that a rogue Admin user could disable
324
the log before doing something evil that the log would capture,
325
so ideally, we'd want to restrict changing this setting from 1
326
to 0 to Setup only while allowing Admin-only users to change it
327
from 0 to 1. Fossil doesn't currently allow that.</p>
328
329
* <p><b>Risky</b>: The <tt>https-login</tt> setting falls under
330
the "Security" section above, but it should probably never be
331
adjusted by Admin-only users. Sites that want it on will never
332
want it to be disabled without a very good reason.</p>
333
334
<p>There is also an inverse risk: if the site has a front-end
335
HTTPS proxy that uses HTTP to communicate over localhost to
336
Fossil, enabling this setting will create an infinite redirect
337
loop! (Ask me how I know.)</p>
338
339
* <p><b>Dangerous</b>: The <tt>email-send-command</tt> setting
340
could allow a rogue Admin to run arbitrary commands on the host
341
system, unless it's prevented via some kind of host-specific
342
restriction. (chroot, jails, SELinux, VMs, etc.) Since it makes
343
no sense to trust Admin-only users with <tt>root</tt> level
344
access on the host system, we almost certainly don't want to
345
allow them to change such settings.</p>
346
347
* **SQL**: The Admin → SQL feature allows the Setup user to enter raw
348
SQL queries against the Fossil repository via Fossil UI. This not
349
only allows arbitrary ability to modify the repository hash tree
350
and its backing data tables, it can probably also be used to damage
351
the host such as via `PRAGMA temp_store = FILE`.
352
353
* **Tickets**: This section allows input of arbitrary TH1 code that
354
runs on the server, affecting the way the Fossil ticketing system
355
works. The justification in the **TH1** section below therefore
356
applies.
357
358
* **TH1**: The [TH1 language][th1] is quite restricted relative to the
359
Tcl language it descends from, so this author does not believe there
360
is a way to damage the Fossil repository or its host via the Admin →
361
TH1 feature, which allows execution of arbitrary TH1 code within the
362
repository's execution context. Nevertheless, interpreters are a
363
well-known source of security problems, so it seems best to restrict
364
this feature to Setup-only users as long as we lack a good reason
365
for Admin-only users to have access to it.
366
367
* **Transfers**: This is for setting up TH1 hooks on various actions,
368
so the justification in the **TH1** section above applies.
369
370
* **Wiki**: These are mainly cosmetic and usability settings. We might
371
open this up to Admin users in the future.
372
373
Just remember, [user caps affect Fossil’s web interfaces only][webo]. A
374
user is a Setup user by default on their local clone of a repo, and
375
Fossil’s ability to protect itself against malicious (or even simply
376
incorrect) pushes is limited. Someone with clone and push capability on
377
your repo could clone it, modify their local repo, and then push the
378
changes back to your repo. Be careful who you give that combination of
379
capabilities to!
380
381
When you run [`fossil ui`][fui], you are the Setup user on that repo
382
through that UI instance, regardless of the capability set defined in
383
the repo’s user table. This is true even if you cloned a remote repo
384
where you do not have Setup caps. This is why `ui` always binds to
385
`localhost` without needing the `--localhost` flag: in this mode, anyone
386
who can connect to that repo’s web UI has full power over that repo.
387
388
389
## <a id="dcap"></a>Dangerous Capabilities Initially Denied to Everyone
390
391
There are two capabilities that Fossil doesn’t grant by default to Setup
392
or Admin users automatically. They are exceptionally dangerous, so
393
Fossil makes these users grant themselves (or others) these capabilities
394
deliberately, hopefully after careful consideration.
395
396
397
### <a id="y"></a>Write Unversioned
398
399
Fossil currently doesn’t distinguish the sub-operations of
400
[`fossil uv`](/help/uv); they’re all covered by [**WrUnver**][capy]
401
(“y”) capability. Since some of these operations are unconditionally
402
destructive due to the nature of unversioned content, and since this
403
goes against Fossil’s philosophy of immutable history, nobody gets cap
404
“y” on a Fossil repo by default, not even the Setup or Admin users. A
405
Setup or Admin user must grant cap “y” to someone — not necessarily
406
themselves! — before modifications to remote
407
unversioned content are possible.
408
409
Operations on unversioned content made without this capability affect
410
your local clone only. In this way, your local unversioned file table
411
can have different content from that in its parent repo. This state of
412
affairs will continue until your user either gets cap “y” and syncs that
413
content with its parent or you say `fossil uv revert` to make your local
414
unversioned content table match that of its parent repo.
415
416
417
### <a id="x"></a>Private Branch Push
418
419
For private branches to remain private, they must never be accidentally
420
pushed to a public repository. It can be [difficult to impossible][shun]
421
to recover from such a mistake, so nobody gets [**Private**][capx] (“x”)
422
capability on a Fossil repo by default, not even Admin or Setup users.
423
424
There are two common uses for private branches.
425
426
One use is part of a local social contract allowing individual
427
developers to work on some things in private until they’re ready to push
428
them up to the parent repository. This goes against [a core tenet][fdp]
429
of Fossil’s design philosophy, but Fossil allows it, so some development
430
organizations do this. If yours is one of these, you might give cap “x”
431
to the “developer” category.
432
433
The other use is in development organizations that follow the Fossil
434
philosophy, where you do not work in private unless you absolutely must.
435
You may have a public-facing project — let’s call it “SQLite” for the
436
sake of argument — but then someone comes along and commissions a custom
437
modification to your project which they wish to keep proprietary. You
438
do your work on a private branch, which you absolutely must never push
439
to the public repo, because that would be illegal. (Breach of contract,
440
copyright violation on a work-for-hire agreement, etc.) If you are using
441
Fossil in this way, we recommend that you give “x” capability to a
442
special developer account only, if at all, to minimize the chance of an
443
accidental push.
444
445
446
[capa]: ./ref.html#a
447
[caps]: ./ref.html#s
448
[capx]: ./ref.html#x
449
[capy]: ./ref.html#y
450
451
[fcp]: https://fossil-scm.org/home/help/configuration
452
[fdp]: ../fossil-v-git.wiki#devorg
453
[forum]: https://fossil-scm.org/forum/
454
[fui]: /help/ui
455
[lg]: ./login-groups.md
456
[rs]: https://fossil-scm.org/home/doc/trunk/www/settings.wiki
457
[sia]: https://fossil-scm.org/home/artifact?ln=1259-1260&name=0fda31b6683c206a
458
[snoy]: https://fossil-scm.org/forum/forumpost/00e1c4ecff
459
[th1]: ../th1.md
460
[tt]: https://en.wikipedia.org/wiki/Tiger_team#Security
461
[webo]: ./#webonly
462

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button