Fossil SCM
Updated www/ssl.wiki to cover the new "Redirect to HTTPS" setting and to add recovery methods for the case where enabling it causes a redirect loop.
Commit
226b14fc72e65bf783e1ac3ccd23be683ab8b33a783fac04765c6b9a4ff150d8
Parent
37918a1fa43949c…
1 file changed
+36
-20
+36
-20
| --- www/ssl.wiki | ||
| +++ www/ssl.wiki | ||
| @@ -203,30 +203,46 @@ | ||
| 203 | 203 | repository, be sure to use the <tt>https:</tt> URI scheme in |
| 204 | 204 | <tt>clone</tt> and <tt>sync</tt> commands. If your server is configured |
| 205 | 205 | to serve the repository via both HTTP and HTTPS, it's easy to |
| 206 | 206 | accidentally use unencrypted HTTP if you forget the all-important 's'. |
| 207 | 207 | |
| 208 | -There is a setting in the Fossil UI under Admin → Access called | |
| 209 | -"Redirect to HTTPS on the Login page." This setting is not enabled by | |
| 210 | -default. This setting does not automatically upgrade clones and syncs | |
| 211 | -done via the <tt>http</tt> URI scheme. It only affects web UI access to | |
| 212 | -the Fossil repository. | |
| 213 | - | |
| 214 | -<b id="rloop">WARNING:</b> Never enable this setting when running Fossil | |
| 215 | -behind an HTTPS proxy with Fossil running underneath it via HTTP or | |
| 216 | -SCGI. This will cause an infinite redirect loop any time someone tries | |
| 217 | -to log into the web UI. Fossil sees that it's being accessed via HTTP, | |
| 218 | -so it redirects the browser to an HTTPS equivalent URL, which causes the | |
| 219 | -client to hit the HTTPS front end proxy up again for access, which | |
| 220 | -causes Fossil to see that it's being accessed via HTTP, so it redirects | |
| 221 | -the client to...'round and 'round it goes until the web browser detects | |
| 222 | -it's in a redirect loop and gives up. | |
| 223 | - | |
| 224 | -If you wish to enforce TLS-only access to a Fossil web server, it is | |
| 225 | -best done at the HTTPS front-end proxy layer, not by use of Fossil-level | |
| 226 | -settings like this one. The [./tls-nginx.md|nginx TLS proxy guide] | |
| 227 | -shows one way to achieve this, for example. | |
| 208 | +As of Fossil 2.8, there is a setting in the Fossil UI under Admin → | |
| 209 | +Access called "Redirect to HTTPS," which is set to "Off" by default. | |
| 210 | +Changing this only affects web UI access to the Fossil repository. It | |
| 211 | +doesn't affect clones and syncs done via the <tt>http</tt> URI scheme. | |
| 212 | + | |
| 213 | +In Fossil 2.7 and earlier, there was a much weaker form of this setting | |
| 214 | +affecting the <tt>/login</tt> page only. If you're using this setting, | |
| 215 | +you should migrate to the new setting as soon as possible, because the | |
| 216 | +old setting allows multiple ways of defeating it. | |
| 217 | + | |
| 218 | +<b id="rloop">WARNING:</b> Enabling HTTPS redirects at the Fossil repo | |
| 219 | +level while running Fossil behind an HTTPS proxy can result in an | |
| 220 | +infinite redirect loop. It happens when the proxy mechanism presents | |
| 221 | +"`http`" URIs to Fossil, so Fossil issues a redirect, so the browser | |
| 222 | +fetches the page again, causing Fossil to see an "`http`" URI again, so | |
| 223 | +it issues a redirect...'round and 'round it goes until the web browser | |
| 224 | +detects it's in a redirect loop and gives up. This problem prevents you | |
| 225 | +from getting back into the Admin UI to fix it, but there are several | |
| 226 | +ways to fix it: | |
| 227 | + | |
| 228 | + # <p><b>Reset via CLI.</b> You can turn the setting back off from the | |
| 229 | + CLI with the command "<tt>fossil -R /path/to/repo.fossil set | |
| 230 | + redirect-to-https 0</tt>". (Currently doesn't work.)</p> | |
| 231 | + # <p><b>Backup first.</b> This setting is stored in the Fossil | |
| 232 | + repository, so if you make a backup first <i>on the server</i>, you | |
| 233 | + can restore the repo file if enabling this feature creates a | |
| 234 | + redirect loop.</p> | |
| 235 | + # <p><b>Download, fix, and restore.</b> You can copy the remote | |
| 236 | + repository file down to a local machine, use <tt>fossil ui</tt> to | |
| 237 | + fix the setting, and then upload it to the repository server | |
| 238 | + again.</p> | |
| 239 | + | |
| 240 | +It's best to enforce TLS-only access at the front-end proxy level | |
| 241 | +anyway. It not only avoids the problem entirely, it can be significantly | |
| 242 | +more secure. The [./tls-nginx.md|nginx TLS proxy guide] shows one way | |
| 243 | +to achieve this.</p> | |
| 228 | 244 | |
| 229 | 245 | |
| 230 | 246 | <h2>Terminology Note</h2> |
| 231 | 247 | |
| 232 | 248 | This document is called <tt>ssl.wiki</tt> for historical reasons. The |
| 233 | 249 |
| --- www/ssl.wiki | |
| +++ www/ssl.wiki | |
| @@ -203,30 +203,46 @@ | |
| 203 | repository, be sure to use the <tt>https:</tt> URI scheme in |
| 204 | <tt>clone</tt> and <tt>sync</tt> commands. If your server is configured |
| 205 | to serve the repository via both HTTP and HTTPS, it's easy to |
| 206 | accidentally use unencrypted HTTP if you forget the all-important 's'. |
| 207 | |
| 208 | There is a setting in the Fossil UI under Admin → Access called |
| 209 | "Redirect to HTTPS on the Login page." This setting is not enabled by |
| 210 | default. This setting does not automatically upgrade clones and syncs |
| 211 | done via the <tt>http</tt> URI scheme. It only affects web UI access to |
| 212 | the Fossil repository. |
| 213 | |
| 214 | <b id="rloop">WARNING:</b> Never enable this setting when running Fossil |
| 215 | behind an HTTPS proxy with Fossil running underneath it via HTTP or |
| 216 | SCGI. This will cause an infinite redirect loop any time someone tries |
| 217 | to log into the web UI. Fossil sees that it's being accessed via HTTP, |
| 218 | so it redirects the browser to an HTTPS equivalent URL, which causes the |
| 219 | client to hit the HTTPS front end proxy up again for access, which |
| 220 | causes Fossil to see that it's being accessed via HTTP, so it redirects |
| 221 | the client to...'round and 'round it goes until the web browser detects |
| 222 | it's in a redirect loop and gives up. |
| 223 | |
| 224 | If you wish to enforce TLS-only access to a Fossil web server, it is |
| 225 | best done at the HTTPS front-end proxy layer, not by use of Fossil-level |
| 226 | settings like this one. The [./tls-nginx.md|nginx TLS proxy guide] |
| 227 | shows one way to achieve this, for example. |
| 228 | |
| 229 | |
| 230 | <h2>Terminology Note</h2> |
| 231 | |
| 232 | This document is called <tt>ssl.wiki</tt> for historical reasons. The |
| 233 |
| --- www/ssl.wiki | |
| +++ www/ssl.wiki | |
| @@ -203,30 +203,46 @@ | |
| 203 | repository, be sure to use the <tt>https:</tt> URI scheme in |
| 204 | <tt>clone</tt> and <tt>sync</tt> commands. If your server is configured |
| 205 | to serve the repository via both HTTP and HTTPS, it's easy to |
| 206 | accidentally use unencrypted HTTP if you forget the all-important 's'. |
| 207 | |
| 208 | As of Fossil 2.8, there is a setting in the Fossil UI under Admin → |
| 209 | Access called "Redirect to HTTPS," which is set to "Off" by default. |
| 210 | Changing this only affects web UI access to the Fossil repository. It |
| 211 | doesn't affect clones and syncs done via the <tt>http</tt> URI scheme. |
| 212 | |
| 213 | In Fossil 2.7 and earlier, there was a much weaker form of this setting |
| 214 | affecting the <tt>/login</tt> page only. If you're using this setting, |
| 215 | you should migrate to the new setting as soon as possible, because the |
| 216 | old setting allows multiple ways of defeating it. |
| 217 | |
| 218 | <b id="rloop">WARNING:</b> Enabling HTTPS redirects at the Fossil repo |
| 219 | level while running Fossil behind an HTTPS proxy can result in an |
| 220 | infinite redirect loop. It happens when the proxy mechanism presents |
| 221 | "`http`" URIs to Fossil, so Fossil issues a redirect, so the browser |
| 222 | fetches the page again, causing Fossil to see an "`http`" URI again, so |
| 223 | it issues a redirect...'round and 'round it goes until the web browser |
| 224 | detects it's in a redirect loop and gives up. This problem prevents you |
| 225 | from getting back into the Admin UI to fix it, but there are several |
| 226 | ways to fix it: |
| 227 | |
| 228 | # <p><b>Reset via CLI.</b> You can turn the setting back off from the |
| 229 | CLI with the command "<tt>fossil -R /path/to/repo.fossil set |
| 230 | redirect-to-https 0</tt>". (Currently doesn't work.)</p> |
| 231 | # <p><b>Backup first.</b> This setting is stored in the Fossil |
| 232 | repository, so if you make a backup first <i>on the server</i>, you |
| 233 | can restore the repo file if enabling this feature creates a |
| 234 | redirect loop.</p> |
| 235 | # <p><b>Download, fix, and restore.</b> You can copy the remote |
| 236 | repository file down to a local machine, use <tt>fossil ui</tt> to |
| 237 | fix the setting, and then upload it to the repository server |
| 238 | again.</p> |
| 239 | |
| 240 | It's best to enforce TLS-only access at the front-end proxy level |
| 241 | anyway. It not only avoids the problem entirely, it can be significantly |
| 242 | more secure. The [./tls-nginx.md|nginx TLS proxy guide] shows one way |
| 243 | to achieve this.</p> |
| 244 | |
| 245 | |
| 246 | <h2>Terminology Note</h2> |
| 247 | |
| 248 | This document is called <tt>ssl.wiki</tt> for historical reasons. The |
| 249 |