Fossil

Check-in [355c16a5]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Moved the section on stunnel configuration from www/server.wiki to www/ssl.wiki, adding links from one to the other. Also changed all remaining references to "SSL" in server.wiki to "TLS".
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 355c16a528d03e799befc20378f461053ce09724c2f2692b8a559c682a36f895
User & Date: wyoung 2019-03-17 06:42:04
Context
2019-03-17
07:01
Expanded the "Standalone server" section of www/server.wiki to add more examples. Also fixed a few grammar problems elsewhere in the doc. check-in: f153777f user: wyoung tags: trunk
06:42
Moved the section on stunnel configuration from www/server.wiki to www/ssl.wiki, adding links from one to the other. Also changed all remaining references to "SSL" in server.wiki to "TLS". check-in: 355c16a5 user: wyoung tags: trunk
06:18
Expanded the discussion of the difference between "fossil ui" and "fossil server" in www/server.wiki. check-in: 67e30333 user: wyoung tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/server.wiki.

21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
..
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
...
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174



175
176
177
178
179
180
181
...
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301



302
303
304
305
306
307
308
<h2>Overview</h2>

<blockquote>
There are basically four ways to set up a Fossil server:

<ol>
  <li>A stand-alone server
  <li>Using inetd or xinetd or stunnel
  <li>CGI
  <li>SCGI (a.k.a. SimpleCGI)
</ol>

Each of these can serve either a single repository, or a directory hierarchy
containing many repositories with names ending in ".fossil".
</blockquote>
................................................................................
the repository.

Both commands have additional command-line options that can be used to refine
their behavior.  See the [/help/server|online documentation] for an overview.
</blockquote>


<h2 id="inetd">Fossil as an inetd/xinetd or stunnel service</h2>

<blockquote>

A Fossil server can be launched on-demand by inetd or xinetd using
the [/help/http|fossil http] command. To launch Fossil from inetd, modify
your inetd configuration file (typically "/etc/inetd.conf") to contain a
line something like this:
................................................................................
but if it is done, then Fossil will automatically put itself into a chroot
jail for the user who owns the fossil repository before reading any information
off of the wire.

Inetd or xinetd must be enabled, and must be (re)started whenever their configuration
changes - consult your system's documentation for details.

[https://www.stunnel.org/ | Stunnel version 5] is an inetd-like process that
accepts and decodes SSL-encrypted connections.  Fossil can be run directly from
stunnel in a manner similar to inetd and xinetd.  This can be used to provide
a secure link to a Fossil project.  The configuration needed to get stunnel5
to invoke Fossil is very similar to the inetd and xinetd examples shown above.
The relevant parts of an stunnel configuration might look something
like the following:

<blockquote><pre><nowiki>
[https]
accept       = www.ubercool-project.org:443
TIMEOUTclose = 0
exec         = /usr/bin/fossil
execargs     = /usr/bin/fossil http /home/fossil/ubercool.fossil --https
</nowiki></pre></blockquote>

See the stunnel5 documentation for further details about the /etc/stunnel/stunnel.conf
configuration file.  Note that the [/help/http|fossil http] command should include
the --https option to let Fossil know to use "https" instead of "http" as the scheme
on generated hyperlinks.

Using inetd or xinetd or stunnel is a more complex setup
than the "standalone" server, but it has the
advantage of only using system resources when an actual connection is
attempted.  If no-one ever connects to that port, a Fossil server will
not (automatically) run. It has the disadvantage of requiring "root" access
and therefore may not normally be available to lower-priced "shared" servers
on the internet.



</blockquote>

<h2 id="cgi">Fossil as CGI</h2>

<blockquote>

A Fossil server can also be run from an ordinary web server as a CGI program.
................................................................................
would be something like this:

<blockquote><pre>
fossil server $REPOSITORY --scgi --localhost --port 9000
</pre></blockquote>
</blockquote>

<h2 id="tls">Securing a repository with SSL</h2>

<blockquote>
Using either CGI or SCGI, it is trivial to use SSL to
secure the server.  Simply set up the Fossil CGI scripts etc. as above,
but modify the Apache (or IIS, etc.) server to require SSL (that is, a
URL with "https://") in order to access the CGI script directory.  This
may also be accomplished (on Apache, at least) using appropriate
".htaccess" rules.

If you are using "inetd" to serve your repository, then you simply need
to add "/usr/bin/stunnel" (perhaps on a different path, depending on your
setup) before the command line to launch Fossil.

At this stage, the standalone server (e.g. "fossil server") does not
support SSL.

For more information, see <a href="./ssl.wiki">Using SSL with Fossil</a>.



</blockquote>

<h2 id="loadmgmt">Managing Server Load</h2>

<blockquote>
A Fossil server is very efficient and normally presents a very light
load on the server.







|







 







|







 







<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|





|
>
>
>







 







|


<
<
<
<
<
<
<
<
<
<
<
|
<
<
<
>
>
>







21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
..
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
...
140
141
142
143
144
145
146





















147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
...
259
260
261
262
263
264
265
266
267
268











269



270
271
272
273
274
275
276
277
278
279
<h2>Overview</h2>

<blockquote>
There are basically four ways to set up a Fossil server:

<ol>
  <li>A stand-alone server
  <li>Using inetd, xinetd, or stunnel
  <li>CGI
  <li>SCGI (a.k.a. SimpleCGI)
</ol>

Each of these can serve either a single repository, or a directory hierarchy
containing many repositories with names ending in ".fossil".
</blockquote>
................................................................................
the repository.

Both commands have additional command-line options that can be used to refine
their behavior.  See the [/help/server|online documentation] for an overview.
</blockquote>


<h2 id="inetd">Fossil as an inetd/xinetd service</h2>

<blockquote>

A Fossil server can be launched on-demand by inetd or xinetd using
the [/help/http|fossil http] command. To launch Fossil from inetd, modify
your inetd configuration file (typically "/etc/inetd.conf") to contain a
line something like this:
................................................................................
but if it is done, then Fossil will automatically put itself into a chroot
jail for the user who owns the fossil repository before reading any information
off of the wire.

Inetd or xinetd must be enabled, and must be (re)started whenever their configuration
changes - consult your system's documentation for details.






















Using inetd or xinetd is a more complex setup
than the "standalone" server, but it has the
advantage of only using system resources when an actual connection is
attempted.  If no-one ever connects to that port, a Fossil server will
not (automatically) run. It has the disadvantage of requiring "root" access
and therefore may not normally be available to lower-priced "shared" servers
on the Internet.

The configuration for <tt>stunnel</tt> is similar, but it is covered in
[./ssl.wiki#stunnel|a separate document].
</blockquote>

<h2 id="cgi">Fossil as CGI</h2>

<blockquote>

A Fossil server can also be run from an ordinary web server as a CGI program.
................................................................................
would be something like this:

<blockquote><pre>
fossil server $REPOSITORY --scgi --localhost --port 9000
</pre></blockquote>
</blockquote>

<h2 id="tls">Securing a repository with TLS</h2>

<blockquote>











  Fossil's built-in HTTP server (e.g. "fossil server") does not support



  TLS, but there are multiple ways to protect your Fossil server with
  TLS. All of this is covered in a separate document, <a
  href="./ssl.wiki">Using TLS-Encrypted Communications with Fossil</a>.
</blockquote>

<h2 id="loadmgmt">Managing Server Load</h2>

<blockquote>
A Fossil server is very efficient and normally presents a very light
load on the server.

Changes to www/ssl.wiki.

209
210
211
212
213
214
215
216
217
218
219



220
221
222
223
224

















225
226
227
228
229
230
231
way to serve via HTTP over TLS, a.k.a. HTTPS, even when you've linked
Fossil to OpenSSL. To serve a Fossil repository via HTTPS, you must put
it behind some kind of HTTPS proxy.


<h3 id="stunnel">stunnel Alone</h3>

Conceptually, the simplest option is to [https://www.stunnel.org/|set up
stunnel].  A typical configuration is to run Fossil as an HTTP server
bound to localhost only, then export access to it via HTTPS with stunnel
encrypting access to Fossil instance hiding behind it.




The difficulty comes in configuring it, which really wants a guide that
no one has written for us yet. Until that appears, you'll have to read
the stunnel documentation and that of your TLS certificate provider to
work out how to set this up.



















<h3 id="althttpd">stunnel + althttpd</h3>

The public SQLite and Fossil web sites can't just use stunnel + Fossil
because parts of the web site are static, served by
[https://www.sqlite.org/docsrc/file/misc/althttpd.c|a separate web







|
|
|
|
>
>
>

<
<
<
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







209
210
211
212
213
214
215
216
217
218
219
220
221
222
223



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
way to serve via HTTP over TLS, a.k.a. HTTPS, even when you've linked
Fossil to OpenSSL. To serve a Fossil repository via HTTPS, you must put
it behind some kind of HTTPS proxy.


<h3 id="stunnel">stunnel Alone</h3>

[https://www.stunnel.org/ | <tt>stunnel</tt>] is an
[https://en.wikipedia.org/wiki/Inetd | <tt>inetd</tt>]-like process that
accepts and decodes TLS-encrypted connections. It can directly proxy
Fossil communications, allowing secure TLS-encrypted communications to a
Fossil repository server. You simply need to install <tt>stunnel</tt>
and then place something like this in its main configuration file,
<tt>stunnel.conf</tt>:




<nowiki><pre>
    [https]
    accept       = www.ubercool-project.org:443
    TIMEOUTclose = 0
    exec         = /usr/bin/fossil
    execargs     = /usr/bin/fossil http /home/fossil/ubercool.fossil --https
</pre></nowiki>

The directory where that file goes varies between OSes, so check the man
pages on your system to find out where it should be locally.

See the <tt>stunnel</tt> documentation for further details about this
configuration file.

It is important that the [/help/http | <tt>fossil http</tt>] command in
that configuration include the <tt>--https</tt> option to let Fossil
know to use "<tt>https</tt>" instead of "<tt>http</tt>" as the URL
scheme on generated hyperlinks.


<h3 id="althttpd">stunnel + althttpd</h3>

The public SQLite and Fossil web sites can't just use stunnel + Fossil
because parts of the web site are static, served by
[https://www.sqlite.org/docsrc/file/misc/althttpd.c|a separate web