|
1
|
<title>CGI Script Configuration Options</title> |
|
2
|
|
|
3
|
<h1>Summary</h1> |
|
4
|
|
|
5
|
It is not necessary to have a central server in order to use Fossil. |
|
6
|
But a central server can help a project run more smoothly by giving developers |
|
7
|
a common point of rendezvous for syncing, and by providing a web-based |
|
8
|
portal where developers and non-developers alike can learn about the |
|
9
|
project and its current state. |
|
10
|
|
|
11
|
Setting up a server using Fossil is easy. |
|
12
|
A [./server/|separate document] talks about all of the many different methods for |
|
13
|
setting up a Fossil server, one of which is [./server/any/cgi.md | as a CGI |
|
14
|
script]. CGI is the technique that the three |
|
15
|
[./selfhost.wiki|self-hosting Fossil repositories] all use. |
|
16
|
|
|
17
|
Setting up a Fossil server using CGI is mostly about writing a short |
|
18
|
script (usually just 2 lines) in the cgi-bin folder of an ordinary |
|
19
|
web-server. But there are a lot of extra options that can be added |
|
20
|
to this script, to customize the configuration. This article describes |
|
21
|
those options. |
|
22
|
|
|
23
|
<h1>CGI Script Options</h1> |
|
24
|
|
|
25
|
The CGI script used to launch a Fossil server will usually look something |
|
26
|
like this: |
|
27
|
|
|
28
|
<verbatim> |
|
29
|
#!/usr/bin/fossil |
|
30
|
repository: /home/www/fossils/myproject.fossil |
|
31
|
</verbatim> |
|
32
|
|
|
33
|
Of course, pathnames will likely be different. The first line |
|
34
|
(the "[wikipedia:/wiki/Shebang_(Unix)|shebang]") |
|
35
|
always gives the name of the Fossil executable. Subsequent lines are of |
|
36
|
the form "<b>property: argument ...</b>". |
|
37
|
The remainder of this document describes the available properties and |
|
38
|
their arguments. |
|
39
|
|
|
40
|
<hr> |
|
41
|
|
|
42
|
<h2 id="repository">repository: <i>PATH</i></h2> |
|
43
|
|
|
44
|
This property defines the Fossil repository that the server will use. |
|
45
|
Every Fossil CGI requires either this property or the |
|
46
|
[#directory|<b>directory:</b>] property (but not both). |
|
47
|
Many Fossil CGI scripts have this one property and no other. |
|
48
|
|
|
49
|
|
|
50
|
<h2 id="directory">directory: <i>PATH</i></h2> |
|
51
|
|
|
52
|
The PATH is the name of a directory that contains one or more Fossil |
|
53
|
repository files having the suffix ".fossil". If this property is |
|
54
|
used instead of [#repository|<b>repository:</b>], then the Fossil |
|
55
|
server is able to serve all of the repositories in the directory. The |
|
56
|
specific repository used is selected by a prefix on the PATH_INFO. See |
|
57
|
the notes for the [#repolist|<b>repolist</b>] option regarding name |
|
58
|
collisions between subdirectories and repository files. |
|
59
|
|
|
60
|
|
|
61
|
<h2 id="notfound">notfound: <i>URL</i></h2> |
|
62
|
|
|
63
|
If the [#directory|<b>directory:</b>] option is used and if the PATH_INFO |
|
64
|
of the HTTP request does not correspond to any Fossil repository, then |
|
65
|
the request redirects to URL. |
|
66
|
|
|
67
|
|
|
68
|
<h2 id="repolist">repolist</h2> |
|
69
|
|
|
70
|
This is a Boolean property. |
|
71
|
If it is present, and if the [#directory:|<b>directory:</b>] option is used, |
|
72
|
and if the PATH_INFO string is empty, then Fossil will show a list |
|
73
|
of available Fossil repositories. |
|
74
|
|
|
75
|
The "skin" of the reply is determined by the first |
|
76
|
repository in the list that has a non-zero |
|
77
|
[/help/repolist-skin|repolist-skin] setting. |
|
78
|
|
|
79
|
If no repository has such a non-zero repolist-skin setting, then |
|
80
|
the repository list is generic HTML without any decoration, with |
|
81
|
the page title taken from the <tt>FOSSIL_REPOLIST_TITLE</tt> |
|
82
|
environment variable. The variable can be defined in the CGI |
|
83
|
control file using the [#setenv|<tt>setenv:</tt>] statement. |
|
84
|
|
|
85
|
The "Project Description" and "Login-Group" columns on the repolist page |
|
86
|
are optional. They are hidden by default. Show them by |
|
87
|
etting the <tt>FOSSIL_REPOLIST_SHOW</tt> environment variable to |
|
88
|
a string that contains substrings "description" and/or "login-group". |
|
89
|
|
|
90
|
The repolist-generated page recurses into subdirectories and will list |
|
91
|
all <tt>*.fossil</tt> files found, with the following exceptions: |
|
92
|
|
|
93
|
* Filenames starting with a period are treated as "hidden" and skipped. |
|
94
|
|
|
95
|
* Subdirectory names which match the base name of a fossil file in |
|
96
|
the same directory are listed in the resulting page but are not |
|
97
|
hyperlinked because the links would be ambiguous and the |
|
98
|
repositories in the subdirectories would be unreachable to |
|
99
|
clients. For example, any repositories under subdirectory |
|
100
|
<tt>XYZ</tt> are unreachable if <tt>XYZ.fossil</tt> exists in |
|
101
|
the same directory as <tt>XYZ</tt>, noting that this particular |
|
102
|
name check is case-insensitive. The entries for such |
|
103
|
repositories are clearly marked in the repolist page's output to |
|
104
|
make the user aware of the problem. To make them accessible, |
|
105
|
move them into a directory which does not share a base name with |
|
106
|
a repository file. |
|
107
|
|
|
108
|
|
|
109
|
<h2 id="localauth">localauth</h2> |
|
110
|
|
|
111
|
This is a Boolean property. |
|
112
|
If it is present, [./caps/ref.html#s | setup capability] |
|
113
|
is granted to any HTTP request that |
|
114
|
comes in over a loopback interface, such as 127.0.0.1. |
|
115
|
|
|
116
|
|
|
117
|
<h2 id="skin">skin: <i>NAME</i></h2> |
|
118
|
|
|
119
|
If NAME is the name of one of the built-in skins supported by Fossil, |
|
120
|
then this option causes Fossil to display using that built-in skin, |
|
121
|
and to ignore any custom skin that might be configured in the repository |
|
122
|
itself. |
|
123
|
|
|
124
|
So, if you wanted to set up a server for a single Fossil project, but |
|
125
|
also give users the option to use several of the different built-in |
|
126
|
skins, you could create multiple CGI scripts, each with a different |
|
127
|
"<b>skin:</b>" property, but all pointing to the same <b>repository:</b>. |
|
128
|
Then users can select which skin to use by using the appropriate CGI. |
|
129
|
|
|
130
|
|
|
131
|
<h2 id="files">files: </i>GLOBLIST</i></h2> |
|
132
|
|
|
133
|
The GLOBLIST argument is a comma-separate list of "globs" that specify |
|
134
|
filenames. In [#directory|<b>directory:</b> mode], if the PATH_INFO |
|
135
|
does not identify any Fossil repository, but it does refer some other |
|
136
|
file in the directory, and that filename matches one of the glob patterns |
|
137
|
in the GLOBLIST, then the file is returned as static content. |
|
138
|
|
|
139
|
|
|
140
|
<h2 id="setenv">setenv: <i>NAME VALUE</i></h2> |
|
141
|
|
|
142
|
This parameter causes additional environment variable NAME to have VALUE. |
|
143
|
This parameter can be repeated as many times as necessary. |
|
144
|
|
|
145
|
|
|
146
|
<h2 id="HOME">HOME: <i>PATH</i></h2> |
|
147
|
|
|
148
|
This parameter is a short-hand for "<b>setenv HOME <i>PATH</i></b>". |
|
149
|
|
|
150
|
|
|
151
|
<h2 id="cgi-debug">cgi-debug: <i>FILE</i></h2> |
|
152
|
|
|
153
|
Cause CGI-related debugging information to be appended in <i>FILE</i>. Use |
|
154
|
this to help debug CGI problems. |
|
155
|
|
|
156
|
|
|
157
|
<h2 id="errorlog">errorlog: <i>FILENAME</i></h2> |
|
158
|
|
|
159
|
This setting causes the server to log any errors in FILENAME. |
|
160
|
It is ok for multiple Fossil CGIs to share the same error log. |
|
161
|
|
|
162
|
Setting up an error log for Fossil servers is not required, but it |
|
163
|
is recommended. |
|
164
|
|
|
165
|
|
|
166
|
<h2 id="timeout">timeout: <i>N</i></h2> |
|
167
|
|
|
168
|
This property changes the timeout on each CGI request to N seconds. |
|
169
|
If N is zero, then there is no timeout. If this property is omitted, |
|
170
|
then the default timeout is 300 seconds (5 minutes). |
|
171
|
|
|
172
|
|
|
173
|
<h2 id="extroot">extroot: <i>PATH</i></h2> |
|
174
|
|
|
175
|
This property defines the DOCUMENT_ROOT for the |
|
176
|
[./serverext.wiki|CGI Server Extensions]. If this property |
|
177
|
is present, then CGI Server Extensions are enabled. When this |
|
178
|
property is omitted, CGI Server Extensions are disabled. |
|
179
|
|
|
180
|
A cascade of CGI invocations can occur here. Fossil itself is |
|
181
|
started as CGI, then Fossil can turn around and invoke a sub-CGI |
|
182
|
extension. The sub-CGI extension outputs reply text, when Fossil |
|
183
|
then (optionally) augments with its own header and footer and returns |
|
184
|
to the original requestor. The property controls the DOCUMENT_ROOT |
|
185
|
of the sub-CGI. |
|
186
|
|
|
187
|
|
|
188
|
<h2 id="redirect">redirect: <i>REPO URL</i></h2> |
|
189
|
|
|
190
|
Extract the "name" query parameter and search REPO for a check-in or |
|
191
|
ticket that matches the value of "name", then redirect to URL. There |
|
192
|
can be multiple "redirect:" lines that are processed in order. If the |
|
193
|
repo name is "*", then an unconditional redirect to URL is taken. |
|
194
|
|
|
195
|
|
|
196
|
<h2 id="jsmode">jsmode: <i>VALUE</i></h2> |
|
197
|
|
|
198
|
Specifies the delivery mode for JavaScript files. See "[/help/http | |
|
199
|
http --jsmode]" for the allowed values and their meanings. |
|
200
|
|
|
201
|
|
|
202
|
<h2 id="mainmenu">mainmenu: <i>FILE</i></h2> |
|
203
|
|
|
204
|
This parameter causes the contents of the given file to override the |
|
205
|
site's <tt>mainmenu</tt> configuration setting, in much the same way |
|
206
|
that the <tt>skin</tt> setting overrides the skin. This can be used to |
|
207
|
apply a common main menu to a number of sites, and centrally maintain |
|
208
|
it, without having to copy its contents into each site. Note, however, |
|
209
|
that the contents of this setting are not stored in the repository and |
|
210
|
will not be cloned along with the repository. |
|
211
|
|