[Email alerts](./alerts.md) and [backoffice](./backoffice.md) - status. Admin-only users cannot modify the email alerts setup, - but they can see some details about its configuration and - current status.
- - *The `/urllist` page, which is a read-only page showing the - ways the repository can be accessed and how it has been accessed - in the past. Logically, this is an extension to logging, - [covered above](#log).
- - *The Fossil repository SQL schema. This is not particularly - sensitive information, since you get more or less the same - information when you clone the repository. It's restricted to - Admin because it's primarily useful in debugging SQL errors, - which happen most often when Fossil itself is in flux and the - schema isn't being automatically updated correctly. That puts - this squarely into the "administrivia" category.
- - *Web cache status, environment, and logging: more - administrivia meant to help the Admin debug problems.
- -* **Configure search** - - -### Cosmetics - -While the Setup user is responsible for setting up the initial "look" of -a Fossil repository, the Setup user entrusts Admin users with -*maintaining* that look. An Admin-only user therefore has the following -special abilities: - -* Modify the repository skin - -* Create and modify URL aliases - -* Manage the "ad units" feature, if enabled. - -* Adjust the `/timeline` display preferences. - -* Change the "logo" element displayed by some skins. - -These capabilities allow an Admin-only user to affect the branding and -possibly even the back-end finances of a project. This is why we began -this document with a philosophical discussion: if you cannot entrust a -user with these powers, you should not grant that user Admin capability. - - -## Clones and Backups - -Keep in mind that Fossil is a *distributed* version control system, -which means that a user known to Fossil might have Setup capability on -one repository but be a mere "user" on one of its clones. The most -common case is that when you clone a repository, even anonymously, you -gain Setup power over the local clone. - -The distinctions above therefore are intransitive: they apply only -within a single repository instance. - -The exception to this is when the clone is done as a Setup user, since -this also copies the `user` table on the initial clone. A user with -Setup capability can subsequently say [`fossil conf pull all`][fcp] to -update that table and everything else not normally synchronized between -Fossil repositories. In this way, a Setup user can create multiple -interchangeable clones. This is useful not only to guard against rogue -Admin-only users, it is a useful element of a load balancing and -failover system. - - -## Setup-Only Features - -Some features are now and must always be restricted to Setup users only. - -* **Configuration**: The Admin → Configuration page nominally falls - under Cosmetics above, but it's such a core part of the Fossil - configuration — something every Setup user is expected to fully - specify on initial repository setup — that we have trouble - justifying any case where an Admin-only user would have good cause - to modify any of it. This page is generally set up once and then - never touched again. - -* **Access**: The Admin → Access page falls under the Security - category above, but like Configuration, it's generally something set - up once and never touched, so only Setup users should change it. - -* **Login-Group**: Login groups allow one Fossil repository to - delegate user access to another. Since an Admin-only user on one - repo might not have such access to another repo on the same host - system, this must be a Setup-only task. - -* **Settings**: The [repository settings][rs] available via Admin → - Settings have too wide a range of power to allow modification by - Admin-only users: - - *Harmless: Admin-only users on a repository may well - have checkin rights on the repository, so the fact that - versionable settings like `crlf-glob` can also be set at the - repository level seems like a thing we might want to allow - Admin-only users the ability to change. Since Fossil currently - has no way to allow only some settings to be changed by - Admin-only users and some not, we can't just show these harmless - settings to Admin-only users.
- - *Low-Risk: The admin-log setting controls - whether the Fossil admin log is generated. Since we've already decided that Admin-only users can see - this log, it seems fine that the Admin users can choose whether - this log gets generated in the first place.
- -There's a small risk that a rogue Admin user could disable - the log before doing something evil that the log would capture, - so ideally, we'd want to restrict changing this setting from 1 - to 0 to Setup only while allowing Admin-only users to change it - from 0 to 1. Fossil doesn't currently allow that.
- - *Risky: The https-login setting falls under - the "Security" section above, but it should probably never be - adjusted by Admin-only users. Sites that want it on will never - want it to be disabled without a very good reason.
- -There is also an inverse risk: if the site has a front-end - HTTPS proxy that uses HTTP to communicate over localhost to - Fossil, enabling this setting will create an infinite redirect - loop! (Ask me how I know.)
- - *Dangerous: The email-send-command setting - could allow a rogue Admin to run arbitrary commands on the host - system, unless it's prevented via some kind of host-specific - restriction. (chroot, jails, SELinux, VMs, etc.) Since it makes - no sense to trust Admin-only users with root level - access on the host system, we almost certainly don't want to - allow them to change such settings.
- -* **SQL**: The Admin → SQL feature allows the Setup user to enter raw - SQL queries against the Fossil repository via Fossil UI. This not - only allows arbitrary ability to modify the repository blockchain - and its backing data tables, it can probably also be used to damage - the host such as via `PRAGMA temp_store = FILE`. - -* **TH1**: The [TH1 language][TH1] is quite restricted relative to the - Tcl language it descends from, so this author does not believe there - is a way to damage the Fossil repository or its host via the Admin → - TH1 feature, which allows execution of arbitrary TH1 code within the - repository's execution context. Nevertheless, interpreters are a - well-known source of security problems, so it seems best to restrict - this feature to Setup-only users as long as we lack a good reason - for Admin-only users to have access to it. - - -[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 Index: www/alerts.md ================================================================== --- www/alerts.md +++ www/alerts.md @@ -30,11 +30,11 @@ Much of this document describes how to set up Fossil's email alert system. To follow this guide, you will need a Fossil UI browser window open to the [Admin → Notification](/setup_notification) Fossil UI screen on the Fossil server that will be sending these email alerts, logged -in as a user with Admin capability. It is not possible to work on a +in as a user with [**Admin** capability](./caps/ref.html#a). It is not possible to work on a clone of the server's repository and push the configuration changes up to that repo as an Admin user, [on purpose](#backup). **Important:** Do not confuse that screen with Admin → Email-Server, which sets up a different subsystem within Fossil. That feature is @@ -160,11 +160,12 @@Use a different login with greater privilege than FOO to access /subscribe-...then the repository's administrator forgot to [give the Alerts capability](#cap7) +...then the repository's administrator forgot to give the +[**EmailAlert** capability][cap7] to that user or to a user category that the user is a member of. After a subscriber signs up for alerts for the first time, a single verification email is sent to that subscriber's given email address. The new subscriber must click a link in that email in order to activate @@ -188,10 +189,12 @@ settings by visiting the `/alerts` page on the repository. With the default skin, you can get there by clicking the "Logout" link in the upper right corner of any Fossil UI page then clicking the "Email Alerts" link. That link is also available via the Sitemap (`/sitemap`) and via the default skin's hamburger menu (☰). + +[cap7]: ./caps/ref.html#7 ### Unsubscribing @@ -223,24 +226,27 @@ Checklist][cl], right? Right. [cl]: https://sendgrid.com/blog/programming-style-guide-checklist/ - + ### User Capabilities -Once email alerts are working, one must also adjust user permissions to -allow users to subscribe to email alerts. In the capability list for -each user on the Admin → Users page is a new capability called "Email -Alerts". The corresponding capability letter is "7", which you must -give to any user that needs to use the subscription setup pages, -`/subscribe` and `/alerts`. +Once email alerts are working, you may need to [adjust the default user +capabilities](./caps/) to give "[Email Alerts][cap7]" capability to any +[user category](./caps/#ucat) or [individual user](./caps/#ucap) that +needs to use the subscription setup pages, `/subscribe` and `/alerts`. +[**Admin**][capa] and [**Setup**][caps] users always have this +capability. To allow any passer-by on the Internet to subscribe, give the "Email Alerts" capability to the "nobody" user category. To require that a person solve a simple CAPTCHA first, give that capability to the "anonymous" user category instead. + +[capa]: ./caps/ref.html#a +[caps]: ./caps/ref.html#s ### First Post Index: www/antibot.wiki ================================================================== --- www/antibot.wiki +++ www/antibot.wiki @@ -10,44 +10,41 @@ The website presented by a Fossil server is intended to be used interactively by humans, not walked by spiders. This article describes the techniques used by Fossil to try to welcome human users while keeping out spiders. -
[Email alerts][ale] and [backoffice](./backoffice.md) + status. Admin-only users cannot modify the email alerts setup, + but they can see some details about its configuration and + current status.
+ + *The `/urllist` page, which is a read-only page showing the + ways the repository can be accessed and how it has been accessed + in the past. Logically, this is an extension to logging, + [covered above](#log).
+ + *The Fossil repository SQL schema. This is not particularly + sensitive information, since you get more or less the same + information when you clone the repository. It's restricted to + Admin because it's primarily useful in debugging SQL errors, + which happen most often when Fossil itself is in flux and the + schema isn't being automatically updated correctly. That puts + this squarely into the "administrivia" category.
+ + *Web cache status, environment, and logging: more + administrivia meant to help the Admin debug problems.
+ +* **Configure search** + +[ale]: ./alerts.md + + +### Cosmetics + +While the Setup user is responsible for setting up the initial "look" of +a Fossil repository, the Setup user entrusts Admin users with +*maintaining* that look. An Admin-only user therefore has the following +special abilities: + +* Modify the repository skin + +* Create and modify URL aliases + +* Manage the "ad units" feature, if enabled. + +* Adjust the `/timeline` display preferences. + +* Change the "logo" element displayed by some skins. + +These capabilities allow an Admin-only user to affect the branding and +possibly even the back-end finances of a project. This is why we began +this document with a philosophical discussion: if you cannot entrust a +user with these powers, you should not grant that user Admin capability. + + +## Clones and Backups + +Keep in mind that Fossil is a *distributed* version control system, +which means that a user known to Fossil might have Setup capability on +one repository but be a mere "user" on one of its clones. The most +common case is that when you clone a repository, even anonymously, you +gain Setup power over the local clone. + +The distinctions above therefore are intransitive: they apply only +within a single repository instance. + +The exception to this is when the clone is done as a Setup user, since +this also copies the `user` table on the initial clone. A user with +Setup capability can subsequently say [`fossil conf pull all`][fcp] to +update that table and everything else not normally synchronized between +Fossil repositories. In this way, a Setup user can create multiple +interchangeable clones. This is useful not only to guard against rogue +Admin-only users, it is a useful element of a load balancing and +failover system. + + +## The All-Powerful Setup User + +Setup users get [every user capability](./ref.html) of Fossil except for +[**WrUnver**](./ref.html#y). (That lone hold-out is [by design][snoy].) + +In addition, Setup users can use every feature of the Fossil UI. If Fossil can do a +thing, a Setup user on that repo can make Fossil do it. + +Setup users can do many things that Admin users cannot: + +* Use all of the Admin UI features +* 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) +* Edit a Setup user’s account! + +The “Admin” feature of Fossil UI is so-named because Admin users can use +about half of its functions, but only Setup can use these pages: + +* **Access**: This page falls under the [Security](#security) + category above, but like Configuration, it's generally something set + up once and never touched, so only Setup users should change it. + +* **Configuration**: This page nominally falls + under [Cosmetics](#cosmetics) above, but it's such a core part of the Fossil + configuration — something every Setup user is expected to fully + specify on initial repository setup — that we have trouble + justifying any case where an Admin-only user would have good cause + to modify any of it. This page is generally set up once and then + never touched again. + +* **Email-Server**: This is an experimental SMTP server feature which + is currently unused in Fossil. Should we get it working, it will + likely remain Setup-only, since it will likely be used as a + replacement for the platform’s default SMTP server, a powerful + position for a piece of software to take. + +* **Login-Group**: [Login groups][lg] allow one Fossil repository to + delegate user access to another. Since an Admin-only user on one + repo might not have such access to another repo on the same host + system, this must be a Setup-only task. + +* **Notification**: This is the main UI for setting up integration + with a platform’s SMTP service, for use in sending out [email + notifications][ale]. Because this screen can set commands to execute + on the host, and because finishing the configuration requires a + login on the Fossil host system, it is not appropriate to give Admin + users access to it. + +* **Settings**: The [repository settings][rs] available via Admin → + Settings have too wide a range of power to allow modification by + Admin-only users: + + *Harmless: Admin-only users on a repository may well + have checkin rights on the repository, so the fact that + versionable settings like `crlf-glob` can also be set at the + repository level seems like a thing we might want to allow + Admin-only users the ability to change. Since Fossil currently + has no way to allow only some settings to be changed by + Admin-only users and some not, we can't just show these harmless + settings to Admin-only users.
+ + *Low-Risk: The admin-log setting controls + whether the Fossil admin log is generated. Since we've already decided that Admin-only users can see + this log, it seems fine that the Admin users can choose whether + this log gets generated in the first place.
+ +There's a small risk that a rogue Admin user could disable + the log before doing something evil that the log would capture, + so ideally, we'd want to restrict changing this setting from 1 + to 0 to Setup only while allowing Admin-only users to change it + from 0 to 1. Fossil doesn't currently allow that.
+ + *Risky: The https-login setting falls under + the "Security" section above, but it should probably never be + adjusted by Admin-only users. Sites that want it on will never + want it to be disabled without a very good reason.
+ +There is also an inverse risk: if the site has a front-end + HTTPS proxy that uses HTTP to communicate over localhost to + Fossil, enabling this setting will create an infinite redirect + loop! (Ask me how I know.)
+ + *Dangerous: The email-send-command setting + could allow a rogue Admin to run arbitrary commands on the host + system, unless it's prevented via some kind of host-specific + restriction. (chroot, jails, SELinux, VMs, etc.) Since it makes + no sense to trust Admin-only users with root level + access on the host system, we almost certainly don't want to + allow them to change such settings.
+ +* **SQL**: The Admin → SQL feature allows the Setup user to enter raw + SQL queries against the Fossil repository via Fossil UI. This not + only allows arbitrary ability to modify the repository blockchain + and its backing data tables, it can probably also be used to damage + the host such as via `PRAGMA temp_store = FILE`. + +* **Tickets**: This section allows input of aribtrary TH1 code that + runs on the server, affecting the way the Fossil ticketing system + works. The justification in the **TH1** section below therefore + applies. + +* **TH1**: The [TH1 language][TH1] is quite restricted relative to the + Tcl language it descends from, so this author does not believe there + is a way to damage the Fossil repository or its host via the Admin → + TH1 feature, which allows execution of arbitrary TH1 code within the + repository's execution context. Nevertheless, interpreters are a + well-known source of security problems, so it seems best to restrict + this feature to Setup-only users as long as we lack a good reason + for Admin-only users to have access to it. + +* **Transfers**: This is for setting up TH1 hooks on various actions, + so the justification in the **TH1** section above applies. + +* **Wiki**: These are mainly cosmetic and usability settings. We might + open this up to Admin users in the future. + +Just remember, [user caps affect Fossil’s web interfaces only][webo]. A +user is a Setup user by default on their local clone of a repo, and +Fossil’s ability to protect itself against malicious (or even simply +incorrect) pushes is limited. Someone with clone and push capability on +your repo could clone it, modify their local repo, and then push the +changes back to your repo. Be careful who you give that combination of +capabilities to! + +When you run [`fossil ui`][fui], you are the Setup user on that repo +through that UI instance, regardless of the capability set defined in +the repo’s user table. This is true even if you cloned a remote repo +where you do not have Setup caps. 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. + +[fcp]: https://fossil-scm.org/fossil/help?cmd=configuration +[forum]: https://fossil-scm.org/forum/ +[fui]: /help?cmd=ui +[lg]: ./login-groups.md +[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 +[snoy]: https://fossil-scm.org/forum/forumpost/00e1c4ecff +[tt]: https://en.wikipedia.org/wiki/Tiger_team#Security ADDED www/caps/impl.md Index: www/caps/impl.md ================================================================== --- /dev/null +++ www/caps/impl.md @@ -0,0 +1,111 @@ +# Implementation Details of User Capabilities + +## Capability Letter Choices + +We [assigned][ref] 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. All of the lowercase ASCII letters are now +assigned. Eventually, we might have to start using ASCII +punctuation and symbols. We expect to run out of reasons to define new caps before +we’re forced to switch to Unicode, though the possibilities for [mnemonic][mn] +assignments with emoji are intriguing. 😉 + +The existing caps are usually mnemonic, 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. + + +## Why Not Bitfields? + +Some may question the use of ASCII character strings for [capability +sets][ucap] instead of bitfields, which are more efficient, both in +terms of storage and processing time. + +Fossil handles these character strings in one of two ways. For most HTTP +hits, Fossil [expands][sexp] the string into a [`struct` full of +flags][sff] so that later code can just do simple Boolean tests. In a +minority of cases, where Fossil only needs to check for the presence of +a single flag, it just does a [`strchr()` call][sc] on the string +instead. + +Both methods are slower than bit testing in a bitfield, but keep the +execution context in mind: 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 required I/O to satisfy the request. +Either method is plenty fast in that context. + +In exchange for this immeasurable cost per hit, we get human-readable +capability sets. + + +## Why Doesn’t Fossil Filter “Bad” Artifacts on Sync? + +Fossil is more trusting about the content it receives from a remote +clone during sync than you might expect. Common manifestations of this +design choice are: + +1. A user may be able to impersonate other users. This can be + [accidental](./index.md#defuser) as well as purposeful. + +2. If your local system clock is out-of-sync with absolute time, + artifacts committed to that repo will appear with the “wrong” time + when sync’d. If the time sync error is big enough, it can make + check-ins appear to go back in time and other bad effects. + +3. You can purposely overwrite good timestamps with bad ones and push + those changes up to the remote with no interference, even though + Fossil tries to make that a Setup-only operation. + +All of this falls out of two of Fossil’s design choices: sync is +all-or-nothing, and [the Fossil block chain][bc] is immutable. Fossil +would have to violate one or both of these principles to filter such +problems out of incoming syncs. + +We have considered auto-[shunning][shun] “bad” content on sync, but this +is [difficult][asd] due to [the design of the sync protocol][dsp]. This +is not an impossible set of circumstances, but implementing a robust +filter on this input path would be roughly as difficult as writing a +basic [inter-frame video codec][ifvc]: do-able, but still a lot of +work. Patches to do this will be thoughtfully considered. + +We can’t simply change content as it arrives. Such manipulations would +change the artifact manifests, which would change the hashes, which +would require rewriting all parts of the block chain from that point out +to the tips of those branches. The local Fossil repo must then go +through the same process as the remote one on subsequent syncs in order +to build up a sync sequence that the remote can understand. Even if +you’re willing to accept all of that, this would break all references to +the old artifact IDs in forum posts, wiki articles, check-in comments, +tickets, etc. + +The bottom line here is that [**Clone**](./ref.html#g) and +[**Write**](./ref.html#i) are a potent combination of user capabilities. +Be careful who you give that pair to! + + +----- + +*[Back to Administering User Capabilities](./)* + + + + +[asd]: https://fossil-scm.org/forum/forumpost/ce4a3b5f3e +[bc]: ../blockchain.md +[dsp]: https://fossil-scm.org/fossil/doc/trunk/www/sync.wiki +[for]: ./forum.wiki +[ifvc]: https://en.wikipedia.org/wiki/Inter_frame +[mn]: https://en.wikipedia.org/wiki/Mnemonic +[ref]: ./ref.html +[sexp]: http://fossil-scm.org/fossil/artifact?udc=1&ln=1223-1298&name=889d6724 +[sff]: http://fossil-scm.org/fossil/artifact?udc=1&ln=80-117&name=52d2860f +[sc]: https://en.cppreference.com/w/c/string/byte/strchr +[shun]: ../shunning.wiki +[ucap]: ./index.md#ucap ADDED www/caps/index.md Index: www/caps/index.md ================================================================== --- /dev/null +++ www/caps/index.md @@ -0,0 +1,374 @@ +# 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 caps as an unordered string of ASCII characters, +one capability per, [currently](./impl.md#choices) limited to +[alphanumerics][an]. Caps are case-sensitive: “**A**” and “**a**” are +different user capabilities. + +This is a complex topic, so some sub-topics have their own documents: + +1. [Login Groups][lg] +2. [Implementation Details](./impl.md) +3. [User Capability Reference](./ref.html) + +[an]: https://en.wikipediAsa.org/wiki/Alphanumeric +[avs]: ./admin-v-setup.md +[lg]: ./login-groups.md +[rbac]: https://en.wikipedia.org/wiki/Role-based_access_control + + +## 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][lg] in Fossil, we will +avoid using it that way again in this document. The correct term in +Fossil is “category.” + +Fossil user categories give you a way to define capability sets for four +hard-coded situations within the Fossil C source code. Logically +speaking: + +> *(developer* ∨ *reader)* ≥ *anonymous* ≥ *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?name=/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 either the “reader” ([**u**][u]) or “developer” +([**v**][v]) capability letter logs in, they get their [individual user +caps](#ucap) plus those assigned to this special user category. They +also get those assigned to the “anonymous” and “nobody” categories. + +Because “developer” users do not automatically inherit “reader” caps, +it is standard practice to give both letters to your “developer” users: +**uv**. You could instead just assign cap **u** to the “developer” +category. + +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 +wiki-only Fossil repo for non-developers could treat the “developer” +user category as if it were called “author,” and a forum-only repo could +treat the same category as if it were called “member.” + +There is currently no way to define custom user categories. + +[svr]: ../server/ + + +## 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. You +may want to have the [cap reference][ref] open when doing such work. + +It is useful at this time to expand on the logical +expression [above](#cat), which covered only the four fixed user categories. +When we bring the individual user capabilities into it, the complete +expression of the way Fossil implements user power becomes: + +> *setup* ≥ *admin* ≥ *moderator* ≥ *(developer* ∨ *reader)* ≥ *[subscriber]* ≥ *anonymous* ≥ *nobody* + +The two additions at the top are clear: [setup is all-powerful][apsu], +and since admin users have [all capabilities][ref] except for Setup +capability, they are [subordinate only to the setup user(s)][avsp]. + +The moderator insertion could go anywhere from where it’s shown now down +to above the “anonymous” level, depending on what other caps you give to +your moderators. Also, there is not just one type of moderator: Fossil +has [wiki][l], [ticket][q], and [forum][5] moderators, each +independent of the others. Usually your moderators are fairly +high-status users, with developer capabilities or higher, but Fossil +does allow the creation of low-status moderators. + +The placement of “subscriber” in that hierarchy is for the +sort of subscriber who has registered an account on the repository +purely to [receive email alerts and announcements][7]. Users with +additional caps can also be subscribers, but not all users *are* in fact +subscribers, which is why we show it in square brackets. (See [Users vs +Subscribers](../alerts.md#uvs).) + +[apsu]: ./admin-v-setup.md#apsu +[avsp]: ./admin-v-setup.md#philosophy + + +## New Repository Defaults + +Fossil creates one user account in new repos, which is 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. +This default is 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 “participant”. + +Those in the “developer” category get the “nobody” and “anonymous” cap +sets plus **[d][d][e][e][i][i]**: delete wiki articles and tickets, view +sensitive user material, and check in changes. + +[bot]: ../antibot.wiki + + +## 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. + + +## Reading vs. Cloning + +Fossil has two capabilities that are often confused: +[**Read**](./ref.html#o) and [**Clone**](./ref.html#g). + +The **Read** 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 local user within that repo has Read capability. +The repo clone is completely under your user’s power at that point, +affected only by OS file permissions and such. If you need to prevent +that, you want to deny **Clone** capability instead. + +Withholding the **Read** capability has a different effect: it +prevents a web client from viewing [embedded +documentation][edoc], using [the file +browser](/help?name=/dir), and pulling file content via the +[`/artifact`](/help?name=/artifact), [`/file`](/help?name=/file), and +[`/raw`](/help?name=/raw) URLs. +It is is common to withhold **Read** capability from low-status visitors +on private or semi-private repos to prevent them from pulling individual +elements of the repo over the web one at a time, as someone may do when +denied the bulk **Clone** capability. + +[edoc]: ../embeddeddoc.wiki + + +## 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! + +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]. It is [difficult enough][fos] to fix +such problems automatically during sync that we are unlikely to ever do +so. + +[auo]: /help?name=new +[fos]: ./impl.md#filter +[shun]: ../shunning.wiki + + + +## 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, per the default above, 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][lg] as well. + + +## 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. The Fossil capability checks are +effectively defeated because your user has [**Setup**][s] capability on +both sides of the sync. + +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, it is the same situation as for `file://` URLs. + +All Fossil syncs are done over HTTP, even for `file://` and `ssh://` +URLs: + +* For `ssh://` URLs, Fossil pipes the HTTP conversation through a + local SSH client to a remote instance of Fossil running the + [`test-http`](/help?name=test-http) command to recieve the tunneled + HTTP connection without cap checks. The SSH client defaults to “`ssh + -e none -T`” on most platforms, except on Windows where it defaults + to “`plink -ssh -T`”. You can override this with [the `ssh-command` + setting](/help?name=ssh-command). + +* For `file://` URLs, the “sending” Fossil instance writes its side of + the HTTP conversation out to a temporary file in the same directory + as the local repo clone and then calls itself on the “receiving” + repository to read that same HTTP transcript file back in to apply + those changes to that repository. Presumably Fossil doesn’t do this + with a pipe to ease portability to Windows. + +Because both mechanisms work on local repos, the checks for capabilities +like [**Read**][o] and [**Write**][i] within the HTTP conversation for +such URLs can never return “false,” because you are the [**Setup**][s] +user on both sides of the conversation. Such checks only have a useful +effect when done over an `http[s]://` URL. + + +## Public Pages + +In Admin → Access, there is an option for giving a list of [globs][glob] +to name URLs which get treated as if the visitor had [the default cap +set](#defcap). For example, you could take the [**Read**][o] capability +away from the “nobody” user category, who has it by default, to prevent +users without logins from pulling down your repository contents one +artifact at a time, yet give those users the ability to read the project +documentation by setting the glob to match your [embedded +documentation][edoc]’s URL root. + + +## Default User Capability Set + +In Admin → Access, you can define a default user capability set, which +is used as: + +1. the default caps for users newly created by an Admin or Setup user +2. the default caps for self-registered users, an option in that same UI +3. the effective caps for URIs considered [public pages](#pubpg) + +This defaults to [**Reader**][u]. + + + + + +[ref]: ./ref.html + +[a]: ./ref.html#a +[b]: ./ref.html#b +[c]: ./ref.html#c +[d]: ./ref.html#d +[e]: ./ref.html#e +[f]: ./ref.html#f +[g]: ./ref.html#g +[h]: ./ref.html#h +[i]: ./ref.html#i +[j]: ./ref.html#j +[k]: ./ref.html#k +[l]: ./ref.html#l +[m]: ./ref.html#m +[n]: ./ref.html#n +[o]: ./ref.html#o +[p]: ./ref.html#p +[q]: ./ref.html#q +[r]: ./ref.html#r +[s]: ./ref.html#s +[t]: ./ref.html#t +[u]: ./ref.html#u +[v]: ./ref.html#v +[w]: ./ref.html#w +[x]: ./ref.html#x +[y]: ./ref.html#y +[z]: ./ref.html#z + +[2]: ./ref.html#2 +[3]: ./ref.html#3 +[4]: ./ref.html#4 +[5]: ./ref.html#5 +[6]: ./ref.html#6 +[7]: ./ref.html#7 + +[glob]: https://en.wikipedia.org/wiki/Glob_(programming) +[japi]: https://docs.google.com/document/d/1fXViveNhDbiXgCuE7QDXQOKeFzf2qNUkBEgiUvoqFN4/view#heading=h.6k0k5plm18p1 +[sp]: ../sync.wiki +[sync]: /help?name=sync +[wp]: /help#webpages ADDED www/caps/login-groups.md Index: www/caps/login-groups.md ================================================================== --- /dev/null +++ www/caps/login-groups.md @@ -0,0 +1,32 @@ +# 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 + +----- + +*[Back to Administering User Capabilities](./)* ADDED www/caps/ref.html Index: www/caps/ref.html ================================================================== --- /dev/null +++ www/caps/ref.html @@ -0,0 +1,412 @@ +Here we document each currently-defined user capability character in +more detail than the brief summary on the “key” page in the Fossil user editor. Each +row gives the capability letter used in the Fossil user editor followed +by the C code’s name for that cap within the FossilUserPerms +object, so you can use this reference both from the UI down and from the +C code up.
+ +The mnemonics +given here vary from obviously-correct to post facto +rationalizations to the outright fanciful. To some extent, this is unavoidable.
+ + +| ? | +Name | +Description | +
|---|---|---|
| a | +Admin | ++ Admin users have all of the capabilities below except for + setup and WrUnver. + See Admin vs. Setup for a more + nuanced discussion. Mnemonic: administrate. + | +
| b | +Attach | ++ Add attachments to wiki articles or tickets. Mnemonics: bind, + button, bond, or bolt. + | +
| c | +ApndTkt | ++ Append comments to existing tickets. Mnemonic: comment. + | +
| d | +Delete | ++ Delete wiki articles or tickets. Mnemonic: delete. + | +
| e | +RdAddr | ++ View personal + identifying information (PII) about other users such as email + addresses. Mnemonics: show email addresses; or + Europe, home of GDPR. + | +
| f | +NewWiki | ++ Create new wiki articles. Mnemonic: fast, English + translation of the Hawaiian word wiki. + | +
| g | +Clone | ++ Clone the repository. Note that this is distinct from check-out capability, o. Mnemonic: + get. + | +
| h | +Hyperlink | ++ Get hyperlinks in generated HTML which link you to other parts of + the repository. This capability exists so we can deny it to the + “nobody” category, to prevent bots from + wandering around aimlessly in the site’s hyperlink web, chewing up server resources to little + good purpose. Mnemonic: hyperlink. + | +
| 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. + Granting this capability also grants o (Read) Mnemonics: + input, check in changes. + | +
| j | +RdWiki | ++ View wiki articles. Mnemonic: injest page content. (All + right, you critics, you do better, then.) + | +
| k | +WrWiki | ++ Edit wiki articles. Granting this capability also grants RdWiki and ApndWiki, + but it does not grant NewWiki! + Mnemonic: kontribute. + | +
| l | +ModWiki | ++ Moderate wiki article appends. Appends do not get + saved permanently to the receiving repo’s block chain until Setup or someone with this cap approves it. + Mnemonic: allow. + | +
| m | +ApndWiki | ++ Append content to existing wiki articles. Mnemonic: amend + wiki + | +
| n | +NewTkt | ++ File new tickets. Mnemonic: new ticket. + | +
| o | +Read | ++ Read repository content from a remote Fossil instance over + HTTP. See Reading vs. + Cloning. Mnemonic: check out remote repo contents. + | +
| p | +Password | ++ Change one’s own password. Mnemonic: password. + | +
| q | +ModTkt | ++ Moderate tickets: delete comments appended to tickets. Mnemonic: + quash noise commentary. + | +
| r | +RdTkt | ++ View existing tickets. Mnemonic: read tickets. + | +
| s | +Setup | ++ The all-powerful Setup user. + Mnemonics: setup or superuser. + | +
| 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 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 ticket report. + | +
| u | +n/a | ++ Inherit all capabilities of the “reader” user category; does not + have a dedicated flag internally within Fossil. Mnemonic: + user + | +
| v | +n/a | ++ Inherit all capabilities of the “developer” user category; does + not have a dedicated flag internally within Fossil. Mnemonic: + developer. + | +
| w | +WrTkt | ++ Edit existing tickets. Granting this capability also grants RdTkt, ApndTkt, and + NewTkt. Mnemonic: write to ticket. + | +
| x | +Private | ++ Push or pull private branches. + Mnemonic: exclusivity; “x” connotes unknown material in + many Western languages due to its traditional + use in mathematics. + | +
| y | +WrUnver | ++ Push unversioned content. Mnemonic: + yield, sense + 4: “hand over.” + | +
| z | +Zip | ++ Pull archives of particular repository versions via /zip, /tarball, and /sqlar URLs. This is an + expensive capability to grant, because creating such archives can + put a large load on a Fossil server which + you may then need to manage. + Mnemonic: zip file download. + | +
| 2 | +RdForum | ++ Read forum posts by other users. + Mnemonic: from thee 2 me. + | +
| 3 | +WrForum | ++ Create new forum threads, reply to threads created by others, and + edit one’s own posts. New posts are held for moderation and do + not appear in repo clones or syncs. Granting this capability also + grants RdForum. Mnemonic: post for + 3 audiences: me, the mods, and the Man. + | +
| 4 | +WrTForum | ++ Extends WrForum, bypassing the moderation + and sync restrictions. Mnemonic: post 4 immediate release. + | +
| 5 | +ModForum | ++ Moderate forum posts. + Granting this capability also grants WrTForum and RdForum, + so a user with this cap never has to moderate their own posts. + Mnemonic: “May I have 5 seconds of your time, honored + Gatekeeper?” + | +
| 6 | +AdminForum | ++ Users with this capability see a checkbox on unmoderated 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 WrTForum capability to that post’s author. + There is currently no UI for a user with this cap to + revoke trust from a user once it is granted; only Admin and Setup can + currently revoke granted caps. Granting this capability also + grants ModForum and those it in turn + grants. Mnemonic: “I’m 6 [sick] of hitting Approve on your + posts!” + | +
| 7 | +EmailAlert | ++ User can sign up for email alerts. + Mnemonic: Seven can + wait, I’ve got email to read now. + | +
| A | +Announce | ++ Send email announcements to users signed up to + receive them. Mnemonic: announce. + | +
| D | +Debug | ++ Enable debugging features. Mnemonic: debug. + | +
Back to Administering User +Capabilities
Index: www/cgi.wiki ================================================================== --- www/cgi.wiki +++ www/cgi.wiki @@ -67,11 +67,11 @@ of the HTTP request does not correspond to any Fossil repository, then the request redirects to URL.Index: www/defcsp.md ================================================================== --- www/defcsp.md +++ www/defcsp.md @@ -177,11 +177,11 @@ CGI in the `FOSSIL_NONCE` environment variable, which it can then use in `