|
1
|
# Using stunnel with Fossil on Windows |
|
2
|
|
|
3
|
While there are many ways to configure Fossil as a server using various web |
|
4
|
servers (Apache, IIS, nginx, etc.), this document will focus on setting up a |
|
5
|
minimal Fossil server using only Fossil's native [server |
|
6
|
capabilities](../any/none.md) and [stunnel](https://www.stunnel.org/) |
|
7
|
to provide a TLS proxy. It is recommended for public repositories to go to the |
|
8
|
extra step of configuring stunnel to provide a proper HTTPS setup. |
|
9
|
|
|
10
|
## Assumptions |
|
11
|
|
|
12
|
1. You have Administrative access to a Windows 2012r2 or above server. |
|
13
|
2. You have PowerShell 5.1 or above installed. |
|
14
|
3. You have acquired a certificate either from a Public CA or an Internal CA. |
|
15
|
|
|
16
|
## Configure Fossil Service for https |
|
17
|
|
|
18
|
Due to the need for the `--https` option for successfully using Fossil with |
|
19
|
stunnel, we will use [Advanced service installation using PowerShell](./service.md#PowerShell). |
|
20
|
We will need to change the command to install the Fossil Service to configure |
|
21
|
it properly for use with stunnel as an https proxy. Run the following: |
|
22
|
|
|
23
|
```PowerShell |
|
24
|
New-Service -Name fossil-secure -DisplayName fossil-secure -BinaryPathName '"C:\Program Files\FossilSCM\fossil.exe" server --localhost --port 9000 --https --repolist "D:/Path/to/Repos"' -StartupType Automatic |
|
25
|
``` |
|
26
|
|
|
27
|
The use of `--localhost` means Fossil will only listen for traffic on the local |
|
28
|
host on the designated port - 9000 in this case - and will not respond to |
|
29
|
network traffic. Using `--https` will tell Fossil to generate HTTPS URLs rather |
|
30
|
than HTTP ones. |
|
31
|
|
|
32
|
`New-Service` does not automatically start a service on install, so you will |
|
33
|
need to enter the following to avoid rebooting the server: |
|
34
|
|
|
35
|
```PowerShell |
|
36
|
Start-Service -Name fossil-secure |
|
37
|
``` |
|
38
|
|
|
39
|
To remove the service, run the following in a Powershell or cmd console: |
|
40
|
|
|
41
|
``` |
|
42
|
sc.exe delete fossil |
|
43
|
``` |
|
44
|
|
|
45
|
or (in a Powershell console) |
|
46
|
|
|
47
|
```PowerShell |
|
48
|
Remove-Service -Name fossil |
|
49
|
``` |
|
50
|
|
|
51
|
if your version of Powershell is 6.0 or above. |
|
52
|
|
|
53
|
## Install stunnel 5.55 |
|
54
|
|
|
55
|
Download stunnel from the [downloads](https://www.stunnel.org/downloads.html) |
|
56
|
page. Select the latest stunnel windows package (at the time of writing this is |
|
57
|
`stunnel-5.55-win64-installer.exe`). Execute the installer and make sure you |
|
58
|
install openSSL tools when you install stunnel. You will need this to convert |
|
59
|
your certificate from PFX to PEM format. |
|
60
|
|
|
61
|
Even though the installer says it is for win64, it installs stunnel by default |
|
62
|
to `\Program Files (x86)\stunnel`. |
|
63
|
|
|
64
|
## Get your certificate ready for Stunnel |
|
65
|
|
|
66
|
Whether you use a Public Certificate Authority or Internal Certificate |
|
67
|
Authority, the next step is exporting the certificate from Windows into a format |
|
68
|
useable by Stunnel. |
|
69
|
|
|
70
|
### Export Certificate from Windows |
|
71
|
|
|
72
|
If your certificate is installed via Windows Certificate Management, you will |
|
73
|
need to export the certificate into a usable format. You can do this either |
|
74
|
using the Windows Certificate Management Console, or PowerShell. |
|
75
|
|
|
76
|
#### Certificate Management Console |
|
77
|
|
|
78
|
Start `mmc.exe` as an Administrator. Select 'File>Add/Remove Snapin', select |
|
79
|
'Certificates' from the list, and click 'Add'. Select 'Computer Account', |
|
80
|
'Next', 'Local Computer', and then 'Finish'. In the Console Root, expand |
|
81
|
'Certificates', then 'Personal', and select 'Certificates'. In the middle pane |
|
82
|
find and select your certificate. Right click the certificate and select |
|
83
|
'All Tasks>Export'. You want to export as PFX the Private Key, include all |
|
84
|
certificates in the certification path, and use a password only to secure the |
|
85
|
file. Enter a path and file name to a working directory and complete the |
|
86
|
export. |
|
87
|
|
|
88
|
Continue with [Convert Certificate from PFX to PEM](#convert). |
|
89
|
|
|
90
|
#### PowerShell |
|
91
|
|
|
92
|
If you know the Friendly |
|
93
|
Name of the Certificate this is relatively easy. Since you need to export |
|
94
|
the private key as well, you must run the following from an Administrative |
|
95
|
PowerShell console. |
|
96
|
|
|
97
|
```PowerShell |
|
98
|
$passwd = ConvertTo-SecureString -string "yourpassword" -Force -AsPlainText |
|
99
|
|
|
100
|
Get-ChildItem Cert:\LocalMachine\My | Where{$_.FriendlyName -eq "FriendlyName"} | |
|
101
|
Export-PfxCertificate -FilePath fossil-scm.pfx -Password $passwd |
|
102
|
``` |
|
103
|
|
|
104
|
You will now have your certificate stored as a PFX file. |
|
105
|
|
|
106
|
<a id="convert"></a> |
|
107
|
### Convert Certificate from PFX to PEM |
|
108
|
|
|
109
|
For this step you will need the openssl tools that were installed with stunnel. |
|
110
|
|
|
111
|
```PowerShell |
|
112
|
# Add stunnel\bin directory to path for this session. |
|
113
|
$env:PATH += ";${env:ProgramFiles(x86)}\stunnel\bin" |
|
114
|
# Export Private Key |
|
115
|
openssl.exe pkcs12 -in fossil-scm.pfx -out fossil-scm.key -nocerts -nodes |
|
116
|
# Export the Certificate |
|
117
|
openssl.exe pkcs12 -in fossil-scm.pfx -out fossil-scm.pem -nokeys |
|
118
|
``` |
|
119
|
|
|
120
|
Now move `fossil-scm.key` and `fossil-scm.pem` to your stunnel config directory |
|
121
|
(by default this should be located at `\Program Files (x86)\stunne\config`). |
|
122
|
|
|
123
|
## stunnel Configuration |
|
124
|
|
|
125
|
Use the reverse proxy configuration given in the generic [Serving via |
|
126
|
stunnel document](../any/stunnel.md#proxy). On Windows, the |
|
127
|
`stunnel.conf` file is located at `\Program Files (x86)\stunnel\config`. |
|
128
|
|
|
129
|
You will need to modify it to point at the PEM and key files generated |
|
130
|
above. |
|
131
|
|
|
132
|
After completing the above configuration restart the stunnel service in Windows |
|
133
|
with the following: |
|
134
|
|
|
135
|
```PowerShell |
|
136
|
Restart-Service -Name stunnel |
|
137
|
``` |
|
138
|
|
|
139
|
## Open up port 443 in the Windows Firewall |
|
140
|
|
|
141
|
The following instructions are for the [Windows Advanced |
|
142
|
Firewall](https://docs.microsoft.com/en-us/windows/security/threat-protection/windows-firewall/windows-firewall-with-advanced-security). |
|
143
|
If you are using a different Firewall, please consult your Firewall |
|
144
|
documentation for how to open port 443 for inbound traffic. |
|
145
|
|
|
146
|
The following command should be entered all on one line. |
|
147
|
|
|
148
|
```PowerShell |
|
149
|
New-NetFirewallRule -DisplayName "Allow Fossil Inbound" -Description "Allow Fossil inbound on port 443 using Stunnel as TLS Proxy." |
|
150
|
-Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow -Program "C:\Program Files (x86)\Stunnel\bin\stunnel.exe" |
|
151
|
``` |
|
152
|
|
|
153
|
You should now be able to access your new Fossil Server via HTTPS. |
|
154
|
|
|
155
|
|
|
156
|
*[Return to the top-level Fossil server article.](../)* |
|
157
|
|