From 4f49b16079b27d7ce633619e4cddfdf2bffbc952 Mon Sep 17 00:00:00 2001 From: cashmere Date: Fri, 4 Sep 2026 09:05:24 +0200 Subject: initial commit --- www/cgi.wiki | 210 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 www/cgi.wiki (limited to 'www/cgi.wiki') 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 @@ +CGI Script Configuration Options + +

Summary

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

CGI Script Options

+ +The CGI script used to launch a Fossil server will usually look something +like this: + + +#!/usr/bin/fossil +repository: /home/www/fossils/myproject.fossil + + +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 "property: argument ...". +The remainder of this document describes the available properties and +their arguments. + +
+ +

repository: PATH

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

directory: PATH

+ +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|repository:], 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|repolist] option regarding name +collisions between subdirectories and repository files. + + +

notfound: URL

+ +If the [#directory|directory:] 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. + + +

repolist

+ +This is a Boolean property. +If it is present, and if the [#directory:|directory:] 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 FOSSIL_REPOLIST_TITLE +environment variable. The variable can be defined in the CGI +control file using the [#setenv|setenv:] statement. + +The "Project Description" and "Login-Group" columns on the repolist page +are optional. They are hidden by default. Show them by +etting the FOSSIL_REPOLIST_SHOW environment variable to +a string that contains substrings "description" and/or "login-group". + +The repolist-generated page recurses into subdirectories and will list +all *.fossil 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 + XYZ are unreachable if XYZ.fossil exists in + the same directory as XYZ, 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. + + +

localauth

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

skin: NAME

+ +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 +"skin:" property, but all pointing to the same repository:. +Then users can select which skin to use by using the appropriate CGI. + + +

files: GLOBLIST

+ +The GLOBLIST argument is a comma-separate list of "globs" that specify +filenames. In [#directory|directory: 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. + + +

setenv: NAME VALUE

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

HOME: PATH

+ +This parameter is a short-hand for "setenv HOME PATH". + + +

cgi-debug: FILE

+ +Cause CGI-related debugging information to be appended in FILE. Use +this to help debug CGI problems. + + +

errorlog: FILENAME

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

timeout: N

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

extroot: PATH

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

redirect: REPO URL

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

jsmode: VALUE

+ +Specifies the delivery mode for JavaScript files. See "[/help/http | +http --jsmode]" for the allowed values and their meanings. + + + + +This parameter causes the contents of the given file to override the +site's mainmenu configuration setting, in much the same way +that the skin 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. -- cgit v1.3.1