diff options
Diffstat (limited to 'www/cgi.wiki')
| -rw-r--r-- | www/cgi.wiki | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/www/cgi.wiki b/www/cgi.wiki new file mode 100644 index 0000000..6b9c375 --- /dev/null +++ b/www/cgi.wiki @@ -0,0 +1,210 @@ +<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/|separate document] talks about all of the many different methods for +setting up a Fossil server, one of which is [./server/any/cgi.md | as a CGI +script]. 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) in the cgi-bin folder of an ordinary +web-server. But there are a lot of extra options that can be added +to this script, to customize the configuration. This article describes +those options. + +<h1>CGI Script Options</h1> + +The CGI script used to launch a Fossil server will usually look something +like this: + +<verbatim> +#!/usr/bin/fossil +repository: /home/www/fossils/myproject.fossil +</verbatim> + +Of course, pathnames will likely be different. The first line +(the "[wikipedia:/wiki/Shebang_(Unix)|shebang]") +always gives the name of the Fossil executable. Subsequent lines are of +the form "<b>property: argument ...</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 CGI scripts 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. See +the notes for the [#repolist|<b>repolist</b>] option regarding name +collisions between subdirectories and repository files. + + +<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/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, with +the page title taken from the <tt>FOSSIL_REPOLIST_TITLE</tt> +environment variable. The variable can be defined in the CGI +control file using the [#setenv|<tt>setenv:</tt>] statement. + +The "Project Description" and "Login-Group" columns on the repolist page +are optional. They are hidden by default. Show them by +etting the <tt>FOSSIL_REPOLIST_SHOW</tt> environment variable to +a string that contains substrings "description" and/or "login-group". + +The repolist-generated page recurses into subdirectories and will list +all <tt>*.fossil</tt> files found, with the following exceptions: + + * Filenames starting with a period are treated as "hidden" and skipped. + + * Subdirectory names which match the base name of a fossil file in + the same directory are listed in the resulting page but are not + hyperlinked because the links would be ambiguous and the + repositories in the subdirectories would be unreachable to + clients. For example, any repositories under subdirectory + <tt>XYZ</tt> are unreachable if <tt>XYZ.fossil</tt> exists in + the same directory as <tt>XYZ</tt>, noting that this particular + name check is case-insensitive. The entries for such + repositories are clearly marked in the repolist page's output to + make the user aware of the problem. To make them accessible, + move them into a directory which does not share a base name with + a repository file. + + +<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. + + +<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>". + + +<h2 id="cgi-debug">cgi-debug: <i>FILE</i></h2> + +Cause CGI-related debugging information to be appended in <i>FILE</i>. Use +this to help debug CGI problems. + + +<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="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="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="redirect">redirect: <i>REPO URL</i></h2> + +Extract the "name" query parameter and search REPO for a check-in or +ticket that matches the value of "name", then redirect to URL. There +can be multiple "redirect:" lines that are processed in order. If the +repo name is "*", then an unconditional redirect to URL is taken. + + +<h2 id="jsmode">jsmode: <i>VALUE</i></h2> + +Specifies the delivery mode for JavaScript files. See "[/help/http | +http --jsmode]" for the allowed values and their meanings. + + +<h2 id="mainmenu">mainmenu: <i>FILE</i></h2> + +This parameter causes the contents of the given file to override the +site's <tt>mainmenu</tt> configuration setting, in much the same way +that the <tt>skin</tt> setting overrides the skin. This can be used to +apply a common main menu to a number of sites, and centrally maintain +it, without having to copy its contents into each site. Note, however, +that the contents of this setting are not stored in the repository and +will not be cloned along with the repository. |