{ '3', CAPCLASS_FORUM, 0,
    "Forum-Write", "Create new forum messages" },
  { '4', CAPCLASS_FORUM, 0,
    "Forum-Trusted", "Create forum messages that bypass moderation" },
  { '5', CAPCLASS_FORUM|CAPCLASS_SUPER, 0,
    "Forum-Mod", "Moderator for forum messages" },
  { '6', CAPCLASS_FORUM|CAPCLASS_SUPER, 0,
    "Forum-Admin", "Grant capability '4' to other users" },
  { '7', CAPCLASS_ALERT, 0,
    "Alerts", "Sign up for email alerts" },
  { 'A', CAPCLASS_ALERT|CAPCLASS_SUPER, 0,
    "Announce", "Send announcements to all subscribers" },
  { 'D', CAPCLASS_OTHER, 0,
    "Debug", "Enable debugging features" },
};

  char Zip;              /* z: download zipped artifact via /zip URL */
  char Private;          /* x: can send and receive private content */
  char WrUnver;          /* y: can push unversioned content */
  char RdForum;          /* 2: Read forum posts */
  char WrForum;          /* 3: Create new forum posts */
  char WrTForum;         /* 4: Post to forums not subject to moderation */
  char ModForum;         /* 5: Moderate (approve or reject) forum posts */
  char AdminForum;       /* 6: Grant capability 4 to other users */
  char EmailAlert;       /* 7: Sign up for email notifications */
  char Announce;         /* A: Send announcements */
  char Debug;            /* D: show extra Fossil debugging features */
  /* These last two are included to block infinite recursion */
  char XReader;          /* u: Inherit all privileges of "reader" */
  char XDeveloper;       /* v: Inherit all privileges of "developer" */
};

## Setup Prerequisites

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](./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
related to this document's topic, but it is currently incomplete, so we
do not cover it at this time.

If you are seeing the following complaint from Fossil:

<blockquote>
  Use a different login with greater privilege than FOO to access
  /subscribe
</blockquote>

...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
the subscription.

Those with Fossil repository logins can adjust their email alert
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


<a id="unsub" name="unsubscribe"></a>
### Unsubscribing

To unsubscribe from alerts, visit the `/alerts` page on the repository,
click the "Unsubscribe" button, then check the "Unsubscribe" checkbox to

That command assumes that your project contains a "readme" file, but of
course it does, because you have followed the [Programming Style Guide
Checklist][cl], right? Right.

[cl]: https://sendgrid.com/blog/programming-style-guide-checklist/


<a id="cap7" name="ucap"></a>
### User Capabilities

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


<a id="first" name="frist"></a>
### First Post

I suggest taking the time to compose a suitable introductory message
especially for your project's forum, one which a new user would find

Fossil, it can present a crippling bandwidth and CPU load.

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.

<h2>The Hyperlink User Capability</h2>

Every Fossil web session has a "user".  For random passers-by on the internet
(and for spiders) that user is "nobody".  The "anonymous" user is also
available for humans who do not wish to identify themselves.  The difference
is that "anonymous" requires a login (using a password supplied via
a CAPTCHA) whereas "nobody" does not require a login.
The site administrator can also create logins with
passwords for specific individuals.

Users without the <b>[./caps/ref.html#h | Hyperlink]</b> capability
do not see most Fossil-generated hyperlinks. This is

a simple defense against spiders, since [./caps/#ucat | the "nobody"
user category] does not have this capability by default.
Users must log in (perhaps as
"anonymous") before they can see any of the hyperlinks.  A spider
that cannot log into your Fossil repository will be unable to walk

its historical check-ins, create diffs between versions, pull zip
archives, etc. by visiting links, because they aren't there.


A text message appears at the top of each page in this situation to
invite humans to log in as anonymous in order to activate hyperlinks.



Because this required login step is annoying to some,
Fossil provides other techniques for blocking spiders which
are less cumbersome to humans.

<h2>Automatic Hyperlinks Based on UserAgent</h2>

Fossil has the ability to selectively enable hyperlinks for users
that lack the <b>Hyperlink</b> capability based on their UserAgent string in the
HTTP request header and on the browsers ability to run Javascript.

The UserAgent string is a text identifier that is included in the header
of most HTTP requests that identifies the specific maker and version of
the browser (or spider) that generated the request.  Typical UserAgent
strings look like this:

provides a good first-guess about whether or not a request originates
from a human or a spider.

In Fossil, under the Admin/Access menu, there is a setting entitled
"<b>Enable hyperlinks for "nobody" based on User-Agent and Javascript</b>".
If this setting is enabled, and if the UserAgent string looks like a
human and not a spider, then Fossil will enable hyperlinks even if
the <b>Hyperlink</b> capability is omitted from the user permissions.  This setting
gives humans easy access to the hyperlinks while preventing spiders
from walking the millions of pages on a typical Fossil site.

But the hyperlinks are not enabled directly with the setting above.
Instead, the HTML code that is generated contains anchor tags ("&lt;a&gt;")
without "href=" attributes.  Then, JavaScript code is added to the
end of the page that goes back and fills in the "href=" attributes of
the anchor tags with the hyperlink targets, thus enabling the hyperlinks.
This extra step of using JavaScript to enable the hyperlink targets
is a security measure against spiders that forge a human-looking
UserAgent string.  Most spiders do not bother to run JavaScript and
so to the spider the empty anchor tag will be useless.  But all modern
web browsers implement JavaScript, so hyperlinks will show up
normally for human users.

<h2>Further Defenses</h2>

Recently (as of this writing, in the spring of 2013) the Fossil server
on the SQLite website ([http://www.sqlite.org/src/]) has been hit repeatedly
by Chinese spiders that use forged UserAgent strings to make them look
like normal web browsers and which interpret JavaScript.  We do not
believe these attacks to be nefarious since SQLite is public domain
and the attackers could obtain all information they ever wanted to

then the delay timer does not start until after the first mouse movement
is detected.

See also [./loadmgmt.md|Managing Server Load] for a description
of how expensive pages can be disabled when the server is under heavy
load.

<h2>The Ongoing Struggle</h2>

Fossil currently does a very good job of providing easy access to humans
while keeping out troublesome robots and spiders.  However, spiders and
bots continue to grow more sophisticated, requiring ever more advanced
defenses.  This "arms race" is unlikely to ever end.  The developers of
Fossil will continue to try improve the spider defenses of Fossil so
check back from time to time for the latest releases and updates.

Readers of this page who have suggestions on how to improve the spider
defenses in Fossil are invited to submit your ideas to the Fossil Users
forum:
[https://fossil-scm.org/forum].

# Differences Between Setup and Admin User

This document explains the distinction between [Setup users][su] and
[Admin users][au]. 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)

[au]: ./ref.md#a
[su]: ./ref.md#s


## <a name="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 block
chain][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 name="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 name="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 name="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 name="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](./shunning.wiki) 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
    [blockchain](./blockchain.md)! 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 blockchain 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 power hierarchy laid out at the top
    of this article, 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


### <a name="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 name="clones"></a>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.


## <a name="apsu"></a>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:

    *   <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 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

# Implementation Details of User Capabilities

## <a name="choices"></a>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. <span style="vertical-align:
bottom">😉</span>

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.


## <a name="bitfield"></a>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.


## <a name="filter"></a>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](./)*

<!-- add padding so anchor links always scroll ref’d section to top -->
<div style="height: 75em"></div>

[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

# 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


## <a name="ucat"></a>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* &or; *reader)* &ge; *anonymous* &ge; *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/


## <a name="ucap"></a>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* &ge; *admin* &ge; *moderator* &ge; *(developer* &or; *reader)* &ge; *[subscriber]* &ge; *anonymous* &ge; *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


## <a name="new"></a>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


## <a name="pvt"></a>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.


## <a name="read-v-clone"></a>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 <b>Read</b> 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


## <a name="defuser"></a>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



## <a name="utclone"></a>Cloning the User Table

When cloning over HTTP, the initial user table in the local clone is set
to its “[new state:](#new)” only one user with Setup capability, named
after either  your OS user account, 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.


## <a name="webonly"></a>Caps Affect Web Interfaces Only

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

User caps *do not* affect operations done on a local repo opened via a
`file://` URL or a file system path. This should strike you as sensible:
only local file permissions matter when operating on a local SQLite DB
file. The same is true when working on a clone done over such a path,
except that there are then two sets of file system permission checks:
once to modify the working check-out’s repo clone DB file, then again on
[sync][sync] with the parent DB file. 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.


## <a name="pubpg"></a>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.


## <a name="defcap"></a>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].


<!-- add padding so anchor links always scroll ref’d section to top -->
<div style="height: 75em"></div>

[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

# 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](./)*

<div class='fossil-doc' data-title="User Capability Reference">

<style type="text/css">
  p#backlink {
    /* Make empty space below the table so hyperlinks to named anchors
       near the bottom of the table still scroll that row to the top of
       the user's browser, even on tall screens. */
    margin-bottom: 75em;
  }

  tr > th {
    background-color: #e8e8e8;
    vertical-align: top;
  }

  tr.cols th {
    white-space: nowrap;
  }

  td, th {
    padding: 0.4em;
  }
</style>

<p>Here we document each currently-defined user capability character in
more detail than the brief summary on the <a
href="/setup_ucap_list">“key” page</a> 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 <tt>FossilUserPerms</tt>
object, so you can use this reference both from the UI down and from the
C code up.</p>

<p>The <a href="https://en.wikipedia.org/wiki/Mnemonic">mnemonics</a>
given here vary from obviously-correct to <i>post facto</i>
rationalizations to the outright fanciful. To <a
href="./impl.md#choices">some extent</a>, this is unavoidable.</p>


<h2>Reference</h2>

<table>
  <tr class="cols">
    <th>?</th>
    <th>Name</th>
    <th style="text-align: left">Description</th>
  </tr>

  <tr id="a">
    <th>a</th>
    <th>Admin</th>
    <td>
      Admin users have <em>all</em> of the capabilities below except for
      <a href="#s">setup</a> and <a href="#y">WrUnver</a>.
      See <a href="admin-v-setup.md">Admin vs.  Setup</a> for a more
      nuanced discussion.  Mnemonic: <b>a</b>dministrate.
    </td>
  </tr> 

  <tr id="b">
    <th>b</th>
    <th>Attach</th>
    <td>
      Add attachments to wiki articles or tickets.  Mnemonics: <b>b</b>ind,
      <b>b</b>utton, <b>b</b>ond, or <b>b</b>olt.
    </td>
  </tr> 

  <tr id="c">
    <th>c</th>
    <th>ApndTkt</th>
    <td>
      Append comments to existing tickets. Mnemonic: <b>c</b>omment.
    </td>
  </tr> 

  <tr id="d">
    <th>d</th>
    <th>Delete</th>
    <td>
      Delete wiki articles or tickets. Mnemonic: <b>d</b>elete.
    </td>
  </tr> 

  <tr id="e">
    <th>e</th>
    <th>RdAddr</th>
    <td>
      View <a
      href="https://en.wikipedia.org/wiki/Personal_data">personal
      identifying information</a> (PII) about other users such as email
      addresses. Mnemonics: show <b>e</b>mail addresses; or
      <b>E</b>urope, home of <a
      href="https://en.wikipedia.org/wiki/General_Data_Protection_Regulation">GDPR</a>.
    </td>
  </tr> 

  <tr id="f">
    <th>f</th>
    <th>NewWiki</th>
    <td>
      Create new wiki articles. Mnemonic: <b>f</b>ast, English
      translation of the Hawaiian word <a
      href="https://en.wikipedia.org/wiki/History_of_wikis#WikiWikiWeb,_the_first_wiki"><i>wiki</i></a>.
    </td>
  </tr> 

  <tr id="g">
    <th>g</th>
    <th>Clone</th>
    <td>
      Clone the repository. Note that this is distinct from <a
      href="#o">check-out capability, <b>o</b></a>. Mnemonic:
      <b>g</b>et.
    </td>
  </tr> 

  <tr id="h">
    <th>h</th>
    <th>Hyperlink</th>
    <td>
      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 <a href="../antibot.wiki">prevent bots from
      wandering around aimlessly</a> in the site’s hyperlink web, <a
      href="../loadmgmt.md">chewing up server resources</a> to little
      good purpose. Mnemonic: <b>h</b>yperlink.
    </td>
  </tr> 

  <tr id="i">
    <th>i</th>
    <th>Write</th>
    <td>
      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 <a href="./basics.md#webonly">only over HTTP</a>.
      Granting this capability also grants <b>o (Read)</b>  Mnemonics:
      <b>i</b>nput, check <b>i</b>n changes.
    </td>
  </tr> 

  <tr id="j">
    <th>j</th>
    <th>RdWiki</th>
    <td>
      View wiki articles. Mnemonic: in<b>j</b>est page content.  (All
      right, you critics, you do better, then.)
    </td>
  </tr> 

  <tr id="k">
    <th>k</th>
    <th>WrWiki</th>
    <td>
      Edit wiki articles. Granting this capability also grants <a
      href="#j"><b>RdWiki</b></a> and <a href="#m"><b>ApndWiki</b></a>,
      but it does <em>not</em> grant <a href="#f"><b>NewWiki</b></a>!
      Mnemonic: <b>k</b>ontribute.
    </td>
  </tr> 

  <tr id="l">
    <th>l</th>
    <th>ModWiki</th>
    <td>
      Moderate <a href="#m">wiki article appends</a>. Appends do not get
      saved permanently to the receiving repo’s block chain until <a
      href="#s">Setup</a> or someone with this cap approves it.
      Mnemonic: a<b>l</b>low.
    </td>
  </tr> 

  <tr id="m">
    <th>m</th>
    <th>ApndWiki</th>
    <td>
      Append content to existing wiki articles.  Mnemonic: a<b>m</b>end
      wiki
    </td>
  </tr> 

  <tr id="n">
    <th>n</th>
    <th>NewTkt</th>
    <td>
      File new tickets. Mnemonic: <b>n</b>ew ticket.
    </td>
  </tr> 

  <tr id="o">
    <th>o</th>
    <th>Read</th>
    <td>
      Read repository content from a remote Fossil instance over
      HTTP. See <a href="index.md#read-v-clone">Reading vs.
      Cloning</a>. Mnemonic: check <b>o</b>ut remote repo contents.
    </td>
  </tr> 

  <tr id="p">
    <th>p</th>
    <th>Password</th>
    <td>
      Change one’s own password. Mnemonic: <b>p</b>assword.
    </td>
  </tr> 

  <tr id="q">
    <th>q</th>
    <th>ModTkt</th>
    <td>
      Moderate tickets: delete comments appended to tickets. Mnemonic:
      <b>q</b>uash noise commentary.
    </td>
  </tr> 

  <tr id="r">
    <th>r</th>
    <th>RdTkt</th>
    <td>
      View existing tickets. Mnemonic: <b>r</b>ead tickets.
    </td>
  </tr> 

  <tr id="s">
    <th>s</th>
    <th>Setup</th>
    <td>
      The <a href="./admin-v-setup.md#apsu">all-powerful Setup user</a>.
      Mnemonics: <b>s</b>etup or <b>s</b>uperuser.
    </td>
  </tr>

  <tr id="t">
    <th>t</th>
    <th>TktFmt</th>
    <td>
      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 <b>t</b>icket report.
    </td>
  </tr> 

  <tr id="u">
    <th>u</th>
    <th>n/a</th>
    <td>
      Inherit all capabilities of the “reader” user category; does not
      have a dedicated flag internally within Fossil. Mnemonic:
      <a href="./index.md#ucat"><b>u</b>ser</a>
    </td>
  </tr> 

  <tr id="v">
    <th>v</th>
    <th>n/a</th>
    <td>
      Inherit all capabilities of the “developer” user category; does
      not have a dedicated flag internally within Fossil.  Mnemonic:
      de<b>v</b>eloper.
    </td>
  </tr> 

  <tr id="w">
    <th>w</th>
    <th>WrTkt</th>
    <td>
      Edit existing tickets. Granting this capability also grants <a
      href="#r"><b>RdTkt</b></a>, <a href="#c"><b>ApndTkt</b></a>, and
      <a href="#n"><b>NewTkt</b></a>. Mnemonic: <b>w</b>rite to ticket.
    </td>
  </tr> 

  <tr id="x">
    <th>x</th>
    <th>Private</th>
    <td>
      Push or pull <a href="../private.wiki">private branches</a>.
      Mnemonic: e<b>x</b>clusivity; “x” connotes unknown material in
      many Western languages due to its <a
      href="https://en.wikipedia.org/wiki/La_Géométrie#The_text">traditional
      use in mathematics</a>.
    </td>
  </tr> 

  <tr id="y">
    <th>y</th>
    <th>WrUnver</th>
    <td>
      Push <a href="../unvers.wiki">unversioned content</a>. Mnemonic:
      <b>y</b>ield, <a href="https://en.wiktionary.org/wiki/yield">sense
      4</a>: “hand over.”
    </td>
  </tr> 

  <tr id="z">
    <th>z</th>
    <th>Zip</th>
    <td>
      Pull archives of particular repository versions via <a
      href="/help?cmd=/zip"><tt>/zip</tt></a>, <a
      href="/help?cmd=/tarball"><tt>/tarball</tt></a>, and <a
      href="/help?cmd=/sqlar"><tt>/sqlar</tt></a> URLs. This is an
      expensive capability to grant, because creating such archives can
      put a large load on <a href="../server/">a Fossil server</a> which
      you may then need to <a href="../loadmgmt.md">manage</a>.
      Mnemonic: <b>z</b>ip file download.
    </td>
  </tr> 

  <tr id="2">
    <th>2</th>
    <th>RdForum</th>
    <td>
      Read <a href="../forum.wiki">forum posts</a> by other users.
      Mnemonic: from thee <b>2</b> me.
    </td>
  </tr> 

  <tr id="3">
    <th>3</th>
    <th>WrForum</th>
    <td>
      Create new forum threads, reply to threads created by others, and
      edit one’s own posts. New posts are <a
      href="../forum.wiki#moderation">held for moderation</a> and do
      not appear in repo clones or syncs. Granting this capability also
      grants <a href="#2"><b>RdForum</b></a>.   Mnemonic: post for
      <b>3</b> audiences: me, <a href="#5">the mods</a>, and <a
      href="https://en.wikipedia.org/wiki/The_Man">the Man</a>.
    </td>
  </tr> 

  <tr id="4">
    <th>4</th>
    <th>WrTForum</th>
    <td>
      Extends <a href="#3"><b>WrForum</b></a>, bypassing the moderation
      and sync restrictions. Mnemonic: post <b>4</b> immediate release.
    </td>
  </tr> 

  <tr id="5">
    <th>5</th>
    <th>ModForum</th>
    <td>
      <a href="../forum.wiki#moderation">Moderate forum posts</a>.
      Granting this capability also grants <a
      href="#4"><b>WrTForum</b></a> and <a href="#2"><b>RdForum</b></a>,
      so a user with this cap never has to moderate their own posts.
      Mnemonic: “May I have <b>5</b> seconds of your time, honored
      Gatekeeper?”
    </td>
  </tr> 

  <tr id="6">
    <th>6</th>
    <th>AdminForum</th>
    <td>
      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 <a
      href="#4"><b>WrTForum</b></a> capability to that post’s author.
      There is currently no UI for a user with this cap to
      <em>revoke</em> trust from a user once it is granted; only <a
      href="#a"><b>Admin</b></a> and <a href="#s"><b>Setup</b></a> can
      currently revoke granted caps.  Granting this capability also
      grants <a href="#5"><b>ModForum</b></a> and those it in turn
      grants.  Mnemonic: “I’m <b>6</b> [sick] of hitting Approve on your
      posts!”
    </td>
  </tr> 

  <tr id="7">
    <th>7</th>
    <th>EmailAlert</th>
    <td>
      User can sign up for <a href="../alerts.md">email alerts</a>.
      Mnemonic: <a href="https://en.wikipedia.org/wiki/Heaven_Can_Wait">Seven can
      wait</a>, I’ve got email to read now.
    </td>
  </tr> 

  <tr id="A">
    <th>A</th>
    <th>Announce</th>
    <td>
      Send email announcements to users <a href="#7">signed up to
      receive them</a>. Mnemonic: <b>a</b>nnounce.
    </td>
  </tr> 

  <tr id="D">
    <th>D</th>
    <th>Debug</th>
    <td>
      Enable debugging features. Mnemonic: <b>d</b>ebug.
    </td>
  </tr> 
</table>

<hr/>

<p id="backlink"><a href="./"><em>Back to Administering User
Capabilities</em></a></p>

If the [#directory|<b>directory:</b>] option is used and if the PATH_INFO
of the HTTP request does not correspond to any Fossil repository, then
the request redirects to URL.

<h2 id="repolist">repolist</h2>

This is a Boolean property.
If it is present, and if the [#directory:|<b>directory:</b>] option is used,
and if the PATH_INFO string is empty, then Fossil will show a list
of available Fossil repositories.

The "skin" of the reply is determined by the first
repository in the list that has a non-zero
[/help?cmd=repolist-skin|repolist-skin] setting.

This property changes the timeout on each CGI request to N seconds.
If N is zero, then there is no timeout.  If this property is omitted,
then the default timeout is 300 seconds (5 minutes).

<h2 id="localauth">localauth</h2>

This is a Boolean property.
If it is present, [./caps/ref.html#s | setup capability]
is granted to any HTTP request that
comes in over a loopback interface, such as 127.0.0.1.
If the PATH_INFO string is empty, Fossil will show a list
of available Fossil repositories.

<h2 id="skin">skin: <i>NAME</i></h2>

If NAME is the name of one of the built-in skins supported by Fossil,
then this option causes Fossil to display using that built-in skin,
and to ignore any custom skin that might be configured in the repository

  $<assigned_to>
  </td>
  <td align="right">Opened by:</td><td bgcolor="#d0d0d0">
  $<opened_by>
  </td>
</pre>
This will add a row which displays these two fields, in the event the user has
<a href="./caps/ref.html#w">ticket "edit" capability</a>.
</p>
</blockquote>

<h2>Modify the 'edit ticket' page</h2><blockquote>
<p>
Before the "Severity:" line, add this:
<pre>

*   **[CGI server extensions][ext]:** Fossil exports the nonce to the
    CGI in the `FOSSIL_NONCE` environment variable, which it can then
    use in `<script>` elements it generates. Because these extensions
    can only be installed by the Fossil server’s system administrator,
    this path is also considered safe.

[su]: ./caps/admin-v-setup.md#apsu


#### <a name="xss"></a>Cross-Site Scripting via Ordinary User Capabilities

We’re so restrictive about how we treat JavaScript because it can lead
to difficult-to-avoid scripting attacks. If we used the same CSP for
`<script>` tags [as for `<style>` tags](#style), anyone with check-in

  *  <b>Durable Links:</b> Once you create a valid internal artifact
     link in Fossil, it <em>remains</em> valid, durably. With
     third-party forum software and mailing list search engines, your
     links are only valid until the third-party component changes its
     URL scheme or disappears from the web.

  *  <b>Role-Based Access Control:</b> The forum uses the same
     [./caps/ | capability-based access control
     system] that Fossil uses to control all other repository accesses.
     The Fossil forum feature simply adds [./caps/ref.html#2 | several new fine-grained
     capabilities] to the existing system.

  *  <b>Enduring, Open File Format:</b> Since Fossil has an
     [./fileformat.wiki | open and well-documented file format], your
     discussion archives are truly that: <em>archives</em>. You are no
     longer dependent on the lifetime and business model of a
     third-party piece of software or service. Should you choose to stop
     using Fossil, you can easily extract your discussion traffic for

     digest delivery.


<h2 id="setup">Setting up a Fossil Forum</h2>

<h3 id="caps">Capabilities</h3>






























By default, no Fossil user has permission to use the forums except for
users with Setup and Admin capabilities, which get these as part of the
large package of other capabilities they get.

For public Fossil repositories that wish to accept new users without
involving a human, go into Admin &rarr; Access and enable the "Allow
users to register themselves" setting. You may also wish to give users
in [./caps/#ucat | the <tt>anonymous</tt> user category] the
<b>[./caps/ref.html#2 | RdForum]</b> and
<b>[./caps/ref.html#3 | WrForum]</b>
capabilities: this allows people to post without creating an account
simply by solving [./antibot.wiki | a simple CAPTCHA].

For a private repository, you probably won't want to give the
<tt>anonymous</tt> user any forum access, but you may wish to give the
<b>RdForum</b> capability to users in the <tt>reader</tt> category.

For either type of repository, you are likely to want to give at least
the <b>[./caps/ref.html#4 | WrTForum]</b> capability to users in the <tt>developer</tt>
category. If you did not give the <b>RdForum</b> capability to
<tt>anonymous</tt> above, you should give <tt>developer</tt> that
capability here if you choose to give it <b>WrForum</b> or
<b>WrTForum</b> capability.

If you want to use the email alert feature, by default only those
users in the Setup and Admin user categories can make use of it. Grant
the <b>[./caps/ref.html#7 | EmailAlert]</b> capability to give others access to this feature.
Alternately, you can handle alert signups outside of Fossil, with
a Setup or Admin users manually signing users up via Admin &rarr;
Notification. You'll want to grant this capability to the
<tt>nobody</tt> user category if you want anyone to sign up without any
restrictions.  Give it to <tt>anonymous</tt> instead if you want the
user to solve a simple CAPTCHA before signing up. Or, give it to
<tt>reader</tt> or <tt>developer</tt> if you want only users with Fossil
logins to have this ability. (That's assuming you give one or both of
these capabilities to every user on your Fossil repository.)

By following this advice, you should not need to tediously add
capabilities to individual accounts except in atypical cases, such as
to grant the <b>[./caps/ref.html#5 | ModForum]</b> capability to an uncommonly
highly-trusted user.


<h3 id="skin">Skin Setup</h3>

If you create a new Fossil repository with version 2.7 or newer, its
default skin is already set up correctly for typical forum

<verbatim>
  if {[anycap 23456] || [anoncap 2] || [anoncap 3]} {
    menulink /forum Forum
  }
</verbatim>

These rules say that any logged-in user with any [./caps/ref.html#2 |
forum-related capability] or an anonymous user <b>RdForum</b> or
<b>WrForum</b> capability will see the "Forum" navbar
link, which just takes you to <tt>/forum</tt>.

The exact code you need here varies depending on which skin you're
using. Follow the style you see for the other navbar links.

The new forum feature also brings many new CSS styles to the table. If
you're using the stock skin or something sufficiently close, the changes

participating in the forum have special capability bits for project
assets managed by Fossil, so you wish to segregate the two user sets.

Yet, what of the users who will have logins on both repositories? Some
users will be trusted with access to the project's main Fossil
repository, and these users will probably also participate in the
project's Fossil-hosted forum. Fossil has a feature to solve this
problem: [./caps/login-groups.md | login groups].





<h3 id="alerts">Email Alerts (a.k.a. Notifications)</h3>

Internet email service has become rather complicated since its initial
simple and insecure implementation decades ago. Fossil's role in all of
this is rather small at the moment, but the details of the integration
are complex enough to justify [./alerts.md | a separate document].

(The other reason that document is separate is that Fossil's email
alerts system also gets used by features of Fossil other than the
forum.)


<h2 id="access">Accessing the Forum</h2>

There are many paths to a repository's Fossil forum:

<ul>
  <li>
    If you're using the default Fossil skin as shipped with Fossil
    2.7+ or one [#skin | updated] to support it, there
    is a Forum button in the navbar which appears for users able to
    access the forum. With the default skin, that button will only


    appear if the user's browser window is at least
    1200 pixels wide.  The
    Fossil admin can adjust this limit in the skin's CSS section, down
    near the bottom in the definition of the `wideonly` style.
  </li>

  <li>The other stock skins have this button in them as of 2.7 as well,
  without the screen width restriction, since the navbar in those skins
  wraps on narrow screens more gracefully than the default skin
  does.</li>

In this section, we're going to call all of the following a "forum
update:"

  *  create a new post
  *  reply to an existing post
  *  edit a post or reply

When a person with the normal <b>WrForum</b> capability
updates the forum, Fossil saves the update in its block chain, but this
update is impermanent because of two other table updates made at the
same time:

<ol>
    <li>Fossil saves the update artifact's ID in its <tt>private</tt>
    table, preventing Fossil from sending such artifacts to any of the
    repository's clones.  (This is the same mechanism behind
    [./private.wiki | private branches].)</li>

    <li>Fossil also adds a reference to that artifact in the
    <tt>modreq</tt> table, which backs the moderation feature.  This is
    what causes Fossil to leave out the Reply button when rendering that
    post's HTML in the forum's web interface.</li>
</ol>

When a moderator approves an update, Fossil deletes these table entries,
making the update [./shunning.wiki | semi-permanent]. This changes how Fossil renders the
HTML for that update. It also means the artifact will now sync to
users with <b>[./caps/ref.html#g | Clone]</b> capability.


When a forum user edits a moderator-approved artifact, what actually
happens under the hood is that Fossil writes another artifact to the
repository which refers to the original version as its parent, causing
Fossil UI to present the new version instead of the original. The
original version remains in the repository, just as with historical
checkins. The parent must remain in the repository for referential
integrity purposes.

When you "Delete" a moderator-approved post or reply through Fossil UI,
it's actually an edit with blank replacement content. The only way to
truly delete such artifacts is through [./shunning.wiki | shunning].

When a user with <b>WrTForum</b> capability
updates the forum, it happens in the same way except that Fossil skips
the <tt>private</tt> and <tt>modreq</tt> table insertions.

When a moderator rejects an update, that artifact is unceremoniously
removed from the tip of the block chain. This is safe because Fossil
prevents replies to a reply or post awaiting moderator approval, so
referential integrity cannot be harmed.  Rejecting an edit is even
safer, since the original post remains behind, so that replies continue
to refer to that original post.


<h2 id="mod-user">Using the Moderation Feature</h2>

Having described all of the work that Fossil performs under the hood on
behalf of its users, we can now give the short list of work left for the
repository's administrators and moderators:

<ol>
    <li>Add the <b>[./caps/ref.html#5 | ModForum]</b> capability to any of
    your users who should have this ability. You don't need to do this
    for any user with <b>[./caps/ref.html#s | Setup]</b> or
    <b>[./caps/ref.html#a | Admin]</b> capability; it's
    [http://fossil-scm.org/index.html/artifact/b16221ffb736caa2?ln=1246-1257
    | already included].</li>

    <li>When someone updates the forum, an entry will appear in the
    timeline if the type filter is set to "Forum" or "Any Type". If that
    user has only the <b>WrForum</b> capability, any
    other user with the <b>ModForum</b> capability
    will see a conditional link appear at the top of the main forum
    page: "Moderation Requests".  Clicking this takes the moderator to
    the <tt>/modreq</tt> page. A moderator may wish to keep the main
    forum page open in a browser tab, reloading it occasionally to see
    when the "Moderation Requests" link reappears.</li>

    <li>A moderator viewing an update pending moderation sees two
    buttons at the bottom, "Approve" and "Reject" in place of the
    "Delete" button that the post's creator sees. Beware that both
    actions are durable and have no undo. Be careful!</li>
</ol>

Git provides file versioning services only, whereas Fossil adds
an integrated [./wikitheory.wiki | wiki],
[./bugtheory.wiki | ticketing & bug tracking],
[./embeddeddoc.wiki | embedded documentation], 
[./event.wiki | technical notes], and a [./forum.wiki | web forum],
all within a single nicely-designed [./customskin.md|skinnable] web
[/help?cmd=ui|UI],
protected by [./caps/ | a fine-grained role-based

access control system].
These additional capabilities are available for Git as 3rd-party
add-ons, but with Fossil they are integrated into
the design.  One way to describe Fossil is that it is
"[https://github.com/ | GitHub]-in-a-box."

For developers who choose to self-host projects (rather than using a

    <li><p><b>Trust over hierarchy:</b> SQLite's developers check
    changes into their local repository, and these are immediately and
    automatically synchronized up to the central repository; there is no
    "[https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows#_dictator_and_lieutenants_workflow|dictator
    and lieutenants]" hierarchy as with Linux kernel contributions.  D.
    Richard Hipp rarely overrides decisions made by those he has trusted
    with commit access on his repositories. Fossil allows you to give
    [./caps/admin-v-setup.md|some users] more power over what
    they can do with the repository, but Fossil [./caps/index.md#ucap |
    only loosely supports] the enforcement of a development organization's
    social and power hierarchies. Fossil is a great fit for
    [https://en.wikipedia.org/wiki/Flat_organization|flat
    organizations].</p></li>

    <li><p><b>No easy drive-by contributions:</b> Git
    [https://www.git-scm.com/docs/git-request-pull|pull requests] offer
    a low-friction path to accepting

#!/usr/bin/env tclsh
#
# Run this TCL script to generate a WIKI page that contains a
# permuted index of the various documentation files.
#
#    tclsh mkindex.tcl
#

set doclist {
  aboutcgi.wiki {How CGI Works In Fossil}
  aboutdownload.wiki {How The Download Page Works}
  adding_code.wiki {Adding New Features To Fossil}
  adding_code.wiki {Hacking Fossil}

  alerts.md {Email Alerts And Notifications}
  antibot.wiki {Defense against Spiders and Bots}
  backoffice.md {The "Backoffice" mechanism of Fossil}
  blame.wiki {The Annotate/Blame Algorithm Of Fossil}
  blockchain.md {Fossil As Blockchain}
  branching.wiki {Branching, Forking, Merging, and Tagging}
  bugtheory.wiki {Bug Tracking In Fossil}
  build.wiki {Compiling and Installing Fossil}
  caps/ {Administering User Capabilities}
  caps/admin-v-setup.md {Differences Between Setup and Admin Users}
  caps/login-groups.md {Differences Between Setup and Admin Users}
  caps/ref.html {User Capability Reference}
  cgi.wiki {CGI Script Configuration Options}
  changes.wiki {Fossil Changelog}
  checkin_names.wiki {Check-in And Version Names}
  checkin.wiki {Check-in Checklist}
  childprojects.wiki {Child Projects}
  copyright-release.html {Contributor License Agreement}
  concepts.wiki {Fossil Core Concepts}

<h2>Permuted Index:</h2>
<ul>
<li><a href="fiveminutes.wiki">5 Minutes as a Single User &mdash; Up and Running in</a></li>
<li><a href="fossil-from-msvc.wiki">2010 IDE &mdash; Integrating Fossil in the Microsoft Express</a></li>
<li><a href="tech_overview.wiki"><b>A Technical Overview Of The Design And Implementation Of Fossil</b></a></li>
<li><a href="serverext.wiki"><b>Adding Extensions To A Fossil Server Using CGI Scripts</b></a></li>
<li><a href="adding_code.wiki"><b>Adding New Features To Fossil</b></a></li>
<li><a href="caps/admin-v-setup.md">Admin Users &mdash; Differences Between Setup and</a></li>
<li><a href="caps/login-groups.md">Admin Users &mdash; Differences Between Setup and</a></li>
<li><a href="caps/"><b>Administering User Capabilities</b></a></li>
<li><a href="copyright-release.html">Agreement &mdash; Contributor License</a></li>
<li><a href="alerts.md">Alerts And Notifications &mdash; Email</a></li>
<li><a href="delta_encoder_algorithm.wiki">Algorithm &mdash; Fossil Delta Encoding</a></li>
<li><a href="blame.wiki">Algorithm Of Fossil &mdash; The Annotate/Blame</a></li>
<li><a href="blame.wiki">Annotate/Blame Algorithm Of Fossil &mdash; The</a></li>
<li><a href="customskin.md">Appearance of Web Pages &mdash; Theming: Customizing The</a></li>
<li><a href="faq.wiki">Asked Questions &mdash; Frequently</a></li>
<li><a href="password.wiki">Authentication &mdash; Password Management And</a></li>
<li><a href="backoffice.md">Backoffice mechanism of Fossil &mdash; The</a></li>
<li><a href="fossil_prompt.wiki">Bash Prompt &mdash; Fossilized</a></li>
<li><a href="whyusefossil.wiki"><b>Benefits Of Version Control</b></a></li>
<li><a href="caps/admin-v-setup.md">Between Setup and Admin Users &mdash; Differences</a></li>
<li><a href="caps/login-groups.md">Between Setup and Admin Users &mdash; Differences</a></li>
<li><a href="hashpolicy.wiki">Between SHA1 and SHA3-256 &mdash; Hash Policy: Choosing</a></li>

<li><a href="blockchain.md">Blockchain &mdash; Fossil As</a></li>
<li><a href="antibot.wiki">Bots &mdash; Defense against Spiders and</a></li>
<li><a href="private.wiki">Branches &mdash; Creating, Syncing, and Deleting Private</a></li>
<li><a href="branching.wiki"><b>Branching, Forking, Merging, and Tagging</b></a></li>
<li><a href="bugtheory.wiki"><b>Bug Tracking In Fossil</b></a></li>
<li><a href="makefile.wiki">Build Process &mdash; The Fossil</a></li>
<li><a href="caps/">Capabilities &mdash; Administering User</a></li>
<li><a href="caps/ref.html">Capability Reference &mdash; User</a></li>
<li><a href="cgi.wiki"><b>CGI Script Configuration Options</b></a></li>
<li><a href="serverext.wiki">CGI Scripts &mdash; Adding Extensions To A Fossil Server Using</a></li>
<li><a href="serverext.wiki"><b>CGI Server Extensions</b></a></li>
<li><a href="aboutcgi.wiki">CGI Works In Fossil &mdash; How</a></li>
<li><a href="changes.wiki">Changelog &mdash; Fossil</a></li>
<li><a href="checkin_names.wiki"><b>Check-in And Version Names</b></a></li>
<li><a href="checkin.wiki"><b>Check-in Checklist</b></a></li>

<li><a href="antibot.wiki"><b>Defense against Spiders and Bots</b></a></li>
<li><a href="shunning.wiki">Deleting Content From Fossil &mdash; Shunning:</a></li>
<li><a href="private.wiki">Deleting Private Branches &mdash; Creating, Syncing, and</a></li>
<li><a href="delta_encoder_algorithm.wiki">Delta Encoding Algorithm &mdash; Fossil</a></li>
<li><a href="delta_format.wiki">Delta Format &mdash; Fossil</a></li>
<li><a href="tech_overview.wiki">Design And Implementation Of Fossil &mdash; A Technical Overview Of The</a></li>
<li><a href="theory1.wiki">Design Of The Fossil DVCS &mdash; Thoughts On The</a></li>
<li><a href="caps/admin-v-setup.md"><b>Differences Between Setup and Admin Users</b></a></li>
<li><a href="caps/login-groups.md"><b>Differences Between Setup and Admin Users</b></a></li>
<li><a href="embeddeddoc.wiki">Documentation &mdash; Embedded Project</a></li>
<li><a href="contribute.wiki">Documentation To The Fossil Project &mdash; Contributing Code or</a></li>
<li><a href="aboutdownload.wiki">Download Page Works &mdash; How The</a></li>
<li><a href="theory1.wiki">DVCS &mdash; Thoughts On The Design Of The Fossil</a></li>
<li><a href="quotes.wiki">DVCSes in General &mdash; Quotes: What People Are Saying About Fossil, Git, and</a></li>
<li><a href="alerts.md"><b>Email Alerts And Notifications</b></a></li>
<li><a href="embeddeddoc.wiki"><b>Embedded Project Documentation</b></a></li>

<li><a href="fossil_prompt.wiki">Prompt &mdash; Fossilized Bash</a></li>
<li><a href="sync.wiki">Protocol &mdash; The Fossil Sync</a></li>
<li><a href="tls-nginx.md"><b>Proxying Fossil via HTTPS with nginx</b></a></li>
<li><a href="faq.wiki">Questions &mdash; Frequently Asked</a></li>
<li><a href="qandc.wiki"><b>Questions And Criticisms</b></a></li>
<li><a href="quickstart.wiki">Quick Start Guide &mdash; Fossil</a></li>
<li><a href="quotes.wiki"><b>Quotes: What People Are Saying About Fossil, Git, and DVCSes in General</b></a></li>
<li><a href="caps/ref.html">Reference &mdash; User Capability</a></li>
<li><a href="image-format-vs-repo-size.md">Repo Size &mdash; Image Format vs Fossil</a></li>
<li><a href="selfhost.wiki">Repositories &mdash; Fossil Self Hosting</a></li>
<li><a href="encryptedrepos.wiki">Repositories &mdash; How To Use Encrypted</a></li>
<li><a href="newrepo.wiki">Repository &mdash; How To Create A New Fossil</a></li>
<li><a href="selfcheck.wiki">Repository Integrity Self Checks &mdash; Fossil</a></li>
<li><a href="mirrortogithub.md">Repository On GitHub &mdash; How To Mirror A Fossil</a></li>
<li><a href="reviews.wiki"><b>Reviews</b></a></li>

<li><a href="defcsp.md">Security Policy &mdash; The Default Content</a></li>
<li><a href="selfcheck.wiki">Self Checks &mdash; Fossil Repository Integrity</a></li>
<li><a href="selfhost.wiki">Self Hosting Repositories &mdash; Fossil</a></li>
<li><a href="server/">Server &mdash; How To Configure A Fossil</a></li>
<li><a href="serverext.wiki">Server Extensions &mdash; CGI</a></li>
<li><a href="serverext.wiki">Server Using CGI Scripts &mdash; Adding Extensions To A Fossil</a></li>
<li><a href="settings.wiki">Settings &mdash; Fossil</a></li>
<li><a href="caps/admin-v-setup.md">Setup and Admin Users &mdash; Differences Between</a></li>
<li><a href="caps/login-groups.md">Setup and Admin Users &mdash; Differences Between</a></li>
<li><a href="hashpolicy.wiki">SHA1 and SHA3-256 &mdash; Hash Policy: Choosing Between</a></li>
<li><a href="hashpolicy.wiki">SHA3-256 &mdash; Hash Policy: Choosing Between SHA1 and</a></li>
<li><a href="shunning.wiki"><b>Shunning: Deleting Content From Fossil</b></a></li>
<li><a href="fiveminutes.wiki">Single User &mdash; Up and Running in 5 Minutes as a</a></li>
<li><a href="../../../sitemap"><b>Site Map</b></a></li>
<li><a href="image-format-vs-repo-size.md">Size &mdash; Image Format vs Fossil Repo</a></li>
<li><a href="customskin.md">Skins &mdash; Custom</a></li>

<li><a href="branching.wiki">Tagging &mdash; Branching, Forking, Merging, and</a></li>
<li><a href="tech_overview.wiki">Technical Overview Of The Design And Implementation Of Fossil &mdash; A</a></li>
<li><a href="../test/release-checklist.wiki">Testing Checklist &mdash; Pre-Release</a></li>
<li><a href="th1.md">TH1 Scripting Language &mdash; The</a></li>
<li><a href="backoffice.md"><b>The "Backoffice" mechanism of Fossil</b></a></li>
<li><a href="blame.wiki"><b>The Annotate/Blame Algorithm Of Fossil</b></a></li>
<li><a href="defcsp.md"><b>The Default Content Security Policy</b></a></li>

<li><a href="makefile.wiki"><b>The Fossil Build Process</b></a></li>
<li><a href="sync.wiki"><b>The Fossil Sync Protocol</b></a></li>
<li><a href="tickets.wiki"><b>The Fossil Ticket System</b></a></li>
<li><a href="webui.wiki"><b>The Fossil Web Interface</b></a></li>
<li><a href="th1.md"><b>The TH1 Scripting Language</b></a></li>
<li><a href="customskin.md"><b>Theming: Customizing The Appearance of Web Pages</b></a></li>
<li><a href="customgraph.md"><b>Theming: Customizing the Timeline Graph</b></a></li>
<li><a href="theory1.wiki"><b>Thoughts On The Design Of The Fossil DVCS</b></a></li>
<li><a href="custom_ticket.wiki">Ticket System &mdash; Customizing The</a></li>
<li><a href="tickets.wiki">Ticket System &mdash; The Fossil</a></li>
<li><a href="customgraph.md">Timeline Graph &mdash; Theming: Customizing the</a></li>
<li><a href="hints.wiki">Tips And Usage Hints &mdash; Fossil</a></li>
<li><a href="bugtheory.wiki">Tracking In Fossil &mdash; Bug</a></li>
<li><a href="unvers.wiki"><b>Unversioned Files</b></a></li>
<li><a href="fiveminutes.wiki"><b>Up and Running in 5 Minutes as a Single User</b></a></li>
<li><a href="hints.wiki">Usage Hints &mdash; Fossil Tips And</a></li>
<li><a href="fiveminutes.wiki">User &mdash; Up and Running in 5 Minutes as a Single</a></li>
<li><a href="caps/">User Capabilities &mdash; Administering</a></li>
<li><a href="caps/ref.html"><b>User Capability Reference</b></a></li>
<li><a href="caps/admin-v-setup.md">Users &mdash; Differences Between Setup and Admin</a></li>
<li><a href="caps/login-groups.md">Users &mdash; Differences Between Setup and Admin</a></li>
<li><a href="serverext.wiki">Using CGI Scripts &mdash; Adding Extensions To A Fossil Server</a></li>
<li><a href="ssl.wiki"><b>Using SSL with Fossil</b></a></li>
<li><a href="env-opts.md">Variables and Global Options &mdash; Environment</a></li>
<li><a href="whyusefossil.wiki">Version Control &mdash; Benefits Of</a></li>
<li><a href="checkin_names.wiki">Version Names &mdash; Check-in And</a></li>
<li><a href="fossil-v-git.wiki">Versus Git &mdash; Fossil</a></li>
<li><a href="tls-nginx.md">via HTTPS with nginx &mdash; Proxying Fossil</a></li>

<p>Prior to serving a Fossil repository to others, consider running <a
href="$ROOT/help?cmd=ui"><tt>fossil ui</tt></a> locally and taking these
minimum recommended preparation steps:</p>

<ol>
  <li><p>Fossil creates only one user in a <a
  href="$ROOT/help?cmd=new">new repository</a> and gives it the <a
  href="../caps/admin-v-setup.md#apsu">all-powerful Setup capability</a>.
  The 10-digit random password generated for that user is fairly strong
  against remote attack, even without explicit password guess rate
  limiting, but because that user has so much power, you may want to
  give it a much stronger password under Admin → Users.</a></li>

  <li><p>Run the Admin → Security-Audit tool to verify that other
  security-related permissions and settings are as you want them.

<h2 id="postsetup">Post-Activation Configuration</h2>

<p>After the server is up and running, log into it as the Setup user and
visit the Admin menu to finish configuring that repository for
service:</p>

<ol>
  <li><p>Add user accounts for your other team members. Use <a
  href="../caps/index.md#ucat">categories</a> to define access policies
  rather than redundantly give each new user the same <a
  href="../caps/index.md#ucap">individual capabilities</a>.</p></li>

  <li><p>Test access to the repository from each category of non-Setup
  user that you created. You may have to give your user categories some
  overlooked capabilities, particularly if you followed <a
  href="#prep">our earlier advice</a> to take the repository private
  prior to setting up the server.</p></li>

  *  FOSSIL_REPOSITORY
  *  FOSSIL_URI
  *  FOSSIL_USER

The FOSSIL_USER string is the name of the logged-in user.  This variable
is missing or is an empty string if the user is not logged in.  The
FOSSIL_CAPABILITIES string is a list of 
[./caps/ref.html|Fossil capabilities] that
indicate what permissions the user has on the Fossil repository.
The FOSSIL_REPOSITORY environment variable gives the filename of the
Fossil repository that is running.  The FOSSIL_URI variable shows the
prefix of the REQUEST_URI that is the Fossil CGI script, or is an
empty string if Fossil is being run by some method other than CGI.

The [https://sqlite.org/src/ext/checklist|checklist application] uses the

itself inside a chroot jail if it can.  The sub-CGI program will also
run inside this same chroot jail.  Make sure all embedded pathnames
have been adjusted accordingly and that all resources needed by the
CGI program are available within the chroot jail.

If anything goes wrong while trying to process an /ext page, Fossil
returns a 404 Not Found error with no details.  However, if the requester
is logged in as a user that has <b>[./caps/ref.html#D | Debug]</b> capability 
then additional diagnostic information may be included in the output.

If the /ext page has a "fossil-ext-debug=1" query parameter and if
the requester is logged in as a user with Debug privilege, then the
CGI output is returned verbatim, as text/plain and with the original
header intact.  This is useful for trying diagnosing problems with the
CGI script.