<title>CGI Server Extensions</title>

<h2>1.0 Introduction</h2>

If you have a [./server/|Fossil server] for your project,
you can add [https://en.wikipedia.org/wiki/Common_Gateway_Interface|CGI]
extensions to that server.  These extensions work like
any other CGI program, except that they also have access to the Fossil
login information and can (optionally) leverage the "skins" of Fossil
so that they appear to be more tightly integrated into the project.

An example of where this is useful is the 
An example of where this is useful is the
[https://sqlite.org/src/ext/checklist|checklist application] on
the [https://sqlite.org/|SQLite] project.  The checklist
helps the SQLite developers track which release tests have passed,
or failed, or are still to be done.  The checklist program began as a
stand-alone CGI which kept its own private user database and implemented
its own permissions and login system and provided its own CSS.  By
converting checklist into a Fossil extension, the same login that works 
converting checklist into a Fossil extension, the same login that works
for the [https://sqlite.org/src|main SQLite source repository] also works
for the checklist.  Permission to change elements of the checklist
is tied on permission to check-in to the main source repository.  And
the standard Fossil header menu and footer appear on each page of
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/any/cgi.md|CGI], then add a line to the 
If the Fossil server is itself run as
[./server/any/cgi.md|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 being run using the 
"[./server/any/none.md|fossil server]" or
"[./server/any/none.md|fossil ui]" or 
"[./server/any/inetd.md|fossil http]" commands, then add an extra 
Or, if the Fossil server is being run using the
"[./server/any/none.md|fossil server]" o
"[./server/any/none.md|fossil ui]" or
"[./server/any/inetd.md|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>

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

The fields of the CGI response header can be any valid HTTP header fields.
Those that Fossil does not understand are simply relayed back to up the
line to the requester.

Fossil takes special action with some content types.  If the Content-Type
is "text/x-fossil-wiki" or "text/x-markdown" then Fossil
converts the content from [/wiki_rules|Fossil-Wiki] or 
converts the content from [/wiki_rules|Fossil-Wiki] or
[/md_rules|Markdown] into HTML, adding its
own header and footer text according to the repository skin.  Content
of type "text/html" is normally passed straight through
unchanged.  However, if the text/html content is of the form:

<blockquote><verbatim>
<div class='fossil-doc' data-title='DOCUMENT TITLE'>
... HTML content there ...
</div>
</verbatim></blockquote>

In other words, if the outer-most markup of the HTML is a &lt;div&gt;
element with a single class of "fossil-doc", 
element with a single class of "fossil-doc",
then Fossil will adds its own header and footer to the HTML.  The
page title contained in the added header will be extracted from the
"data-title" attribute.

Except for the three cases noted above, Fossil makes no changes or
additions to the CGI-generated content.  Fossil just passes the verbatim
content back up the stack towards the requester.

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 
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 diagnosing problems with the
CGI script.