initial commitHEADmaster

1 files changed, 81 insertions, 0 deletions

diff --git a/www/server/any/stunnel.md b/www/server/any/stunnel.md
new file mode 100644
index 0000000..c8824a7
--- /dev/null
+++ b/www/server/any/stunnel.md
@@ -0,0 +1,81 @@
+# 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.
+
+
+## <a id="sa"></a>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.
+
+
+
+## <a id="proxy"></a>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.](../)*
+
+<div style="height:50em" id="this-space-intentionally-left-blank"></div>