|
f146e21…
|
drh
|
1 |
# Serving via stunnel |
|
f146e21…
|
drh
|
2 |
|
|
f146e21…
|
drh
|
3 |
[`stunnel`](https://www.stunnel.org/) is a TLS/SSL proxy for programs |
|
f146e21…
|
drh
|
4 |
that themselves serve only via HTTP, such as Fossil. (Fossil *can* speak |
|
f146e21…
|
drh
|
5 |
HTTPS, but only as a client.) `stunnel` decodes the HTTPS data from the |
|
f146e21…
|
drh
|
6 |
outside world as HTTP before passing it to Fossil, and it encodes the |
|
f146e21…
|
drh
|
7 |
HTTP replies from Fossil as HTTPS before sending them to the remote host |
|
f146e21…
|
drh
|
8 |
that made the request. |
|
f146e21…
|
drh
|
9 |
|
|
f146e21…
|
drh
|
10 |
You can run `stunnel` in one of two modes: socket listener — much like |
|
f146e21…
|
drh
|
11 |
in our [`inetd` doc](./inetd.md) — and as an HTTP reverse proxy. We’ll |
|
f146e21…
|
drh
|
12 |
cover both cases here, separately. |
|
f146e21…
|
drh
|
13 |
|
|
f146e21…
|
drh
|
14 |
|
|
93cee1f…
|
wyoung
|
15 |
## <a id="sa"></a>Socket Activation |
|
f146e21…
|
drh
|
16 |
|
|
f146e21…
|
drh
|
17 |
The following `stunnel.conf` configuration configures it to run Fossil |
|
f146e21…
|
drh
|
18 |
in socket listener mode, launching Fossil only when an HTTPS hit comes |
|
f146e21…
|
drh
|
19 |
in, then shutting it back down as soon as the transaction is complete: |
|
f146e21…
|
drh
|
20 |
|
|
f146e21…
|
drh
|
21 |
```dosini |
|
f146e21…
|
drh
|
22 |
[fossil] |
|
f146e21…
|
drh
|
23 |
accept = 443 |
|
f146e21…
|
drh
|
24 |
TIMEOUTclose = 0 |
|
f146e21…
|
drh
|
25 |
exec = /usr/bin/fossil |
|
f146e21…
|
drh
|
26 |
execargs = /usr/bin/fossil http /home/fossil/ubercool.fossil --https |
|
f146e21…
|
drh
|
27 |
cert = /etc/letsencrypt/live/ubercool-project.org/fullchain.pem |
|
f146e21…
|
drh
|
28 |
key = /etc/letsencrypt/live/ubercool-project.org/privkey.pem |
|
f146e21…
|
drh
|
29 |
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 |
|
f146e21…
|
drh
|
30 |
options = CIPHER_SERVER_PREFERENCE |
|
f146e21…
|
drh
|
31 |
``` |
|
f146e21…
|
drh
|
32 |
|
|
f146e21…
|
drh
|
33 |
This configuration shows the TLS certificate generated by the [Let’s |
|
f146e21…
|
drh
|
34 |
Encrypt](https://letsencrypt.org) [Certbot](https://certbot.eff.org) in |
|
f146e21…
|
drh
|
35 |
[certonly mode](https://certbot.eff.org/lets-encrypt/debianbuster-other). |
|
f146e21…
|
drh
|
36 |
There are other ways to get TLS certificates, but this is a popular and |
|
f146e21…
|
drh
|
37 |
free option. |
|
f146e21…
|
drh
|
38 |
|
|
f146e21…
|
drh
|
39 |
You will need to adjust the site names and paths in this example. Where |
|
f146e21…
|
drh
|
40 |
this file goes varies by OS type, so check the man pages on your system |
|
f146e21…
|
drh
|
41 |
to find out where it should be locally. |
|
f146e21…
|
drh
|
42 |
|
|
f146e21…
|
drh
|
43 |
See the `stunnel` documentation for further details about this |
|
f146e21…
|
drh
|
44 |
configuration file. |
|
f146e21…
|
drh
|
45 |
|
|
f146e21…
|
drh
|
46 |
It is important that the [`fossil http`](/help/http) command in that |
|
f146e21…
|
drh
|
47 |
configuration include the `--https` option to let Fossil know to use |
|
f146e21…
|
drh
|
48 |
“`https://`” instead of “`http://`” in generated hyperlinks. |
|
f146e21…
|
drh
|
49 |
|
|
f146e21…
|
drh
|
50 |
|
|
f146e21…
|
drh
|
51 |
|
|
93cee1f…
|
wyoung
|
52 |
## <a id="proxy"></a>Reverse Proxy |
|
f146e21…
|
drh
|
53 |
|
|
f146e21…
|
drh
|
54 |
You can instead have Fossil running in the background in [standalone |
|
f146e21…
|
drh
|
55 |
HTTP server mode](./none.md), bound to a high random TCP port number on |
|
f146e21…
|
drh
|
56 |
localhost via the `--localhost` and `--port` flags, then configure |
|
f146e21…
|
drh
|
57 |
`stunnel` to reverse proxy public HTTPS connections down to it via HTTP. |
|
f146e21…
|
drh
|
58 |
|
|
f146e21…
|
drh
|
59 |
The configuration is the same as the above except that you drop the |
|
f146e21…
|
drh
|
60 |
`exec` and `execargs` directives and add this instead: |
|
f146e21…
|
drh
|
61 |
|
|
f146e21…
|
drh
|
62 |
```dosini |
|
f146e21…
|
drh
|
63 |
connect = 9000 |
|
f146e21…
|
drh
|
64 |
``` |
|
f146e21…
|
drh
|
65 |
|
|
f146e21…
|
drh
|
66 |
That tells `stunnel` to connect to an already-running process listening |
|
f146e21…
|
drh
|
67 |
on the given TCP port number. |
|
f146e21…
|
drh
|
68 |
|
|
f146e21…
|
drh
|
69 |
There are a few advantages to this mode: |
|
f146e21…
|
drh
|
70 |
|
|
f146e21…
|
drh
|
71 |
1. At the cost of some server memory and a tiny bit of idle CPU time, |
|
f146e21…
|
drh
|
72 |
Fossil remains running so that hits can be served a smidge faster |
|
f146e21…
|
drh
|
73 |
than in socket listener mode, where the Fossil binary has to be |
|
f146e21…
|
drh
|
74 |
loaded and re-initialized on each HTTPS hit. |
|
f146e21…
|
drh
|
75 |
|
|
f146e21…
|
drh
|
76 |
2. The socket listener mode doesn’t work on all platforms that |
|
f146e21…
|
drh
|
77 |
`stunnel` runs on, particularly [on Windows](../windows/stunnel.md). |
|
f146e21…
|
drh
|
78 |
|
|
f146e21…
|
drh
|
79 |
*[Return to the top-level Fossil server article.](../)* |
|
93cee1f…
|
wyoung
|
80 |
|
|
93cee1f…
|
wyoung
|
81 |
<div style="height:50em" id="this-space-intentionally-left-blank"></div> |