initial commitHEADmaster

1 files changed, 461 insertions, 0 deletions

diff --git a/www/caps/admin-v-setup.md b/www/caps/admin-v-setup.md
new file mode 100644
index 0000000..db1b412
--- /dev/null
+++ b/www/caps/admin-v-setup.md
@@ -0,0 +1,461 @@
+# Differences Between Setup and Admin Users
+
+This document explains the distinction between [Setup users][caps] and
+[Admin users][capa]. For other information about use types, see:
+
+* [Administering User Capabilities](./)
+* [How Moderation Works](../forum.wiki#moderation)
+* [Users vs Subscribers](../alerts.md#uvs)
+* [Defense Against Spiders](../antibot.wiki)
+
+
+## <a id="philosophy"></a>Philosophical Core
+
+The Setup user "owns" the Fossil repository and may delegate a subset of
+that power to one or more Admin users.
+
+The Setup user can grant Admin capability and take it away, but Admin
+users cannot grant themselves Setup capability, either directly via the
+Admin → Users UI page or via any indirect means. (If you discover
+indirect means to elevate Admin privilege to Setup, it's a bug, so
+please [report it][forum]!)
+
+It is common for the Setup user to have administrative control over the
+host system running the Fossil repository, whereas it makes no sense for
+Admin users to have that ability. If an Admin-only user had `root`
+access on a Linux box running the Fossil instance they are an Admin on,
+they could elevate their capability to Setup in several ways. (The
+`fossil user` command, the `fossil sql` command, editing the repository
+DB file directly, etc.) Therefore, if you wish to grant someone
+Setup-like capability on a Fossil repository but you're unwilling to
+give them a login on the host system, you probably want to grant
+them Admin capability instead.
+
+Admin power is delegated from Setup. When a Setup user grants Admin
+capability, it is an expression of trust in that user's judgement.
+
+Admin-only users must not fight against the policies of the Setup user.
+Such a rift would be just cause for the Setup user to strip the Admin
+user's capabilities. This may then create a fork in the project’s
+development effort as the ex-Admin takes their clone and stands it up
+elsewhere, so they may become that fork’s Setup user.
+
+A useful rule of thumb here is that Admin users should only change
+things that the Setup user has not changed from the stock configuration.
+In this way, an Admin-only user can avoid overriding the Setup user's
+choices.
+
+You can also look at the role of Admin from the other direction, up
+through the [user power hierarchy][ucap] rather than down from Setup. An
+Admin user is usually a “super-developer” role, given full control over
+the repository’s managed content: versioned artifacts in [the hash tree][bc],
+[unversioned content][uv], forum posts, wiki articles,
+tickets, etc.
+
+We’ll explore these distinctions in the rest of this document.
+
+[bc]:   ../blockchain.md
+[ucap]: ./index.md#ucap
+[uv]:   ../unvers.wiki
+
+
+## <a id="binary"></a>No Granularity
+
+Fossil doesn’t make any distinction between these two user types beyond
+this binary choice: Setup or Admin.
+
+A few features of Fossil are broken down so that only part of the
+feature is accessible to Admin, with the rest left only to Setup users,
+but for the most part each feature affected by this distinction is
+either Admin + Setup or Setup-only.
+
+We could add more capability letters to break down individual
+sub-features, but we’d run out of ASCII alphanumerics pretty quickly,
+and we might even run out of ASCII punctuation and symbols. Then would
+we need to shift to Unicode?
+
+Consider the Admin → Settings page, which is currently restricted to
+Setup users only: you might imagine breaking this up into several
+subsets so that some settings can be changed by Admin users.  Is that a
+good idea? Maybe, but it should be done only after due consideration. It
+would definitely be wrong to assign a user capability bit to *each*
+setting on that page.
+
+Now consider the opposite sort of case, Admin → Skins.  Fossil grants
+Admin users full access to this page so that the Admins can maintain and
+extend the skin as the repository evolves, not so Admins can switch the
+entire skin to another without consulting with the Setup user first. How
+would Fossil decide, using user capabilities only, which skin changes
+the Admin user is allowed to do, and which must be left to Setup? Do we
+assign a separate capability letter to each step in `/setup_skin`? Do we
+assign one more each to the five sections of a skin? (Header, Footer,
+CSS, JavaScript, and Details.) It quickly becomes unmanageable.
+
+
+
+## <a id="capgroups"></a>Capability Groups
+
+We can break up the set of powers the Admin user capability grants into
+several groups, then defend each group as a coherent whole.
+
+
+### <a id="security"></a>Security
+
+While establishing the Fossil repository's security policy is a task for
+the Setup user, *maintaining* that policy is something that Fossil
+allows a Setup user to delegate to trustworthy users via the Admin user
+capability:
+
+*   **Manage users**: The only thing an Admin-only user cannot do on the
+    Admin → Users page is grant Setup capability, either to themselves
+    or to other users. The intent is that Admin users be able to take
+    some of the load of routine user management tasks off the shoulders
+    of the Setup user: delete accounts created by spammers, fix email
+    alert subscriptions, reset passwords, etc.
+
+*   **Security audit**: The Admin → Security-Audit page runs several
+    tests on the Fossil repository's configuration, then reports
+    potential problems it found and offers canned solutions. Those
+    canned solutions do not do anything that an Admin-user could not do
+    via other means, so this page offers the Admin-only user no more
+    power than they otherwise had. For example, this page's "Take it
+    Private" feature can also be done manually via Admin → Users. This
+    page is a convenience, not a grant of new power to the Admin-only
+    user.
+
+*   **Logging**:<a id="log"></a> Admin-only users get to see the various
+    Fossil logs in case they need to use them to understand a problem
+    they're empowered to solve. An obvious example is a spam attack: the
+    Admin might want to find the user's last-used IP, see if they cloned
+    the repository, see if they attempted to brute-force an existing
+    login before self-registering, etc.
+
+Some security-conscious people might be bothered by the fact that
+Admin-only users have these abilities. Think of a large IT organization:
+if the CIO hires a [tiger team][tt] to test the company's internal IT
+defenses, the line grunts fix the reported problems, not the CIO.
+
+
+### <a id="administrivia"></a>Administrivia
+
+It is perfectly fine for a Fossil repository to only have Setup users,
+no Admin users. The smaller the repository, the more likely the
+repository has no Admin-only users. If the Setup user neither needs nor
+wants to grant Admin power to others, there is no requirement in Fossil
+to do so. [Setup capability is a pure superset of Admin capability.][sia]
+
+As the number of users on a Fossil repository grows, the value in
+delegating administrivia also grows, because the Setup user typically
+has other time sinks they consider more important.
+
+Admin users can take over the following routine tasks on behalf of the
+Setup user:
+
+*   **Shunning**: After user management, this is one of the greatest
+    powers of an Admin-only user. Fossil grants access to the Admin →
+    Shunned page to Admin users rather than reserve it to Setup users
+    because one of the primary purposes of [the Fossil shunning
+    system][shun] is to clean up after a spammer, and that's
+    exactly the sort of administrivia we wish to delegate to Admin users.
+
+    Coupled with the Rebuild button on the same page, an Admin user has
+    the power to delete the repository's entire
+    [hash tree][bc]! This makes this feature a pretty good
+    razor in deciding whether to grant someone Admin capability: do you
+    trust that user to shun Fossil artifacts responsibly?
+
+    Realize that shunning is cooperative in Fossil. As long as there are
+    surviving repository clones, an Admin-only user who deletes the
+    whole hash tree has merely caused a nuisance. An Admin-only user
+    cannot permanently destroy the repository unless the Setup user has
+    been so silly as to have no up-to-date clones.
+
+*   **Moderation**: According to [the user power hierarchy][ucap],
+    Admins are greater than Moderators, so control over
+    what Moderators can do clearly belongs to both Admins and to the
+    Setup user(s).
+
+*   **Status**: Although the Fossil `/stat` page is visible to every
+    user with Read capability, there are several additional things this
+    page gives access to when a user also has the Admin capability:
+
+    *   <p>[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.</p>
+
+    *   <p>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).</p>
+
+    *   <p>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.</p>
+
+    *   <p>Web cache status, environment, and logging: more
+        administrivia meant to help the Admin debug problems.</p>
+
+*   **Configure search**
+
+[ale]:  ../alerts.md
+[shun]: ../shunning.wiki
+
+
+### <a id="cosmetics"></a>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.
+
+
+## <a id="clones"></a>Clones and Backups
+
+Fossil is a *distributed* version control system, which has direct
+effects on the “Setup user” concept in the face of clones. When you
+clone a repository, your local user becomes a Setup user on the local
+clone even if you are not one on the remote repository. This may be
+surprising to you, but it should also be sensible once you realize that
+your operating system will generally give you full control over the
+local repository file.  What use trying to apply remote restrictions on
+the local file, then?
+
+The distinctions above therefore are intransitive: they apply only
+within a single repository instance.
+
+Fossil behaves differently when you do a clone as a user with Setup
+capability on the remote repository, which primarily has effects on the
+fidelity of clone-as-backup, which we cover [elsewhere](../backup.md).
+We strongly encourage you to read that document if you expect to use a
+clone as a complete replacement for the remote repository.
+
+
+## <a id="apsu"></a>The All-Powerful Setup User
+
+Setup users get [every user capability](./ref.html) of Fossil except for
+[two exceptionally dangerous capabilities](#dcap), which they can later
+grant to themselves or to others.
+
+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. They may not
+only use all of the Admin UI features, they may also:
+
+*   See record IDs (RIDs) on screens that show them
+*   See the MIME type of attachments on [`/ainfo` pages](/help/www/ainfo)
+*   See a remote repo’s HTTP [cache status](/help/www/cachestat)
+    and [pull cache entries](/help/www/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:
+
+    *   <p><b>Harmless</b>: 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.</p>
+
+    *   <p><b>Low-Risk</b>: The <tt>admin-log</tt> setting controls
+        whether the Fossil admin log is generated. Since we've <a
+        href="#log">already decided</a> 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.</p>
+
+        <p>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.</p>
+
+    *   <p><b>Risky</b>: The <tt>https-login</tt> 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.</p>
+
+        <p>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.)</p>
+
+    *   <p><b>Dangerous</b>: The <tt>email-send-command</tt> 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 <tt>root</tt> level
+        access on the host system, we almost certainly don't want to
+        allow them to change such settings.</p>
+
+*   **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 hash tree
+    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 arbitrary 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.
+
+
+## <a id="dcap"></a>Dangerous Capabilities Initially Denied to Everyone
+
+There are two capabilities that Fossil doesn’t grant by default to Setup
+or Admin users automatically. They are exceptionally dangerous, so
+Fossil makes these users grant themselves (or others) these capabilities
+deliberately, hopefully after careful consideration.
+
+
+### <a id="y"></a>Write Unversioned
+
+Fossil currently doesn’t distinguish the sub-operations of
+[`fossil uv`](/help/uv); they’re all covered by [**WrUnver**][capy]
+(“y”) capability. Since some of these operations are unconditionally
+destructive due to the nature of unversioned content, and since this
+goes against Fossil’s philosophy of immutable history, nobody gets cap
+“y” on a Fossil repo by default, not even the Setup or Admin users.  A
+Setup or Admin user must grant cap “y” to someone — not necessarily
+themselves! — before modifications to remote
+unversioned content are possible.
+
+Operations on unversioned content made without this capability affect
+your local clone only. In this way, your local unversioned file table
+can have different content from that in its parent repo. This state of
+affairs will continue until your user either gets cap “y” and syncs that
+content with its parent or you say `fossil uv revert` to make your local
+unversioned content table match that of its parent repo.
+
+
+### <a id="x"></a>Private Branch Push
+
+For private branches to remain private, they must never be accidentally
+pushed to a public repository. It can be [difficult to impossible][shun]
+to recover from such a mistake, so nobody gets [**Private**][capx] (“x”)
+capability on a Fossil repo by default, not even Admin or Setup users.
+
+There are two common uses for private branches.
+
+One use is part of a local social contract allowing individual
+developers to work on some things in private until they’re ready to push
+them up to the parent repository. This goes against [a core tenet][fdp]
+of Fossil’s design philosophy, but Fossil allows it, so some development
+organizations do this. If yours is one of these, you might give cap “x”
+to the “developer” category.
+
+The other use is in development organizations that follow the Fossil
+philosophy, where you do not work in private unless you absolutely must.
+You may have a public-facing project — let’s call it “SQLite” for the
+sake of argument — but then someone comes along and commissions a custom
+modification to your project which they wish to keep proprietary.  You
+do your work on a private branch, which you absolutely must never push
+to the public repo, because that would be illegal.  (Breach of contract,
+copyright violation on a work-for-hire agreement, etc.) If you are using
+Fossil in this way, we recommend that you give “x” capability to a
+special developer account only, if at all, to minimize the chance of an
+accidental push.
+
+
+[capa]: ./ref.html#a
+[caps]: ./ref.html#s
+[capx]: ./ref.html#x
+[capy]: ./ref.html#y
+
+[fcp]:   https://fossil-scm.org/home/help/configuration
+[fdp]:   ../fossil-v-git.wiki#devorg
+[forum]: https://fossil-scm.org/forum/
+[fui]:   /help/ui
+[lg]:    ./login-groups.md
+[rs]:    https://fossil-scm.org/home/doc/trunk/www/settings.wiki
+[sia]:   https://fossil-scm.org/home/artifact?ln=1259-1260&name=0fda31b6683c206a
+[snoy]:  https://fossil-scm.org/forum/forumpost/00e1c4ecff
+[th1]:   ../th1.md
+[tt]:    https://en.wikipedia.org/wiki/Tiger_team#Security
+[webo]:  ./#webonly