at "/home/www/resps/subdir.fossil" but there is no such repository.
     So then it looks at "/home/www/repos/subdir/three.fossil" and finds
     a repository.  The PATH_INFO is shortened by removing
     "subdir/three/" leaving it at just "timeline".
<li> Fossil looks at the rest of PATH_INFO to see that the webpage
     requested is "timeline".
</ol>
</blockquote>
<h2>Additional CGI Script Options</h2>
<blockquote>
<p>
The CGI script can have additional options used to fine-tune
Fossil's behavior.  See the [./cgi.wiki|CGI script documentation]
for details.
</p>
</blockquote>
<h2>Additional Observations</h2>
<blockquote><ol type="I">
<li><p>
Fossil does not distinguish between the various HTTP methods (GET, PUT,
DELETE, etc).  Fossil figures out what it needs to do purely from the
webpage term of the URI.

separate child Fossil process to handle each request.  In other words, CGI
is used internally to implement "fossil ui/server".
<p>
SCGI is processed using the same built-in web server, just modified
to parse SCGI requests instead of HTTP requests.  Each SCGI request is
converted into CGI, then Fossil creates a separate child Fossil
process to handle each CGI request.
<li><p>
Fossil is itself often launched using CGI.  But Fossil can also then
turn around and launch [./serverext.wiki|sub-CGI scripts to implement
extensions].
</ol>
</blockquote>

<title>CGI Script Configuration Options</title>

<h1>Summary</h1>

It is not necessary to have a central server in order to use Fossil.
But a central server can help a project run more smoothly by giving developers
a common point of rendezvous for syncing, and by providing a web-based
portal where developers and non-developers alike can learn about the
project and its current state.

Setting up a server using Fossil is easy.
A [./server.wiki|separate document] talks about four different methods for
setting up a Fossil server.  One of those methods, and perhaps the most
popular is [./server.wiki#cgi|CGI].  CGI is the technique that the three
[./selfhost.wiki|self-hosting Fossil repositories] all use.

Setting up a Fossil server using CGI is mostly about writing a short
script (usually just 2 lines line) in the cgi-bin folder of an ordinary
web-browser.  But there are a lot of extra options that can be added
to this script, to customize the configuration.  This article descripts
those options.

<h1>CGI Script Options</h1>

The CGI script used to launch a Fossil server will usually look something
like this:

<blockquote><verbatim>
#!/usr/bin/fossil
repository: /home/www/fossils/myproject.fossil
</verbatim></blockquote>

Of course, pathnames will likely be different.  The first line (the "shebang")
always gives the name of the Fossil executable.  Subsequent lines are of
the form "<b>property:&nbsp;argument&nbsp;...</b>".
The remainder of this document describes the available properties and
their arguments.

<hr>
<h2 id="repository">repository: <i>PATH</i></h2>

This property defines the Fossil repository that the server will use.
Every Fossil CGI requires either this property or the
[#directory|<b>directory:</b>] property (but not both).
Many Fossil repository sets have this one property and no other.

<h2 id="directory">directory: <i>PATH</i></h2>

The PATH is the name of a directory that contains one or more Fossil
repository files having the suffix ".fossil".  If this property is used
instead of [#repository|<b>repository:</b>], then the Fossil server is
able to serve all of the repositories in the directory.  The specific
repository used is selected by a prefix on the PATH_INFO.


<h2 id="errorlog">errorlog: <i>FILENAME</i></h2>

This setting causes the server to log any errors in FILENAME.
It is ok for multiple Fossil CGIs to share the same error log.

Setting up an error log for Fossil servers is not required, but it
is recommended.

<h2 id="notfound">notfound: <i>URL</i></h2>

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.
If no repository has such a non-zero repolist-skin setting, then
the repository list is generic HTML without any decoration.

<h2 id="extroot">extroot: <i>PATH</i></h2>

This property defines the DOCUMENT_ROOT for the
[./serverext.wiki|CGI Server Extensions].  If this property
is present, then CGI Server Extensions are enabled.  When this
property is omitted, CGI Server Extensions are disabled.

A cascade of CGI invocations can occur here.  Fossil itself is
started as CGI, then Fossil can turn around and invoke a sub-CGI
extension.  The sub-CGI extension outputs reply text, when Fossil
then (optionally) augments with its own header and footer and returns
to the original requestor.  The property controls the DOCUMENT_ROOT
of the sub-CGI.

<h2 id="timeout">timeout: <i>N</i></h2>

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

So, if you wanted to set up a server for a single Fossil project, but
also give users the option to use several of the different built-in
skins, you could create multiple CGI scripts, each with a different
"<b>skin:</b>" property, but all pointing to the same <b>repository:</b>.
Then users can select which skin to use by using the appropriate CGI.

<h2 id="files">files: </i>GLOBLIST</i></h2>

The GLOBLIST argument is a comma-separate list of "globs" that specify
filenames.  In [#directory|<b>directory:</b> mode], if the PATH_INFO
does not identify any Fossil repository, but it does refer some other
file in the directory, and that filename matches one of the glob patterns
in the GLOBLIST, then the file is returned as static content.

<h2 id="setenv">setenv: <i>NAME VALUE</i></h2>

This parameter causes additional environment variable NAME to have VALUE.
This parameter can be repeated as many times as necessary.

<h2 id="HOME">HOME: <i>PATH</i></h2>

This parameter is a short-hand for "<b>setenv HOME <i>PATH</i></b>".

<title>Change Log</title>

<a name='v2_10'></a>
<h2>Changes for Version 2.10 (pending)</h2>

  *  Added support for [./serverext.wiki|CGI-based Server Extensions].
  *  Added the [/help?cmd=repolist-skin|repolist-skin] setting used to
     add style to repository list pages.
  *  Enhance the hierarchical display of Forum threads to do less
     indentation and to provide links back to the previous message
     in the thread.  Provide sequential numbers for all messages in
     a forum thread.
  *  Add support for fenced code blocks and improved hyperlink
     processing to the [/md_rules|markdown formatter].
  *  Enhance the [/help?cmd=/stat|/stat] page so that it gives the
     option to show a breakdown of forum posts.
  *  Change the default [./hashpolicy.wiki|hash policy] to SHA3.
  *  Timeout [./server.wiki#cgi|CGI requests] after 300 seconds, or 
     some other value set by the 
     [./cgi.wiki#timeout|"timeout:" property] in the CGI script.
  *  Documentation improvements

<a name='v2_9'></a>
<h2>Changes for Version 2.9 (2019-07-13)</h2>

  *  Added the [/help?cmd=git|fossil git export] command and instructions
     for [./mirrortogithub.md|creating a GitHub mirror of a Fossil project].

  *  There is a 
     [long list of restrictions](https://git-scm.com/docs/git-check-ref-format)
     on tag and branch names in Git.  If any of your Fossil tag or branch names
     violate these rules, then the names are translated prior to being exported
     to Git.  The translation usually involves converting the offending characters
     into underscores.

<a name='ex1'></a>
## Example GitHub Mirrors

As of this writing (2019-03-16) Fossil’s own repository is mirrored
on GitHub at:

>
<https://github.com/drhsqlite/fossil-mirror>

  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}
  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}
  contribute.wiki {Contributing Code or Documentation To The Fossil Project}

<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="admin-v-setup.md">Capabilities &mdash; The Differences Between the Setup and Admin 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="checkin.wiki">Checklist &mdash; Check-in</a></li>
<li><a href="../test/release-checklist.wiki">Checklist &mdash; Pre-Release Testing</a></li>
<li><a href="foss-cklist.wiki"><b>Checklist For Successful Open-Source Projects</b></a></li>
<li><a href="selfcheck.wiki">Checks &mdash; Fossil Repository Integrity Self</a></li>
<li><a href="childprojects.wiki"><b>Child Projects</b></a></li>
<li><a href="hashpolicy.wiki">Choosing Between SHA1 and SHA3-256 &mdash; Hash Policy:</a></li>
<li><a href="contribute.wiki">Code or Documentation To The Fossil Project &mdash; Contributing</a></li>
<li><a href="style.wiki">Code Style Guidelines &mdash; Source</a></li>
<li><a href="../../../help">Commands and Webpages &mdash; Lists of</a></li>
<li><a href="build.wiki"><b>Compiling and Installing Fossil</b></a></li>
<li><a href="concepts.wiki">Concepts &mdash; Fossil Core</a></li>
<li><a href="cgi.wiki">Configuration Options &mdash; CGI Script</a></li>
<li><a href="server.wiki">Configure A Fossil Server &mdash; How To</a></li>
<li><a href="shunning.wiki">Content From Fossil &mdash; Shunning: Deleting</a></li>
<li><a href="contribute.wiki"><b>Contributing Code or Documentation To The Fossil Project</b></a></li>
<li><a href="copyright-release.html"><b>Contributor License Agreement</b></a></li>
<li><a href="whyusefossil.wiki">Control &mdash; Benefits Of Version</a></li>
<li><a href="concepts.wiki">Core Concepts &mdash; Fossil</a></li>
<li><a href="newrepo.wiki">Create A New Fossil Repository &mdash; How To</a></li>

<li><a href="checkin_names.wiki">Names &mdash; Check-in And Version</a></li>
<li><a href="adding_code.wiki">New Features To Fossil &mdash; Adding</a></li>
<li><a href="newrepo.wiki">New Fossil Repository &mdash; How To Create A</a></li>
<li><a href="tls-nginx.md">nginx &mdash; Proxying Fossil via HTTPS with</a></li>
<li><a href="alerts.md">Notifications &mdash; Email Alerts And</a></li>
<li><a href="foss-cklist.wiki">Open-Source Projects &mdash; Checklist For Successful</a></li>
<li><a href="pop.wiki">Operation &mdash; Principles Of</a></li>
<li><a href="cgi.wiki">Options &mdash; CGI Script Configuration</a></li>
<li><a href="env-opts.md">Options &mdash; Environment Variables and Global</a></li>
<li><a href="tech_overview.wiki">Overview Of The Design And Implementation Of Fossil &mdash; A Technical</a></li>
<li><a href="index.wiki">Page &mdash; Home</a></li>
<li><a href="aboutdownload.wiki">Page Works &mdash; How The Download</a></li>
<li><a href="customskin.md">Pages &mdash; Theming: Customizing The Appearance of Web</a></li>
<li><a href="password.wiki"><b>Password Management And Authentication</b></a></li>
<li><a href="globs.md">Patterns &mdash; File Name Glob</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="../../../md_rules">Rules &mdash; Markdown Formatting</a></li>
<li><a href="../../../wiki_rules">Rules &mdash; Wiki Formatting</a></li>
<li><a href="fiveminutes.wiki">Running in 5 Minutes as a Single User &mdash; Up and</a></li>
<li><a href="quotes.wiki">Saying About Fossil, Git, and DVCSes in General &mdash; Quotes: What People Are</a></li>
<li><a href="cgi.wiki">Script Configuration Options &mdash; CGI</a></li>
<li><a href="th1.md">Scripting Language &mdash; The TH1</a></li>
<li><a href="serverext.wiki">Scripts &mdash; Adding Extensions To A Fossil Server Using CGI</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.wiki">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>

</pre></blockquote>

Server (2) is a
<a href="http://www.linode.com/">Linode 4096</a> located in Newark, NJ
and set up just like the canonical server (1) with the addition of a
cron job for synchronization.  The same cron job also runs the
[/help?cmd=git|fossil git export] command after each sync in order to
[./mirrortogithub.md#ex1|mirror all changes to GitHub].

directory: /home/fossil/repos
notfound: http://url-to-go-to-if-repo-not-found/
</pre></blockquote>

Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b>
will serve up the repository "/home/fossil/repos/XYZ.fossil" (if it exists).

Additional options available to the CGI script are 
[./cgi.wiki|documented separately].

Note that Fossil itself can be launched as CGI, as described here.  But
Fossil can also launch [./serverext.wiki|sub-CGIs to implement server extensions].
Do not confuse these two concepts.  Note also that the
[./serverext.wiki|sub-CGI mechanism] works regardless of how the main
Fossil server is launched.

<h2 id="scgi">Fossil as SCGI</h2>
<blockquote>

The [/help/server|fossil server] command, described above as a way of
starting a stand-alone web server, can also be used for SCGI.  Simply add
the --scgi command-line option and the stand-alone server will interpret

the checklist.

<h2>2.0 How It Works</h2>

CGI Extensions are disabled by default.
An administrator activates the CGI extension mechanism by specifying
an "Extension Root Directory" or "extroot" as part of the server setup.
If the Fossil server is itself run as 
[./server.wiki#cgi|CGI], then add a line to the 
[./cgi.wiki#extroot|CGI script file] that says:

<blockquote><pre>
extroot: <i>DIRECTORY</i>
</pre></blockquote>

Or, if the Fossil server is begin run as using the 
"[./server.wiki#standalone|fossil server]" or
"[./server.wiki#standalone|fossil ui]" or 
"[./server.wiki#inetd|fossil http]" commands, then add an extra 
"--extroot <i>DIRECTORY</i>" option to that command.

The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI.
Files in the DOCUMENT_ROOT are accessed via URLs like this:

<blockquote>
https://example-project.org/ext/<i>FILENAME</i>

repository: /fossil/fossil.fossil
errorlog: /logs/errors.txt
extroot: /fossil-extroot
</verbatim></blockquote>

The extroot for this Fossil server is /fossil-extroot and in that directory
is an executable file named "fileup1" - another [https://wapp.tcl.tk|Wapp]
script.  (The extension mechanism is not required to use Wapp.  You can use
any kind of program you like.  But the creator of SQLite and Fossil is fond
of [https://www.tcl.tk|Tcl/Tk] and so he tends to gravitate toward Tcl-based
technologies like Wapp.)  The fileup1 script is a demo program that lets
the user upload a file using a form, and then displays that file in the reply.
There is a link on the page that causes the fileup1 script to return a copy
of its own source-code, so you can see how it works.

"[https://duckduckgo.com/?q=cgi+environment_variables|cgi environment variables]"
to find more detail about what each of the above variables mean and how
they are used.
Live listings of the values of some or all of these environment variables
can be found at links like these:

  *  [https://fossil-scm.org/home/test_env]
  *  [https://sqlite.org/src/ext/checklist/top/env]

In addition to the standard CGI environment variables listed above, 
Fossil adds the following:

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

The [https://sqlite.org/src/ext/checklist|checklist application] uses the
FOSSIL_USER environment variable to determine the name of the user and
the FOSSIL_CAPABILITIES variable to determine if the user is allowed to
mark off changes to the checklist.  Only users with check-in permission
to the Fossil repository are allowed to mark off checklist items.  That
means that the FOSSIL_CAPABILITIES string must contain the letter "i".
Search for "FOSSIL_CAPABILITIES" in the
[https://sqlite.org/src/ext/checklist/top/self|source listing] to see how
this happens.

If the CGI output is one of the forms for which Fossil inserts its own
header and footer, then the inserted header will include a
Content Security Policy (CSP) restriction on the use of javascript within
the webpage.  Any <script>...</script> elements within the 
CGI output must include a nonce or else they will be suppressed by the
web browser.  The FOSSIL_NONCE variable contains the value of that nonce.
So, in other words, to get javascript to work, it must be enclosed in:

<blockquote><verbatim>
<script nonce='$FOSSIL_NONCE'>...</script>
</verbatim></blockquote>

Except, of course, the $FOSSIL_NONCE is replace by the value of the
FOSSIL_NONCE environment variable.

If the HTTP request includes content (for example if this is a POST request)
then the CONTENT_LENGTH value will be positive and the data for the content
will be readable on standard input.

<h2>4.0 CGI Outputs</h2>