## 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. 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 Alerts 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 (☰).




<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"></a>
### User Capabilities

Once email alerts are working, one must also adjust user permissions to
allow users to subscribe to email alerts.  In the capability list for
each user on the Admin → Users page is a new capability called "Email
Alerts".  The corresponding capability letter is "7", which you must
give to any user that needs to use the subscription setup pages,
`/subscribe` and `/alerts`.


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.





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

The "h" or "hyperlink" capability is a permission that can be granted
to users that enables the display of hyperlinks.  Most of the hyperlinks
generated by Fossil are suppressed if this capability is missing.  So
one simple defense against spiders is to disable the "h" permission for

the "nobody" user.  This means that users must log in (perhaps as
"anonymous") before they can see any of the hyperlinks.  Spiders do not
normally attempt to log into websites and will therefore
not see most of the hyperlinks and will not try to walk the millions of
historical check-ins and diffs available on a Fossil-generated website.


If the "h" capability is missing from user "nobody" but is present for
user "anonymous", then a message automatically appears at the top of each
page inviting the user to log in as anonymous in order to activate hyperlinks.

Removing the "h" capability from user "nobody" is an effective means
of preventing spiders from walking a Fossil-generated website.  But
it can also be annoying to humans, since it requires them to log in.
Hence, 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 "h" 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 "h" 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].

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, setup administrator privileges
(capability letter 's') are granted to any HTTP request that
comes in over a loopback interface, such as 127.0.0.1.
and if the PATH_INFO string is empty, then 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
"edit" capability.
</p>
</blockquote>

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

  *  <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
     [https://en.wikipedia.org/wiki/Role-based_access_control | RBAC
     system] that Fossil uses to control all other repository accesses.
     The Fossil forum feature simply adds several new fine-grained
     capability bits 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>

Fossil forums use the same [./capability.md | role-based access control
mechanism] as for normal Fossil repository logins. There are
[./capability.md#2 | several dedicated forum-related capabilities] you
can grant to a user.

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 the <tt>anonymous</tt> category the Read Forum (2) and Write Forum


(3) 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
Read Forum capability (2) to users in the <tt>reader</tt> category.

For either type of repository, you are likely to want to give at least
the WriteTrusted capability (4) to users in the <tt>developer</tt>
category. If you did not give the Read Forum capability (2) to
<tt>anonymous</tt> above, you should give <tt>developer</tt> that
capability here if you choose to give it capability 3 or 4.


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 Email Alerts capability (7) 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 Moderate Forum capability (5) 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 forum-related
capability (2-6 inclusive, as of this writing) or an anonymous user with
read or write capability on the forum (2, 3) 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 which is probably less well known than it should be, and which
has been a feature of Fossil since April of 2011: Admin →
Login-Group. This allows one Fossil repository to recognize users
authorized on a different Fossil repository.


<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>
    <p>If you're using the default Fossil skin as shipped with Fossil
    2.7 or one updated to include the changes since 2.6 or prior, there
    is a Forum button in the navbar which appears for users with any of
    the forum-related user capabilities: 2 through 6 inclusive for those
    with repository logins, or caps 2 and 3 for users without a user
    account but who have solved the Anonymous user CAPTCHA.</p>
    <p>This button will not appear in the default skin for such users if
    their browser window is not greater than 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.</p>
  </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>Write Forum</b> capability (<tt>3</tt>)
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 semi-permanent. This changes how Fossil renders the
HTML for that update. It also means the artifact will now sync to
clones, if the sync is done by a user with <b>Check-Out</b> capability
(<tt>o</tt>).

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>WriteTrusted Forum</b> capability (<tt>4</tt>)
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>Moderate Forum</b> capability (<tt>5</tt>) to any of
    your users who should have this ability. You don't need to do this
    for any user with Setup (<tt>s</tt>) or Admin (<tt>a</tt>)
    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>Write Forum</b> capability (<tt>3</tt>), any
    other user with the <b>Moderate Forum</b> capability (<tt>5</tt>)
    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 a fine-grained
[https://en.wikipedia.org/wiki/Role-based_access_control|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

<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 the
  pre-defined user capabilities to define access policies rather than
  give out those same set of capabilities redundantly to each
  user.</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 
[/setup_ulist_notes|Fossil capability letters] 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 Debug privilege (capability letter "D")
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.