Fossil SCM
Nearly complete rewrite of the "Caps Affect Web Interfaces Only" section of the caps/index.md doc, disentangling the concepts for greater clarity.
Commit
50eeced0489532f9f9377c9b43be7844308b960bbff129bcc5d9f206625caa6d
Parent
52fb87ba5003934…
1 file changed
+58
-36
+58
-36
| --- www/caps/index.md | ||
| +++ www/caps/index.md | ||
| @@ -256,54 +256,76 @@ | ||
| 256 | 256 | All of the above applies to [login groups][lg] as well. |
| 257 | 257 | |
| 258 | 258 | |
| 259 | 259 | ## <a name="webonly"></a>Caps Affect Web Interfaces Only |
| 260 | 260 | |
| 261 | -User caps only affect Fossil’s [UI pages][wp], remote operations over | |
| 262 | -`http[s]://` URLs, and [the JSON API][japi]. | |
| 263 | - | |
| 264 | -User caps *do not* affect operations done on a local repo opened via a | |
| 265 | -`file://` URL or a file system path. This should strike you as sensible: | |
| 266 | -only local file permissions matter when operating on a local SQLite DB | |
| 267 | -file. The same is true when working on a clone done over such a path, | |
| 268 | -except that there are then two sets of file system permission checks: | |
| 269 | -once to modify the working check-out’s repo clone DB file, then again on | |
| 270 | -[sync][sync] with the parent DB file. The Fossil capability checks are | |
| 271 | -effectively defeated because your user has [**Setup**][s] capability on | |
| 272 | -both sides of the sync. | |
| 273 | - | |
| 274 | -What may surprise you is that user caps *also do not affect SSH!* When | |
| 275 | -you make a change to such a repository, the change first goes to the | |
| 276 | -local clone, where file system permissions are all that matter, but then | |
| 277 | -upon sync, the situation is effectively the same as when the parent repo | |
| 278 | -is on the local file system. If you can log into the remote system over | |
| 279 | -SSH and that user has the necessary file system permissions on that | |
| 280 | -remote repo DB file, it is the same situation as for `file://` URLs. | |
| 281 | - | |
| 282 | -All Fossil syncs are done over HTTP, even for `file://` and `ssh://` | |
| 283 | -URLs: | |
| 261 | +Fossil’s user capability system only affects accesses over `http[s]://` | |
| 262 | +URLs. This includes clone, sync/push/pull, the [UI pages][wp], and [the | |
| 263 | +JSON API][japi]. For everything else, the user caps aren’t consulted at | |
| 264 | +all. | |
| 265 | + | |
| 266 | +The only checks made when working directly with a local repository are | |
| 267 | +the operating system’s file system permissions. This should strike you | |
| 268 | +as sensible, since if you have local file access to the repository, you | |
| 269 | +can do anything you want to that repo DB including adding a | |
| 270 | +[**Setup**][s] user for yourself, after which Fossil’s user capability | |
| 271 | +system is effectively bypassed. This is why the `fossil ui` command | |
| 272 | +gives you Setup permissions within Fossil UI: it can’t usefully prevent | |
| 273 | +you from doing anything through the UI since only the local file system | |
| 274 | +permissions actually matter. | |
| 275 | + | |
| 276 | +What may be more surprising to you is that this is also true when | |
| 277 | +working on a *clone* done over a local file path, except that there are | |
| 278 | +then two sets of file system permission checks: once to modify the | |
| 279 | +working check-out’s repo clone DB file, then again on [sync][sync] with | |
| 280 | +the parent DB file. The Fossil capability checks are effectively | |
| 281 | +defeated because your user has [**Setup**][s] capability on both sides | |
| 282 | +of the sync. Be aware that those file checks do still matter, however: | |
| 283 | +Fossil requires write access to a repo DB while cloning from it, so you | |
| 284 | +can’t clone from a read-only repo DB file over a local file path. | |
| 285 | + | |
| 286 | +Even more surprising may be the fact that user caps do not affect | |
| 287 | +cloning and syncing over SSH! When you make a change to such a | |
| 288 | +repository, the change first goes to the local clone where file system | |
| 289 | +permissions are all that matter, but then upon sync, the situation is | |
| 290 | +effectively the same as when the parent repo is on the local file | |
| 291 | +system. The reason behind this is that if you can log into the remote | |
| 292 | +system over SSH and that user has the necessary file system permissions | |
| 293 | +on that remote repo DB file to allow clone and sync operations, then | |
| 294 | +we’re back in the same situation as with local files: there’s no point | |
| 295 | +trying to enforce the Fossil user capabilities when you can just modify | |
| 296 | +the remote DB directly, so the operation proceeds unimpeded. | |
| 297 | + | |
| 298 | +Where this gets confusing is that *all* Fossil syncs are done over the | |
| 299 | +HTTP protocol, including those done over `file://` and `ssh://` URLs, | |
| 300 | +not just those done over `http[s]://` URLs: | |
| 284 | 301 | |
| 285 | 302 | * For `ssh://` URLs, Fossil pipes the HTTP conversation through a |
| 286 | 303 | local SSH client to a remote instance of Fossil running the |
| 287 | - [`test-http`](/help?name=test-http) command to recieve the tunneled | |
| 288 | - HTTP connection without cap checks. The SSH client defaults to “`ssh | |
| 289 | - -e none -T`” on most platforms, except on Windows where it defaults | |
| 290 | - to “`plink -ssh -T`”. You can override this with [the `ssh-command` | |
| 304 | + [`test-http`](/help?name=test-http) command to receive the tunneled | |
| 305 | + HTTP connection. The reason Fossil’s user capability system is | |
| 306 | + bypassed in this case is that [`test-http` gives full capabilities | |
| 307 | + to its users][sxcap]. | |
| 308 | + | |
| 309 | + The SSH client command defaults to “`ssh -e none -T`” on most | |
| 310 | + platforms except Windows where it defaults to “`plink -ssh -T`”. | |
| 311 | + You can override this with [the `ssh-command` | |
| 291 | 312 | setting](/help?name=ssh-command). |
| 292 | 313 | |
| 293 | -* For `file://` URLs, the “sending” Fossil instance writes its side of | |
| 314 | +* For `file://` URLs — as opposed to plain local file paths — | |
| 315 | + the “sending” Fossil instance writes its side of | |
| 294 | 316 | the HTTP conversation out to a temporary file in the same directory |
| 295 | 317 | as the local repo clone and then calls itself on the “receiving” |
| 296 | 318 | repository to read that same HTTP transcript file back in to apply |
| 297 | - those changes to that repository. Presumably Fossil doesn’t do this | |
| 298 | - with a pipe to ease portability to Windows. | |
| 299 | - | |
| 300 | -Because both mechanisms work on local repos, the checks for capabilities | |
| 301 | -like [**Read**][o] and [**Write**][i] within the HTTP conversation for | |
| 302 | -such URLs can never return “false,” because you are the [**Setup**][s] | |
| 303 | -user on both sides of the conversation. Such checks only have a useful | |
| 304 | -effect when done over an `http[s]://` URL. | |
| 319 | + those changes to that repository. Presumably Fossil does this | |
| 320 | + instead of using a pipe to ease portability to Windows. | |
| 321 | + | |
| 322 | +Checks for capabilities like [**Read**][o] and [**Write**][i] within the | |
| 323 | +HTTP conversation between two Fossil instances only have a useful effect | |
| 324 | +when done over an `http[s]://` URL. | |
| 325 | + | |
| 326 | +[sxcap]: https://fossil-scm.org/home/file?ci=8813ae91a699ac73&name=src%2Fmain.c&ln=2632-2637 | |
| 305 | 327 | |
| 306 | 328 | |
| 307 | 329 | ## <a name="pubpg"></a>Public Pages |
| 308 | 330 | |
| 309 | 331 | In Admin → Access, there is an option for giving a list of [globs][glob] |
| 310 | 332 |
| --- www/caps/index.md | |
| +++ www/caps/index.md | |
| @@ -256,54 +256,76 @@ | |
| 256 | All of the above applies to [login groups][lg] as well. |
| 257 | |
| 258 | |
| 259 | ## <a name="webonly"></a>Caps Affect Web Interfaces Only |
| 260 | |
| 261 | User caps only affect Fossil’s [UI pages][wp], remote operations over |
| 262 | `http[s]://` URLs, and [the JSON API][japi]. |
| 263 | |
| 264 | User caps *do not* affect operations done on a local repo opened via a |
| 265 | `file://` URL or a file system path. This should strike you as sensible: |
| 266 | only local file permissions matter when operating on a local SQLite DB |
| 267 | file. The same is true when working on a clone done over such a path, |
| 268 | except that there are then two sets of file system permission checks: |
| 269 | once to modify the working check-out’s repo clone DB file, then again on |
| 270 | [sync][sync] with the parent DB file. The Fossil capability checks are |
| 271 | effectively defeated because your user has [**Setup**][s] capability on |
| 272 | both sides of the sync. |
| 273 | |
| 274 | What may surprise you is that user caps *also do not affect SSH!* When |
| 275 | you make a change to such a repository, the change first goes to the |
| 276 | local clone, where file system permissions are all that matter, but then |
| 277 | upon sync, the situation is effectively the same as when the parent repo |
| 278 | is on the local file system. If you can log into the remote system over |
| 279 | SSH and that user has the necessary file system permissions on that |
| 280 | remote repo DB file, it is the same situation as for `file://` URLs. |
| 281 | |
| 282 | All Fossil syncs are done over HTTP, even for `file://` and `ssh://` |
| 283 | URLs: |
| 284 | |
| 285 | * For `ssh://` URLs, Fossil pipes the HTTP conversation through a |
| 286 | local SSH client to a remote instance of Fossil running the |
| 287 | [`test-http`](/help?name=test-http) command to recieve the tunneled |
| 288 | HTTP connection without cap checks. The SSH client defaults to “`ssh |
| 289 | -e none -T`” on most platforms, except on Windows where it defaults |
| 290 | to “`plink -ssh -T`”. You can override this with [the `ssh-command` |
| 291 | setting](/help?name=ssh-command). |
| 292 | |
| 293 | * For `file://` URLs, the “sending” Fossil instance writes its side of |
| 294 | the HTTP conversation out to a temporary file in the same directory |
| 295 | as the local repo clone and then calls itself on the “receiving” |
| 296 | repository to read that same HTTP transcript file back in to apply |
| 297 | those changes to that repository. Presumably Fossil doesn’t do this |
| 298 | with a pipe to ease portability to Windows. |
| 299 | |
| 300 | Because both mechanisms work on local repos, the checks for capabilities |
| 301 | like [**Read**][o] and [**Write**][i] within the HTTP conversation for |
| 302 | such URLs can never return “false,” because you are the [**Setup**][s] |
| 303 | user on both sides of the conversation. Such checks only have a useful |
| 304 | effect when done over an `http[s]://` URL. |
| 305 | |
| 306 | |
| 307 | ## <a name="pubpg"></a>Public Pages |
| 308 | |
| 309 | In Admin → Access, there is an option for giving a list of [globs][glob] |
| 310 |
| --- www/caps/index.md | |
| +++ www/caps/index.md | |
| @@ -256,54 +256,76 @@ | |
| 256 | All of the above applies to [login groups][lg] as well. |
| 257 | |
| 258 | |
| 259 | ## <a name="webonly"></a>Caps Affect Web Interfaces Only |
| 260 | |
| 261 | Fossil’s user capability system only affects accesses over `http[s]://` |
| 262 | URLs. This includes clone, sync/push/pull, the [UI pages][wp], and [the |
| 263 | JSON API][japi]. For everything else, the user caps aren’t consulted at |
| 264 | all. |
| 265 | |
| 266 | The only checks made when working directly with a local repository are |
| 267 | the operating system’s file system permissions. This should strike you |
| 268 | as sensible, since if you have local file access to the repository, you |
| 269 | can do anything you want to that repo DB including adding a |
| 270 | [**Setup**][s] user for yourself, after which Fossil’s user capability |
| 271 | system is effectively bypassed. This is why the `fossil ui` command |
| 272 | gives you Setup permissions within Fossil UI: it can’t usefully prevent |
| 273 | you from doing anything through the UI since only the local file system |
| 274 | permissions actually matter. |
| 275 | |
| 276 | What may be more surprising to you is that this is also true when |
| 277 | working on a *clone* done over a local file path, except that there are |
| 278 | then two sets of file system permission checks: once to modify the |
| 279 | working check-out’s repo clone DB file, then again on [sync][sync] with |
| 280 | the parent DB file. The Fossil capability checks are effectively |
| 281 | defeated because your user has [**Setup**][s] capability on both sides |
| 282 | of the sync. Be aware that those file checks do still matter, however: |
| 283 | Fossil requires write access to a repo DB while cloning from it, so you |
| 284 | can’t clone from a read-only repo DB file over a local file path. |
| 285 | |
| 286 | Even more surprising may be the fact that user caps do not affect |
| 287 | cloning and syncing over SSH! When you make a change to such a |
| 288 | repository, the change first goes to the local clone where file system |
| 289 | permissions are all that matter, but then upon sync, the situation is |
| 290 | effectively the same as when the parent repo is on the local file |
| 291 | system. The reason behind this is that if you can log into the remote |
| 292 | system over SSH and that user has the necessary file system permissions |
| 293 | on that remote repo DB file to allow clone and sync operations, then |
| 294 | we’re back in the same situation as with local files: there’s no point |
| 295 | trying to enforce the Fossil user capabilities when you can just modify |
| 296 | the remote DB directly, so the operation proceeds unimpeded. |
| 297 | |
| 298 | Where this gets confusing is that *all* Fossil syncs are done over the |
| 299 | HTTP protocol, including those done over `file://` and `ssh://` URLs, |
| 300 | not just those done over `http[s]://` URLs: |
| 301 | |
| 302 | * For `ssh://` URLs, Fossil pipes the HTTP conversation through a |
| 303 | local SSH client to a remote instance of Fossil running the |
| 304 | [`test-http`](/help?name=test-http) command to receive the tunneled |
| 305 | HTTP connection. The reason Fossil’s user capability system is |
| 306 | bypassed in this case is that [`test-http` gives full capabilities |
| 307 | to its users][sxcap]. |
| 308 | |
| 309 | The SSH client command defaults to “`ssh -e none -T`” on most |
| 310 | platforms except Windows where it defaults to “`plink -ssh -T`”. |
| 311 | You can override this with [the `ssh-command` |
| 312 | setting](/help?name=ssh-command). |
| 313 | |
| 314 | * For `file://` URLs — as opposed to plain local file paths — |
| 315 | the “sending” Fossil instance writes its side of |
| 316 | the HTTP conversation out to a temporary file in the same directory |
| 317 | as the local repo clone and then calls itself on the “receiving” |
| 318 | repository to read that same HTTP transcript file back in to apply |
| 319 | those changes to that repository. Presumably Fossil does this |
| 320 | instead of using a pipe to ease portability to Windows. |
| 321 | |
| 322 | Checks for capabilities like [**Read**][o] and [**Write**][i] within the |
| 323 | HTTP conversation between two Fossil instances only have a useful effect |
| 324 | when done over an `http[s]://` URL. |
| 325 | |
| 326 | [sxcap]: https://fossil-scm.org/home/file?ci=8813ae91a699ac73&name=src%2Fmain.c&ln=2632-2637 |
| 327 | |
| 328 | |
| 329 | ## <a name="pubpg"></a>Public Pages |
| 330 | |
| 331 | In Admin → Access, there is an option for giving a list of [globs][glob] |
| 332 |