Fossil SCM
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.
Commit
ee901c7be39e4b999eb903cb7127d11c8ee03eae16dacbd458e916f05312070c
Parent
689f7683b694a0b…
2 files changed
+127
-57
+9
-82
+127
-57
| --- www/admin-v-setup.md | ||
| +++ www/admin-v-setup.md | ||
| @@ -1,6 +1,6 @@ | ||
| 1 | -# The Differences Between the Setup and Admin User Capabilities | |
| 1 | +# Differences Between Setup and Admin User Capabilities | |
| 2 | 2 | |
| 3 | 3 | This document explains the distinction between [Setup users][su] and |
| 4 | 4 | [Admin users][au]. For other information about use types, see: |
| 5 | 5 | |
| 6 | 6 | * [Administering User Capabilities](./capabilities.md) |
| @@ -7,14 +7,14 @@ | ||
| 7 | 7 | * [How Moderation Works](./forum.wiki#moderation) |
| 8 | 8 | * [Users vs Subscribers](./alerts.md#uvs) |
| 9 | 9 | * [Defense Against Spiders](./antibot.wiki) |
| 10 | 10 | |
| 11 | 11 | [au]: ./capabilities.md#a |
| 12 | -[su]: ./capabilities.md#apsu | |
| 12 | +[su]: ./capabilities.md#s | |
| 13 | 13 | |
| 14 | 14 | |
| 15 | -## Philosophical Core | |
| 15 | +## <a name="philosophy"></a>Philosophical Core | |
| 16 | 16 | |
| 17 | 17 | The Setup user "owns" the Fossil repository and may delegate a subset of |
| 18 | 18 | that power to one or more Admin users. |
| 19 | 19 | |
| 20 | 20 | The Setup user can grant Admin capability and take it away, but Admin |
| @@ -26,71 +26,85 @@ | ||
| 26 | 26 | It is common for the Setup user to have administrative control over the |
| 27 | 27 | host system running the Fossil repository, whereas it makes no sense for |
| 28 | 28 | Admin users to have that ability. If an Admin-only user had `root` |
| 29 | 29 | access on a Linux box running the Fossil instance they are an Admin on, |
| 30 | 30 | they could elevate their capability to Setup in several ways. (The |
| 31 | -`fossil admin` command, the `fossil sql` command, editing the repository | |
| 31 | +`fossil user` command, the `fossil sql` command, editing the repository | |
| 32 | 32 | DB file directly, etc.) Therefore, if you wish to grant someone |
| 33 | 33 | Setup-like capability on a Fossil repository but you're unwilling to |
| 34 | -give them full control over the host system, you probably want to grant | |
| 34 | +give them a login on the host system, you probably want to grant | |
| 35 | 35 | them Admin capability instead. |
| 36 | 36 | |
| 37 | 37 | Admin power is delegated from Setup. When a Setup user grants Admin |
| 38 | 38 | capability, it is an expression of trust in that user's judgement. |
| 39 | 39 | |
| 40 | 40 | Admin-only users must not fight against the policies of the Setup user. |
| 41 | 41 | Such a rift would be just cause for the Setup user to strip the Admin |
| 42 | -user's capabilities, for the ex-Admin to fork the repository, and for | |
| 43 | -both to go their separate ways. | |
| 42 | +user's capabilities. This may then create a fork in the project’s | |
| 43 | +development effort as the ex-Admin takes their clone and stands it up | |
| 44 | +elsewhere, so they may become that fork’s Setup user. | |
| 44 | 45 | |
| 45 | 46 | A useful rule of thumb here is that Admin users should only change |
| 46 | 47 | things that the Setup user has not changed from the stock configuration. |
| 47 | 48 | In this way, an Admin-only user can avoid overriding the Setup user's |
| 48 | 49 | choices. |
| 49 | 50 | |
| 50 | -This rule is not enforced by the Fossil permission system for a couple | |
| 51 | -of reasons: | |
| 52 | - | |
| 53 | -1. There are too many exceptions to encode in the remaining | |
| 54 | - [user capability bits][ucap]. As of this writing, we've already | |
| 55 | - assigned meaning to all of the lowercase letters, most of the | |
| 56 | - decimal digits, and a few of the uppercase letters. We'd rather not | |
| 57 | - resort to punctuation and Unicode to express future extensions to | |
| 58 | - the policy choices Fossil offers its power users. | |
| 59 | - | |
| 60 | -2. Even if we had enough suitable printable ASCII characters left to | |
| 61 | - assign one to every imaginable purpose and policy, we want to keep | |
| 62 | - the number of exceptions manageable. Consider the Admin → Settings | |
| 63 | - page, which is currently restricted to Setup users only: you might | |
| 64 | - imagine breaking this up into several subsets so that some subsets | |
| 65 | - are available to non-Setup users, each controlled by a user | |
| 66 | - capability bit. Is that a good idea? Maybe, but it should be done | |
| 67 | - only after due consideration. It would definitely be wrong to assign | |
| 68 | - a user capability bit to *each* setting on that page. | |
| 69 | - | |
| 70 | -Let's consider a concrete application of this rule: Admin → Skins. | |
| 71 | -Fossil grants Admin-only users full access to this page so that the | |
| 72 | -Admins can maintain and extend the skin as the repository evolves, not | |
| 73 | -so Admins can switch the entire skin to another without consulting with | |
| 74 | -the Setup user first. If, during a forum discussion one of the mere | |
| 75 | -users notices a problem with the skin, an Admin-only user should feel | |
| 76 | -free to correct this without bothering the Setup user. | |
| 77 | - | |
| 78 | -Another common case is that the Setup user upgrades Fossil on the server | |
| 79 | -but forgets to merge the upstream skin changes: Admin users are | |
| 80 | -entrusted to do that work on behalf of the Setup user. | |
| 81 | - | |
| 82 | -[ucap]: ./capabilities.md#ref | |
| 83 | - | |
| 84 | - | |
| 85 | -## Capability Groups | |
| 51 | +You can also look at the role of Admin from the other direction, up | |
| 52 | +through the [user power hierarchy][ucap] rather than down from Setup. An | |
| 53 | +Admin user is usually a “super-developer” role, given full control over | |
| 54 | +the repository’s managed content: versioned artifacts in [the block | |
| 55 | +chain][bc], [unversioned content][uv], forum posts, wiki articles, | |
| 56 | +tickets, etc. | |
| 57 | + | |
| 58 | +We’ll explore these distinctions in the rest of this document. | |
| 59 | + | |
| 60 | +[bc]: ./blockchain.md | |
| 61 | +[ucap]: ./capabilities.md#ucap | |
| 62 | +[uv]: ./unvers.wiki | |
| 63 | + | |
| 64 | + | |
| 65 | +## <a name="binary"></a>No Granularity | |
| 66 | + | |
| 67 | +Fossil doesn’t make any distinction between these two user types beyond | |
| 68 | +this binary choice: Setup or Admin. | |
| 69 | + | |
| 70 | +A few features of Fossil are broken down so that only part of the | |
| 71 | +feature is accessible to Admin, with the rest left only to Setup users, | |
| 72 | +but for the most part each feature affected by this distinction is | |
| 73 | +either Admin + Setup or Setup-only. | |
| 74 | + | |
| 75 | +We could add more capability letters to break down individual | |
| 76 | +sub-features, but we’d run out of ASCII alphanumerics pretty quickly, | |
| 77 | +and we might even run out of ASCII punctuation and symbols. Then would | |
| 78 | +we need to shift to Unicode? | |
| 79 | + | |
| 80 | +Consider the Admin → Settings page, which is currently restricted to | |
| 81 | +Setup users only: you might imagine breaking this up into several | |
| 82 | +subsets so that some settings can be changed by Admin users. Is that a | |
| 83 | +good idea? Maybe, but it should be done only after due consideration. It | |
| 84 | +would definitely be wrong to assign a user capability bit to *each* | |
| 85 | +setting on that page. | |
| 86 | + | |
| 87 | +Now consider the opposite sort of case, Admin → Skins. Fossil grants | |
| 88 | +Admin users full access to this page so that the Admins can maintain and | |
| 89 | +extend the skin as the repository evolves, not so Admins can switch the | |
| 90 | +entire skin to another without consulting with the Setup user first. How | |
| 91 | +would Fossil decide, using user capabilities only, which skin changes | |
| 92 | +the Admin user is allowed to do, and which must be left to Setup? Do we | |
| 93 | +assign a separate capability letter to each step in `/setup_skin`? Do we | |
| 94 | +assign one more each to the five sections of a skin? (Header, Footer, | |
| 95 | +CSS, JavaScript, and Details.) It quickly becomes unmanageable. | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | +## <a name="capgroups"></a>Capability Groups | |
| 86 | 100 | |
| 87 | 101 | We can break up the set of powers the Admin user capability grants into |
| 88 | 102 | several groups, then defend each group as a coherent whole. |
| 89 | 103 | |
| 90 | 104 | |
| 91 | -### Security | |
| 105 | +### <a name="security"></a>Security | |
| 92 | 106 | |
| 93 | 107 | While establishing the Fossil repository's security policy is a task for |
| 94 | 108 | the Setup user, *maintaining* that policy is something that Fossil |
| 95 | 109 | allows a Setup user to delegate to trustworthy users via the Admin user |
| 96 | 110 | capability: |
| @@ -123,11 +137,11 @@ | ||
| 123 | 137 | Admin-only users have these abilities. Think of a large IT organization: |
| 124 | 138 | if the CIO hires a [tiger team][tt] to test the company's internal IT |
| 125 | 139 | defenses, the line grunts fix the reported problems, not the CIO. |
| 126 | 140 | |
| 127 | 141 | |
| 128 | -### Administrivia | |
| 142 | +### <a name="administrivia"></a>Administrivia | |
| 129 | 143 | |
| 130 | 144 | It is perfectly fine for a Fossil repository to only have Setup users, |
| 131 | 145 | no Admin users. The smaller the repository, the more likely the |
| 132 | 146 | repository has no Admin-only users. If the Setup user neither needs nor |
| 133 | 147 | wants to grant Admin power to others, there is no requirement in Fossil |
| @@ -166,11 +180,11 @@ | ||
| 166 | 180 | |
| 167 | 181 | * **Status**: Although the Fossil `/stat` page is visible to every |
| 168 | 182 | user with Read capability, there are several additional things this |
| 169 | 183 | page gives access to when a user also has the Admin capability: |
| 170 | 184 | |
| 171 | - * <p>[Email alerts](./alerts.md) and [backoffice](./backoffice.md) | |
| 185 | + * <p>[Email alerts][ale] and [backoffice](./backoffice.md) | |
| 172 | 186 | status. Admin-only users cannot modify the email alerts setup, |
| 173 | 187 | but they can see some details about its configuration and |
| 174 | 188 | current status.</p> |
| 175 | 189 | |
| 176 | 190 | * <p>The `/urllist` page, which is a read-only page showing the |
| @@ -189,12 +203,14 @@ | ||
| 189 | 203 | * <p>Web cache status, environment, and logging: more |
| 190 | 204 | administrivia meant to help the Admin debug problems.</p> |
| 191 | 205 | |
| 192 | 206 | * **Configure search** |
| 193 | 207 | |
| 208 | +[ale]: ./alerts.md | |
| 209 | + | |
| 194 | 210 | |
| 195 | -### Cosmetics | |
| 211 | +### <a name="cosmetics"></a>Cosmetics | |
| 196 | 212 | |
| 197 | 213 | While the Setup user is responsible for setting up the initial "look" of |
| 198 | 214 | a Fossil repository, the Setup user entrusts Admin users with |
| 199 | 215 | *maintaining* that look. An Admin-only user therefore has the following |
| 200 | 216 | special abilities: |
| @@ -213,11 +229,11 @@ | ||
| 213 | 229 | possibly even the back-end finances of a project. This is why we began |
| 214 | 230 | this document with a philosophical discussion: if you cannot entrust a |
| 215 | 231 | user with these powers, you should not grant that user Admin capability. |
| 216 | 232 | |
| 217 | 233 | |
| 218 | -## Clones and Backups | |
| 234 | +## <a name="clones"></a>Clones and Backups | |
| 219 | 235 | |
| 220 | 236 | Keep in mind that Fossil is a *distributed* version control system, |
| 221 | 237 | which means that a user known to Fossil might have Setup capability on |
| 222 | 238 | one repository but be a mere "user" on one of its clones. The most |
| 223 | 239 | common case is that when you clone a repository, even anonymously, you |
| @@ -234,30 +250,56 @@ | ||
| 234 | 250 | interchangeable clones. This is useful not only to guard against rogue |
| 235 | 251 | Admin-only users, it is a useful element of a load balancing and |
| 236 | 252 | failover system. |
| 237 | 253 | |
| 238 | 254 | |
| 239 | -## Setup-Only Features | |
| 255 | +## <a name="apsu"></a>The All-Powerful Setup User | |
| 256 | + | |
| 257 | +Setup users can use every feature of the Fossil UI. If Fossil can do a | |
| 258 | +thing, a Setup user on that repo can make Fossil do it. | |
| 259 | + | |
| 260 | +Setup users can do many things that Admin users cannot: | |
| 261 | + | |
| 262 | +* Use all of the Admin UI features | |
| 263 | +* See record IDs (RIDs) on screens that show them | |
| 264 | +* See the MIME type of attachments on [`/ainfo` pages](/help?cmd=/ainfo) | |
| 265 | +* See a remote repo’s HTTP [cache status](/help?cmd=/cachestat) | |
| 266 | + and [pull cache entries](/help?cmd=/cacheget) | |
| 267 | +* Edit a Setup user’s account! | |
| 268 | + | |
| 269 | +The “Admin” feature of Fossil UI is so-named because Admin users can use | |
| 270 | +about half of its functions, but only Setup can use these pages: | |
| 240 | 271 | |
| 241 | -Some features are now and must always be restricted to Setup users only. | |
| 272 | +* **Access**: This page falls under the [Security](#security) | |
| 273 | + category above, but like Configuration, it's generally something set | |
| 274 | + up once and never touched, so only Setup users should change it. | |
| 242 | 275 | |
| 243 | -* **Configuration**: The Admin → Configuration page nominally falls | |
| 244 | - under Cosmetics above, but it's such a core part of the Fossil | |
| 276 | +* **Configuration**: This page nominally falls | |
| 277 | + under [Cosmetics](#cosmetics) above, but it's such a core part of the Fossil | |
| 245 | 278 | configuration — something every Setup user is expected to fully |
| 246 | 279 | specify on initial repository setup — that we have trouble |
| 247 | 280 | justifying any case where an Admin-only user would have good cause |
| 248 | 281 | to modify any of it. This page is generally set up once and then |
| 249 | 282 | never touched again. |
| 250 | 283 | |
| 251 | -* **Access**: The Admin → Access page falls under the Security | |
| 252 | - category above, but like Configuration, it's generally something set | |
| 253 | - up once and never touched, so only Setup users should change it. | |
| 254 | - | |
| 255 | -* **Login-Group**: Login groups allow one Fossil repository to | |
| 284 | +* **Email-Server**: This is an experimental SMTP server feature which | |
| 285 | + is currently unused in Fossil. Should we get it working, it will | |
| 286 | + likely remain Setup-only, since it will likely be used as a | |
| 287 | + replacement for the platform’s default SMTP server, a powerful | |
| 288 | + position for a piece of software to take. | |
| 289 | + | |
| 290 | +* **Login-Group**: [Login groups][lg] allow one Fossil repository to | |
| 256 | 291 | delegate user access to another. Since an Admin-only user on one |
| 257 | 292 | repo might not have such access to another repo on the same host |
| 258 | 293 | system, this must be a Setup-only task. |
| 294 | + | |
| 295 | +* **Notification**: This is the main UI for setting up integration | |
| 296 | + with a platform’s SMTP service, for use in sending out [email | |
| 297 | + notifications][ale]. Because this screen can set commands to execute | |
| 298 | + on the host, and because finishing the configuration requires a | |
| 299 | + login on the Fossil host system, it is not appropriate to give Admin | |
| 300 | + users access to it. | |
| 259 | 301 | |
| 260 | 302 | * **Settings**: The [repository settings][rs] available via Admin → |
| 261 | 303 | Settings have too wide a range of power to allow modification by |
| 262 | 304 | Admin-only users: |
| 263 | 305 | |
| @@ -303,10 +345,15 @@ | ||
| 303 | 345 | * **SQL**: The Admin → SQL feature allows the Setup user to enter raw |
| 304 | 346 | SQL queries against the Fossil repository via Fossil UI. This not |
| 305 | 347 | only allows arbitrary ability to modify the repository blockchain |
| 306 | 348 | and its backing data tables, it can probably also be used to damage |
| 307 | 349 | the host such as via `PRAGMA temp_store = FILE`. |
| 350 | + | |
| 351 | +* **Tickets**: This section allows input of aribtrary TH1 code that | |
| 352 | + runs on the server, affecting the way the Fossil ticketing system | |
| 353 | + works. The justification in the **TH1** section below therefore | |
| 354 | + applies. | |
| 308 | 355 | |
| 309 | 356 | * **TH1**: The [TH1 language][TH1] is quite restricted relative to the |
| 310 | 357 | Tcl language it descends from, so this author does not believe there |
| 311 | 358 | is a way to damage the Fossil repository or its host via the Admin → |
| 312 | 359 | TH1 feature, which allows execution of arbitrary TH1 code within the |
| @@ -313,12 +360,35 @@ | ||
| 313 | 360 | repository's execution context. Nevertheless, interpreters are a |
| 314 | 361 | well-known source of security problems, so it seems best to restrict |
| 315 | 362 | this feature to Setup-only users as long as we lack a good reason |
| 316 | 363 | for Admin-only users to have access to it. |
| 317 | 364 | |
| 365 | +* **Transfers**: This is for setting up TH1 hooks on various actions, | |
| 366 | + so the justification in the **TH1** section above applies. | |
| 367 | + | |
| 368 | +* **Wiki**: These are mainly cosmetic and usability settings. We might | |
| 369 | + open this up to Admin users in the future. | |
| 370 | + | |
| 371 | +Just remember, [user caps affect Fossil’s web interfaces only][webo]. A | |
| 372 | +user is a Setup user by default on their local clone of a repo, and | |
| 373 | +Fossil’s ability to protect itself against malicious (or even simply | |
| 374 | +incorrect) pushes is limited. Someone with clone and push capability on | |
| 375 | +your repo could clone it, modify their local repo, and then push the | |
| 376 | +changes back to your repo. Be careful who you give that combination of | |
| 377 | +capabilities to! | |
| 378 | + | |
| 379 | +When you run [`fossil ui`][fui], you are the Setup user on that repo | |
| 380 | +through that UI instance, regardless of the capability set defined in | |
| 381 | +the repo’s user table. This is true even if you cloned a remote repo | |
| 382 | +where you do not have Setup caps. This is why `ui` always binds to | |
| 383 | +`localhost` without needing the `--localhost` flag: in this mode, anyone | |
| 384 | +who can connect to that repo’s web UI has full power over that repo. | |
| 318 | 385 | |
| 319 | 386 | [fcp]: https://fossil-scm.org/fossil/help?cmd=configuration |
| 320 | 387 | [forum]: https://fossil-scm.org/forum/ |
| 388 | +[fui]: /help?cmd=ui | |
| 389 | +[lg]: ./capabilities.md#group | |
| 321 | 390 | [rs]: https://www.fossil-scm.org/index.html/doc/trunk/www/settings.wiki |
| 322 | 391 | [sia]: https://fossil-scm.org/fossil/artifact?udc=1&ln=1259-1260&name=0fda31b6683c206a |
| 323 | 392 | [th1]: https://www.fossil-scm.org/index.html/doc/trunk/www/th1.md |
| 324 | 393 | [tt]: https://en.wikipedia.org/wiki/Tiger_team#Security |
| 394 | +[webo]: ./capabilities.md#webonly | |
| 325 | 395 |
| --- www/admin-v-setup.md | |
| +++ www/admin-v-setup.md | |
| @@ -1,6 +1,6 @@ | |
| 1 | # The Differences Between the Setup and Admin User Capabilities |
| 2 | |
| 3 | This document explains the distinction between [Setup users][su] and |
| 4 | [Admin users][au]. For other information about use types, see: |
| 5 | |
| 6 | * [Administering User Capabilities](./capabilities.md) |
| @@ -7,14 +7,14 @@ | |
| 7 | * [How Moderation Works](./forum.wiki#moderation) |
| 8 | * [Users vs Subscribers](./alerts.md#uvs) |
| 9 | * [Defense Against Spiders](./antibot.wiki) |
| 10 | |
| 11 | [au]: ./capabilities.md#a |
| 12 | [su]: ./capabilities.md#apsu |
| 13 | |
| 14 | |
| 15 | ## Philosophical Core |
| 16 | |
| 17 | The Setup user "owns" the Fossil repository and may delegate a subset of |
| 18 | that power to one or more Admin users. |
| 19 | |
| 20 | The Setup user can grant Admin capability and take it away, but Admin |
| @@ -26,71 +26,85 @@ | |
| 26 | It is common for the Setup user to have administrative control over the |
| 27 | host system running the Fossil repository, whereas it makes no sense for |
| 28 | Admin users to have that ability. If an Admin-only user had `root` |
| 29 | access on a Linux box running the Fossil instance they are an Admin on, |
| 30 | they could elevate their capability to Setup in several ways. (The |
| 31 | `fossil admin` command, the `fossil sql` command, editing the repository |
| 32 | DB file directly, etc.) Therefore, if you wish to grant someone |
| 33 | Setup-like capability on a Fossil repository but you're unwilling to |
| 34 | give them full control over the host system, you probably want to grant |
| 35 | them Admin capability instead. |
| 36 | |
| 37 | Admin power is delegated from Setup. When a Setup user grants Admin |
| 38 | capability, it is an expression of trust in that user's judgement. |
| 39 | |
| 40 | Admin-only users must not fight against the policies of the Setup user. |
| 41 | Such a rift would be just cause for the Setup user to strip the Admin |
| 42 | user's capabilities, for the ex-Admin to fork the repository, and for |
| 43 | both to go their separate ways. |
| 44 | |
| 45 | A useful rule of thumb here is that Admin users should only change |
| 46 | things that the Setup user has not changed from the stock configuration. |
| 47 | In this way, an Admin-only user can avoid overriding the Setup user's |
| 48 | choices. |
| 49 | |
| 50 | This rule is not enforced by the Fossil permission system for a couple |
| 51 | of reasons: |
| 52 | |
| 53 | 1. There are too many exceptions to encode in the remaining |
| 54 | [user capability bits][ucap]. As of this writing, we've already |
| 55 | assigned meaning to all of the lowercase letters, most of the |
| 56 | decimal digits, and a few of the uppercase letters. We'd rather not |
| 57 | resort to punctuation and Unicode to express future extensions to |
| 58 | the policy choices Fossil offers its power users. |
| 59 | |
| 60 | 2. Even if we had enough suitable printable ASCII characters left to |
| 61 | assign one to every imaginable purpose and policy, we want to keep |
| 62 | the number of exceptions manageable. Consider the Admin → Settings |
| 63 | page, which is currently restricted to Setup users only: you might |
| 64 | imagine breaking this up into several subsets so that some subsets |
| 65 | are available to non-Setup users, each controlled by a user |
| 66 | capability bit. Is that a good idea? Maybe, but it should be done |
| 67 | only after due consideration. It would definitely be wrong to assign |
| 68 | a user capability bit to *each* setting on that page. |
| 69 | |
| 70 | Let's consider a concrete application of this rule: Admin → Skins. |
| 71 | Fossil grants Admin-only users full access to this page so that the |
| 72 | Admins can maintain and extend the skin as the repository evolves, not |
| 73 | so Admins can switch the entire skin to another without consulting with |
| 74 | the Setup user first. If, during a forum discussion one of the mere |
| 75 | users notices a problem with the skin, an Admin-only user should feel |
| 76 | free to correct this without bothering the Setup user. |
| 77 | |
| 78 | Another common case is that the Setup user upgrades Fossil on the server |
| 79 | but forgets to merge the upstream skin changes: Admin users are |
| 80 | entrusted to do that work on behalf of the Setup user. |
| 81 | |
| 82 | [ucap]: ./capabilities.md#ref |
| 83 | |
| 84 | |
| 85 | ## Capability Groups |
| 86 | |
| 87 | We can break up the set of powers the Admin user capability grants into |
| 88 | several groups, then defend each group as a coherent whole. |
| 89 | |
| 90 | |
| 91 | ### Security |
| 92 | |
| 93 | While establishing the Fossil repository's security policy is a task for |
| 94 | the Setup user, *maintaining* that policy is something that Fossil |
| 95 | allows a Setup user to delegate to trustworthy users via the Admin user |
| 96 | capability: |
| @@ -123,11 +137,11 @@ | |
| 123 | Admin-only users have these abilities. Think of a large IT organization: |
| 124 | if the CIO hires a [tiger team][tt] to test the company's internal IT |
| 125 | defenses, the line grunts fix the reported problems, not the CIO. |
| 126 | |
| 127 | |
| 128 | ### Administrivia |
| 129 | |
| 130 | It is perfectly fine for a Fossil repository to only have Setup users, |
| 131 | no Admin users. The smaller the repository, the more likely the |
| 132 | repository has no Admin-only users. If the Setup user neither needs nor |
| 133 | wants to grant Admin power to others, there is no requirement in Fossil |
| @@ -166,11 +180,11 @@ | |
| 166 | |
| 167 | * **Status**: Although the Fossil `/stat` page is visible to every |
| 168 | user with Read capability, there are several additional things this |
| 169 | page gives access to when a user also has the Admin capability: |
| 170 | |
| 171 | * <p>[Email alerts](./alerts.md) and [backoffice](./backoffice.md) |
| 172 | status. Admin-only users cannot modify the email alerts setup, |
| 173 | but they can see some details about its configuration and |
| 174 | current status.</p> |
| 175 | |
| 176 | * <p>The `/urllist` page, which is a read-only page showing the |
| @@ -189,12 +203,14 @@ | |
| 189 | * <p>Web cache status, environment, and logging: more |
| 190 | administrivia meant to help the Admin debug problems.</p> |
| 191 | |
| 192 | * **Configure search** |
| 193 | |
| 194 | |
| 195 | ### Cosmetics |
| 196 | |
| 197 | While the Setup user is responsible for setting up the initial "look" of |
| 198 | a Fossil repository, the Setup user entrusts Admin users with |
| 199 | *maintaining* that look. An Admin-only user therefore has the following |
| 200 | special abilities: |
| @@ -213,11 +229,11 @@ | |
| 213 | possibly even the back-end finances of a project. This is why we began |
| 214 | this document with a philosophical discussion: if you cannot entrust a |
| 215 | user with these powers, you should not grant that user Admin capability. |
| 216 | |
| 217 | |
| 218 | ## Clones and Backups |
| 219 | |
| 220 | Keep in mind that Fossil is a *distributed* version control system, |
| 221 | which means that a user known to Fossil might have Setup capability on |
| 222 | one repository but be a mere "user" on one of its clones. The most |
| 223 | common case is that when you clone a repository, even anonymously, you |
| @@ -234,30 +250,56 @@ | |
| 234 | interchangeable clones. This is useful not only to guard against rogue |
| 235 | Admin-only users, it is a useful element of a load balancing and |
| 236 | failover system. |
| 237 | |
| 238 | |
| 239 | ## Setup-Only Features |
| 240 | |
| 241 | Some features are now and must always be restricted to Setup users only. |
| 242 | |
| 243 | * **Configuration**: The Admin → Configuration page nominally falls |
| 244 | under Cosmetics above, but it's such a core part of the Fossil |
| 245 | configuration — something every Setup user is expected to fully |
| 246 | specify on initial repository setup — that we have trouble |
| 247 | justifying any case where an Admin-only user would have good cause |
| 248 | to modify any of it. This page is generally set up once and then |
| 249 | never touched again. |
| 250 | |
| 251 | * **Access**: The Admin → Access page falls under the Security |
| 252 | category above, but like Configuration, it's generally something set |
| 253 | up once and never touched, so only Setup users should change it. |
| 254 | |
| 255 | * **Login-Group**: Login groups allow one Fossil repository to |
| 256 | delegate user access to another. Since an Admin-only user on one |
| 257 | repo might not have such access to another repo on the same host |
| 258 | system, this must be a Setup-only task. |
| 259 | |
| 260 | * **Settings**: The [repository settings][rs] available via Admin → |
| 261 | Settings have too wide a range of power to allow modification by |
| 262 | Admin-only users: |
| 263 | |
| @@ -303,10 +345,15 @@ | |
| 303 | * **SQL**: The Admin → SQL feature allows the Setup user to enter raw |
| 304 | SQL queries against the Fossil repository via Fossil UI. This not |
| 305 | only allows arbitrary ability to modify the repository blockchain |
| 306 | and its backing data tables, it can probably also be used to damage |
| 307 | the host such as via `PRAGMA temp_store = FILE`. |
| 308 | |
| 309 | * **TH1**: The [TH1 language][TH1] is quite restricted relative to the |
| 310 | Tcl language it descends from, so this author does not believe there |
| 311 | is a way to damage the Fossil repository or its host via the Admin → |
| 312 | TH1 feature, which allows execution of arbitrary TH1 code within the |
| @@ -313,12 +360,35 @@ | |
| 313 | repository's execution context. Nevertheless, interpreters are a |
| 314 | well-known source of security problems, so it seems best to restrict |
| 315 | this feature to Setup-only users as long as we lack a good reason |
| 316 | for Admin-only users to have access to it. |
| 317 | |
| 318 | |
| 319 | [fcp]: https://fossil-scm.org/fossil/help?cmd=configuration |
| 320 | [forum]: https://fossil-scm.org/forum/ |
| 321 | [rs]: https://www.fossil-scm.org/index.html/doc/trunk/www/settings.wiki |
| 322 | [sia]: https://fossil-scm.org/fossil/artifact?udc=1&ln=1259-1260&name=0fda31b6683c206a |
| 323 | [th1]: https://www.fossil-scm.org/index.html/doc/trunk/www/th1.md |
| 324 | [tt]: https://en.wikipedia.org/wiki/Tiger_team#Security |
| 325 |
| --- www/admin-v-setup.md | |
| +++ www/admin-v-setup.md | |
| @@ -1,6 +1,6 @@ | |
| 1 | # Differences Between Setup and Admin User Capabilities |
| 2 | |
| 3 | This document explains the distinction between [Setup users][su] and |
| 4 | [Admin users][au]. For other information about use types, see: |
| 5 | |
| 6 | * [Administering User Capabilities](./capabilities.md) |
| @@ -7,14 +7,14 @@ | |
| 7 | * [How Moderation Works](./forum.wiki#moderation) |
| 8 | * [Users vs Subscribers](./alerts.md#uvs) |
| 9 | * [Defense Against Spiders](./antibot.wiki) |
| 10 | |
| 11 | [au]: ./capabilities.md#a |
| 12 | [su]: ./capabilities.md#s |
| 13 | |
| 14 | |
| 15 | ## <a name="philosophy"></a>Philosophical Core |
| 16 | |
| 17 | The Setup user "owns" the Fossil repository and may delegate a subset of |
| 18 | that power to one or more Admin users. |
| 19 | |
| 20 | The Setup user can grant Admin capability and take it away, but Admin |
| @@ -26,71 +26,85 @@ | |
| 26 | It is common for the Setup user to have administrative control over the |
| 27 | host system running the Fossil repository, whereas it makes no sense for |
| 28 | Admin users to have that ability. If an Admin-only user had `root` |
| 29 | access on a Linux box running the Fossil instance they are an Admin on, |
| 30 | they could elevate their capability to Setup in several ways. (The |
| 31 | `fossil user` command, the `fossil sql` command, editing the repository |
| 32 | DB file directly, etc.) Therefore, if you wish to grant someone |
| 33 | Setup-like capability on a Fossil repository but you're unwilling to |
| 34 | give them a login on the host system, you probably want to grant |
| 35 | them Admin capability instead. |
| 36 | |
| 37 | Admin power is delegated from Setup. When a Setup user grants Admin |
| 38 | capability, it is an expression of trust in that user's judgement. |
| 39 | |
| 40 | Admin-only users must not fight against the policies of the Setup user. |
| 41 | Such a rift would be just cause for the Setup user to strip the Admin |
| 42 | user's capabilities. This may then create a fork in the project’s |
| 43 | development effort as the ex-Admin takes their clone and stands it up |
| 44 | elsewhere, so they may become that fork’s Setup user. |
| 45 | |
| 46 | A useful rule of thumb here is that Admin users should only change |
| 47 | things that the Setup user has not changed from the stock configuration. |
| 48 | In this way, an Admin-only user can avoid overriding the Setup user's |
| 49 | choices. |
| 50 | |
| 51 | You can also look at the role of Admin from the other direction, up |
| 52 | through the [user power hierarchy][ucap] rather than down from Setup. An |
| 53 | Admin user is usually a “super-developer” role, given full control over |
| 54 | the repository’s managed content: versioned artifacts in [the block |
| 55 | chain][bc], [unversioned content][uv], forum posts, wiki articles, |
| 56 | tickets, etc. |
| 57 | |
| 58 | We’ll explore these distinctions in the rest of this document. |
| 59 | |
| 60 | [bc]: ./blockchain.md |
| 61 | [ucap]: ./capabilities.md#ucap |
| 62 | [uv]: ./unvers.wiki |
| 63 | |
| 64 | |
| 65 | ## <a name="binary"></a>No Granularity |
| 66 | |
| 67 | Fossil doesn’t make any distinction between these two user types beyond |
| 68 | this binary choice: Setup or Admin. |
| 69 | |
| 70 | A few features of Fossil are broken down so that only part of the |
| 71 | feature is accessible to Admin, with the rest left only to Setup users, |
| 72 | but for the most part each feature affected by this distinction is |
| 73 | either Admin + Setup or Setup-only. |
| 74 | |
| 75 | We could add more capability letters to break down individual |
| 76 | sub-features, but we’d run out of ASCII alphanumerics pretty quickly, |
| 77 | and we might even run out of ASCII punctuation and symbols. Then would |
| 78 | we need to shift to Unicode? |
| 79 | |
| 80 | Consider the Admin → Settings page, which is currently restricted to |
| 81 | Setup users only: you might imagine breaking this up into several |
| 82 | subsets so that some settings can be changed by Admin users. Is that a |
| 83 | good idea? Maybe, but it should be done only after due consideration. It |
| 84 | would definitely be wrong to assign a user capability bit to *each* |
| 85 | setting on that page. |
| 86 | |
| 87 | Now consider the opposite sort of case, Admin → Skins. Fossil grants |
| 88 | Admin users full access to this page so that the Admins can maintain and |
| 89 | extend the skin as the repository evolves, not so Admins can switch the |
| 90 | entire skin to another without consulting with the Setup user first. How |
| 91 | would Fossil decide, using user capabilities only, which skin changes |
| 92 | the Admin user is allowed to do, and which must be left to Setup? Do we |
| 93 | assign a separate capability letter to each step in `/setup_skin`? Do we |
| 94 | assign one more each to the five sections of a skin? (Header, Footer, |
| 95 | CSS, JavaScript, and Details.) It quickly becomes unmanageable. |
| 96 | |
| 97 | |
| 98 | |
| 99 | ## <a name="capgroups"></a>Capability Groups |
| 100 | |
| 101 | We can break up the set of powers the Admin user capability grants into |
| 102 | several groups, then defend each group as a coherent whole. |
| 103 | |
| 104 | |
| 105 | ### <a name="security"></a>Security |
| 106 | |
| 107 | While establishing the Fossil repository's security policy is a task for |
| 108 | the Setup user, *maintaining* that policy is something that Fossil |
| 109 | allows a Setup user to delegate to trustworthy users via the Admin user |
| 110 | capability: |
| @@ -123,11 +137,11 @@ | |
| 137 | Admin-only users have these abilities. Think of a large IT organization: |
| 138 | if the CIO hires a [tiger team][tt] to test the company's internal IT |
| 139 | defenses, the line grunts fix the reported problems, not the CIO. |
| 140 | |
| 141 | |
| 142 | ### <a name="administrivia"></a>Administrivia |
| 143 | |
| 144 | It is perfectly fine for a Fossil repository to only have Setup users, |
| 145 | no Admin users. The smaller the repository, the more likely the |
| 146 | repository has no Admin-only users. If the Setup user neither needs nor |
| 147 | wants to grant Admin power to others, there is no requirement in Fossil |
| @@ -166,11 +180,11 @@ | |
| 180 | |
| 181 | * **Status**: Although the Fossil `/stat` page is visible to every |
| 182 | user with Read capability, there are several additional things this |
| 183 | page gives access to when a user also has the Admin capability: |
| 184 | |
| 185 | * <p>[Email alerts][ale] and [backoffice](./backoffice.md) |
| 186 | status. Admin-only users cannot modify the email alerts setup, |
| 187 | but they can see some details about its configuration and |
| 188 | current status.</p> |
| 189 | |
| 190 | * <p>The `/urllist` page, which is a read-only page showing the |
| @@ -189,12 +203,14 @@ | |
| 203 | * <p>Web cache status, environment, and logging: more |
| 204 | administrivia meant to help the Admin debug problems.</p> |
| 205 | |
| 206 | * **Configure search** |
| 207 | |
| 208 | [ale]: ./alerts.md |
| 209 | |
| 210 | |
| 211 | ### <a name="cosmetics"></a>Cosmetics |
| 212 | |
| 213 | While the Setup user is responsible for setting up the initial "look" of |
| 214 | a Fossil repository, the Setup user entrusts Admin users with |
| 215 | *maintaining* that look. An Admin-only user therefore has the following |
| 216 | special abilities: |
| @@ -213,11 +229,11 @@ | |
| 229 | possibly even the back-end finances of a project. This is why we began |
| 230 | this document with a philosophical discussion: if you cannot entrust a |
| 231 | user with these powers, you should not grant that user Admin capability. |
| 232 | |
| 233 | |
| 234 | ## <a name="clones"></a>Clones and Backups |
| 235 | |
| 236 | Keep in mind that Fossil is a *distributed* version control system, |
| 237 | which means that a user known to Fossil might have Setup capability on |
| 238 | one repository but be a mere "user" on one of its clones. The most |
| 239 | common case is that when you clone a repository, even anonymously, you |
| @@ -234,30 +250,56 @@ | |
| 250 | interchangeable clones. This is useful not only to guard against rogue |
| 251 | Admin-only users, it is a useful element of a load balancing and |
| 252 | failover system. |
| 253 | |
| 254 | |
| 255 | ## <a name="apsu"></a>The All-Powerful Setup User |
| 256 | |
| 257 | Setup users can use every feature of the Fossil UI. If Fossil can do a |
| 258 | thing, a Setup user on that repo can make Fossil do it. |
| 259 | |
| 260 | Setup users can do many things that Admin users cannot: |
| 261 | |
| 262 | * Use all of the Admin UI features |
| 263 | * See record IDs (RIDs) on screens that show them |
| 264 | * See the MIME type of attachments on [`/ainfo` pages](/help?cmd=/ainfo) |
| 265 | * See a remote repo’s HTTP [cache status](/help?cmd=/cachestat) |
| 266 | and [pull cache entries](/help?cmd=/cacheget) |
| 267 | * Edit a Setup user’s account! |
| 268 | |
| 269 | The “Admin” feature of Fossil UI is so-named because Admin users can use |
| 270 | about half of its functions, but only Setup can use these pages: |
| 271 | |
| 272 | * **Access**: This page falls under the [Security](#security) |
| 273 | category above, but like Configuration, it's generally something set |
| 274 | up once and never touched, so only Setup users should change it. |
| 275 | |
| 276 | * **Configuration**: This page nominally falls |
| 277 | under [Cosmetics](#cosmetics) above, but it's such a core part of the Fossil |
| 278 | configuration — something every Setup user is expected to fully |
| 279 | specify on initial repository setup — that we have trouble |
| 280 | justifying any case where an Admin-only user would have good cause |
| 281 | to modify any of it. This page is generally set up once and then |
| 282 | never touched again. |
| 283 | |
| 284 | * **Email-Server**: This is an experimental SMTP server feature which |
| 285 | is currently unused in Fossil. Should we get it working, it will |
| 286 | likely remain Setup-only, since it will likely be used as a |
| 287 | replacement for the platform’s default SMTP server, a powerful |
| 288 | position for a piece of software to take. |
| 289 | |
| 290 | * **Login-Group**: [Login groups][lg] allow one Fossil repository to |
| 291 | delegate user access to another. Since an Admin-only user on one |
| 292 | repo might not have such access to another repo on the same host |
| 293 | system, this must be a Setup-only task. |
| 294 | |
| 295 | * **Notification**: This is the main UI for setting up integration |
| 296 | with a platform’s SMTP service, for use in sending out [email |
| 297 | notifications][ale]. Because this screen can set commands to execute |
| 298 | on the host, and because finishing the configuration requires a |
| 299 | login on the Fossil host system, it is not appropriate to give Admin |
| 300 | users access to it. |
| 301 | |
| 302 | * **Settings**: The [repository settings][rs] available via Admin → |
| 303 | Settings have too wide a range of power to allow modification by |
| 304 | Admin-only users: |
| 305 | |
| @@ -303,10 +345,15 @@ | |
| 345 | * **SQL**: The Admin → SQL feature allows the Setup user to enter raw |
| 346 | SQL queries against the Fossil repository via Fossil UI. This not |
| 347 | only allows arbitrary ability to modify the repository blockchain |
| 348 | and its backing data tables, it can probably also be used to damage |
| 349 | the host such as via `PRAGMA temp_store = FILE`. |
| 350 | |
| 351 | * **Tickets**: This section allows input of aribtrary TH1 code that |
| 352 | runs on the server, affecting the way the Fossil ticketing system |
| 353 | works. The justification in the **TH1** section below therefore |
| 354 | applies. |
| 355 | |
| 356 | * **TH1**: The [TH1 language][TH1] is quite restricted relative to the |
| 357 | Tcl language it descends from, so this author does not believe there |
| 358 | is a way to damage the Fossil repository or its host via the Admin → |
| 359 | TH1 feature, which allows execution of arbitrary TH1 code within the |
| @@ -313,12 +360,35 @@ | |
| 360 | repository's execution context. Nevertheless, interpreters are a |
| 361 | well-known source of security problems, so it seems best to restrict |
| 362 | this feature to Setup-only users as long as we lack a good reason |
| 363 | for Admin-only users to have access to it. |
| 364 | |
| 365 | * **Transfers**: This is for setting up TH1 hooks on various actions, |
| 366 | so the justification in the **TH1** section above applies. |
| 367 | |
| 368 | * **Wiki**: These are mainly cosmetic and usability settings. We might |
| 369 | open this up to Admin users in the future. |
| 370 | |
| 371 | Just remember, [user caps affect Fossil’s web interfaces only][webo]. A |
| 372 | user is a Setup user by default on their local clone of a repo, and |
| 373 | Fossil’s ability to protect itself against malicious (or even simply |
| 374 | incorrect) pushes is limited. Someone with clone and push capability on |
| 375 | your repo could clone it, modify their local repo, and then push the |
| 376 | changes back to your repo. Be careful who you give that combination of |
| 377 | capabilities to! |
| 378 | |
| 379 | When you run [`fossil ui`][fui], you are the Setup user on that repo |
| 380 | through that UI instance, regardless of the capability set defined in |
| 381 | the repo’s user table. This is true even if you cloned a remote repo |
| 382 | where you do not have Setup caps. This is why `ui` always binds to |
| 383 | `localhost` without needing the `--localhost` flag: in this mode, anyone |
| 384 | who can connect to that repo’s web UI has full power over that repo. |
| 385 | |
| 386 | [fcp]: https://fossil-scm.org/fossil/help?cmd=configuration |
| 387 | [forum]: https://fossil-scm.org/forum/ |
| 388 | [fui]: /help?cmd=ui |
| 389 | [lg]: ./capabilities.md#group |
| 390 | [rs]: https://www.fossil-scm.org/index.html/doc/trunk/www/settings.wiki |
| 391 | [sia]: https://fossil-scm.org/fossil/artifact?udc=1&ln=1259-1260&name=0fda31b6683c206a |
| 392 | [th1]: https://www.fossil-scm.org/index.html/doc/trunk/www/th1.md |
| 393 | [tt]: https://en.wikipedia.org/wiki/Tiger_team#Security |
| 394 | [webo]: ./capabilities.md#webonly |
| 395 |
+9
-82
| --- www/capabilities.md | ||
| +++ www/capabilities.md | ||
| @@ -88,11 +88,11 @@ | ||
| 88 | 88 | When we bring the individual user capabilities into it, the complete |
| 89 | 89 | expression of the way Fossil implements user power becomes: |
| 90 | 90 | |
| 91 | 91 | > *setup* ≥ *admin* ≥ *moderator* ≥ *(developer* ∨ *reader)* ≥ *[subscriber]* ≥ *anonymous* ≥ *nobody* |
| 92 | 92 | |
| 93 | -The two additions at the top are clear: [setup is all-powerful](#apsu), | |
| 93 | +The two additions at the top are clear: [setup is all-powerful][apsu], | |
| 94 | 94 | and admin users are [subordinate to the setup user(s)](#a). Both are |
| 95 | 95 | superior to all other users. |
| 96 | 96 | |
| 97 | 97 | The moderator insertion could go anywhere from where it’s shown now down |
| 98 | 98 | to above the “anonymous” level, depending on what other caps you give to |
| @@ -107,18 +107,20 @@ | ||
| 107 | 107 | purely to [receive email alerts and announcements](#7). Users with |
| 108 | 108 | additional caps can also be subscribers, but not all users *are* in fact |
| 109 | 109 | subscribers, which is why we show it in square brackets. (See [Users vs |
| 110 | 110 | Subscribers](./alerts.md#uvs).) |
| 111 | 111 | |
| 112 | +[apsu]: ./admin-v-setup.md#apsu | |
| 113 | + | |
| 112 | 114 | |
| 113 | 115 | ## <a name="new"></a>New Repository Defaults |
| 114 | 116 | |
| 115 | 117 | When you create a new repository, Fossil creates only one user account |
| 116 | 118 | named after your OS user name [by default](#defuser). |
| 117 | 119 | |
| 118 | 120 | Fossil gives the initial repository user the [all-powerful Setup |
| 119 | -capability](#apsu). | |
| 121 | +capability][apsu]. | |
| 120 | 122 | |
| 121 | 123 | Users who visit a [served repository][svr] without logging in get the |
| 122 | 124 | “nobody” user category’s caps which default to |
| 123 | 125 | **[g](#g)[j](#j)[o](#o)[r](#r)[z](#z)**: clone the repo, read the wiki, |
| 124 | 126 | check-out files via the web UI, view tickets, and pull version archives. |
| @@ -161,11 +163,11 @@ | ||
| 161 | 163 | |
| 162 | 164 | Beware: Fossil does not reassign the capabilities these users had to |
| 163 | 165 | other users or to the “reader” or “developer” user category! All users |
| 164 | 166 | except those with Setup capability will lose all capabilities they |
| 165 | 167 | inherited from “nobody” and “anonymous” categories. Setup is the [lone |
| 166 | -exception](#apsu). | |
| 168 | +exception][apsu]. | |
| 167 | 169 | |
| 168 | 170 | If you will have non-Setup users in your private repo, you should parcel |
| 169 | 171 | out some subset of the capability set the “nobody” and “anonymous” |
| 170 | 172 | categories had to other categories or to individual users first. |
| 171 | 173 | |
| @@ -279,11 +281,11 @@ | ||
| 279 | 281 | local clone, where file system permissions are all that matter, but then |
| 280 | 282 | upon sync, the situation is effectively the same as when the parent repo |
| 281 | 283 | is on the local file system. If you can log into the remote system over |
| 282 | 284 | SSH and that user has the necessary file system permissions on that |
| 283 | 285 | remote repo DB file, your user is effectively the [all-powerful Setup |
| 284 | -user](#apsu) on both sides of the SSH connection. | |
| 286 | +user][apsu] on both sides of the SSH connection. | |
| 285 | 287 | |
| 286 | 288 | Fossil reuses the HTTP-based [sync protocol][sp] in both cases above, |
| 287 | 289 | tunnelling HTTP through an OS pipe or through SSH (FIXME?), but all of |
| 288 | 290 | the user cap checks in Fossil are on its web interfaces only. |
| 289 | 291 | |
| @@ -292,38 +294,10 @@ | ||
| 292 | 294 | |
| 293 | 295 | [japi]: https://docs.google.com/document/d/1fXViveNhDbiXgCuE7QDXQOKeFzf2qNUkBEgiUvoqFN4/view#heading=h.6k0k5plm18p1 |
| 294 | 296 | [sp]: ./sync.wiki |
| 295 | 297 | [wp]: /help#webpages |
| 296 | 298 | |
| 297 | - | |
| 298 | -## <a name="apsu"></a>The All-Powerful Setup User | |
| 299 | - | |
| 300 | -A user with [Setup capability, **s**](#s) needs no other user | |
| 301 | -capabliities, because its scope of its power is hard-coded in the Fossil | |
| 302 | -C source. You can take all capabilities away from all of the user | |
| 303 | -categories so that the Setup user inherits no capabilities from them, | |
| 304 | -yet the Setup user will still be able to use every feature of the Fossil | |
| 305 | -web user interface. | |
| 306 | - | |
| 307 | -Another way to look at it is that the setup user is a superset of all | |
| 308 | -other capabilities, even [Admin capability, **a**](#a). This is | |
| 309 | -literally how it’s implemented in the code: enabling setup capability on | |
| 310 | -a user turns on all of the flags controlled by all of the [other | |
| 311 | -capability characters](#ref). | |
| 312 | - | |
| 313 | -When you run [`fossil ui`][fui], you are effectively given setup | |
| 314 | -capability on that repo through that UI instance, regardless of the | |
| 315 | -capability set defined in the repo’s user table. This is why `ui` always | |
| 316 | -binds to `localhost` without needing the `--localhost` flag: in this | |
| 317 | -mode, anyone who can connect to that repo’s web UI has full power over | |
| 318 | -that repo. | |
| 319 | - | |
| 320 | -See the [Admin vs Setup article][avs] for a deeper treatment on the | |
| 321 | -differences between these two related capability sets. | |
| 322 | - | |
| 323 | -[fui]: /help?cmd=ui | |
| 324 | - | |
| 325 | 299 | |
| 326 | 300 | ## <a name="ref"></a>Capability Reference |
| 327 | 301 | |
| 328 | 302 | This section documents each currently-defined user capability character |
| 329 | 303 | in more detail than the brief summary on the [user capability “key” |
| @@ -334,38 +308,12 @@ | ||
| 334 | 308 | The [mnemonics][mn] given here vary from obviously-correct to *post |
| 335 | 309 | facto* rationalizations to the outright fanciful. To [some |
| 336 | 310 | extent](#choices), this is unavoidable. |
| 337 | 311 | |
| 338 | 312 | * <a name="a"></a>**a (Admin)** — Admin users have *all* of the capabilities |
| 339 | - below except for [setup](#s): they can create new users, change user | |
| 340 | - capability assignments, and use about half of the functions on the | |
| 341 | - Admin screen in Fossil UI. (And that is why that screen is now | |
| 342 | - called “Admin,” not “Setup,” as it was in old versions of Fossil!) | |
| 343 | - | |
| 344 | - There are a couple of ways to view the role of Fossil | |
| 345 | - administrators: | |
| 346 | - | |
| 347 | - * Administrators occupy a place between “developer” category users | |
| 348 | - and the setup user; a super-developer capability, if you will. | |
| 349 | - Administrators have full control over the repository’s managed | |
| 350 | - content: versioned artifacts in [the block chain][bc], | |
| 351 | - [unversioned content][uv], forum posts, wiki articles, tickets, | |
| 352 | - etc.<p> | |
| 353 | - | |
| 354 | - * Administrators are subordinate to the repository’s superuser, | |
| 355 | - being the one with setup capability. Granting users admin | |
| 356 | - capability is useful in repositories with enough users | |
| 357 | - generating enough activity that the [all-powerful setup | |
| 358 | - user](#apsu) could use helpers to take care of routine | |
| 359 | - administrivia, user management, content management, site | |
| 360 | - cosmetics, etc. without giving over complete control of the | |
| 361 | - repository. | |
| 362 | - | |
| 363 | - For a much deeper dive into this topic, see the [Admin vs. Setup | |
| 364 | - article][avs]. | |
| 365 | - | |
| 366 | - Mnemonic: **a**dministrate. | |
| 313 | + below except for [setup](#s). See [Admin vs. Setup][avs] for a more | |
| 314 | + nuanced discussion. Mnemonic: **a**dministrate. | |
| 367 | 315 | |
| 368 | 316 | * <a name="b"></a>**b (Attach)** — Add attachments to wiki articles or tickets. |
| 369 | 317 | Mnemonics: **b**ind, **b**utton, **b**ond, or **b**olt. |
| 370 | 318 | |
| 371 | 319 | * <a name="c"></a>**c (ApndTkt)** — Append comments to existing tickets. |
| @@ -440,32 +388,11 @@ | ||
| 440 | 388 | **q**uash noise commentary. |
| 441 | 389 | |
| 442 | 390 | * <a name="r"></a>**r (RdTkt)** — View existing tickets. Mnemonic: **r**ead |
| 443 | 391 | tickets. |
| 444 | 392 | |
| 445 | -* <a name="s"></a>**s (Setup)** — The [all-powerful Setup user](#apsu) who | |
| 446 | - can uniquely: | |
| 447 | - | |
| 448 | - * Use roughly half of the Admin page settings | |
| 449 | - * See record IDs (RIDs) on screens that show them | |
| 450 | - * See the MIME type of attachments on [`/ainfo` pages](/help?cmd=/ainfo) | |
| 451 | - * See a remote repo’s HTTP [cache status](/help?cmd=/cachestat) | |
| 452 | - and [pull cache entries](/help?cmd=/cacheget) | |
| 453 | - * TODO: fold in results of [the timestamp override thread](https://fossil-scm.org/forum/forumpost/ee950efd2d) | |
| 454 | - * Edit a Setup user’s account! | |
| 455 | - | |
| 456 | - The Admin pages that only Setup can use are: Access, Configuration, | |
| 457 | - Email-Server, Login-Group, Notification, Settings, SQL, TH1, | |
| 458 | - Tickets, Transfers (TH1 hooks), and Wiki. | |
| 459 | - | |
| 460 | - Remember, [user caps affect Fossil’s web interfaces](#webonly) only. | |
| 461 | - A user can do anything they like to a repo stored on their local | |
| 462 | - machine. Fossil protects itself against malcious pushes, but someone | |
| 463 | - with clone and push capability on your repo could clone it, modify | |
| 464 | - their local repo as the local default Setup user account they got on | |
| 465 | - clone, and then push the changes back to your repo. | |
| 466 | - | |
| 393 | +* <a name="s"></a>**s (Setup)** — The [all-powerful Setup user][apsu]. | |
| 467 | 394 | Mnemonics: **s**etup or **s**uperuser. |
| 468 | 395 | |
| 469 | 396 | * <a name="t"></a>**t (TktFmt)** — Create new ticket report formats. Note that |
| 470 | 397 | although this allows the user to provide SQL code to be run in the |
| 471 | 398 | server’s context, and this capability is given to the untrusted |
| 472 | 399 |
| --- www/capabilities.md | |
| +++ www/capabilities.md | |
| @@ -88,11 +88,11 @@ | |
| 88 | When we bring the individual user capabilities into it, the complete |
| 89 | expression of the way Fossil implements user power becomes: |
| 90 | |
| 91 | > *setup* ≥ *admin* ≥ *moderator* ≥ *(developer* ∨ *reader)* ≥ *[subscriber]* ≥ *anonymous* ≥ *nobody* |
| 92 | |
| 93 | The two additions at the top are clear: [setup is all-powerful](#apsu), |
| 94 | and admin users are [subordinate to the setup user(s)](#a). Both are |
| 95 | superior to all other users. |
| 96 | |
| 97 | The moderator insertion could go anywhere from where it’s shown now down |
| 98 | to above the “anonymous” level, depending on what other caps you give to |
| @@ -107,18 +107,20 @@ | |
| 107 | purely to [receive email alerts and announcements](#7). Users with |
| 108 | additional caps can also be subscribers, but not all users *are* in fact |
| 109 | subscribers, which is why we show it in square brackets. (See [Users vs |
| 110 | Subscribers](./alerts.md#uvs).) |
| 111 | |
| 112 | |
| 113 | ## <a name="new"></a>New Repository Defaults |
| 114 | |
| 115 | When you create a new repository, Fossil creates only one user account |
| 116 | named after your OS user name [by default](#defuser). |
| 117 | |
| 118 | Fossil gives the initial repository user the [all-powerful Setup |
| 119 | capability](#apsu). |
| 120 | |
| 121 | Users who visit a [served repository][svr] without logging in get the |
| 122 | “nobody” user category’s caps which default to |
| 123 | **[g](#g)[j](#j)[o](#o)[r](#r)[z](#z)**: clone the repo, read the wiki, |
| 124 | check-out files via the web UI, view tickets, and pull version archives. |
| @@ -161,11 +163,11 @@ | |
| 161 | |
| 162 | Beware: Fossil does not reassign the capabilities these users had to |
| 163 | other users or to the “reader” or “developer” user category! All users |
| 164 | except those with Setup capability will lose all capabilities they |
| 165 | inherited from “nobody” and “anonymous” categories. Setup is the [lone |
| 166 | exception](#apsu). |
| 167 | |
| 168 | If you will have non-Setup users in your private repo, you should parcel |
| 169 | out some subset of the capability set the “nobody” and “anonymous” |
| 170 | categories had to other categories or to individual users first. |
| 171 | |
| @@ -279,11 +281,11 @@ | |
| 279 | local clone, where file system permissions are all that matter, but then |
| 280 | upon sync, the situation is effectively the same as when the parent repo |
| 281 | is on the local file system. If you can log into the remote system over |
| 282 | SSH and that user has the necessary file system permissions on that |
| 283 | remote repo DB file, your user is effectively the [all-powerful Setup |
| 284 | user](#apsu) on both sides of the SSH connection. |
| 285 | |
| 286 | Fossil reuses the HTTP-based [sync protocol][sp] in both cases above, |
| 287 | tunnelling HTTP through an OS pipe or through SSH (FIXME?), but all of |
| 288 | the user cap checks in Fossil are on its web interfaces only. |
| 289 | |
| @@ -292,38 +294,10 @@ | |
| 292 | |
| 293 | [japi]: https://docs.google.com/document/d/1fXViveNhDbiXgCuE7QDXQOKeFzf2qNUkBEgiUvoqFN4/view#heading=h.6k0k5plm18p1 |
| 294 | [sp]: ./sync.wiki |
| 295 | [wp]: /help#webpages |
| 296 | |
| 297 | |
| 298 | ## <a name="apsu"></a>The All-Powerful Setup User |
| 299 | |
| 300 | A user with [Setup capability, **s**](#s) needs no other user |
| 301 | capabliities, because its scope of its power is hard-coded in the Fossil |
| 302 | C source. You can take all capabilities away from all of the user |
| 303 | categories so that the Setup user inherits no capabilities from them, |
| 304 | yet the Setup user will still be able to use every feature of the Fossil |
| 305 | web user interface. |
| 306 | |
| 307 | Another way to look at it is that the setup user is a superset of all |
| 308 | other capabilities, even [Admin capability, **a**](#a). This is |
| 309 | literally how it’s implemented in the code: enabling setup capability on |
| 310 | a user turns on all of the flags controlled by all of the [other |
| 311 | capability characters](#ref). |
| 312 | |
| 313 | When you run [`fossil ui`][fui], you are effectively given setup |
| 314 | capability on that repo through that UI instance, regardless of the |
| 315 | capability set defined in the repo’s user table. This is why `ui` always |
| 316 | binds to `localhost` without needing the `--localhost` flag: in this |
| 317 | mode, anyone who can connect to that repo’s web UI has full power over |
| 318 | that repo. |
| 319 | |
| 320 | See the [Admin vs Setup article][avs] for a deeper treatment on the |
| 321 | differences between these two related capability sets. |
| 322 | |
| 323 | [fui]: /help?cmd=ui |
| 324 | |
| 325 | |
| 326 | ## <a name="ref"></a>Capability Reference |
| 327 | |
| 328 | This section documents each currently-defined user capability character |
| 329 | in more detail than the brief summary on the [user capability “key” |
| @@ -334,38 +308,12 @@ | |
| 334 | The [mnemonics][mn] given here vary from obviously-correct to *post |
| 335 | facto* rationalizations to the outright fanciful. To [some |
| 336 | extent](#choices), this is unavoidable. |
| 337 | |
| 338 | * <a name="a"></a>**a (Admin)** — Admin users have *all* of the capabilities |
| 339 | below except for [setup](#s): they can create new users, change user |
| 340 | capability assignments, and use about half of the functions on the |
| 341 | Admin screen in Fossil UI. (And that is why that screen is now |
| 342 | called “Admin,” not “Setup,” as it was in old versions of Fossil!) |
| 343 | |
| 344 | There are a couple of ways to view the role of Fossil |
| 345 | administrators: |
| 346 | |
| 347 | * Administrators occupy a place between “developer” category users |
| 348 | and the setup user; a super-developer capability, if you will. |
| 349 | Administrators have full control over the repository’s managed |
| 350 | content: versioned artifacts in [the block chain][bc], |
| 351 | [unversioned content][uv], forum posts, wiki articles, tickets, |
| 352 | etc.<p> |
| 353 | |
| 354 | * Administrators are subordinate to the repository’s superuser, |
| 355 | being the one with setup capability. Granting users admin |
| 356 | capability is useful in repositories with enough users |
| 357 | generating enough activity that the [all-powerful setup |
| 358 | user](#apsu) could use helpers to take care of routine |
| 359 | administrivia, user management, content management, site |
| 360 | cosmetics, etc. without giving over complete control of the |
| 361 | repository. |
| 362 | |
| 363 | For a much deeper dive into this topic, see the [Admin vs. Setup |
| 364 | article][avs]. |
| 365 | |
| 366 | Mnemonic: **a**dministrate. |
| 367 | |
| 368 | * <a name="b"></a>**b (Attach)** — Add attachments to wiki articles or tickets. |
| 369 | Mnemonics: **b**ind, **b**utton, **b**ond, or **b**olt. |
| 370 | |
| 371 | * <a name="c"></a>**c (ApndTkt)** — Append comments to existing tickets. |
| @@ -440,32 +388,11 @@ | |
| 440 | **q**uash noise commentary. |
| 441 | |
| 442 | * <a name="r"></a>**r (RdTkt)** — View existing tickets. Mnemonic: **r**ead |
| 443 | tickets. |
| 444 | |
| 445 | * <a name="s"></a>**s (Setup)** — The [all-powerful Setup user](#apsu) who |
| 446 | can uniquely: |
| 447 | |
| 448 | * Use roughly half of the Admin page settings |
| 449 | * See record IDs (RIDs) on screens that show them |
| 450 | * See the MIME type of attachments on [`/ainfo` pages](/help?cmd=/ainfo) |
| 451 | * See a remote repo’s HTTP [cache status](/help?cmd=/cachestat) |
| 452 | and [pull cache entries](/help?cmd=/cacheget) |
| 453 | * TODO: fold in results of [the timestamp override thread](https://fossil-scm.org/forum/forumpost/ee950efd2d) |
| 454 | * Edit a Setup user’s account! |
| 455 | |
| 456 | The Admin pages that only Setup can use are: Access, Configuration, |
| 457 | Email-Server, Login-Group, Notification, Settings, SQL, TH1, |
| 458 | Tickets, Transfers (TH1 hooks), and Wiki. |
| 459 | |
| 460 | Remember, [user caps affect Fossil’s web interfaces](#webonly) only. |
| 461 | A user can do anything they like to a repo stored on their local |
| 462 | machine. Fossil protects itself against malcious pushes, but someone |
| 463 | with clone and push capability on your repo could clone it, modify |
| 464 | their local repo as the local default Setup user account they got on |
| 465 | clone, and then push the changes back to your repo. |
| 466 | |
| 467 | Mnemonics: **s**etup or **s**uperuser. |
| 468 | |
| 469 | * <a name="t"></a>**t (TktFmt)** — Create new ticket report formats. Note that |
| 470 | although this allows the user to provide SQL code to be run in the |
| 471 | server’s context, and this capability is given to the untrusted |
| 472 |
| --- www/capabilities.md | |
| +++ www/capabilities.md | |
| @@ -88,11 +88,11 @@ | |
| 88 | When we bring the individual user capabilities into it, the complete |
| 89 | expression of the way Fossil implements user power becomes: |
| 90 | |
| 91 | > *setup* ≥ *admin* ≥ *moderator* ≥ *(developer* ∨ *reader)* ≥ *[subscriber]* ≥ *anonymous* ≥ *nobody* |
| 92 | |
| 93 | The two additions at the top are clear: [setup is all-powerful][apsu], |
| 94 | and admin users are [subordinate to the setup user(s)](#a). Both are |
| 95 | superior to all other users. |
| 96 | |
| 97 | The moderator insertion could go anywhere from where it’s shown now down |
| 98 | to above the “anonymous” level, depending on what other caps you give to |
| @@ -107,18 +107,20 @@ | |
| 107 | purely to [receive email alerts and announcements](#7). Users with |
| 108 | additional caps can also be subscribers, but not all users *are* in fact |
| 109 | subscribers, which is why we show it in square brackets. (See [Users vs |
| 110 | Subscribers](./alerts.md#uvs).) |
| 111 | |
| 112 | [apsu]: ./admin-v-setup.md#apsu |
| 113 | |
| 114 | |
| 115 | ## <a name="new"></a>New Repository Defaults |
| 116 | |
| 117 | When you create a new repository, Fossil creates only one user account |
| 118 | named after your OS user name [by default](#defuser). |
| 119 | |
| 120 | Fossil gives the initial repository user the [all-powerful Setup |
| 121 | capability][apsu]. |
| 122 | |
| 123 | Users who visit a [served repository][svr] without logging in get the |
| 124 | “nobody” user category’s caps which default to |
| 125 | **[g](#g)[j](#j)[o](#o)[r](#r)[z](#z)**: clone the repo, read the wiki, |
| 126 | check-out files via the web UI, view tickets, and pull version archives. |
| @@ -161,11 +163,11 @@ | |
| 163 | |
| 164 | Beware: Fossil does not reassign the capabilities these users had to |
| 165 | other users or to the “reader” or “developer” user category! All users |
| 166 | except those with Setup capability will lose all capabilities they |
| 167 | inherited from “nobody” and “anonymous” categories. Setup is the [lone |
| 168 | exception][apsu]. |
| 169 | |
| 170 | If you will have non-Setup users in your private repo, you should parcel |
| 171 | out some subset of the capability set the “nobody” and “anonymous” |
| 172 | categories had to other categories or to individual users first. |
| 173 | |
| @@ -279,11 +281,11 @@ | |
| 281 | local clone, where file system permissions are all that matter, but then |
| 282 | upon sync, the situation is effectively the same as when the parent repo |
| 283 | is on the local file system. If you can log into the remote system over |
| 284 | SSH and that user has the necessary file system permissions on that |
| 285 | remote repo DB file, your user is effectively the [all-powerful Setup |
| 286 | user][apsu] on both sides of the SSH connection. |
| 287 | |
| 288 | Fossil reuses the HTTP-based [sync protocol][sp] in both cases above, |
| 289 | tunnelling HTTP through an OS pipe or through SSH (FIXME?), but all of |
| 290 | the user cap checks in Fossil are on its web interfaces only. |
| 291 | |
| @@ -292,38 +294,10 @@ | |
| 294 | |
| 295 | [japi]: https://docs.google.com/document/d/1fXViveNhDbiXgCuE7QDXQOKeFzf2qNUkBEgiUvoqFN4/view#heading=h.6k0k5plm18p1 |
| 296 | [sp]: ./sync.wiki |
| 297 | [wp]: /help#webpages |
| 298 | |
| 299 | |
| 300 | ## <a name="ref"></a>Capability Reference |
| 301 | |
| 302 | This section documents each currently-defined user capability character |
| 303 | in more detail than the brief summary on the [user capability “key” |
| @@ -334,38 +308,12 @@ | |
| 308 | The [mnemonics][mn] given here vary from obviously-correct to *post |
| 309 | facto* rationalizations to the outright fanciful. To [some |
| 310 | extent](#choices), this is unavoidable. |
| 311 | |
| 312 | * <a name="a"></a>**a (Admin)** — Admin users have *all* of the capabilities |
| 313 | below except for [setup](#s). See [Admin vs. Setup][avs] for a more |
| 314 | nuanced discussion. Mnemonic: **a**dministrate. |
| 315 | |
| 316 | * <a name="b"></a>**b (Attach)** — Add attachments to wiki articles or tickets. |
| 317 | Mnemonics: **b**ind, **b**utton, **b**ond, or **b**olt. |
| 318 | |
| 319 | * <a name="c"></a>**c (ApndTkt)** — Append comments to existing tickets. |
| @@ -440,32 +388,11 @@ | |
| 388 | **q**uash noise commentary. |
| 389 | |
| 390 | * <a name="r"></a>**r (RdTkt)** — View existing tickets. Mnemonic: **r**ead |
| 391 | tickets. |
| 392 | |
| 393 | * <a name="s"></a>**s (Setup)** — The [all-powerful Setup user][apsu]. |
| 394 | Mnemonics: **s**etup or **s**uperuser. |
| 395 | |
| 396 | * <a name="t"></a>**t (TktFmt)** — Create new ticket report formats. Note that |
| 397 | although this allows the user to provide SQL code to be run in the |
| 398 | server’s context, and this capability is given to the untrusted |
| 399 |