Fossil SCM

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

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button