Fossil

Check-in [832f107e]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Added www/capabilities.md, a complete treatment on user capabilities, user categories, login groups, and administration matters involving all of this. It does not replace the pre-existing admin-v-setup.md doc, but a bit of its content did move into this new doc. The new doc also contains the user capability info previously in the forum.wiki doc. This is on a branch because although it's quite useful already, it could use some work before being merged down. At the barest minimum, there are some unanswered questions in the new doc that need addressing.

This new doc does not replace the existing documentation in the UI. It may be that we end up paring that down a bit now that we have a full doc to refer to, but that is a topic for the forum thread that will appear shortly after this checkin.

Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | caps-doc
Files: files | file ages | folders
SHA3-256: 832f107ebbb4a82dc71a44d2b6a073e5306c41b6e1dfa5484549627723a2fb58
User & Date: wyoung 2019-08-23 08:31:45
Context
2019-08-23
11:49
Clarified the placement of "moderator" and "subscriber" in the power hierarchy expression within www/capabilities.md, since each could float up and down somewhat within the fixed hierarchy we give here. Also fixed a broken URL. check-in: ba88f4f2 user: wyoung tags: caps-doc
08:31
Added www/capabilities.md, a complete treatment on user capabilities, user categories, login groups, and administration matters involving all of this. It does not replace the pre-existing admin-v-setup.md doc, but a bit of its content did move into this new doc. The new doc also contains the user capability info previously in the forum.wiki doc. This is on a branch because although it's quite useful already, it could use some work before being merged down. At the barest minimum, there are some unanswered questions in the new doc that need addressing.

This new doc does not replace the existing documentation in the UI. It may be that we end up paring that down a bit now that we have a full doc to refer to, but that is a topic for the forum thread that will appear shortly after this checkin. check-in: 832f107e user: wyoung tags: caps-doc

2019-08-22
15:06
Stronger recommendation for changing the default user's random hex password prior to setting up a Fossil server after learning it's 6 hex digits, not 8 as I thoght when I wrote that! check-in: 9fcd6e44 user: wyoung tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/admin-v-setup.md.

1
2
3
4
5
6
7
8
9

10

11
12
13
14
15
16



17
18
19
20
21
22
23
..
77
78
79
80
81
82
83


84
85
86
87
88
89
90
...
319
320
321
322
323
324
325
326
# The Differences Between the Setup and Admin User Capabilities

Several of the Fossil user capabilities form a clear power hierarchy.
Mathematically speaking:

> *Setup > Admin > Moderator > User > Subscriber > Anonymous > Nobody*

This document explains the distinction between the first two. For the
others, see:



* [How Moderation Works](./forum.wiki#moderation)

* [Users vs Subscribers](./alerts.md#uvs)

* [Defense Against Spiders](./antibot.wiki)





## Philosophical Core

The Setup user "owns" the Fossil repository and may delegate a subset of
that power to one or more Admin users.

The Setup user can grant Admin capability and take it away, but Admin
................................................................................
the Setup user first. If, during a forum discussion one of the mere
users notices a problem with the skin, an Admin-only user should feel
free to correct this without bothering the Setup user.

Another common case is that the Setup user upgrades Fossil on the server
but forgets to merge the upstream skin changes: Admin users are
entrusted to do that work on behalf of the Setup user.




## Capability Groups

We can break up the set of powers the Admin user capability grants into
several groups, then defend each group as a coherent whole.

................................................................................

[fcp]:   https://fossil-scm.org/fossil/help?cmd=configuration
[forum]: https://fossil-scm.org/forum/
[rs]:    https://www.fossil-scm.org/index.html/doc/trunk/www/settings.wiki
[sia]:   https://fossil-scm.org/fossil/artifact?udc=1&ln=1259-1260&name=0fda31b6683c206a
[th1]:   https://www.fossil-scm.org/index.html/doc/trunk/www/th1.md
[tt]:    https://en.wikipedia.org/wiki/Tiger_team#Security
[ucap]:  https://fossil-scm.org/fossil/setup_ucap_list


<
<
<
<
<
|
<
>

>

<

<


>
>
>







 







>
>







 







<
1
2





3

4
5
6
7

8

9
10
11
12
13
14
15
16
17
18
19
20
..
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
...
318
319
320
321
322
323
324

# The Differences Between the Setup and Admin User Capabilities






This document explains the distinction between [Setup users][su] and

[Admin users][au]. For other information about use types, see:

* [Administering User Capabilities](./capabilities.md)
* [How Moderation Works](./forum.wiki#moderation)

* [Users vs Subscribers](./alerts.md#uvs)

* [Defense Against Spiders](./antibot.wiki)

[au]: ./capabilities.md#a
[su]: ./capabilities.md#apsu


## Philosophical Core

The Setup user "owns" the Fossil repository and may delegate a subset of
that power to one or more Admin users.

The Setup user can grant Admin capability and take it away, but Admin
................................................................................
the Setup user first. If, during a forum discussion one of the mere
users notices a problem with the skin, an Admin-only user should feel
free to correct this without bothering the Setup user.

Another common case is that the Setup user upgrades Fossil on the server
but forgets to merge the upstream skin changes: Admin users are
entrusted to do that work on behalf of the Setup user.

[ucap]: ./capabilities.md#ref


## Capability Groups

We can break up the set of powers the Admin user capability grants into
several groups, then defend each group as a coherent whole.

................................................................................

[fcp]:   https://fossil-scm.org/fossil/help?cmd=configuration
[forum]: https://fossil-scm.org/forum/
[rs]:    https://www.fossil-scm.org/index.html/doc/trunk/www/settings.wiki
[sia]:   https://fossil-scm.org/fossil/artifact?udc=1&ln=1259-1260&name=0fda31b6683c206a
[th1]:   https://www.fossil-scm.org/index.html/doc/trunk/www/th1.md
[tt]:    https://en.wikipedia.org/wiki/Tiger_team#Security

Added www/capabilities.md.

























































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
# Administering User Capabilities

Fossil includes a powerful [role-based access control system][rbac]
which affects which users have which capabilities within a given
[served][svr] Fossil repository. We call this the capability system, or
“caps” for short.

Fossil stores a user’s capabilities as an unordered string of ASCII
characters, one capability per, limited to [alphanumerics][an]. Caps are
case-sensitive: “**A**” and “**a**” are different capabilities. We
explain how we came to assign each character [below](#impl).

[an]:   https://en.wikipediAsa.org/wiki/Alphanumeric
[avs]:  ./admin-v-setup.md
[rbac]: https://en.wikipedia.org/wiki/Role-based_access_contro
[sync]: /help?cmd=sync


## <a name="cat"></a>User Categories

Before we explain individual user capabilities and their proper
administration, we want to talk about an oft-overlooked and
misunderstood feature of Fossil: user categories.

Fossil defines four user categories. Two of these apply based on the
user’s login status: **nobody** and **anonymous**. The other two act
like Unix or LDAP user groups: **reader** and **developer**. Because we
use the word “group” for [another purpose](#group) in Fossil, we will
avoid using it that way again in this document. The correct term in
Fossil is “category.”

Fossil’s user category set is currently fixed. There is no way to define
custom categories.

These categories form a strict hierarchy. Mathematically speaking:

> *developer* &ge; *reader* &ge; *anonymous* &ge; *nobody*

When a user visits a [served Fossil repository][svr] via its web UI,
they initially get the capabilities of the “nobody” user category. This
category would be better named “everybody” because it applies whether
you’re logged in or not.

When a user logs in as “anonymous” via [`/login`](/help?cmd=/login) they
get all of the “nobody” category’s caps plus those assigned to the
“anonymous” user category. It would be better named “user” because it
affects all logged-in users, not just those logged in via Fossil’s
anonymous user feature.

When a user with capability letter [**u**](#u) signs in, they get their
own user’s explicit capabilities plus those assigned to the “reader”
category. They also get those assigned to the “anonymous” and “nobody”
categories.

That then extends to those in the “developer” category, being those with
capability letter [**v**](#v): they get their own explicit caps, plus
the “developer” caps, plus the “reader” caps, plus the “anonymous” caps,
plus the “nobody” caps. Thus the hierarchy mathematically defined above.

Fossil shows how these capabilities apply hierarchically in the user
editing screen (Admin → Users → name) with the `[N]` `[A]` `[D]` `[R]`
tags next to each capability check box. If a user gets a capability from
one of the user categories already assigned to it, there is no value in
redundantly assigning that same cap to the user explicitly. For example,
with the default **dei** cap set for the “developer” category, the cap
set **ve** is redundant because **v** grants **dei**, which includes
**e**.

We suggest that you lean heavily on these fixed user categories when
setting up new users. Ideally, your users will group neatly into one of
the predefined categories, but if not, you might be able to shoehorn
them into our fixed scheme. For example, the administrator of a repo
that’s mainly used as a wiki or forum for non-developers could treat the
“developer” user category as if it were called “contributor” or
“author.”

[svr]: ./server/


## <a name="ucap"></a>Individual User Capabilities

When one or more users need to be different from the basic capabilities
defined in user categories, you can assign caps to individual users. For
the most part, you want to simply read the [reference material
below](#ref) when doing such work.

However, it is useful at this time to expand on the mathematical
expression [above](#cat), which covered only the four user categories.
If we bring the individual user capabilities into it, the full hierarchy
of user power in Fossil is:

> *setup* &ge; *admin* &ge; *moderator* &ge; *developer* &ge; *reader* &ge; *subscriber* &ge; *anonymous* &ge; *nobody*


## <a name="new"></a>New Repository Defaults

When you create a new repository, Fossil creates only one user account
named after your OS user name [by default](#defuser).

Fossil gives the initial repository user the [all-powerful Setup
capability](#apsu).

Users who visit a [served repository][svr] without logging in get the
“nobody” user category’s caps which default to
**[g](#g)[j](#j)[o](#o)[r](#r)[z](#z)**: clone the repo, read the wiki,
check-out files via the web UI, view tickets, and pull version archives.
The defaults are suited to random passers-by on a typical FOSS project’s
public web site and its code repository.

Users who [prove they are not a bot][bot] by logging in — even if only
as “anonymous” — get the “nobody” capability set plus
**[h](#h)[m](#m)[n](#n)[c](#c)**: see internal hyperlinks, append to
existing wiki articles, file new tickets, and comment on existing
tickets. We chose these additional capabilities as those we don’t want
bots to have, but which a typical small FOSS project would be happy to
give anonymous humans visiting the project site.

The “reader” user category is typically assigned to users who want to be
identified within the repository but who primarily have a passive role
in the project. The default capability set on a Fossil repo adds
**[k](#k)[p](#p)[t](#t)[w](#w)** caps to those granted by “nobody” and
“anonymous”. This category is not well-named, because the default caps
are all about modifying repository content: edit existing wiki pages,
change one’s own password, create new ticket report formats, and modify
existing tickets. This category would be better named “contributor,” or
“participant.”

Those in the “developer” category get all of the above plus the
**[d](#d)[e](#e)[i](#i)** caps: delete wiki articles and tickets, view
sensitive user material, and check in changes.

The default setup does not explicitly define anything between
“developer” and “setup,” but there is the intermediary [Admin
capability, **a**](#a).

[bot]: ./antibot.wiki


## <a name="pvt"></a>Consequences of Taking a Repository Private

When you click Admin → Security-Audit → “Take it private,” one of the
things it does is set the user capabilities for the “nobody” and
“anonymous” user categories to blank, so that users who haven’t logged
in can’t even see your project’s home page, and the option to log in as
“anonymous” isn’t even offered. Until you log in with a user name, all
you see is the repository’s skin and those few UI elements that work
without any user capability checks at all, such as the “Login” link.

Beware: Fossil does not reassign the capabilities these users had to
other users or to the “reader” or “developer” user category! All users
except those with Setup capability will lose all capabilities they
inherited from “nobody” and “anonymous” categories. Setup is the [lone
exception](#apsu).

If you will have non-Setup users in your private repo, you should parcel
out some subset of the capability set the “nobody” and “anonymous”
categories had to other categories or to individual users first.


## <a name="defuser"></a>Default User Name

By default, Fossil assumes your OS user account name is the same as the
one you use in any Fossil repository. It is the [default for a new
repository](#new), though you can override this with [the `--admin-user`
option][auo]. Fossil has other ways of overriding this in other contexts
such as the `name@` syntax in clone URLs.

It’s simplest to stick with the default; a mismatch can cause problems.
For example, if you clone someone else’s repo anonymously, turn off
autosync, and make check-ins to that repository, they will be assigned
to your OS user name by default. If you later get a login on the remote
repository under a different name and sync your repo with it, your
earlier “private” check-ins will get synced to the remote under your OS
user name!

This is unavoidable because those check-ins are already written durably
to [the local Fossil block chain][bc]. Changing a check-in’s user name
during sync would require rewriting parts of that block chain, which
then means it isn’t actually a “sync” protocol. Either the local and
remote clones would be different or the check-in IDs would change as the
artifacts get rewritten. That in turn means all references to the old
IDs in check-in comments, wiki articles, forum posts, tickets, and more
would break.

When such problems occur, you can amend the check-in to hide the
incorrect name from Fossil reports, but the original values remain in
the repository [forever][shun].

This does mean that anyone with check-in rights on your repository can
impersonate any Fossil user in those check-ins. They check in their work
under any name they like locally, then upon sync, those names are
transferred as-is to the remote repository. Be careful who you give
check-in rights to!

[auo]:  /help?cmd=new
[bc]:   ./blockchain.md
[shun]: ./shunning.wiki



## <a name="group"></a>Login Groups

The Admin → Login-Groups UI feature and its corresponding [`login-group`
command][lg] solve a common problem with Fossil: you’ve created multiple
repositories that some set of users all need access to, those users all
have the same access level on all of these shared repositories, and you
don’t want to redundantly configure the user set for each repository.

This feature ties changes to the “`user`” table in one repo to that in
one or more other repos. With this configured, you get a new choice on
the user edit screen, offering to make changes specific to the one
repository only or to apply it to all others in the login group as well.

A user can log into one repo in a login group only if that user has an
entry in that repo’s user table. That is, setting up a login group
doesn’t automatically transfer all user accounts from the joined repo to
the joining repo. Only when a user exists by name in both repos will
that user be able to share credentials across the repos.

Login groups can have names, allowing one “master” repo to host multiple
subsets of its users to other repos.

Trust in login groups is transitive within a single server. If repo C
joined repo B and repo B joined A, changes in C’s user table affect both
A and B, if you tell Fossil that the change applies to all repos in the
login group.

[lg]: /help?cmd=login-group


## <a name="utclone" id="ssh"></a>Cloning the User Table

When cloning over HTTP, the initial user table in the local clone is set
to its “[new state:](#new)” only one user with Setup capability, named
after either [your OS user account](#defuser) or after the user given in
the clone URL.

There is one exception: if you clone as a named Setup user, you get a
complete copy of the user information. This restriction keeps the user
table private except for the only user allowed to make absolutely
complete clones of a remote repo, such as for failover or backup
purposes. Every other user’s clone is missing this and a few other
items, either for information security or PII privacy reasons.

When cloning with file system paths, `file://` URLs, or over SSH, you
get a complete clone, including the parent repo’s complete user table.

All of the above applies to [login groups](#group) as well.


## <a name="fssync" id="ssh"></a>Caps Affect Web Interfaces Only

User caps only affect Fossil’s [UI pages][wp] and clones done over
`http[s]://` URLs. If you use any other URL type, Fossil will not check
user caps.

This is sensible when working only on a local repository: only local
file permissions matter when operating on a local SQLite DB file.  The
same sense extends to clones done via a file system path
(`/path/to/repo.fossil`) or through a `file://` URL. The only difference
is that there are two sets of file system permission checks: once to
modify the working check-out’s repo clone DB file, then again on
[sync][sync] with the parent DB file.

However, Fossil *also* ignores caps when working on a repo cloned over
SSH! When you make a change to such a repository, the change first goes
to the local clone, where file system permissions are all that matter,
but then upon sync, the situation is effectively the same as when the
parent repo is on the local file system. If you can log into the remote
system over SSH and that user has the necessary file system permissions
on that remote repo DB file, your user is effectively the [all-powerful
Setup user](#apsu) on both sides of the SSH connection.

Fossil reuses the HTTP-based [sync protocol][sp] in both cases above,
tunnelling HTTP through an OS pipe or through SSH (FIXME?), but all of
the user cap checks in Fossil are on the web UI route handlers only.

TODO: Why then can I not `/xfer` my local repo contents to a remote repo
without logging in?

[sp]: ./sync.wiki
[wp]: /help#webpages


## <a name="apsu"></a>The All-Powerful Setup User

A user with [Setup capability, **s**](#s) needs no other user
capabliities, because its scope of its power is hard-coded in the Fossil
C source. You can take all capabilities away from all of the user
categories so that the Setup user inherits no capabilities from them,
yet the Setup user will still be able to use every feature of the Fossil
web user interface.

Another way to look at it is that the setup user is a superset of all
other capabilities, even [Admin capability, **a**](#a). This is
literally how it’s implemented in the code: enabling setup capability on
a user turns on all of the flags controlled by all of the [other
capability characters](#ref).

When you run [`fossil ui`][fui], you are effectively given setup
capability on that repo through that UI instance, regardless of the
capability set defined in the repo’s user table. This is why `ui` always
binds to `localhost` without needing the `--localhost` flag: in this
mode, anyone who can connect to that repo’s web UI has full power over
that repo.

See the [Admin vs Setup article][avs] for a deeper treatment on the
differences between these two related capability sets.

[fui]: /help?cmd=ui


## <a name="ref"></a>Capability Reference

This section documents each currently-defined user capability character
in more detail than the brief summary on the [user capability “key”
page](/setup_ucap_list).

*   <a name="a"></a>**a** — Admin users have all of the capabilities
    below except for [setup](#s): they can create new users, change user
    capability assignments, and use about half of the functions on the
    Admin screen in Fossil UI. (And that is why that screen is now
    called “Admin,” not “Setup,” as it was in old versions of Fossil!)

    There are a couple of ways to view the role of Fossil
    administrators:

    *   Administrators occupy a place between “developer” category users
        and the setup user; a super-developer capability, if you will.
        Administrators have full control over the repository’s managed
        content: versioned artifacts in [the block chain][bc],
        [unversioned content][uv], forum posts, wiki articles, tickets,
        etc.<p>

    *   Administrators are subordinate to the repository’s superuser,
        being the one with setup capability.  Granting users admin
        capability is useful in repositories with enough users
        generating enough activity that the [all-powerful setup
        user](#apsu) could use helpers to take care of routine
        administrivia, user management, content management, site
        cosmetics, etc. without giving over complete control of the
        repository.

    For a much deeper dive into this topic, see the [Admin vs. Setup
    article][avs].

    Mnemonic: **a**dministrate.

*   <a name="b"></a>**b** — Add attachments to wiki articles or tickets.
    Mnemonics: **b**ind, **b**utton, **b**ond, or **b**olt.

*   <a name="c"></a>**c** — Append comments to existing tickets.
    Mnemonic: **c**omment.

*   <a name="d"></a>**d** — Delete wiki articles or tickets. Mnemonic:
    **d**elete.

*   <a name="e"></a>**e** — View [personal identifying information][pii]
    (PII) about other users such as email addresses. Mnemonics: show
    **e**mail addresses; or **E**urope, home of [GDPR][gdpr].

*   <a name="f"></a>**f** — Create new wiki articles. Mnemonic:
    **f**ast, English translation of the Hawaiian word [*wiki*][wnh].

*   <a name="g"></a>**g** — Clone the repository. Note that this is
    distinct from [check-out capability, **o**](#o). Mnemonic: **g**et.

*   <a name="h"></a>**h** — Get hyperlinks in generated HTML which link
    you to other parts of the repository. This capability exists and is
    disabled by default for the “nobody” category to [prevent bots from
    wandering around aimlessly][bot] in the site’s hyperlink web,
    chewing up server resources to little good purpose. Mnemonic:
    **h**yperlink.

*   <a name="i"></a>**i** — Check changes into the repository. Note that
    a lack of this capability does not prevent you from checking changes
    into your local clone, only from syncing those changes up to the
    parent repo, and then [only over HTTP](#fssync). Mnemonic: check
    **i**n changes.

*   <a name="j"></a>**j** — View wiki articles. Mnemonic: in**j**est
    page content.  (All right, you critics, you do better, then.)

*   <a name="k"></a>**k** — Edit wiki articles. Mnemonic:
    **k**ontribute.

*   <a name="l"></a>**l** — Moderate [wiki article appends](#m). Appends
    do not get saved permamently to the receiving repo’s block chain
    until some user (one with this cap or [Setup cap](#s)) approves it.
    Mnemonic: a**l**low.

*   <a name="m"></a>**m** — Append content to existing wiki articles.
    Mmnemonics: a**m**end or **m**odify.

*   <a name="n"></a>**n** — File new tickets. Mnemonic: **n**ew ticket.

*   <a name="o"></a>**o** — Check data out from Fossil. This capability
    has nothing to do with the ability to “open” a local repo clone or
    switch branches in that clone. It only controls whether similar
    operations over HTTP to a remote repo are allowed. You must have
    this capability to view [embedded documentation][edoc], for example,
    since that basically amounts to opening a file in the remote repo.
    This capability also controls the [`/artifact`][au], [`/file`][fu],
    and [`/raw`][ru] URLs.  Mnemonic: check **o**ut file.

*   <a name="p"></a>**p** — Change one’s own password.  Mnemonic:
    **p**assword.

*   <a name="q"></a>**q** — Moderate tickets: comments appended to
    tickets can be deleted by users with this capability. Mnemonic:
    **q**uash noise commentary.

*   <a name="r"></a>**r** — View existing tickets. Mnemonic: **r**ead
    tickets.

*   <a name="s"></a>**s** — The [all-powerful Setup user](#apsu).
    Mnemonics: **s**etup or **s**uperuser.

*   <a name="t"></a>**t** — Create new ticket report formats. Note that
    although this allows the user to provide SQL code to be run in the
    server’s context, and this capability is given to the untrusted
    “anonymous” user category by default, this is a safe capability to
    give to users because it is internally restricted to read-only
    queries on the tickets table only. (This restriction is done with a
    SQLite authorization hook, not by any method so weak as SQL text
    filtering.) Mnemonic: new **t**icket report.

*   <a name="u"></a>**u** — Inherit all capabilities of the “reader”
    user category. Mnemonic: **u**ser, per [naming suggestion
    above](#cat).

*   <a name="v"></a>**v** — Inheheit all capabilities of the “developer”
    user category. Mnemonic: de**v**eloper.

*   <a name="w"></a>**w** — Edit existing tickets. Mnemonic: **w**rite
    to ticket.

*   <a name="x"></a>**x** — Push or pull [private branches][pb].
    Mnemonic: e**x**clusivity; “x” connotes unknown material in many
    Western languages due to its [traditional use in mathematics][lgrd]

*   <a name="y"></a>**y** — Push [unversioned content][uv]. Mnemonic:
    **y**ield, [sense 4][ywik]: “hand over.”

*   <a name="z"></a>**z** — Pull archives of particular repository
    versions via [`/zip`][zu], [`/tarball`][tbu], and [`/sqlar`][sau]
    URLs. This is an expensive capability to assign, because creating
    such archives can put a large load on [a Fossil server][svr], which
    you may then need to [manage][load]. Mnemonic: **z**ip file
    download.

*   <a name="2"></a>**2** — Read [forum posts][for] by other users.
    Mnemonic: from thee **2** me.

*   <a name="3"></a>**3** — Create new forum threads, reply to threads
    created by others, and edit one’s own posts. New posts are held for
    [moderation][fmod], and they are marked to prevent them from being
    included in clone and sync operations. Mnemonic: post for **3**
    audiences: me, [the mods](#5), and [the Man][man].

*   <a name="4"></a>**4** — Same as [**3**](#3) except that forum
    updates bypass the [moderation and private artifact
    restrictions][fmod]. Mnemonic: post 4 immediate release.

*   <a name="5"></a>**5** — [Moderate][fmod] forum posts. Note that this
    capabilitty does not automatically grant [**4**](#4), so it is
    possible to have a user that can create a new post via capability
    [**3**](#3) and then approve that post immediately themselves with
    *this* capability! Mnemonic: “May I have **5** seconds of your time,
    honored Gatekeeper?”

*   <a name="6"></a>**6** — Users with this capability see a checkbox on
    un-moderated forum posts labeled “Trust user X so that future posts
    by user X do not require moderation.” Checking that box and then
    clicking the moderator-only “Approve” button on that post grants
    capability [**4**](#4) to that post’s author. There is currently no
    UI for a user with capability **6** to remove trust from a user once
    it is granted. Mnemonic: “I’m six of hitting Approve on your posts!”

*   <a name="7"></a>**7** — Sign up for [email alerts][ale]. Mnemonic:
    [Seven can wait][scw], I’ve got email to read now.

*   <a name="A"></a>**A** — Send email announcements to users
    [signed up to receive them](#7).  Mnemonic: **a**nnounce.

*   <a name="D"></a>**D** — Enable debugging features. Mnemonic:
    **d**ebug.


[ale]:  ./alerts.md
[au]:   /help?cmd=/artifact
[edoc]: ./embeddeddoc.wiki
[fmod]: ./forum.wiki#moderation
[for]:  ./forum.wiki
[fu]:   /help?cmd=/file
[gdpr]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation
[lgrd]: https://en.wikipedia.org/wiki/La_Géométrie#The_text
[load]: ./loadmgmt.md
[man]:  https://en.wikipedia.org/wiki/The_Man
[pb]:   ./private.wiki
[pii]:  https://en.wikipedia.org/wiki/Personal_data
[sau]:  /help?cmd=/sqlar
[tbu]:  /help?cmd=/tarball
[ru]:   /help?cmd=/raw
[scw]:  https://en.wikipedia.org/wiki/Heaven_Can_Wait
[uv]:   ./unvers.wiki
[wnh]:  https://en.wikipedia.org/wiki/History_of_wikis#WikiWikiWeb,_the_first_wiki
[ywik]: https://en.wiktionary.org/wiki/yield
[zu]:   /help?cmd=/zip


## <a name="impl"></a>Implementation Details

We assigned user capability characters using only lowercase ASCII
letters at first, so those are the most important within Fossil: they
control the functions most core to Fossil’s operation. Once we used up
most of the lowercase letters, we started using uppercase, and then
during the development of the [forum feature][for] we assigned most of
the decimal numerals.  Eventually, we might have to start using
punctuation. We expect to run out of reasons to define new caps before
we’re forced to switch to Unicode, though the possibilities for mnemonic
assignments with emoji are intriguing.

The existing caps are usually [mnemonic][mn], especially among the
earliest and therefore most central assignments, made when we still had
lots of letters to choose from.  There is still hope for good future
mnemonic assignments among the uppercase letters, which are mostly still
unused.

When Fossil is deciding whether a user has a given capability, it simply
searches the cap string for a given character. This is slower than
checking bits in a bitfield, but it’s fast enough in the context where
it runs: at the front end of an HTTP request handler, where the
nanosecond differences in such implementation details are completely
swamped by the millisecond scale ping time of that repo’s network
connection, followed by the requires I/O to satisfy the request. A
[`strchr()` call](https://en.cppreference.com/w/c/string/byte/strchr) is
plenty fast in that context.

[mn]:   https://en.wikipedia.org/wiki/Mnemonic

Changes to www/forum.wiki.

107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
     digest delivery.


<h2 id="setup">Setting up a Fossil Forum</h2>

<h3 id="caps">Capabilities</h3>

Fossil forums use the same role-based access control mechanism as
for normal Fossil repository logins.

There are several dedicated forum-related capability bits you can grant
a user:

  *  <b>Read Forum</b> (<tt>2</tt>): The user may read forum posts.

  *  <b>Write Forum</b> (<tt>3</tt>): The user may create new forum
     threads, reply to existing threads, and edit their own posts. New
     posts are held for moderation, and they are marked to prevent them
     from being included in clone and sync operations.

  *  <b>WriteTrusted Forum</b> (<tt>4</tt>): Same as <b>Write Forum</b>
     except that forum updates bypass the [#moderation | moderation and
     private artifact restrictions].

  *  <b>Moderate Forum</b> (<tt>5</tt>): User gets buttons on posts
     which allow them to either reject or approve posts held for
     moderation. User also gets access to a page (<tt>/modreq</tt>)
     showing the list of pending moderation tasks.

  *  <b>Supervise Forum</b> (<tt>6</tt>): User can grant or revoke
     <b>WriteTrusted</b> capability for other users. (Currently
     unimplemented.)

  *  <b>Email Alerts</b> (<tt>7</tt>): User can sign themselves up for
     email alerts, a.k.a. notifications.

By default, no Fossil user has permission to use the forums except for
users with Setup and Admin capabilities, which get these as part of the
large package of other capabilities they get.

For public Fossil repositories that wish to accept new users without
involving a human, go into Admin &rarr; Access and enable the "Allow







|
|
<
|
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







107
108
109
110
111
112
113
114
115

116
117























118
119
120
121
122
123
124
     digest delivery.


<h2 id="setup">Setting up a Fossil Forum</h2>

<h3 id="caps">Capabilities</h3>

Fossil forums use the same [./capability.md | role-based access control
mechanism] as for normal Fossil repository logins. There are

[./capability.md#2 | several dedicated forum-related capabilities] you
can grant to a user.
























By default, no Fossil user has permission to use the forums except for
users with Setup and Admin capabilities, which get these as part of the
large package of other capabilities they get.

For public Fossil repositories that wish to accept new users without
involving a human, go into Admin &rarr; Access and enable the "Allow

Changes to www/mkindex.tcl.

16
17
18
19
20
21
22

23
24
25
26
27
28
29
  antibot.wiki {Defense against Spiders and Bots}
  backoffice.md {The "Backoffice" mechanism of Fossil}
  blame.wiki {The Annotate/Blame Algorithm Of Fossil}
  blockchain.md {Fossil As Blockchain}
  branching.wiki {Branching, Forking, Merging, and Tagging}
  bugtheory.wiki {Bug Tracking In Fossil}
  build.wiki {Compiling and Installing Fossil}

  cgi.wiki {CGI Script Configuration Options}
  changes.wiki {Fossil Changelog}
  checkin_names.wiki {Check-in And Version Names}
  checkin.wiki {Check-in Checklist}
  childprojects.wiki {Child Projects}
  copyright-release.html {Contributor License Agreement}
  concepts.wiki {Fossil Core Concepts}







>







16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
  antibot.wiki {Defense against Spiders and Bots}
  backoffice.md {The "Backoffice" mechanism of Fossil}
  blame.wiki {The Annotate/Blame Algorithm Of Fossil}
  blockchain.md {Fossil As Blockchain}
  branching.wiki {Branching, Forking, Merging, and Tagging}
  bugtheory.wiki {Bug Tracking In Fossil}
  build.wiki {Compiling and Installing Fossil}
  capabilities.md {Administering User Capabilities}
  cgi.wiki {CGI Script Configuration Options}
  changes.wiki {Fossil Changelog}
  checkin_names.wiki {Check-in And Version Names}
  checkin.wiki {Check-in Checklist}
  childprojects.wiki {Child Projects}
  copyright-release.html {Contributor License Agreement}
  concepts.wiki {Fossil Core Concepts}