Fossil

Check-in [53b2e866]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Moved the stunnel proxying docs from www/ssl.wiki to a new document www/server/any/stunnel.md, and pointed www/server.wiki at it. Also replaced some similar material in this branch's new www/server/windows/stunnel.md file at this generic document. Between these two changes, the generic stunnel docs now cover the reverse proxying option for the first time. (The old version used the socket activation method exclusively.) The new document also gives a more realistic configuration, showing Let's Encrypt paths and a sensible ciphersuite configuration.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | server-docs
Files: files | file ages | folders
SHA3-256: 53b2e866e1632ad000c2e87e37c453a590acd4eba968c32287545e688dd0a2e0
User & Date: wyoung 2019-08-16 09:54:12
Context
2019-08-16
09:55
Added some named anchors to www/server/any/stunnel.md check-in: ce4b4bae user: wyoung tags: server-docs
09:54
Moved the stunnel proxying docs from www/ssl.wiki to a new document www/server/any/stunnel.md, and pointed www/server.wiki at it. Also replaced some similar material in this branch's new www/server/windows/stunnel.md file at this generic document. Between these two changes, the generic stunnel docs now cover the reverse proxying option for the first time. (The old version used the socket activation method exclusively.) The new document also gives a more realistic configuration, showing Let's Encrypt paths and a sensible ciphersuite configuration. check-in: 53b2e866 user: wyoung tags: server-docs
09:15
Split the HTTP-only parts out of www/tls-nginx.md into a new document discussing only the reverse-proxying of `fossil --scgi` to HTTP using nginx on Debian type OSes. That material is now in www/server/debian/nginx.md, which is referred to from www/server.wiki. While in there, did a bit of prose polishing on this old guide. check-in: 2baa8151 user: wyoung tags: server-docs
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/server.wiki.

71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
    </tr>

    <tr>
        <th style="background-color: #e8e8e8; padding: 6px; text-align: right">Any</th>
        <td style="text-align: center"><a href="./server/any/none.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/inetd.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/xinetd.md">✅</a></td>
        <td style="text-align: center"><a href="./ssl.wiki#stunnel">✅</a></td>
        <td style="text-align: center"><a href="./server/any/cgi.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/scgi.md">✅</a></td>
        <td style="text-align: center">❌</td>
        <td style="text-align: center">❌</td>
        <td style="text-align: center">❌</td>
        <td style="text-align: center">❌</td>
    </tr>

    <tr>
        <th style="background-color: #e8e8e8; padding: 6px; text-align: right">Debian/Ubuntu</th>
        <td style="text-align: center"><a href="./server/any/none.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/inetd.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/xinetd.md">✅</a></td>
        <td style="text-align: center"><a href="./ssl.wiki#stunnel">✅</a></td>
        <td style="text-align: center"><a href="./server/any/cgi.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/scgi.md">✅</a></td>
        <td style="text-align: center"><a href="./server/debian/nginx.md">✅</a></td>
        <td style="text-align: center">❌</td>
        <td style="text-align: center">❌</td>
        <td style="text-align: center">❌</td>
    </tr>







|













|







71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
    </tr>

    <tr>
        <th style="background-color: #e8e8e8; padding: 6px; text-align: right">Any</th>
        <td style="text-align: center"><a href="./server/any/none.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/inetd.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/xinetd.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/stunnel.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/cgi.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/scgi.md">✅</a></td>
        <td style="text-align: center">❌</td>
        <td style="text-align: center">❌</td>
        <td style="text-align: center">❌</td>
        <td style="text-align: center">❌</td>
    </tr>

    <tr>
        <th style="background-color: #e8e8e8; padding: 6px; text-align: right">Debian/Ubuntu</th>
        <td style="text-align: center"><a href="./server/any/none.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/inetd.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/xinetd.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/stunnel.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/cgi.md">✅</a></td>
        <td style="text-align: center"><a href="./server/any/scgi.md">✅</a></td>
        <td style="text-align: center"><a href="./server/debian/nginx.md">✅</a></td>
        <td style="text-align: center">❌</td>
        <td style="text-align: center">❌</td>
        <td style="text-align: center">❌</td>
    </tr>

Added www/server/any/stunnel.md.



























































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
# 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 activation — 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 activation 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 activation mode, where the Fossil binary has to be
    loaded and re-initialized on each HTTPS hit.

2.  The socket activation mode doesn’t work on all platforms that
    `stunnel` runs on, particularly [on Windows](../windows/stunnel.md).

Changes to www/server/windows/stunnel.md.

23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
...
111
112
113
114
115
116
117


118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

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 8080 --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 - 8080 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
................................................................................
```

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



Next, open up the `stunnel.conf` file located at `\Program Files (x86)\stunnel\config`
and add the below section.

```dosini
; proxy to fossil-scm service
[fossil]
accept = 443
connect = 8080
cert = fossil-scm.pem
key = fossil-scm.key
TIMEOUTclose = 0
```

After completing the above configuration restart the stunnel service in Windows
with the following:

```PowerShell
Restart-Service -Name stunnel
```







|




|







 







>
>
|
<

<
|
|
<
<
<
<
<
<







23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
...
111
112
113
114
115
116
117
118
119
120

121

122
123






124
125
126
127
128
129
130

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
................................................................................
```

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
```

Changes to www/ssl.wiki.

209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
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.


<h3 id="stunnel">stunnel Alone</h3>

[https://www.stunnel.org/ | <tt>stunnel</tt>] is an
[https://en.wikipedia.org/wiki/Inetd | <tt>inetd</tt>]-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 <tt>stunnel</tt>
and then place something like this in its main configuration file,
<tt>stunnel.conf</tt>:

<nowiki><pre>
    [https]
    accept       = www.ubercool-project.org:443
    TIMEOUTclose = 0
    exec         = /usr/bin/fossil
    execargs     = /usr/bin/fossil http /home/fossil/ubercool.fossil --https
</pre></nowiki>

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 <tt>stunnel</tt> documentation for further details about this
configuration file.

It is important that the [/help/http | <tt>fossil http</tt>] command in
that configuration include the <tt>--https</tt> option to let Fossil
know to use "<tt>https</tt>" instead of "<tt>http</tt>" as the URL
scheme on generated hyperlinks.


<h3 id="althttpd">stunnel + althttpd</h3>

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







|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







209
210
211
212
213
214
215
216

























217
218
219
220
221
222
223
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.


<h3 id="stunnel">stunnel Alone</h3>

That's covered [./server/any/stunnel.md | elsewhere].



























<h3 id="althttpd">stunnel + althttpd</h3>

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