Fossil

Check-in [689f7683]
Login

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

Overview
Comment:Grepped the Fossil source code for C code that checks for Setup caps exclusively to preotect functions and listed those in the Reference section of capablities.md. Also expanded the coverage of the "caps affect Fossil web interfaces only" section, which plays into this.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | caps-doc
Files: files | file ages | folders
SHA3-256: 689f7683b694a0beb93291ef8326a1a35fe0f59ba8778f89ec3d0925860284d0
User & Date: wyoung 2019-08-27 03:56:03
Context
2019-08-27
18:04
Merged most of the new material on Setup vs Admin in the new capabilities doc into the pre-existing admin-v-setup.md doc, which already covers this topic. check-in: ee901c7b user: wyoung tags: caps-doc
03:56
Grepped the Fossil source code for C code that checks for Setup caps exclusively to preotect functions and listed those in the Reference section of capablities.md. Also expanded the coverage of the "caps affect Fossil web interfaces only" section, which plays into this. check-in: 689f7683 user: wyoung tags: caps-doc
01:55
Rewrote explanation of "o" cap. check-in: 208ca0d7 user: wyoung tags: caps-doc
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/capabilities.md.

237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
...
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
...
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
...
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
...
438
439
440
441
442
443
444
445





















446
447
448
449
450
451
452
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
................................................................................

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
................................................................................
    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 (Write)** — 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). Granting this
    capability also grants **o (Read)**.  Mnemonic: check **i**n
    changes.

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

*   <a name="k"></a>**k (WrWiki)** — Edit wiki articles. Granting this
................................................................................
    Mmnemonics: a**m**end or **m**odify.

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

*   <a name="o"></a>**o (Read)** — Read repository content from a remote
    Fossil instance over HTTP. This capability has nothing to do with
    reading data from a local repository, because [caps affect Fossil’s
    web interfaces only](#fssync). Once you’ve cloned a remote
    repository to your local machine, you can do any reading you want on
    that repository irrespective of whether your user has **o**
    capability; the repo clone is completely under your user’s power at
    that point, affectted only by OS file permissions and such. (To
    prevent cloning, see [**g**](#g).)

    It is common to withhold this capability from low-status visitors to
................................................................................
*   <a name="q"></a>**q (ModTkt)** — Moderate tickets: comments appended to
    tickets can be deleted by users with this capability. Mnemonic:
    **q**uash noise commentary.

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

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





















    Mnemonics: **s**etup or **s**uperuser.

*   <a name="t"></a>**t (TktFmt)** — 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







|







 







|

|
|
<

>
|
|
|
<
|
|


<
>
|
|
|
|
|
|
|



|




>
|
|







 







|







 







|







 







|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
...
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
...
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
...
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
...
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
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"></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
................................................................................

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="webonly"></a>Caps Affect Web Interfaces Only

User caps only affect Fossil’s [UI pages][wp], remote operations over
`http[s]://` URLs, and [the JSON API][japi].


User caps *do not* affect operations done on a local repo opened via a
`file://` URL or a file system path. This should strike you as sensible:
only local file permissions matter when operating on a local SQLite DB
file. The same is true when working on a clone done over such a path,

except that there are then 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.


What may surprise you is that user caps *also do not affect 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 its web interfaces only.

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

[japi]: https://docs.google.com/document/d/1fXViveNhDbiXgCuE7QDXQOKeFzf2qNUkBEgiUvoqFN4/view#heading=h.6k0k5plm18p1
[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
................................................................................
    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 (Write)** — 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](#webonly). Granting this
    capability also grants **o (Read)**.  Mnemonic: check **i**n
    changes.

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

*   <a name="k"></a>**k (WrWiki)** — Edit wiki articles. Granting this
................................................................................
    Mmnemonics: a**m**end or **m**odify.

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

*   <a name="o"></a>**o (Read)** — Read repository content from a remote
    Fossil instance over HTTP. This capability has nothing to do with
    reading data from a local repository, because [caps affect Fossil’s
    web interfaces only](#webonly). Once you’ve cloned a remote
    repository to your local machine, you can do any reading you want on
    that repository irrespective of whether your user has **o**
    capability; the repo clone is completely under your user’s power at
    that point, affectted only by OS file permissions and such. (To
    prevent cloning, see [**g**](#g).)

    It is common to withhold this capability from low-status visitors to
................................................................................
*   <a name="q"></a>**q (ModTkt)** — Moderate tickets: comments appended to
    tickets can be deleted by users with this capability. Mnemonic:
    **q**uash noise commentary.

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

*   <a name="s"></a>**s (Setup)** — The [all-powerful Setup user](#apsu) who
    can uniquely:

    *   Use roughly half of the Admin page settings
    *   See record IDs (RIDs) on screens that show them
    *   See the MIME type of attachments on [`/ainfo` pages](/help?cmd=/ainfo)
    *   See a remote repo’s HTTP [cache status](/help?cmd=/cachestat)
        and [pull cache entries](/help?cmd=/cacheget)
    *   TODO: fold in results of [the timestamp override thread](https://fossil-scm.org/forum/forumpost/ee950efd2d)
    *   Edit a Setup user’s account!

    The Admin pages that only Setup can use are: Access, Configuration,
    Email-Server, Login-Group, Notification, Settings, SQL, TH1,
    Tickets, Transfers (TH1 hooks), and Wiki.

    Remember, [user caps affect Fossil’s web interfaces](#webonly) only.
    A user can do anything they like to a repo stored on their local
    machine. Fossil protects itself against malcious pushes, but someone
    with clone and push capability on your repo could clone it, modify
    their local repo as the local default Setup user account they got on
    clone, and then push the changes back to your repo.

    Mnemonics: **s**etup or **s**uperuser.

*   <a name="t"></a>**t (TktFmt)** — 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