The [./selfhost.wiki | self-hosting fossil repositories] use
CGI.
DELETED www/server.wiki
Index: www/server.wiki
==================================================================
--- www/server.wiki
+++ /dev/null
@@ -1,400 +0,0 @@
-
-
-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 [./selfhost.wiki | 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 make other server-specific changes. Consult the documentation
-for your particular web server. In particular, the following permissions are
-normally required (but, again, may be different for a particular
-configuration):
-
-
- - The Fossil binary (/usr/bin/fossil in the example above)
- must be readable/executable, and ALL directories leading up to it
- must be readable by the process which executes the CGI.
- - ALL directories leading to the CGI script must also be readable and the CGI
- script itself must be executable for the user under which it will run (which often differs
- from the one running the web server - consult your site's documentation or administrator).
- - The repository file AND the directory containing it must be writable by the same account
- which executes the Fossil binary (again, this might differ from the WWW user). The directory
- needs to be writable so that SQLite can write its journal files.
- - Fossil must be able to create temporary files, the default directory
- for which depends on the OS. When the CGI process is operating within
- a chroot, ensure that this directory exists and is readable/writeable
- by the user who executes the Fossil binary.
-
-
-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 serve 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/XYZ.fossil" (if it exists).
-
-Additional options available to the CGI script are
-[./cgi.wiki|documented separately].
-
-Note that Fossil itself can be launched as CGI, as described here. But
-Fossil can also launch [./serverext.wiki|sub-CGIs to implement server extensions].
-Do not confuse these two concepts. Note also that the
-[./serverext.wiki|sub-CGI mechanism] works regardless of how the main
-Fossil server is launched.
-
-Fossil as SCGI
-
-
-The [/help/server|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 web server (such as [http://nginx.org|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";
- scgi_param HTTPS "on";
-}
-
-
-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 serve a directory full of Fossil repositories
-rather than just a single repository, work the same way in SCGI mode.
-
-For security, it is probably a good idea to add the --localhost option
-to the [/help/server|fossil server] command to prevent Fossil from accepting
-off-site connections. One might also want to specify the listening TCP port
-number, rather than letting Fossil choose one for itself, just to avoid
-ambiguity. A typical command to start a Fossil SCGI server
-would be something like this:
-
-
-fossil server $REPOSITORY --scgi --localhost --port 9000
-
-
-
-Securing a repository with TLS
-
-
- 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, Using TLS-Encrypted Communications with Fossil.
-
-
-Managing Server Load
-
-
-A Fossil server is very efficient and normally presents a very light
-load on the server.
-The Fossil [./selfhost.wiki | self-hosting server] is a 1/24th slice VM at
-[http://www.linode.com | Linode.com] hosting 65 other repositories in
-addition to Fossil (and including some very high-traffic sites such
-as [http://www.sqlite.org] and [http://system.data.sqlite.org]) and
-it has a typical load of 0.05 to 0.1. A single HTTP request to Fossil
-normally takes less than 10 milliseconds of CPU time to complete, so
-requests can be arriving at a continuous rate of 20 or more per second,
-and the CPU can still be mostly idle.
-
-However, there are some Fossil web pages that can consume large
-amounts of CPU time, especially on repositories with a large number
-of files or with long revision histories. High CPU usage pages include
-[/help?cmd=/zip | /zip], [/help?cmd=/tarball | /tarball],
-[/help?cmd=/annotate | /annotate] and others. On very large repositories,
-these commands can take 15 seconds or more of CPU time.
-If these kinds of requests arrive too quickly, the load average on the
-server can grow dramatically, making the server unresponsive.
-
-Fossil provides two capabilities to help avoid server overload problems
-due to excessive requests to expensive pages:
-
-
- An optional cache is available that remembers the 10 most recently
- requested /zip or /tarball pages and returns the precomputed answer
- if the same page is requested again.
- Page requests can be configured to fail with a
- [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4 | "503 Server Overload"]
- HTTP error if an expensive request is received while the host load
- average is too high.
-
-
-Both of these load-control mechanisms are turned off by default, but they
-are recommended for high-traffic sites.
-
-The webpage cache is activated using the [/help?cmd=cache|fossil cache init]
-command-line on the server. Add a -R option to specify the specific repository
-for which to enable caching. If running this command as root, be sure to
-"chown" the cache database (which is a separate file in the same directory
-and with the same name as the repository but with the suffix changed to ".cache")
-to give it write permission for the userid of the web server.
-
-To activate the server load control feature
-visit the Admin → Access setup page in the administrative web
-interface; in the "Server Load Average Limit" box
-enter the load average threshold above which "503 Server
-Overload" replies will be issued for expensive requests. On the
-self-hosting Fossil server, that value is set to 1.5, but you could easily
-set it higher on a multi-core server.
-
-The maximum load average can also be set on the command line using
-commands like this:
-
-fossil set max-loadavg 1.5
-fossil all set max-loadavg 1.5
-
-
-The second form is especially useful for changing the maximum load average
-simultaneously on a large number of repositories.
-
-Note that this load-average limiting feature is only available on operating
-systems that support the "getloadavg()" API. Most modern Unix systems have
-this interface, but Windows does not, so the feature will not work on Windows.
-Note also that Linux implements "getloadavg()" by accessing the "/proc/loadavg"
-file in the "proc" virtual file system. If you are running a Fossil instance
-inside a chroot() jail on Linux, you will need to make the "/proc" file
-system available inside that jail in order for this feature to work. On
-the [./selfhost.wiki|self-hosting Fossil repositories], this was accomplished
-by adding a line to the "/etc/fstab" file that looks like:
-
-
-chroot_jail_proc /home/www/proc proc ro 0 0
-
-
-The /home/www/proc pathname should be adjusted so that the "/proc" component is
-in the root of the chroot jail, of course.
-
-To see if the load-average limiter is functional, visit the [/test_env] page
-of the server to view the current load average. If the value for the load
-average is greater than zero, that means that it is possible to activate
-the load-average limiter on that repository. If the load average shows
-exactly "0.0", then that means that Fossil is unable to find the load average
-(either because it is in a chroot() jail without /proc access, or because
-it is running on a system that does not support "getloadavg()") and so the
-load-average limiter will not function.
-
-
ADDED www/server/any/althttpd.md
Index: www/server/any/althttpd.md
==================================================================
--- /dev/null
+++ www/server/any/althttpd.md
@@ -0,0 +1,37 @@
+# Serving via althttpd
+
+The public SQLite and Fossil web sites are not purely served by Fossil
+for two reasons:
+
+1. We want access to these sites to be secured with TLS, which we do
+ [via `stunnel`](./stunnel.md).
+
+2. Parts of these web sites are static, stored as plain files on disk,
+ not as Fossil artifacts. We serve such files using a separate web
+ server called [`althttpd`][ah], written by the primary author of
+ both SQLite and Fossil, D. Richard Hipp. `althttpd` is a lightweight
+ HTTP-only web server. It handles the static HTTP hits on
+ sqlite.org and fossil-scm.org, delegating HTTPS
+ hits to `stunnel` and dynamic content hits to Fossil [via
+ CGI][cgi].
+
+The largest single chunk of static content served directly by `althttpd`
+rather than via Fossil is the [SQLite documentation][sd], which is built
+[from source files][ds]. We don’t want those output files stored in
+Fossil; we already keep that process’s *input* files in Fossil. Thus the
+choice to serve the output statically.
+
+In addition to the [server’s documentation page][ah], there is a large,
+helpful header comment in the server’s [single-file C
+implementation][ac]. Between that and the generic [Serving via CGI][cgi]
+docs, you should be able to figure out how to serve Fossil via
+`althttpd`.
+
+*[Return to the top-level Fossil server article.](../)*
+
+
+[ac]: https://sqlite.org/docsrc/file/misc/althttpd.c
+[ah]: https://sqlite.org/docsrc/doc/trunk/misc/althttpd.md
+[cgi]: ./cgi.md
+[ds]: https://sqlite.org/docsrc/
+[sd]: https://sqlite.org/docs.html
ADDED www/server/any/cgi.md
Index: www/server/any/cgi.md
==================================================================
--- /dev/null
+++ www/server/any/cgi.md
@@ -0,0 +1,68 @@
+# Serving via CGI
+
+A Fossil server can be run from most ordinary web servers as a CGI
+program. This feature allows Fossil to seamlessly integrate into a
+larger website. We use CGI for the [self-hosting Fossil repository web
+site](../../selfhost.wiki).
+
+To run Fossil as CGI, create a CGI script (here called "repo") in the
+CGI directory of your web server with content like this:
+
+ #!/usr/bin/fossil
+ repository: /home/fossil/repo.fossil
+
+Adjust the paths appropriately. It may be necessary to set certain
+permissions on this file or to modify an `.htaccess` file or make other
+server-specific changes. Consult the documentation for your particular
+web server. The following permissions are *normally* required, but,
+again, may be different for a particular configuration:
+
+* The Fossil binary (`/usr/bin/fossil` in the example above)
+ must be readable/executable.
+
+* *All* directories leading up to the Fossil binary must be readable
+ by the process which executes the CGI.
+
+* The CGI script must be executable for the user under which it will
+ run, which often differs from the one running the web server.
+ Consult your site's documentation or the web server’s system
+ administrator.
+
+* *All* directories leading to the CGI script must be readable by the
+ web server.
+
+* The repository file *and* the directory containing it must be
+ writable by the same account which executes the Fossil binary.
+ (This might differ from the user the web server normally runs
+ under.) The directory holding the repository file(s) needs to be
+ writable so that SQLite can write its journal files.
+
+* Fossil must be able to create temporary files in a
+ [directory that varies by host OS](../../env-opts.md#temp). When the
+ CGI process is operating [within a chroot](../../chroot.md),
+ ensure that this directory exists and is readable/writeable by the
+ user who executes the Fossil binary.
+
+Once the CGI 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 This is assuming you
+are running a web server like Apache that uses a “`cgi-bin`” directory
+for scripts like our “`repo`” example.
+
+To serve 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/XYZ.fossil` if it
+exists.
+
+Additional options available to the CGI script are [documented
+separately](../../cgi.wiki).
+
+*[Return to the top-level Fossil server article.](../)*
ADDED www/server/any/inetd.md
Index: www/server/any/inetd.md
==================================================================
--- /dev/null
+++ www/server/any/inetd.md
@@ -0,0 +1,52 @@
+# Serving via inetd
+
+A Fossil server can be launched on-demand by `inetd` by using the
+[`fossil http`](/help/http) command. To do so, add a line like the
+following to its configuration file, typically `/etc/inetd.conf`:
+
+ 80 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 TCP port 80 that it should launch the program
+`/usr/bin/fossil` with the arguments shown. Obviously you will need to
+modify the pathnames 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 use a non-standard TCP port on systems where the port
+specification must be a symbolic name and cannot be numeric, add the
+desired name and port to `/etc/services`. For example, if you want your
+Fossil server running on TCP port 12345 instead of 80, you will need to
+add:
+
+ fossil 12345/tcp # fossil server
+
+and use the symbolic name “`fossil`” instead of the numeric TCP port
+number (“12345” in the above example) in `inetd.conf`.
+
+Notice that we configured `inetd` to launch Fossil as root. See the
+top-level section on “[The Fossil Chroot
+Jail](../../chroot.md)” for the consequences of this and
+alternatives to it.
+
+You can instead configure `inetd` to bind to a higher-numbered TCP port,
+allowing Fossil to be run as a normal user. In that case, Fossil will
+not put itself into a chroot jail, because it assumes you have set up
+file permissions and such on the server appropriate for that user.
+
+The `inetd` daemon must be enabled for this to work, and it must be
+restarted whenever its configuration file changes.
+
+This is a more complicated method than the [standalone HTTP server
+method](./none.md), 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, which may not be
+available to you, either due to local IT policy or because of
+restrictions at your shared Internet hosting service.
+
+For further details, see the relevant section in your system's
+documentation. The FreeBSD Handbook covers `inetd` in [this
+chapter](https://www.freebsd.org/doc/en/books/handbook/network-inetd.html).
+
+*[Return to the top-level Fossil server article.](../)*
ADDED www/server/any/none.md
Index: www/server/any/none.md
==================================================================
--- /dev/null
+++ www/server/any/none.md
@@ -0,0 +1,51 @@
+# Standalone HTTP Server
+
+The easiest way to set up a Fossil server is to use either the
+[`server`](/help/server) or [`ui`](/help/ui) command:
+
+* **fossil server** _REPOSITORY_
+* **fossil ui** _REPOSITORY_
+
+The _REPOSITORY_ argument is either the name of the repository file or a
+directory containing many repositories named “`*.fossil`”. Both of these
+commands start a Fossil server, usually on TCP port 8080, though a
+higher numbered port will be used instead 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.
+
+There are several key differences between “`ui`” and “`server`”:
+
+* “`ui`” always binds the server to the loopback IP address (127.0.0.1)
+ so that it cannot serve to other machines.
+
+* Anyone who visits this URL is treated as the all-powerful Setup
+ user, which is why the first difference exists.
+
+* “`ui`” launches a local web browser pointed at this URL.
+
+You can omit the _REPOSITORY_ argument if you run one of the above
+commands from within a Fossil checkout directory to serve that
+repository:
+
+ $ fossil ui # or...
+ $ fossil server
+
+You can abbreviate Fossil sub-commands as long as they are unambiguous.
+“`server`” can currently be as short as “`ser`”.
+
+You can serve a directory containing multiple `*.fossil` files like so:
+
+ $ fossil server --port 9000 --repolist /path/to/repo/dir
+
+There is an [example script](/file/tools/fslsrv) in the Fossil
+distribution that wraps `fossil server` to produce more complicated
+effects. Feel free to take it, study it, and modify it to suit your
+local needs.
+
+See the [online documentation](/help/server) for more information on the
+options and arguments you can give to these commands.
+
+*[Return to the top-level Fossil server article.](../)*
ADDED www/server/any/scgi.md
Index: www/server/any/scgi.md
==================================================================
--- /dev/null
+++ www/server/any/scgi.md
@@ -0,0 +1,56 @@
+# Serving via SCGI
+
+There is an alternative to running Fossil as a [standalone HTTP
+server](./none.md), which is to run it in SimpleCGI (a.k.a. SCGI) mode,
+which uses the same [`fossil server`](/help/server) command as for HTTP
+service. Simply add the `--scgi` command-line option and the stand-alone
+server will speak the SCGI protocol rather than raw HTTP.
+
+This can be used with a web server such as [nginx](http://nginx.org)
+which does not support [Fossil’s CGI mode](./cgi.md).
+
+A basic nginx configuration to support SCGI with Fossil looks like this:
+
+ location /example/ {
+ include scgi_params;
+ scgi_pass localhost:9000;
+ scgi_param SCRIPT_NAME "/example";
+ scgi_param HTTPS "on";
+ }
+
+Start Fossil so that it will respond to nginx’s SCGI calls like this:
+
+ fossil server /path/to/repo.fossil --scgi --localhost --port 9000
+
+The `--scgi` option switches Fossil into SCGI mode from its default,
+which is [stand-alone HTTP server mode](./none.md). All of the other
+options discussed in that linked document — such as the ability to serve
+a directory full of Fossil repositories rather than just a single
+repository — work the same way in SCGI mode.
+
+The `--localhost` option is simply good security: we’re using nginx to
+expose Fossil service to the outside world, so there is no good reason
+to allow outsiders to contact this Fossil SCGI server directly.
+
+Giving an explicit non-default TCP port number via `--port` is a good
+idea to avoid conflicts with use of Fossil’s default TCP service port,
+8080, which may conflict with local uses of `fossil ui` and such.
+
+Fossil requires the `SCRIPT_NAME` environment variable in order to
+function properly, but nginx does not provide this variable by default,
+so it is necessary to provide it in the configuration. Failure to do
+this will cause Fossil to return an error.
+
+The [example `fslsrv` script](/file/tools/fslsrv) shows off these same
+concepts in a more complicated setting. You might want to mine that
+script for ideas.
+
+You might want to next read one of the platform-specific versions of this
+document, which goes into more detail:
+
+* [Debian/Ubuntu](../debian/nginx.md)
+
+There is a [separate article](../../tls-nginx.md) showing how to add TLS
+encryption to this basic SCGI + nginx setup.
+
+*[Return to the top-level Fossil server article.](../)*
ADDED www/server/any/stunnel.md
Index: www/server/any/stunnel.md
==================================================================
--- /dev/null
+++ www/server/any/stunnel.md
@@ -0,0 +1,79 @@
+# Serving via stunnel
+
+[`stunnel`](https://www.stunnel.org/) is a TLS/SSL proxy for programs
+that themselves serve only via HTTP, such as Fossil. (Fossil *can* speak
+HTTPS, but only as a client.) `stunnel` decodes the HTTPS data from the
+outside world as HTTP before passing it to Fossil, and it encodes the
+HTTP replies from Fossil as HTTPS before sending them to the remote host
+that made the request.
+
+You can run `stunnel` in one of two modes: socket listener — much like
+in our [`inetd` doc](./inetd.md) — and as an HTTP reverse proxy. We’ll
+cover both cases here, separately.
+
+
+## Socket Activation
+
+The following `stunnel.conf` configuration configures it to run Fossil
+in socket listener mode, launching Fossil only when an HTTPS hit comes
+in, then shutting it back down as soon as the transaction is complete:
+
+```dosini
+ [fossil]
+ accept = 443
+ TIMEOUTclose = 0
+ exec = /usr/bin/fossil
+ execargs = /usr/bin/fossil http /home/fossil/ubercool.fossil --https
+ cert = /etc/letsencrypt/live/ubercool-project.org/fullchain.pem
+ key = /etc/letsencrypt/live/ubercool-project.org/privkey.pem
+ ciphers = ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES128-SHA:DES-CBC3-SHA
+ options = CIPHER_SERVER_PREFERENCE
+```
+
+This configuration shows the TLS certificate generated by the [Let’s
+Encrypt](https://letsencrypt.org) [Certbot](https://certbot.eff.org) in
+[certonly mode](https://certbot.eff.org/lets-encrypt/debianbuster-other).
+There are other ways to get TLS certificates, but this is a popular and
+free option.
+
+You will need to adjust the site names and paths in this example. Where
+this file goes varies by OS type, so check the man pages on your system
+to find out where it should be locally.
+
+See the `stunnel` documentation for further details about this
+configuration file.
+
+It is important that the [`fossil http`](/help/http) command in that
+configuration include the `--https` option to let Fossil know to use
+“`https://`” instead of “`http://`” in generated hyperlinks.
+
+
+
+## Reverse Proxy
+
+You can instead have Fossil running in the background in [standalone
+HTTP server mode](./none.md), bound to a high random TCP port number on
+localhost via the `--localhost` and `--port` flags, then configure
+`stunnel` to reverse proxy public HTTPS connections down to it via HTTP.
+
+The configuration is the same as the above except that you drop the
+`exec` and `execargs` directives and add this instead:
+
+```dosini
+ connect = 9000
+```
+
+That tells `stunnel` to connect to an already-running process listening
+on the given TCP port number.
+
+There are a few advantages to this mode:
+
+1. At the cost of some server memory and a tiny bit of idle CPU time,
+ Fossil remains running so that hits can be served a smidge faster
+ than in socket listener mode, where the Fossil binary has to be
+ loaded and re-initialized on each HTTPS hit.
+
+2. The socket listener mode doesn’t work on all platforms that
+ `stunnel` runs on, particularly [on Windows](../windows/stunnel.md).
+
+*[Return to the top-level Fossil server article.](../)*
ADDED www/server/any/xinetd.md
Index: www/server/any/xinetd.md
==================================================================
--- /dev/null
+++ www/server/any/xinetd.md
@@ -0,0 +1,27 @@
+# Serving via xinetd
+
+Some operating systems have replaced the old Unix `inetd` daemon with
+`xinetd`, which has a similar mission but with a very different
+configuration file format.
+
+The typical configuration file is either `/etc/xinetd.conf` or a subfile
+in the `/etc/xinetd.d` directory. You need a configuration something
+like this for Fossil:
+
+ service http
+ {
+ port = 80
+ socket_type = stream
+ wait = no
+ user = root
+ server = /usr/bin/fossil
+ server_args = http /home/fossil/repos/
+ }
+
+This example configures Fossil to serve multiple repositories under the
+`/home/fossil/repos/` directory.
+
+Beyond this, see the general commentary in our article on [the `inetd`
+method](./inetd.md) as they also apply to service via `xinetd`.
+
+*[Return to the top-level Fossil server article.](../)*
ADDED www/server/debian/nginx.md
Index: www/server/debian/nginx.md
==================================================================
--- /dev/null
+++ www/server/debian/nginx.md
@@ -0,0 +1,230 @@
+# Serving via nginx on Debian and Ubuntu
+
+This document is an extension of [the platform-independent SCGI
+instructions][scgii], which may suffice for your purposes if your needs
+are simple.
+
+Here, we add more detailed information on nginx itself, plus details
+about running it on Debian type OSes. We focus on Debian 10 (Buster) and
+Ubuntu 18.04 here, which are common Tier 1 OS offerings for [virtual
+private servers][vps]. This material may not work for older OSes. It is
+known in particular to not work as given for Debian 9 and older!
+
+If you want to add TLS to this configuration, that is covered [in a
+separate document][tls] which was written with the assumption that
+you’ve read this first.
+
+[scgii]: ../any/scgi.md
+[tls]: ../../tls-nginx.md
+[vps]: https://en.wikipedia.org/wiki/Virtual_private_server
+
+
+## Benefits
+
+This scheme is considerably more complicated than the [standalone HTTP
+server](../any/none.md) and [CGI options](../any/cgi.md). Even with the
+benefit of this guide and pre-built binary packages, it requires quite a
+bit of work to set it up. Why should you put up with this complexity?
+Because it gives many benefits that are difficult or impossible to get
+with the less complicated options:
+
+* **Power** — nginx is one of the most powerful web servers in the
+ world. The chance that you will run into a web serving wall that you
+ can’t scale with nginx is very low.
+
+ To give you some idea of the sort of thing you can readily
+ accomplish with nginx, your author runs a single public web server
+ that provides transparent name-based virtual hosting for four
+ separate domains:
+
+ * One is entirely static, not involving any dynamic content or
+ Fossil integration at all.
+
+ * Another is served almost entirely by Fossil, with a few select
+ static content exceptions punched past Fossil, which are handled
+ entirely via nginx.
+
+ * The other two domains are aliases for one another — e.g.
+ `example.com` and `example.net` — with most of the content being
+ static. This pair of domains has three different Fossil repo
+ proxies attached to various sections of the URI hierarchy.
+
+ By using nginx, I was able to do all of the above with minimal
+ repetition between the site configurations.
+
+* **Integration** — Because nginx is so popular, it integrates with
+many different technologies, and many other systems integrate with it in
+turn. This makes it great middleware, sitting between the outer web
+world and interior site services like Fossil. It allows Fossil to
+participate seamlessly as part of a larger web stack.
+
+* **Availability** — nginx is already in most operating system binary
+package repositories, so you don’t need to go out of your way to get it.
+
+
+## Fossil Service Modes
+
+Fossil provides four major ways to access a repository it’s serving
+remotely, three of which are straightforward to use with nginx:
+
+* **HTTP** — Fossil has a built-in HTTP server: [`fossil
+ server`](/help/server). While this method is efficient and it’s
+ possible to use nginx to proxy access to another HTTP server, this
+ option is overkill for our purposes. nginx is itself a fully
+ featured HTTP server, so we will choose in this guide not to make
+ nginx reinterpret Fossil’s implementation of HTTP.
+
+* **CGI** — This method is simple but inefficient, because it launches
+ a separate Fossil instance on every HTTP hit.
+
+ Since Fossil is a relatively small self-contained program, and it’s
+ designed to start up quickly, this method can work well in a
+ surprisingly large number of cases.
+
+ Nevertheless, we will avoid this option in this document because
+ we’re already buying into a certain amount of complexity here in
+ order to gain power. There’s no sense in throwing away any of that
+ hard-won performance on CGI overhead.
+
+* **SCGI** — The [SCGI protocol][scgip] provides the simplicity of CGI
+ without its performance problems.
+
+* **SSH** — This method exists primarily to avoid the need for HTTPS,
+ but we *want* HTTPS. (We’ll get to that in [another document][tls].)
+ There is probably a way to get nginx to proxy Fossil to HTTPS via
+ SSH, but it would be pointlessly complicated.
+
+SCGI it is, then.
+
+[scgip]: https://en.wikipedia.org/wiki/Simple_Common_Gateway_Interface
+
+
+## Installing the Dependencies
+
+The first step is to install some non-default packages we’ll need. SSH into
+your server, then say:
+
+ $ sudo apt install fossil nginx
+
+
+## Running Fossil in SCGI Mode
+
+I run my Fossil SCGI server instances with a variant of [the `fslsrv`
+shell script](/file/tools/fslsrv) currently hosted in the Fossil source
+code repository. You’ll want to download that and make a copy of it, so
+you can customize it to your particular needs.
+
+This script allows running multiple Fossil SCGI servers, one per
+repository, each bound to a different high-numbered `localhost` port, so
+that only nginx can see and proxy them out to the public. The
+“`example`” repo is on TCP port localhost:12345, and the “`foo`” repo is
+on localhost:12346.
+
+As written, the `fslsrv` script expects repositories to be stored in the
+calling user’s home directory under `~/museum`, because where else do
+you keep Fossils?
+
+That home directory also needs to have a directory to hold log files,
+`~/log/fossil/*.log`. Fossil doesn’t put out much logging, but when it
+does, it’s better to have it captured than to need to re-create the
+problem after the fact.
+
+The use of `--baseurl` in this script lets us have each Fossil
+repository mounted in a different location in the URL scheme. Here, for
+example, we’re saying that the “`example`” repository is hosted under
+the `/code` URI on its domains, but that the “`foo`” repo is hosted at
+the top level of its domain. You’ll want to do something like the
+former for a Fossil repo that’s just one piece of a larger site, but the
+latter for a repo that is basically the whole point of the site.
+
+You might also want another script to automate the update, build, and
+deployment steps for new Fossil versions:
+
+ #!/bin/sh
+ cd $HOME/src/fossil/trunk
+ fossil up
+ make -j11
+ killall fossil
+ sudo make install
+ fslsrv
+
+The `killall fossil` step is needed only on OSes that refuse to let you
+replace a running binary on disk.
+
+As written, the `fslsrv` script assumes a Linux environment. It expects
+`/bin/bash` to exist, and it depends on non-POSIX tools like `pgrep`.
+It should not be difficult to port to systems like macOS or the BSDs.
+
+
+## Configuration
+
+On Debian and Ubuntu systems the primary user-level configuration file
+for nginx is `/etc/nginx/sites-enabled/default`. I recommend that this
+file contain only a list of include statements, one for each site that
+server hosts:
+
+ include local/example
+ include local/foo
+
+Those files then each define one domain’s configuration. Here,
+`/etc/nginx/local/example` contains the configuration for
+`*.example.com` and `*.example.net`; and `local/foo` contains the
+configuration for `*.foo.net`.
+
+The configuration for our `foo.net` web site, stored in
+`/etc/nginx/sites-enabled/local/foo` is:
+
+ server {
+ server_name .foo.net;
+ include local/generic;
+
+ access_log /var/log/nginx/foo.net-https-access.log;
+ error_log /var/log/nginx/foo.net-https-error.log;
+
+ # Bypass Fossil for the static Doxygen docs
+ location /doc/html {
+ root /var/www/foo.net;
+
+ location ~* \.(html|ico|css|js|gif|jpg|png)$ {
+ expires 7d;
+ add_header Vary Accept-Encoding;
+ access_log off;
+ }
+ }
+
+ # Redirect everything else to the Fossil instance
+ location / {
+ include scgi_params;
+ scgi_pass 127.0.0.1:12345;
+ scgi_param HTTPS "on";
+ scgi_param SCRIPT_NAME "";
+ }
+ }
+
+As you can see, this is a simple extension of [the basic nginx service
+configuration for SCGI][scgii], showing off a few ideas you might want to
+try on your own site, such as static asset proxying.
+
+The `local/generic` file referenced above helps us reduce unnecessary
+repetition among the multiple sites this configuration hosts:
+
+ root /var/www/$host;
+
+ listen 80;
+ listen [::]:80;
+
+ charset utf-8;
+
+There are some configuration directives that nginx refuses to substitute
+variables into, citing performance considerations, so there is a limit
+to how much repetition you can squeeze out this way. One such example is
+the `access_log` and `error_log` directives, which follow an obvious
+pattern from one host to the next. Sadly, you must tolerate some
+repetition across `server { }` blocks when setting up multiple domains
+on a single server.
+
+The configuration for `example.com` and `example.net` is similar.
+
+See [the nginx docs](http://nginx.org/en/docs/) for more ideas.
+
+*[Return to the top-level Fossil server article.](../)*
ADDED www/server/debian/service.md
Index: www/server/debian/service.md
==================================================================
--- /dev/null
+++ www/server/debian/service.md
@@ -0,0 +1,184 @@
+# Serving via systemd on Debian and Ubuntu
+
+[`systemd`][sdhome] is the default service management framework on
+Debian [since version 8][wpa] and Ubuntu since version 15.04, both
+released in April 2015.
+
+There are multiple ways to get a service to launch under `systemd`.
+We’re going to show two methods which correspond approximately to two of
+our generic Fossil server setup methods, the [`inetd`](../any/inetd.md)
+and [standalone HTTP server](../any/none.md) methods.
+
+[sdhome]: https://www.freedesktop.org/wiki/Software/systemd/
+[wpa]: https://en.wikipedia.org/wiki/Systemd#Adoption
+
+
+
+## User Service
+
+A fun thing you can easily do with `systemd` that you can’t directly do
+with older technologies like `inetd` and `xinetd` is to set a server up
+as a “user” service.
+
+You can’t listen on TCP port 80 with this method due to security
+restrictions on TCP ports in every OS where `systemd` runs, but you can
+create a listener socket on a high-numbered (≥ 1024) TCP port,
+suitable for sharing a Fossil repo to a workgroup on a private LAN.
+
+To do this, write the following in
+`~/.local/share/systemd/user/fossil.service`:
+
+```dosini
+ [Unit]
+ Description=Fossil user server
+ After=network.target
+
+ [Service]
+ WorkingDirectory=/home/fossil/museum
+ ExecStart=/home/fossil/bin/fossil server --port 9000 repo.fossil
+ Restart=always
+ RestartSec=3
+
+ [Install]
+ WantedBy=sockets.target
+ WantedBy=multi-user.target
+```
+
+Unlike with `inetd` and `xinetd`, we don’t need to tell `systemd` which
+user and group to run this service as, because we’ve installed it as a
+user service under the account we’re logged into.
+
+We’ve told `systemd` that we want automatic service restarts with
+back-off logic, making this much more robust than the by-hand launches
+of `fossil` in the platform-independent Fossil server instructions. The
+service will stay up until we explicitly tell it to shut down.
+
+Because we’ve set this up as a user service, the commands you give to
+manipulate the service vary somewhat from the sort you’re more likely to
+find online:
+
+ $ systemctl --user daemon-reload
+ $ systemctl --user enable fossil
+ $ systemctl --user start fossil
+ $ systemctl --user status -l fossil
+ $ systemctl --user stop fossil
+
+That is, we don’t need to talk to `systemd` with `sudo` privileges, but
+we do need to tell it to look at the user configuration rather than the
+system-level configuration.
+
+This scheme isolates the permissions needed by the Fossil server, which
+reduces the amount of damage it can do if there is ever a
+remotely-triggerable security flaw found in Fossil.
+
+A simple and useful modification to the above scheme is to add the
+`--scgi` and `--localhost` flags to the `ExecStart` line to replace the
+use of `fslsrv` in [the generic SCGI instructions](../any/scgi.md),
+giving a much more robust configuration.
+
+
+## Socket Activation
+
+Another useful method to serve a Fossil repo via `systemd` is via a
+socket listener, which `systemd` calls “[socket activation][sa].”
+It’s more complicated, but it has some nice properties. It is the
+feature that allows `systemd` to replace `inetd`, `xinetd`, Upstart, and
+several other competing technologies.
+
+We first need to define the privileged socket listener by writing
+`/etc/systemd/system/fossil.socket`:
+
+```dosini
+ [Unit]
+ Description=Fossil socket
+
+ [Socket]
+ Accept=yes
+ ListenStream=80
+ NoDelay=true
+
+ [Install]
+ WantedBy=sockets.target
+```
+
+Note the change of configuration directory from the `~/.local` directory
+to the system level. We need to start this socket listener at the root
+level because of the low-numbered TCP port restriction we brought up
+above.
+
+This configuration says more or less the same thing as the socket part
+of an `inted` entry [exemplified elsewhere in this
+documentation](../any/inetd.md).
+
+Next, create the service definition file in that same directory as
+`fossil@.service`:
+
+```dosini
+ [Unit]
+ Description=Fossil socket server
+ After=network.target
+
+ [Service]
+ WorkingDirectory=/home/fossil/museum
+ ExecStart=/home/fossil/bin/fossil http repo.fossil
+ StandardInput=socket
+
+ [Install]
+ WantedBy=sockets.target
+ WantedBy=multi-user.target
+```
+
+We’ll explain the “`@`” in the file name below.
+
+Notice that we haven’t told `systemd` which user and group to run Fossil
+under. Since this is a system-level service definition, that means it
+will run as root, which then causes Fossil to [automatically drop into a
+`chroot(2)` jail](../../chroot.md) rooted at the `WorkingDirectory`
+we’ve configured above, shortly each `fossil http` call starts.
+
+The `Restart*` directives we had in the user service configuration above
+are unnecessary for this method, since Fossil isn’t supposed to remain
+running under it. Each HTTP hit starts one Fossil instance, which
+handles that single client’s request and then immediately shuts down.
+
+Next, you need to tell `systemd` to reload its system-level
+configuration files and enable the listening socket:
+
+ $ sudo systemctl daemon-reload
+ $ sudo systemctl enable fossil.socket
+
+And now you can manipulate the socket listener:
+
+ $ sudo systemctl start fossil.socket
+ $ sudo systemctl status -l fossil.socket
+ $ sudo systemctl stop fossil.socket
+
+Notice that we’re working with the *socket*, not the *service*. The fact
+that we’ve given them the same base name and marked the service as an
+instantiated service with the “`@`” notation allows `systemd` to
+automatically start an instance of the service each time a hit comes in
+on the socket that `systemd` is monitoring on Fossil’s behalf. To see
+this service instantiation at work, visit a long-running Fossil page
+(e.g. `/tarball`) and then give a command like this:
+
+ $ sudo systemctl --full | grep fossil
+
+This will show information about the `fossil` socket and service
+instances, which should show your `/tarball` hit handler, if it’s still
+running:
+
+ fossil@20-127.0.0.1:80-127.0.0.1:38304.service
+
+You can feed that service instance description to a `systemctl kill`
+command to stop that single instance without restarting the whole
+`fossil` service, for example.
+
+In all of this, realize that we’re able to manipulate a single socket
+listener or single service instance at a time, rather than reload the
+whole externally-facing network configuration as with the far more
+primitive `inetd` service.
+
+[sa]: http://0pointer.de/blog/projects/socket-activation.html
+
+
+*[Return to the top-level Fossil server article.](../)*
ADDED www/server/index.html
Index: www/server/index.html
==================================================================
--- /dev/null
+++ www/server/index.html
@@ -0,0 +1,238 @@
+
+
+
+
+
+
No Server Required
+
+
Fossil does not require a central server, but a server can be very useful.
+
+
This article is a quick-reference guide for setting up your own
+Fossil server, with links to more detailed instructions specific to
+particular systems, should you want extra help.
+
+
+
Methods
+
+
There are basically four ways to set up a Fossil server:
+
+
+ - CGI
+
- Stand-alone HTTP server
+
- Socket listener
+
- SCGI
+
+
+
All of these methods can serve either a single repository or a
+directory containing repositories named "*.fossil".
+
+
You are not restricted to using a single method. The same Fossil
+repository can be served using two or more of the above techniques at
+the same time. These methods use clean, well-defined, standard
+interfaces (CGI, SCGI, and HTTP) which allow you to easily migrate from
+one method to another to accommodate changes in hosting providers or
+administrator preferences.
+
+
CGI
+
+
Most ordinary web servers can run Fossil as a
+CGI script. This method is known to work with Apache,
+lighttpd, and althttpd. The Fossil server
+administrator places a short CGI script in
+the web server's document hierarchy, and when a client requests the
+appropriate URL, that script runs Fossil to generate the response.
+
+
CGI is a good choice for merging Fossil into an existing web site,
+particularly on hosts that have CGI set up for you already and won't let
+you modify the web server configuration further. The Fossil self-hosting repositories are implemented
+with CGI underneath althttpd.
+
+
Stand-alone HTTP Server
+
+
This is the easiest method.
+A stand-alone server uses the fossil server command to run a
+process that listens for incoming HTTP requests on a socket and then
+dispatches a copy of itself to deal with each incoming request. You can
+expose Fossil directly to the clients in this way or you can interpose a
+reverse proxy
+layer between the clients and Fossil.
+
+
Socket Listener
+
+
Only slightly more complicated is the socket listener method.
+Instead of letting Fossil run in the background continuously to handle
+HTTP requests from clients, you configure a socket listener daemon to
+run a fossil http command on each
+HTTP hit. That Fossil instance handles only that one hit and then shuts
+back down, letting the socket listener go back to waiting for the next
+hit. This scheme is known to work with inetd, xinetd, stunnel, launchd, and systemd.
+
+
SCGI
+
+
The Fossil standalone server can also run in
+SCGI mode — fossil server --scgi
+— instead of HTTP mode, which allows it to
+respond to requests from web servers such as
+nginx that don't support CGI. SCGI is a simpler protocol to proxy
+than HTTP, since the HTTP doesn't have to be re-interpreted in terms of
+the proxy's existing HTTP implementation, but it's more complex to set
+up because you also have to set up an SCGI-to-HTTP proxy for it. It is
+worth taking on this difficulty only when you need to integrate Fossil
+into an existing web site already being served by an SCGI-capable web
+server.
+
+
Setup Tutorials
+
+
We've broken the configuration for each method out into a series of
+sub-articles. Some of these are generic, while others depend on
+particular operating systems or front-end software:
+
+
+
+
+
+ | ⇩ OS / Method ⇨ |
+ direct |
+ inetd |
+ stunnel |
+ CGI |
+ SCGI |
+ althttpd |
+ proxy |
+ service |
+
+
+
+ | Any |
+ ✅ |
+ ✅ |
+ ✅ |
+ ✅ |
+ ✅ |
+ ✅ |
+ ❌ |
+ ❌ |
+
+
+
+ | Debian/Ubuntu |
+ ✅ |
+ ✅ |
+ ✅ |
+ ✅ |
+ ✅ |
+ ✅ |
+ ✅ |
+ ✅ |
+
+
+
+ | macOS |
+ ✅ |
+ ❌ |
+ ✅ |
+ ✅ |
+ ✅ |
+ ✅ |
+ ❌ |
+ ✅ |
+
+
+
+ | Windows |
+ ✅ |
+ ❌ |
+ ✅ |
+ ✅ |
+ ❌ |
+ ❌ |
+ ✅ |
+ ✅ |
+
+
+
+
Where there is a check mark in the "Any" row, the method for that is
+generic enough that it works across OSes that Fossil is known to work
+on. The check marks below that usually just link to this generic
+documentation.
+
+
The method in the "proxy" column is for the platform's default
+web server configured as a reverse proxy for
+Fossil's built-in HTTP server: nginx, IIS, Apache, etc.
+
+
We welcome contributions to fill gaps
+(❌) in the table above.
+
+
+
+
Further Details
+
+
+
+
No Server Required
+
+Fossil does not require a central server.
+Data sharing and synchronization can be entirely peer-to-peer.
+Fossil uses
+[https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type|conflict-free replicated data types]
+to ensure that (in the limit) all participating peers see the same content.
+
+But, A Server Can Be Useful
+
+Fossil does not require a server, but a server can be very useful.
+Here are a few reasons to set up a Fossil server for your project:
+
+ 1. A server gives developers a common point of rendezvous for
+ syncing their work.
+ It is possible for developers to synchronous peer-to-peer but
+ that requires the developers coordinate the sync, which in turn
+ requires that the developers both want to sync at the same moment.
+ A server aleviates this time dependency by allowing each developer
+ to sync whenever it is convenient (for example, automatically syncing
+ after each commit and before each update). Developers all stay
+ in sync with each other, without having to interrupt each other
+ constantly to set up a peer-to-peer sync.
+
+ 2. A server works as a project website for non-developers.
+ Fossil does more than just version control. It also supports
+ trouble-tickets, and wiki, and a forum. It shows the status
+ of the project. And the embedded documentation feature provides
+ a great mechanism for providing only instructions.
+
+ 3. A server provides project leaders with up-to-date status.
+ Project coordinators and BDFLs can click on a link or two at the
+ central Fossil server for a project, and quickly tell what is
+ going on. They can do this from anywhere, even from their phones,
+ without needing to actually sync to the device they are using.
+
+ 4. A server provides automatic off-site backups.
+ A Fossil server is an automatic remote backup for all the work
+ going into a project. You can even set up multiple servers, at
+ multiple sites, with automatic synchronization between them, for
+ added redundancy. Such a set up means that no work is lost due
+ to a single machine failure.
ADDED www/server/windows/cgi-bin-perm.png
Index: www/server/windows/cgi-bin-perm.png
==================================================================
--- /dev/null
+++ www/server/windows/cgi-bin-perm.png
cannot compute difference between binary files
ADDED www/server/windows/cgi-exec-perm.png
Index: www/server/windows/cgi-exec-perm.png
==================================================================
--- /dev/null
+++ www/server/windows/cgi-exec-perm.png
cannot compute difference between binary files
ADDED www/server/windows/cgi-install-iis.png
Index: www/server/windows/cgi-install-iis.png
==================================================================
--- /dev/null
+++ www/server/windows/cgi-install-iis.png
cannot compute difference between binary files
ADDED www/server/windows/cgi-script-map.png
Index: www/server/windows/cgi-script-map.png
==================================================================
--- /dev/null
+++ www/server/windows/cgi-script-map.png
cannot compute difference between binary files
ADDED www/server/windows/cgi.md
Index: www/server/windows/cgi.md
==================================================================
--- /dev/null
+++ www/server/windows/cgi.md
@@ -0,0 +1,115 @@
+# Serving via IIS + CGI
+
+## This Is Not the Method You Are Looking For
+
+Setting up CGI service under IIS is surprisingly complicated compared to
+running Fossil as a CGI under most other operating systems. We recommend
+that you use the simpler [reverse proxying method](./iis.md) instead
+unless there is some compelling reason why that method cannot work for
+you, such as its dependence on non-stock IIS extensions. (Keep in mind
+that both extensions it requires are by Microsoft, not third parties!)
+
+Once you’ve got this scheme working, it gives the same benefits as those
+listed at the top of the linked-to document.
+
+There is a small benefit you get from using CGI over reverse proxying on
+other OSes, which is that the Fossil program only runs briefly in order
+to serve each HTTP hit. Once the request is done, that Fossil instance
+shuts back down, releasing all of its resources. You don’t need to keep
+a background Fossil HTTP server running full-time to provide CGI-based
+Fossil service.
+
+You lose a lot of that benefit on Windows:
+
+1. It only matters to start with on servers that are highly RAM
+ constrained. (Roughly ≤ 128 MiB.) Our configuration steps below
+ assume you’re using the Windows and IIS GUIs, which have RAM
+ requirements well in excess of this, making Fossil’s resource
+ requirements a drop in the bucket next to them. On the [Azure
+ B1s][b1s] virtual machine I used to prepare these instructions, the
+ Windows Server Manager GUI kept filling the VM’s 1 GiB of RAM
+ during feature installation and crashing. I had to upgrade the VM’s
+ RAM to 2 GiB just to get useful work done!
+
+2. Process creation on Windows is [much more expensive][cp] than on the
+ other OSes Fossil runs on, so the benefits of firing up a Fossil
+ executable to process each HTTP request are partially swamped by the
+ overhead of doing so.
+
+Therefore, unless you’re willing to replace all of the GUI configuration
+steps below with command line equivalents, or shut the GUI down entirely
+after configuring IIS, CGI is a much less compelling option on Windows.
+
+**WARNING:** The following tutorial appears to fail with the current
+(2019-08-17) version of Fossil, [apparently][fbug] due to an inability
+of Fossil to detect that it’s being run in CGI mode.
+
+[b1s]: https://azure.microsoft.com/en-us/blog/introducing-b-series-our-new-burstable-vm-size/
+[cp]: https://stackoverflow.com/a/48244/142454
+[fbug]: https://fossil-scm.org/forum/forumpost/de18dc32c0
+
+
+## Install IIS with CGI Support
+
+The steps for this are identical to those for the [reverse proxying IIS
+setup](./iis.md#install) except that you need to enable CGI in the last
+step, since it isn’t installed by default. For Windows Server, the path
+is:
+
+
+
+The path is similar on the consumer-focused versions of Windows, once
+you get to that last step.
+
+
+## Setup
+
+1. Install the Fossil executable to `c:\inetpub\wwwroot\bin` on the web
+ server. We can’t use an executable you might already have because IIS
+ runs under a separate user account, so we need to give that
+ executable special permissions, and that’s easiest to do under the
+ IIS tree:
+
+ 
+
+2. In IIS Manager (a.k.a. `INETMGR`) drill down into the Sites folder
+ in the left-side pane and right-click your web site’s
+ configuration. (e.g. “Default Web Site”)
+
+3. On that menu say “Add Virtual Directory.” Give it the alias “`cgi`”
+ and point it at a suitable directory, such as
+ “`c:\inetpub\wwwroot\cgi`”.
+
+4. Double-click the “Handler Mappings” icon, then in the right-side
+ pane, click “Add Script Map...” Apply the following settings:
+
+ 
+
+ The Executable path must point to the path we set up in step 1, not
+ to some other `fossil.exe` you may have elsewhere on your system.
+ You will need to change the default “`*.dll`” filter in the Open
+ dialog to “`*.exe`” in order to see it when browsing via the “`...`”
+ button.
+
+5. Create a file called `repo.fslcgi` within the CGI directory you
+ chose in step 3, with a single line like this:
+
+ repository: c:\Users\SOMEONE\museum\repo.fossil
+
+ Give the actual path to the repository, of course.
+
+6. Up at the top level of IIS Manager, double-click the “ISAPI and CGI
+ Restrictions” icon, then click “Add...” in the right-side pane.
+ Give the script you just created permission to execute:
+
+ 
+
+7. In the right-side pane, click “Restart” to apply this configuration,
+ then test it by visiting the newly-available URL in a browser:
+
+ http://localhost/cgi/repo.fslcgi
+
+For more complicated setups such as “directory” mode, see [the generic
+CGI instructions](../any/cgi.md).
+
+*[Return to the top-level Fossil server article.](../)*
ADDED www/server/windows/iis.md
Index: www/server/windows/iis.md
==================================================================
--- /dev/null
+++ www/server/windows/iis.md
@@ -0,0 +1,134 @@
+# Serving via IIS
+
+## Why Bother?
+
+The first part of the scheme below sets Fossil up as an HTTP server, so
+you might be wondering why you wouldn’t just modify that to make it
+listen on all network interfaces on TCP port 80, so you can avoid the
+need for IIS entirely. For simple use cases, you can indeed do without
+IIS, but there are several use cases where adding it is helpful:
+
+1. Proxying Fossil with IIS lets you [add TLS encryption][tls], which
+ [Fossil does not currently speak](../../ssl.wiki) in its server role.
+
+2. The URL rewriting we do below allows Fossil to be part of a larger
+ site already being served with IIS.
+
+3. You can have a mixed-mode site, with Fossil acting as a powerful
+ dynamic content management service and IIS as a fast static content
+ server. The pure-Fossil alternative requires that you check all of
+ your static content into Fossil as versioned or unversioned
+ artifacts.
+
+This article shows how you can get any combination of those benefits by
+using IIS as a reverse proxy for `fossil server`.
+
+There are other ways to use IIS to serve Fossil, such as [via
+CGI](./cgi.md).
+
+
+## Background Fossil Service Setup
+
+You will need to have the Fossil HTTP server running in the background,
+serving some local repository, bound to localhost on a fixed
+high-numbered TCP port. For the purposes of testing, simply start it by
+hand in your command shell of choice:
+
+ fossil serve --port 9000 --localhost repo.fossil
+
+That command assumes you’ve got `fossil.exe` in your `%PATH%` and you’re
+in a directory holding `repo.fossil`. See [the platform-independent
+instructions](../any/none.md) for further details.
+
+For a more robust setup, we recommend that you [install Fossil as a
+Windows service](./service.md), which will allow Fossil to start at
+system boot, before anyone has logged in interactively.
+
+
+## Install IIS
+
+IIS might not be installed in your system yet, so follow the path
+appropriate to your host OS. We’ve tested only the latest Microsoft
+OSes as of the time of this writing, but the basic process should be
+similar on older OSes.
+
+
+### Windows Server 2019
+
+1. Start “Server Manager”
+2. Tell it you want to “Add roles and features”
+3. Select “Role-based or feature-based installation”
+4. Select your local server
+5. In the Server Roles section, enable “Web Server (IIS)”
+
+### Windows
+
+1. Open Control Panel
+2. Go to “Programs”
+3. Select “Turn Windows features on or off” in the left-side pane
+4. In the “Windows Features” dialog, enable “Internet Information
+ Services”
+
+The default set of IIS features there will suffice for this tutorial,
+but you might want to enable additional features.
+
+
+## Setting up the Proxy
+
+The stock IIS setup doesn’t have reverse proxying features, but they’re
+easily added through extensions. You will need to install the
+[Application Request Routing][arr] and [URL Rewrite][ure] extensions. In
+my testing here, URL Rewrite showed up immediately after installing it,
+but I had to reboot the server to get ARR to show up. (Yay Windows.)
+
+You can install these things through the direct links above, or you can
+do it via the Web Platform Installer feature of IIS Manager (a.k.a.
+`INETMGR`).
+
+Set these extensions up in IIS Manager like so:
+
+1. Double-click the “Application Request Routing Cache” icon.
+
+2. Right-click in the window that results, and select “Server Proxy
+ Settings...”
+
+3. Check the “Enable Proxy” box in the dialog. Click the “Apply” text
+ in the right-side pane.
+
+4. Return to the top server-level configuration area of IIS Manager and
+ double-click the “URL Rewrite” icon. Alternately, you might find
+ “URL Rewrite” in the right-side pane from within the ARR settings.
+
+5. Right click in the window that results, and click “Add Rule(s)...”
+ Tell it you want a “Blank rule” under “Inbound rules”.
+
+6. In the dialog that results, create a new rule called “Fossil repo
+ proxy.” Set the “Pattern” to “`^(.*)$`” and “Rewrite URL” set to
+ “`http://localhost:9000/{R:1}`”. That tells it to take everything in
+ the path part of the URL and send it down to localhost:9000, where
+ `fossil server` is listening.
+
+7. Click “Apply” in the right-side pane, then get back to the top level
+ configuration for the server, and click “Restart” in that same pane.
+
+At this point, if you go to `http://localhost/` in your browser, you
+should see your Fossil repository’s web interface instead of the default
+IIS web site, as before you did all of the above.
+
+This is a very simple configuration. You can do more complicated and
+interesting things with this, such as redirecting only `/code` URLs to
+Fossil by setting the Pattern in step 6 to “`^/code(.*)$`”. (You would
+also need to pass `--baseurl http://example.com/code` in the `fossil
+server` command to make this work properly.) IIS would then directly
+serve all other URLs. You could also intermix ASP.NET applications in
+the URL scheme in this way.
+
+See the documentation on [URL Rewrite rules][urr] for more ideas.
+
+*[Return to the top-level Fossil server article.](../)*
+
+
+[arr]: https://www.iis.net/downloads/microsoft/application-request-routing
+[tls]: https://docs.microsoft.com/en-us/iis/manage/configuring-security/understanding-iis-url-authorization
+[ure]: https://www.iis.net/downloads/microsoft/url-rewrite
+[urr]: https://docs.microsoft.com/en-us/iis/extensions/url-rewrite-module/creating-rewrite-rules-for-the-url-rewrite-module
ADDED www/server/windows/index.md
Index: www/server/windows/index.md
==================================================================
--- /dev/null
+++ www/server/windows/index.md
@@ -0,0 +1,6 @@
+# Using Windows as a Fossil Server
+
+- [Fossil as a Service](service.md)
+- [Using stunnel with Fossil on Windows](stunnel.md)
+
+*[Return to the top-level Fossil server article.](../)*
ADDED www/server/windows/none.md
Index: www/server/windows/none.md
==================================================================
--- /dev/null
+++ www/server/windows/none.md
@@ -0,0 +1,69 @@
+# Serving as a Standalone Server on Windows
+
+On Windows, this method works more or less identically to how it’s
+documented in [the generic instructions](../any/none.md).
+
+...but only while `fossil.exe` is actually running, which is the source
+of much trouble on Windows. This problem has two halves:
+
+
+## No App Startup Without Desktop
+
+The easy methods for starting a program in Windows at system start all
+require an interactive desktop. There is no *easy* way to start an arbitrary
+program on Windows at boot before anyone has logged in. In Unix
+terms, Windows has no simple equivalent to [the `/etc/rc.local` file][rcl].
+
+You can partially get around the first problem by setting your `fossil
+server` call up as one of the user’s interactive startup items. Windows
+10 has its own [idiosyncratic way of doing this][si10], and in older
+systems you have [several alternatives to this][si7]. Regardless of the
+actual mechanism, these will cause the Fossil standalone HTTP server to
+start on an *interactive desktop login* only. While you’re sitting at
+the Windows login screen, the Fossil server is *down*.
+
+[rcl]: http://nixdoc.net/man-pages/FreeBSD/man8/rc.local.8.html
+[si10]: https://www.tenforums.com/tutorials/2944-add-delete-enable-disable-startup-items-windows-10-a.html
+[si7]: https://www.wikihow.com/Change-Startup-Programs-in-Windows-7
+
+
+
+## No Simple Background Mode
+
+Windows also lacks a direct equivalent of the Bourne shell’s “`&`” control operator to
+run a program in the background, which you can give in Unix’s `rc.local`
+file, which is just a normal Bourne shell script.
+
+By “background,” I mean
+“not attached to any interactive user’s login session.” When the
+`rc.local` script exits in Unix, any program it backgrounded *stays
+running*. There is no simple and direct equivalent to this mechanism in
+Windows.
+
+If you set `fossil server` to run on interactive login, as above, it
+will shut right back down again when that user logs back out.
+
+With Windows 10, it’s especially problematic because you can no longer
+make the OS put off updates arbitrarily: your Fossil server will go down
+every time Windows Update decides it needs to reboot your computer, and
+then Fossil service will *stay* down until someone logs back into that
+machine interactively.
+
+
+## Better Solutions
+
+Because of these problems, we only recommend setting `fossil server` up
+on Windows this way when
+you’re a solo developer or you work in a small office where everyone
+arrives more or less at the same time each day, and everyone goes home
+about the same time each day, so that one user can keep the Fossil
+server up through the working day.
+
+If your needs go at all beyond this, you should expect proper “server”
+behavior, which you can get on Windows by [registering Fossil as a
+Windows service](./service.md), which solves the interactive startup and
+shutdown problems above, at a bit of complexity over the Startup Items
+method. You may also want to consider putting that service behind [an
+IIS front-end proxy](./iis.md) to add additional web serving features.
+
+*[Return to the top-level Fossil server article.](../)*
ADDED www/server/windows/service.md
Index: www/server/windows/service.md
==================================================================
--- /dev/null
+++ www/server/windows/service.md
@@ -0,0 +1,57 @@
+# Fossil as a Windows Service
+
+If you need Fossil to start automatically on Windows, it is suggested to install
+Fossil as a Windows Service.
+
+## Assumptions
+
+1. You have Administrative access to a Windows 2012r2 or above server.
+2. You have PowerShell 5.1 or above installed.
+
+## Place Fossil on Server
+
+However you obtained your copy of Fossil, it is recommended that you follow
+Windows conventions and place it within `\Program Files (x86)\FossilSCM`. Since
+Fossil is a 32bit binary, this is the proper location for the executable. This
+way Fossil is in an expected location and you will have minimal issues with
+Windows interfering in your ability to run Fossil as a service. You will need
+Administrative rights to place fossil at the recommended location. You do NOT
+need to add this location to the path, though you may do so if you wish.
+
+## Make Fossil a Windows Service
+
+Luckily the hard work to use Fossil as a Windows Service has been done by the
+Fossil team. We simply have to install it with the proper command line options.
+As of Fossil 2.9 the built in `fossil winsrv` command is failing, so an
+alternative service install using PowerShell is documented here. The below
+should all be entered as a single line in an Administrative PowerShell console.
+
+```PowerShell
+New-Service -Name fossil -DisplayName fossil -BinaryPathName '"C:\Program Files (x86)\FossilSCM\fossil.exe"
+server --port 8080 --repolist "D:/Path/to/Repos"' -StartupType Automatic
+```
+
+Please note the use of forward slashes in the paths passed to Fossil. Windows
+will accept either back slashes or forward slashes in path names, but Fossil has
+a preference for forward slashes. The use of `--repolist` will make this a
+multiple repository server. If you want to serve only a single repository,
+then leave off the `--repolist` parameter and provide the full path to the
+proper repository file. Other options are listed in the
+[fossil server](/help?cmd=server) documentation.
+
+The service will be installed by default to use the Local Service account.
+Since Fossil only needs access to local files, this is fine and causes no
+issues. The service will not be running once installed. You will need to start
+it to proceed (the `-StartupType Automatic` parameter to `New-Service` will
+result in the service auto-starting on boot). This can be done by entering
+
+```PowerShell
+Start-Service -Name fossil
+```
+
+in the PowerShell console.
+
+Congratulations, you now have a base http accessible Fossil server running on
+Windows.
+
+*[Return to the top-level Fossil server article.](../)*
ADDED www/server/windows/stunnel.md
Index: www/server/windows/stunnel.md
==================================================================
--- /dev/null
+++ www/server/windows/stunnel.md
@@ -0,0 +1,149 @@
+# Using stunnel with Fossil on Windows
+
+While there are many ways to configure Fossil as a server using various web
+servers (Apache, IIS, nginx, etc.), this document will focus on setting up a
+minimal Fossil server using only Fossil's native [server
+capabilities](../any/none.md) and [stunnel](https://www.stunnel.org/)
+to provide a TLS proxy. It is recommended for public repositories to go to the
+extra step of configuring stunnel to provide a proper HTTPS setup.
+
+## Assumptions
+
+1. You have Administrative access to a Windows 2012r2 or above server.
+2. You have PowerShell 5.1 or above installed.
+3. You have acquired a certificate either from a Public CA or an Internal CA.
+
+These instructions were tested with Fossil 2.10 and stunnel 5.55. Other
+versions may not function in a similar manner. There is a bug in Fossil 2.9 and
+earlier that prevents these versions of Fossil from properly constructing https
+URLs when used with stunnel as a proxy. Please make sure you are using Fossil
+2.10 or later on Windows.
+
+## Configure Fossil Service for https
+
+Following most of [Fossil as a Windows Service](./service.md), you will need
+to change the command to install the Fossil Service to configure it properly for
+use with stunnel as an https proxy. Run the following instead:
+
+```PowerShell
+New-Service -Name fossil-secure -DisplayName fossil-secure -BinaryPathName '"C:\Program Files (x86)\FossilSCM\fossil.exe"
+server --localhost --port 9000 --https --repolist "D:/Path/to/Repos"' -StartupType Automatic
+
+```
+
+The use of `--localhost` means Fossil will only listen for traffic on the local
+host on the designated port - 9000 in this case - and will not respond to
+network traffic. Using `--https` will tell Fossil to generate HTTPS URLs rather
+than HTTP ones.
+
+`New-Service` does not automatically start a service on install, so you will
+need to enter the following to avoid rebooting the server:
+
+```PowerShell
+Start-Service -Name fossil-secure
+```
+
+## Install stunnel 5.55
+
+Download stunnel from the [downloads](https://www.stunnel.org/downloads.html)
+page. Select the latest stunnel windows package (at the time of writing this is
+`stunnel-5.55-win64-installer.exe`). Execute the installer and make sure you
+install openSSL tools when you install stunnel. You will need this to convert
+your certificate from PFX to PEM format.
+
+Even though the installer says it is for win64, it installs stunnel by default
+to `\Program Files (x86)\stunnel`.
+
+## Get your certificate ready for Stunnel
+
+Whether you use a Public Certificate Authority or Internal Certificate
+Authority, the next step is exporting the certificate from Windows into a format
+useable by Stunnel.
+
+### Export Certificate from Windows
+
+If your certificate is installed via Windows Certificate Management, you will
+need to export the certificate into a usable format. You can do this either
+using the Windows Certificate Management Console, or PowerShell.
+
+#### Certificate Management Console
+
+Start `mmc.exe` as an Administrator. Select 'File>Add/Remove Snapin', select
+'Certificates' from the list, and click 'Add'. Select 'Computer Account',
+'Next', 'Local Computer', and then 'Finish'. In the Console Root, expand
+'Certificates', then 'Personal', and select 'Certificates'. In the middle pane
+find and select your certificate. Right click the certificate and select
+'All Tasks>Export'. You want to export as PFX the Private Key, include all
+certificates in the certification path, and use a password only to secure the
+file. Enter a path and file name to a working directory and complete the
+export.
+
+Continue with [Convert Certificate from PFX to PEM](#convert).
+
+#### PowerShell
+
+If you know the Friendly
+Name of the Certificate this is relatively easy. Since you need to export
+the private key as well, you must run the following from an Administrative
+PowerShell console.
+
+```PowerShell
+$passwd = ConvertTo-SecureString -string "yourpassword" -Force -AsPlainText
+
+Get-ChildItem Cert:\LocalMachine\My | Where{$_.FriendlyName -eq "FriendlyName"} |
+Export-PfxCertificate -FilePath fossil-scm.pfx -Password $passwd
+```
+
+You will now have your certificate stored as a PFX file.
+
+
+### Convert Certificate from PFX to PEM
+
+For this step you will need the openssl tools that were installed with stunnel.
+
+```PowerShell
+# Add stunnel\bin directory to path for this session.
+$env:PATH += ";${env:ProgramFiles(x86)}\stunnel\bin"
+# Export Private Key
+openssl.exe pkcs12 -in fossil-scm.pfx -out fossil-scm.key -nocerts -nodes
+# Export the Certificate
+openssl.exe pkcs12 -in fossil-scm.pfx -out fossil-scm.pem -nokeys
+```
+
+Now move `fossil-scm.key` and `fossil-scm.pem` to your stunnel config directory
+(by default this should be located at `\Program Files (x86)\stunne\config`).
+
+## stunnel Configuration
+
+Use the reverse proxy configuration given in the generic [Serving via
+stunnel document](../any/stunnel.md#proxy). On Windows, the
+`stunnel.conf` file is located at `\Program Files (x86)\stunnel\config`.
+
+You will need to modify it to point at the PEM and key files generated
+above.
+
+After completing the above configuration restart the stunnel service in Windows
+with the following:
+
+```PowerShell
+Restart-Service -Name stunnel
+```
+
+## Open up port 443 in the Windows Firewall
+
+The following instructions are for the [Windows Advanced
+Firewall](https://docs.microsoft.com/en-us/windows/security/threat-protection/windows-firewall/windows-firewall-with-advanced-security).
+If you are using a different Firewall, please consult your Firewall
+documentation for how to open port 443 for inbound traffic.
+
+The following command should be entered all on one line.
+
+```PowerShell
+New-NetFirewallRule -DisplayName "Allow Fossil Inbound" -Description "Allow Fossil inbound on port 443 using Stunnel as TLS Proxy."
+ -Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow -Program "C:\Program Files (x86)\Stunnel\bin\stunnel.exe"
+```
+
+You should now be able to access your new Fossil Server via HTTPS.
+
+
+*[Return to the top-level Fossil server article.](../)*
Index: www/serverext.wiki
==================================================================
--- www/serverext.wiki
+++ www/serverext.wiki
@@ -1,10 +1,10 @@
CGI Server Extensions
1.0 Introduction
-If you have a [./server.wiki|Fossil server] for your project,
+If you have a [./server/|Fossil server] for your project,
you can add [https://en.wikipedia.org/wiki/Common_Gateway_Interface|CGI]
extensions to that server. These extensions work like
any other CGI program, except that they also have access to the Fossil
login information and can (optionally) leverage the "skins" of Fossil
so that they appear to be more tightly integrated into the project.
@@ -27,21 +27,21 @@
CGI Extensions are disabled by default.
An administrator activates the CGI extension mechanism by specifying
an "Extension Root Directory" or "extroot" as part of the server setup.
If the Fossil server is itself run as
-[./server.wiki#cgi|CGI], then add a line to the
+[./server/any/cgi.md|CGI], then add a line to the
[./cgi.wiki#extroot|CGI script file] that says:
extroot: DIRECTORY
Or, if the Fossil server is begin run as using the
-"[./server.wiki#standalone|fossil server]" or
-"[./server.wiki#standalone|fossil ui]" or
-"[./server.wiki#inetd|fossil http]" commands, then add an extra
+"[./server/any/none.md|fossil server]" or
+"[./server/any/none.md|fossil ui]" or
+"[./server/any/inetd.md|fossil http]" commands, then add an extra
"--extroot DIRECTORY" option to that command.
The DIRECTORY is the DOCUMENT_ROOT for the CGI.
Files in the DOCUMENT_ROOT are accessed via URLs like this:
Index: www/ssl.wiki
==================================================================
--- www/ssl.wiki
+++ www/ssl.wiki
@@ -1,6 +1,6 @@
-TLS and Fossil
+Securing a Repository with TLS
Using TLS-Encrypted Communications with Fossil
If you are storing sensitive information in a repository accessible over
a network whose integrity you do not fully trust, you should use TLS to
@@ -206,72 +206,17 @@
Fossil TLS Configuration: Server Side
Fossil's built-in HTTP server feature does not currently have a built-in
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.
-
-
-stunnel Alone
-
-[https://www.stunnel.org/ | stunnel] is an
-[https://en.wikipedia.org/wiki/Inetd | inetd]-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 stunnel
-and then place something like this in its main configuration file,
-stunnel.conf:
-
-
- [https]
- accept = www.ubercool-project.org:443
- TIMEOUTclose = 0
- exec = /usr/bin/fossil
- execargs = /usr/bin/fossil http /home/fossil/ubercool.fossil --https
-
-
-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 stunnel documentation for further details about this
-configuration file.
-
-It is important that the [/help/http | fossil http] command in
-that configuration include the --https option to let Fossil
-know to use "https" instead of "http" as the URL
-scheme on generated hyperlinks.
-
-
-stunnel + althttpd
-
-The public SQLite and Fossil web sites can't just use stunnel + Fossil
-because parts of the web site are static, served by
-[https://sqlite.org/docsrc/doc/trunk/misc/althttpd.md|a separate web
-server called althttpd], written by the primary author of both
-SQLite and Fossil. althttpd is a lightweight HTTP-only web
-server. It handles the static HTTP hits on sqlite.org and
-fossil-scm.org, delegating HTTPS hits to stunnel and dynamic
-content hits to Fossil.
-
-(The largest single chunk of static content served directly by
-althttpd rather than via Fossil is the
-[https://sqlite.org/docs.html | SQLite documentation], which is built
-[https://sqlite.org/docsrc/ | from source files] and then served
-statically.)
-
-In addition to the documentation linked above, there is a large header
-comment in the [https://sqlite.org/docsrc/file/misc/althttpd.c|single C
-file] of althttpd which is most helpful.
-
-
-nginx
-
-If your needs are more complex than althttpd can handle or you'd prefer
-to use only software available in your server operating system's package
-repository, we recommend that you step up to [http://nginx.org/|nginx].
-Setting this up is complex enough that we cover it [./tls-nginx.md|in a
-separate document].
+it behind some kind of HTTPS proxy. We have a number of documents
+elsewhere in this repository that cover your options for [./server/
+| serving Fossil repositories]. A few of the most useful of these are:
+
+ * Serving via stunnel
+ * Serving via stunnel + althttpd
+ * Serving via SCGI (nginx)
Enforcing TLS Access
To use TLS encryption in cloning and syncing to a remote Fossil
Index: www/sync.wiki
==================================================================
--- www/sync.wiki
+++ www/sync.wiki
@@ -59,11 +59,11 @@
The server might be running as an independent server
using the server command, or it might be launched from
inetd or xinetd using the http command. Or the server might
be launched from CGI.
-(See "[./server.wiki|How To Configure A Fossil Server]" for details.)
+(See "[./server/|How To Configure A Fossil Server]" for details.)
The specifics of how the server listens
for incoming HTTP requests is immaterial to this protocol.
The important point is that the server is listening for requests and
the client is the issuer of the requests.
Index: www/tls-nginx.md
==================================================================
--- www/tls-nginx.md
+++ www/tls-nginx.md
@@ -3,183 +3,45 @@
One of the [many ways](./ssl.wiki) to provide TLS-encrypted HTTP access
(a.k.a. HTTPS) to Fossil is to run it behind a web proxy that supports
TLS. This document explains how to use the powerful [nginx web
server](http://nginx.org/) to do that.
-
-## Benefits
-
-This scheme is complicated, even with the benefit of this guide and
-pre-built binary packages. Why should you put up with this complexity?
-Because it gives many benefits that are difficult or impossible to get
-with the less complicated options:
-
-* **Power** — nginx is one of the most powerful web servers in the
- world. The chance that you will run into a web serving wall that you
- can’t scale with nginx is very low.
-
- To give you some idea of the sort of thing you can readily
- accomplish with nginx, your author runs a single public web server
- that provides transparent name-based virtual hosting for four
- separate domains:
-
- * One is entirely static, not involving any dynamic content or
- Fossil integration at all.
-
- * Another is served almost entirely by Fossil, with a few select
- static content exceptions punched past Fossil, which are handled
- entirely via nginx.
-
- * The other two domains are aliases for one another — e.g.
- `example.com` and `example.net` — with most of the content being
- static. This pair of domains has three different Fossil repo
- proxies attached to various sections of the URI hierarchy.
-
- All of this is done with minimal configuration repetition between
- the site configurations.
-
-* **Integration** — Because nginx is so popular, it integrates with
-many different technologies, and many other systems integrate with it in
-turn. This makes it great middleware, sitting between the outer web
-world and interior site services like Fossil. It allows Fossil to
-participate seamlessly as part of a larger web stack.
-
-* **Availability** — nginx is already in most operating system binary
-package repositories, so you don’t need to go out of your way to get it.
-
-
-## Fossil Remote Access Methods
-
-Fossil provides four major ways to access a repository it’s serving
-remotely, three of which are straightforward to use with nginx:
-
-* **HTTP** — Fossil has a built-in HTTP server: `fossil server`.
- While this method is efficient and it’s possible to use nginx to
- proxy access to another HTTP server, this option is overkill for our
- purposes. nginx is itself a fully featured HTTP server, so we will
- choose in this guide not to make nginx reinterpret Fossil’s
- implementation of HTTP.
-
-* **CGI** — This method is simple but inefficient, because it launches
- a separate Fossil instance on every HTTP hit.
-
- Since Fossil is a relatively small self-contained program, and it’s
- designed to start up quickly, this method can work well in a
- surprisingly large number of cases.
-
- Nevertheless, we will avoid this option in this document because
- we’re already buying into a certain amount of complexity here in
- order to gain power. There’s no sense in throwing away any of that
- hard-won performance on CGI overhead.
-
-* **SCGI** — The [SCGI protocol][scgi] provides the simplicity of CGI
- without its performance problems.
-
-* **SSH** — This method exists primarily to avoid the need for HTTPS
- in the first place. There is probably a way to get nginx to proxy
- Fossil to HTTPS via SSH, but it would be pointlessly complicated.
-
-SCGI it is, then.
-
-
-# Installing
-
-The first step is to install the pieces we’ll be working with. This
-varies on different operating systems, so to avoid overcomplicating this
-guide, we’re going to assume you’re using Ubuntu Server 18.04 LTS, a
-common Tier 1 offering for [virtual private servers][vps].
-
-SSH into your server, then say:
-
- $ sudo apt install certbot fossil nginx
-
-For other operating systems, simply visit [the front Certbot web
-page][cb] and tell it what OS and web stack you’re using. Chances are
-good that they’ve got a good guide for you already.
-
-
-# Running Fossil in SCGI Mode
-
-You presumably already have a working Fossil configuration on the public
-server you’re trying to set up and are just following this guide to
-replace HTTP service with HTTPS.
-
-(You can adjust the advice in this guide to get both HTTP *and* HTTPS
-service on the same site, but I strongly recommend that you do not do
-that: the good excuses remaining for continuing to allow HTTP on public
-web servers are running thin these days.)
-
-I run my Fossil SCGI server instances with a variant of [the `fslsrv`
-shell script](/file/tools/fslsrv) currently hosted in the Fossil source
-code repository. You’ll want to download that and make a copy of it, so
-you can customize it to your particular needs.
-
-This script allows running multiple Fossil SCGI servers, one per
-repository, each bound to a different high-numbered `localhost` port, so
-that only nginx can see and proxy them out to the public. The
-“`example`” repo is on TCP port localhost:12345, and the “`foo`” repo is
-on localhost:12346.
-
-As written, the `fslsrv` script expects repositories to be stored in the
-calling user’s home directory under `~/museum`, because where else do
-you keep Fossils?
-
-That home directory also needs to have a directory to hold log files,
-`~/log/fossil/*.log`. Fossil doesn’t put out much logging, but when it
-does, it’s better to have it captured than to need to re-create the
-problem after the fact.
-
-The use of `--baseurl` in this script lets us have each Fossil
-repository mounted in a different location in the URL scheme. Here, for
-example, we’re saying that the “`example`” repository is hosted under
-the `/code` URI on its domains, but that the “`foo`” repo is hosted at
-the top level of its domain. You’ll want to do something like the
-former for a Fossil repo that’s just one piece of a larger site, but the
-latter for a repo that is basically the whole point of the site.
-
-You might also want another script to automate the update, build, and
-deployment steps for new Fossil versions:
-
- #!/bin/sh
- cd $HOME/src/fossil/trunk
- fossil up
- make -j11
- killall fossil
- sudo make install
- fslsrv
-
-The `killall fossil` step is needed only on OSes that refuse to let you
-replace a running binary on disk.
-
-As written, the `fslsrv` script assumes a Linux environment. It expects
-`/bin/bash` to exist, and it depends on non-POSIX tools like `pgrep`.
-It should not be difficult to port to systems like macOS or the BSDs.
+This document is an extension of the [Serving via nginx on Debian][nod]
+document. Please read that first, then come back here to extend its
+configuration with TLS.
+
+[nod]: ./server/debian/nginx.md
+
+
+## Install Certbot
+
+The [nginx-on-Debian document][nod] had you install a few non-default
+packages to the system, but there’s one more you need for this guide:
+
+ $ sudo apt install certbot
+
+You can extend this guide to other operating systems by following the
+instructions found via [the front Certbot web page][cb] instead, telling
+it what OS and web stack you’re using. Chances are good that they’ve got
+a good guide for you already.
# Configuring Let’s Encrypt, the Easy Way
If your web serving needs are simple, [Certbot][cb] can configure nginx
-for you and keep its certificates up to date. You can follow the Certbot
-documentation for [nginx on Ubuntu 18.04 LTS guide][cbnu] as-is, though
-we’d recommend one small change: to use the version of Certbot in the
-Ubuntu package repository rather than the first-party Certbot package
-that the guide recommends.
-
-The primary local configuration you need is to tell nginx how to proxy
-certain URLs down to the Fossil instance you started above with the
-`fslsrv` script:
-
- location / {
- include scgi_params;
- scgi_pass 127.0.0.1:12345;
- scgi_param HTTPS "on";
- scgi_param SCRIPT_NAME "";
- }
-
-The TCP port number in that snippet is the key: it has to match the port
-number generated by `fslsrv` from the base port number passed to the
-`start_one` function.
+for you and keep its certificates up to date. Simply follow Certbot’s
+[nginx on Ubuntu 18.04 LTS guide][cbnu]. We’d recommend one small
+change: to use the version of Certbot in the Ubuntu package repository
+rather than download it from the Certbot site.
+
+You should be able to use the nginx configuration given in our [Serving
+via nginx on Debian][nod] guide with little to no change. The main thing
+to watch out for is that the TCP port number in the nginx configuration
+needs to match the value you gave when starting Fossil. If you followed
+that guide’s advice, it will be 9000. Another option is to use [the
+`fslsrv` script](/file/tools/fslsrv), in which case the TCP port number
+will be 12345 or higher.
# Configuring Let’s Encrypt, the Hard Way
If you’re finding that you can’t get certificates to be issued or
@@ -193,11 +55,12 @@
Environment][acme] protocol (ACME) to determine whether a given client
actually has control over the domain(s) for which it wants a certificate
minted. Let’s Encrypt will not blithely let you mint certificates for
`google.com` and `paypal.com` just because you ask for it!
-Your author’s configuration, glossed above, is complicated enough that
+Your author’s configuration, glossed [in the HTTP-only guide][nod],
+is complicated enough that
the current version of Certbot (0.28 at the time of this writing) can’t
cope with it. That’s the primary motivation for me to write this guide:
I’m addressing the “me” years hence who needs to upgrade to Ubuntu 20.04
or 22.04 LTS and has forgotten all of this stuff. 😉
@@ -216,24 +79,12 @@
entirely.
## Step 2: Configuring nginx
-On Ubuntu systems, at least, the primary user-level configuration file
-is `/etc/nginx/sites-enabled/default`. For a configuration like I
-described at the top of this article, I recommend that this file contain
-only a list of include statements, one for each site that server hosts:
-
- include local/example
- include local/foo
-
-Those files then each define one domain’s configuration. Here,
-`/etc/nginx/local/example` contains the configuration for
-`*.example.com` and `*.example.net`; and `local/foo` contains the
-configuration for `*.foo.net`.
-
-Here’s an example configuration:
+This is a straightforward extension to [the HTTP-only
+configuration](./server/debian/nginx.md#config):
server {
server_name .foo.net;
include local/tls-common;
@@ -268,12 +119,13 @@
include local/http-certbot-only;
access_log /var/log/nginx/foo.net-http-access.log;
error_log /var/log/nginx/foo.net-http-error.log;
}
-Notice that we need two `server { }` blocks: one for HTTPS service, and
-one for HTTP-only service:
+One big difference between this and the HTTP-only case is
+that we need two `server { }` blocks: one for HTTPS service, and
+one for HTTP-only service.
### HTTP over TLS (HTTPS) Service
The first `server { }` block includes this file, `local/tls-common`:
@@ -385,43 +237,17 @@
# Force everything else to HTTPS with a permanent redirect.
#return 301 https://$host$request_uri;
As written above, this configuration does nothing other than to tell
nginx that it’s allowed to serve content via HTTP on port 80 as well.
-
We’ll uncomment the `rewrite` and `return` directives below, when we’re
ready to begin testing.
-
-#### Why the Repetition?
-
-These `server { }` blocks contain several directives that have to be
-either completely repeated or copied with only trivial changes when
-you’re hosting multiple domains from a single server.
-
-You might then wonder, why haven’t I factored some of those directives
-into the included files `local/tls-common` and
-`local/http-certbot-only`? Why can’t the HTTP-only `server { }` block
-above be just two lines? That is, why can I not say:
-
- server_name .foo.net;
- include local/http-certbot-only;
-
-Then in `local/http-certbot-only` say:
-
- root /var/www/$host;
- access_log /var/log/nginx/$host-http-access.log;
- error_log /var/log/nginx/$host-http-error.log;
-
-Sadly, nginx doesn’t allow variable substitution into these particular
-directives. As I understand it, allowing that would make nginx slower,
-so we must largely repeat these directives in each HTTP `server { }`
-block.
-
-These configurations are, as shown, as small as I know how to get them.
-If you know of a way to reduce some of this repetition, [I solicit your
-advice][fd].
+Notice that this configuration is very different from that in the
+[HTTP-only nginx on Debian][nod] guide. Most of that guide’s nginx
+directives moved up into the TLS `server { }` block, because we
+eventually want this site to be as close to HTTPS-only as we can get it.
## Step 3: Dry Run
We want to first request a dry run, because Let’s Encrypt puts some
@@ -541,29 +367,19 @@
it would actually [cause an infinite redirect loop if
enabled](./ssl.wiki#rloop).
-## Step 6: Re-Sync Your Repositories
+## Step 6: Re-Point Fossil at Your Repositories
-Now that the repositories hosted by this server are available via HTTPS,
-you need to tell Fossil about it:
+As of Fossil 2.9, the permanent HTTP-to-HTTPS redirect we enabled above
+causes Fossil to remember the new URL automatically the first time it’s
+redirected to it. All you need to do to switch your syncs to HTTPS is:
$ cd ~/path/to/checkout
- $ fossil sync https://example.com/code
-
-Once that’s done per repository file, all checkouts of that repo will
-from that point on use the HTTPS URI to sync.
-
-You might wonder if that’s necessary, since we have the automatic
-HTTP-to-HTTPS redirect on this site now. If you clone or sync one of
-these nginx-hosted Fossil repositories over an untrustworthy network
-that allows [MITM attacks][mitm], that redirect won’t protect you from a
-sufficiently capable and motivated attacker unless you’ve also gone
-ahead and [enabled HSTS](#hsts). You can put off the need to enable
-HSTS by explicitly using HTTPS URIs.
-
+ $ fossil sync
+
## Step 7: Renewing Automatically
Now that the configuration is solid, you can renew the LE cert with the
`certbot` command from above without the `--dry-run` flag plus a restart
@@ -588,27 +404,21 @@
-----------
**Document Evolution**
-TLS and web proxying are a constantly evolving technology. This article
-replaces my [earlier effort][2016], which had whole sections that were
-basically obsolete within about a year of posting it. Two years on, and
-I was encouraging readers to ignore about half of that HOWTO. I am now
-writing this document about 3 years later because Let’s Encrypt
-deprecated key technology that HOWTO depended on, to the point that
-following that old HOWTO is more likely to confuse than enlighten.
+Large parts of this article have been rewritten several times now due to
+shifting technology in the TLS and proxying spheres.
There is no particularly good reason to expect that this sort of thing
-will not continue to happen, so this effort is expected to be a living
+will not continue to happen, so we consider this to be a living
document. If you do not have commit access on the `fossil-scm.org`
repository to update this document as the world changes around it, you
can discuss this document [on the forum][fd]. This document’s author
keeps an eye on the forum and expects to keep this document updated with
ideas that appear in that thread.
-[2016]: https://www.mail-archive.com/fossil-users@lists.fossil-scm.org/msg22907.html
[acme]: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment
[cb]: https://certbot.eff.org/
[cbnu]: https://certbot.eff.org/lets-encrypt/ubuntubionic-nginx
[fd]: https://fossil-scm.org/forum/forumpost/ae6a4ee157
[hsts]: https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security
@@ -616,7 +426,5 @@
[mitm]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
[nest]: https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/
[ocsp]: https://en.wikipedia.org/wiki/OCSP_stapling
[qslc]: https://github.com/ssllabs/research/wiki/SSL-and-TLS-Deployment-Best-Practices
[qslt]: https://www.ssllabs.com/ssltest/
-[scgi]: https://en.wikipedia.org/wiki/Simple_Common_Gateway_Interface
-[vps]: https://en.wikipedia.org/wiki/Virtual_private_server