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