How To Configure A Fossil Server
Not logged in

Introduction

A server is not necessary to use Fossil, but a server does help in collaborating with peers. A Fossil server also works well as a complete website for a project. For example, the complete http://www.fossil-scm.org/ website, including the page you are now reading (but excepting the download page), is just a Fossil server displaying the content of the self-hosting repository for Fossil.

This article is a guide for setting up your own Fossil server.

Overview

There are basically four ways to set up a Fossil server:
  1. A stand-alone server
  2. Using inetd or xinetd or stunnel
  3. CGI
  4. SCGI (a.k.a. SimpleCGI)
Each of these can serve either a single repository, or a directory hierarchy containing many repositories with names ending in ".fossil".

Standalone server

The easiest way to set up a Fossil server is to use either the server or the ui commands:
  • fossil server REPOSITORY
  • fossil ui REPOSITORY

The REPOSITORY argument is either the name of the repository file, or a directory containing many repositories. Both of these commands start a Fossil server, usually on TCP port 8080, though a higher numbered port might also be used if 8080 is already occupied. You can access these using URLs of the form http://localhost:8080/, or if REPOSITORY is a directory, URLs of the form http://localhost:8080/repo/ where repo is the base name of the repository file without the ".fossil" suffix. The difference between "ui" and "server" is that "ui" will also start a web browser and points it to the URL mentioned above, and "ui" command binds to the loopback IP address (127.0.0.1) only so that the "ui" command cannot be used to serve content to a different machine.

If one of the commands above is run from within an option checkout, then the REPOSITORY argument can be omitted and the checkout is used as the repository.

Both commands have additional command-line options that can be used to refine their behavior. See the online documentation for an overview.

Fossil as an inetd/xinetd or stunnel service

A Fossil server can be launched on-demand by inetd or xinetd using the fossil http command. To launch Fossil from inetd, modify your inetd configuration file (typically "/etc/inetd.conf") to contain a line something like this:

12345 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil
In this example, you are telling "inetd" that when an incoming connection appears on port "12345", that it should launch the binary "/usr/bin/fossil" program with the arguments shown. Obviously you will need to modify the pathnames parts as appropriate for your particular setup. The final argument is either the name of the fossil repository to be served, or a directory containing multiple repositories.

If you system is running xinetd, then the configuration is likely to be in the file "/etc/xinetd.conf" or in a subfile of "/etc/xinetd.d". An xinetd configuration file will appear like this:

service http-alt
{
  port = 591
  socket_type = stream
  wait = no
  user = root
  server = /usr/bin/fossil
  server_args = http /home/fossil/repos/
}

The xinetd example above has Fossil configured to serve multiple repositories, contained under the "/home/fossil/repos/" directory.

In both cases notice that Fossil was launched as root. This is not required, 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.

Stunnel version 4 is an inetd-like process that accepts and decodes SSL-encrypted connections. Fossil can be run directly from stunnel in a mannar similar to inetd and xinetd. This can be used to provide a secure link to a Fossil project. The configuration needed to get stunnel4 to invoke Fossil is very similar to the inetd and xinetd examples shown above. See the stunnel4 documentation for details.

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.

Fossil as CGI

A Fossil server can also be run from an ordinary web server as a CGI program. This feature allows Fossil to be seamlessly integrated into a larger website. CGI is how the self-hosting fossil repositories are implemented.

To run Fossil as CGI, create a CGI script (here called "repo") in the CGI directory of your web server and having content like this:

#!/usr/bin/fossil
repository: /home/fossil/repo.fossil

As always, adjust your paths appropriately. It may be necessary to set permissions properly, or to modify an ".htaccess" file or other server-specific things like that. Consult the documentation for your particular server.

Once the script is set up correctly, and assuming your server is also set correctly, you should be able to access your repository with a URL like: http://mydomain.org/cgi-bin/repo (assuming the "repo" script is accessible under "cgi-bin", which would be a typical deployment on Apache for instance).

To server multiple repositories from a directory using CGI, use the "directory:" tag in the CGI script rather than "repository:". You might also want to add a "notfound:" tag to tell where to redirect if the particular repository requested by the URL is not found:

#!/usr/bin/fossil
directory: /home/fossil/repos
notfound: http://url-to-go-to-if-repo-not-found/

Once deployed, a URL like: http://mydomain.org/cgi-bin/repo/XYZ will serve up the repository "/home/fossil/repos/XYX.fossil" (if it exists).

Fossil as SCGI

The fossil server command, described above as a way of starting a stand-alone web server, can also be used for SCGI. Simply add the --scgi command-line option and the stand-alone server will interpret and respond to the SimpleCGI or SCGI protocol rather than raw HTTP. This can be used in combination with a webserver (such as Nginx) that does not support CGI. A typical Nginx configuration to support SCGI with Fossil would look something like this:

location ~ ^/demo_project/ {
    include scgi_params;
    scgi_pass localhost:9000;
    scgi_param SCRIPT_NAME "/demo_project";
}

Note that Fossil requires the SCRIPT_NAME variable in order to function properly, but Nginx does not provide this variable by default. So it is necessary to provide the SCRIPT_NAME parameter in the configuration. Failure to do this will cause Fossil to return an error.

All of the features of the stand-alone server mode described above, such as the ability to server a directory full of Fossil repositories rather than just a single repository, work the same way in SCGI mode.

Securing a repository with SSL

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 Using SSL with Fossil.

Various security concerns with hosted repositories

There are two main concerns relating to usage of Fossil for sharing sensitive information (source or any other data):

  • Interception of the Fossil synchronization stream, thereby capturing data, and
  • Direct access to the Fossil repository on the server

Regarding the first, it is adequate to secure the server using SSL, and disallowing any non-SSL access. The data stream will be encrypted by the HTTPS protocol, rendering the data reasonably secure. The truly paranoid may wish to deploy ssh encrypted tunnels, but that is quite a bit more difficult and cumbersome to set up (particularly for a larger number of users).

As far as direct access to the repository, the same steps must be taken as for any other internet-facing data-store. Access passwords to any disk-accessing accounts should be strong (and preferably changed from time to time). However, the data in the repository itself are not encrypted (unless you save encrypted data yourself), and so the system administrators of your server will be able to access your data (as with any hosting service setup). The only workaround in this case is to host the server yourself, in which case you will need to allocate resources to deal with administration issues.