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.  By 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.  And permission to change elements of the checklist
is based on permission to check-in to the main source repository.

<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 CGI, then add a line to the CGI
script file that says:

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

of the URL to work with: "/ext/checklist".  Fossil extracts the "/ext"
prefix and uses that to determine that this a CGI extension request.
Then it takes the leftover "/checklist" part and appends it to the
"extroot" to get the filename "/sqlite-src-ext/checklist".  Fossil finds
that file to be executable, so it runs it as CGI and returns the result.

The /sqlite-src-ext/checklist file is a
[https://wapp.tcl.tk|Wapp program].  The current source code to the
this program can be seen at
[https://www.sqlite.org/src/ext/checklist/self] and
historical versions are available at
[https://sqlite.org/docsrc/finfo/misc/checklist.tcl].

There is a cascade of CGIs happening here.  The webserver that receives
the initial HTTP request runs Fossil as a CGI based on the
"https://sqlite.org/src" portion of the URL.  The Fossil instance then
runs the checklist sub-CGI based on the "/ext/checklists" suffix.  The
output of the sub-CGI is read by Fossil and then relayed on to the
main webserver which in turn relays the result back to the original client.

  *  SCRIPT_DIRECTORY
  *  SCRIPT_FILENAME
  *  SCRIPT_NAME
  *  SERVER_NAME
  *  SERVER_PORT
  *  SERVER_PROTOCOL

Do a web search for
"[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/env]

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

  *  FOSSIL_CAPABILITIES
  *  FOSSIL_REPOSITORY
  *  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 [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/self|source listing] to see how
this happens.

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>

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 "application/x-fossil-wiki" or "application/x-markdown" then Fossil
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", 
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.

<h2>5.0 Filename Restrictions</h2>

For security reasons, Fossil places restrictions on the names of files
in the extroot directory that can participate in the extension CGI
mechanism:

  1.  Filenames must consist of only ASCII alphanumeric characters,
      ".", "_", and "-", and of course "/" as the file separator.
      Files with names that includes spaces or
      other punctuation or special characters are ignored.

  2.  No element of the pathname can begin with "." or "-".  Files or
      directories whose names begin with "." or "-" are ignored.

If a CGI program requires separate data files, it is safe to put those
files in the same directory as the CGI program itself as long as the names
of the data files contain special characters that cause them to be ignored
by Fossil.


<h2>6.0 Trouble-Shooting Hints</h2>

Remember that the /ext will return any file in the extroot directory
hierarchy as static content if the file is readable but not executable.
When initially setting up the /ext mechanism, it is sometimes helpful
to verify that you are able to receive static content prior to working