stunnel 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
inetd doc — and as an HTTP reverse proxy. We’ll
cover both cases here, separately.
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:
[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 Certbot in certonly mode. 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.
stunnel documentation for further details about this
It is important that the
fossil http command in that
configuration include the
--https option to let Fossil know to use
https://” instead of “
http://” in generated hyperlinks.
You can instead have Fossil running in the background in standalone
HTTP server mode, bound to a high random TCP port number on
localhost via the
--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
execargs directives and add this instead:
connect = 9000
stunnel to connect to an already-running process listening
on the given TCP port number.
There are a few advantages to this mode:
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.
The socket listener mode doesn’t work on all platforms that
stunnelruns on, particularly on Windows.