Fossil SCM
Update the ssl-server.md document to conform to the latest changes.
Commit
593c13baf27e01c69fbfe951ef0f7d4013006cde0866ca7b807045e1b920d2c7
Parent
a0623f6928bf6bd…
1 file changed
+27
-42
+27
-42
| --- www/ssl-server.md | ||
| +++ www/ssl-server.md | ||
| @@ -28,25 +28,27 @@ | ||
| 28 | 28 | obtaining a CA-signed certificate. |
| 29 | 29 | |
| 30 | 30 | ## Usage |
| 31 | 31 | |
| 32 | 32 | To put any of the Fossil server commands into SSL/TLS mode, simply |
| 33 | -add the "--ssl" command-line option. (Or use "--tls" which is an | |
| 34 | -alias.) Like this: | |
| 33 | +add the "--cert" command-line option. | |
| 35 | 34 | |
| 36 | 35 | > ~~~ |
| 37 | -fossil ui --ssl | |
| 36 | +fossil ui --cert unsafe-builtin | |
| 38 | 37 | ~~~ |
| 39 | 38 | |
| 40 | -Since no certificate (or "cert") has been specified, Fossil will use | |
| 41 | -a self-signed cert that is built into Fossil itself. The fact that the | |
| 42 | -cert is self-signed, rather than being signed by a | |
| 39 | +The --cert option is what tells Fossil to use TLS encryption. | |
| 40 | +Normally, the argument to --cert is the name of a file containing | |
| 41 | +the certificate (the "fullchain.pem" file) for the website. In this | |
| 42 | +example, the magic name "unsafe-builtin" is used, which causes Fossil | |
| 43 | +to use a self-signed cert rather than a real cert obtained from a | |
| 43 | 44 | [Certificate Authority](https://en.wikipedia.org/wiki/Certificate_authority) |
| 44 | -or "CA", means that your web-browser will complain bitterly and will refuse | |
| 45 | -to display the pages that Fossil returns. Some web browsers (ex: Firefox) | |
| 46 | -will allow you to click an "I know the risks" button and continue. Other | |
| 47 | -web browsers will stubornly refuse to display the page, under the theory | |
| 45 | +or "CA". As the name implies, this self-signed cert is not secure and | |
| 46 | +should only be used for testing. Your web-browser will complain bitterly | |
| 47 | +and will refuse to display the pages using the "unsafe-builtin" cert. | |
| 48 | +Firefox will allow you to click an "I know the risks" button and continue. | |
| 49 | +Other web browsers will stubornly refuse to display the page, under the theory | |
| 48 | 50 | that weak encryption is worse than no encryption at all. Continue reading |
| 49 | 51 | to see how to solve this. |
| 50 | 52 | |
| 51 | 53 | ## About Certs |
| 52 | 54 | |
| @@ -71,13 +73,13 @@ | ||
| 71 | 73 | can verify it. But the private key is kept strictly private and is never |
| 72 | 74 | shared with anyone. |
| 73 | 75 | |
| 74 | 76 | ## How To Tell Fossil About Your Cert And Private Key |
| 75 | 77 | |
| 76 | -If you do not tell Fossil about a cert and private key, it uses a | |
| 77 | -generic "private key" and self-signed cert that is built into Fossil. | |
| 78 | -This is wildly insecure, since the private key is not really private - | |
| 78 | +If you do not have your own cert and private key, you can ask Fossil | |
| 79 | +to use "unsafe-builtin", which is a self-signed cert that is built into | |
| 80 | +Fossil. This is wildly insecure, since the private key is not really private - | |
| 79 | 81 | it is [in plain sight](/info/c2a7b14c3f541edb96?ln=89-116) in the Fossil |
| 80 | 82 | source tree for anybody to read. <b>Never add the private key that is |
| 81 | 83 | built into Fossil to your OS's trust store</b> as doing so will severely |
| 82 | 84 | compromise your computer. The built-in cert is only useful for testing. |
| 83 | 85 | If you want actual security, you will need to come up with your own private |
| @@ -105,22 +107,32 @@ | ||
| 105 | 107 | certificate, you can concatenate the two into a single file and the |
| 106 | 108 | individual components will still be easily accessible. |
| 107 | 109 | |
| 108 | 110 | If you have a single file that holds both your private key and your |
| 109 | 111 | cert, you can hand it off to the "[fossil server](/help?cmd=server)" |
| 110 | -command using the --tls-cert-file option. Like this: | |
| 112 | +command using the --cert option. Like this: | |
| 111 | 113 | |
| 112 | 114 | > ~~~ |
| 113 | -fossil server --port 443 --tls-cert-file mycert.pem /home/www/myproject.fossil | |
| 115 | +fossil server --port 443 --cert mycert.pem /home/www/myproject.fossil | |
| 114 | 116 | ~~~ |
| 115 | 117 | |
| 116 | 118 | The command above is sufficient to run a fully-encrypted web site for |
| 117 | 119 | the "myproject.fossil" Fossil repository. This command must be run as |
| 118 | 120 | root, since it wants to listen on TCP port 443, and only root processes are |
| 119 | 121 | allowed to do that. This is safe, however, since before reading any |
| 120 | 122 | information off of the wire, Fossil will put itself inside a chroot jail |
| 121 | 123 | at /home/www and drop all root privileges. |
| 124 | + | |
| 125 | +### Keeping The Cert And Private Key In Separate Files | |
| 126 | + | |
| 127 | +If you do not want to combine your cert and private key into a single | |
| 128 | +big PEM file, you can keep them separate using the --pkey option to | |
| 129 | +Fossil. | |
| 130 | + | |
| 131 | +> ~~~ | |
| 132 | +fossil server --port 443 --cert fullchain.pem --pkey privkey.pem /home/www/myproject.fossil | |
| 133 | +~~~ | |
| 122 | 134 | |
| 123 | 135 | ## The ACME Protocol |
| 124 | 136 | |
| 125 | 137 | The [ACME Protocol][2] is used to prove to a CA that you control a |
| 126 | 138 | website. CAs require proof that you control a domain before they |
| @@ -172,34 +184,7 @@ | ||
| 172 | 184 | named "/home/www/.well-known" and put token files there, which the CA |
| 173 | 185 | will verify. Then certbot will store your new cert in a particular file. |
| 174 | 186 | |
| 175 | 187 | Once certbot has obtained your cert, then you can concatenate that |
| 176 | 188 | cert with your private key and run Fossil in SSL/TLS mode as shown above. |
| 177 | - | |
| 178 | -## Separate Cert And Private Key Files Using Settings | |
| 179 | - | |
| 180 | -If you do not want to concatenate your cert and private key, you can | |
| 181 | -tell Fossil about the files separately using settings. Run a command | |
| 182 | -like this on your repository: | |
| 183 | - | |
| 184 | -> ~~~ | |
| 185 | -fossil ssl-config load-cert --filename CERT-FILE.pem PRIVATE-KEY.pem | |
| 186 | -~~~ | |
| 187 | - | |
| 188 | -Substitute whatever filenames are appropriate in the command above, of | |
| 189 | -course. Run "[fossil ssl-config](/help?cmd=ssl-config)" by itself to see | |
| 190 | -the resulting configuration. Once you have done this, you can then | |
| 191 | -restart your TLS server using just: | |
| 192 | - | |
| 193 | -> ~~~ | |
| 194 | -fossil server --port 443 --tls /home/www/myproject.fossil | |
| 195 | -~~~ | |
| 196 | - | |
| 197 | -Note however that this technique only works if you are serving a single | |
| 198 | -repository from your website. If the argument to your "fossil server" command | |
| 199 | -is the name of a directory that contains many Fossil repositories, then | |
| 200 | -there is no one repository in which to put this setting, and so you have | |
| 201 | -to specify the location of the combined cert and private key file using | |
| 202 | -the --tls-cert-file option on the command-line. | |
| 203 | - | |
| 204 | 189 | |
| 205 | 190 | [2]: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment |
| 206 | 191 |
| --- www/ssl-server.md | |
| +++ www/ssl-server.md | |
| @@ -28,25 +28,27 @@ | |
| 28 | obtaining a CA-signed certificate. |
| 29 | |
| 30 | ## Usage |
| 31 | |
| 32 | To put any of the Fossil server commands into SSL/TLS mode, simply |
| 33 | add the "--ssl" command-line option. (Or use "--tls" which is an |
| 34 | alias.) Like this: |
| 35 | |
| 36 | > ~~~ |
| 37 | fossil ui --ssl |
| 38 | ~~~ |
| 39 | |
| 40 | Since no certificate (or "cert") has been specified, Fossil will use |
| 41 | a self-signed cert that is built into Fossil itself. The fact that the |
| 42 | cert is self-signed, rather than being signed by a |
| 43 | [Certificate Authority](https://en.wikipedia.org/wiki/Certificate_authority) |
| 44 | or "CA", means that your web-browser will complain bitterly and will refuse |
| 45 | to display the pages that Fossil returns. Some web browsers (ex: Firefox) |
| 46 | will allow you to click an "I know the risks" button and continue. Other |
| 47 | web browsers will stubornly refuse to display the page, under the theory |
| 48 | that weak encryption is worse than no encryption at all. Continue reading |
| 49 | to see how to solve this. |
| 50 | |
| 51 | ## About Certs |
| 52 | |
| @@ -71,13 +73,13 @@ | |
| 71 | can verify it. But the private key is kept strictly private and is never |
| 72 | shared with anyone. |
| 73 | |
| 74 | ## How To Tell Fossil About Your Cert And Private Key |
| 75 | |
| 76 | If you do not tell Fossil about a cert and private key, it uses a |
| 77 | generic "private key" and self-signed cert that is built into Fossil. |
| 78 | This is wildly insecure, since the private key is not really private - |
| 79 | it is [in plain sight](/info/c2a7b14c3f541edb96?ln=89-116) in the Fossil |
| 80 | source tree for anybody to read. <b>Never add the private key that is |
| 81 | built into Fossil to your OS's trust store</b> as doing so will severely |
| 82 | compromise your computer. The built-in cert is only useful for testing. |
| 83 | If you want actual security, you will need to come up with your own private |
| @@ -105,22 +107,32 @@ | |
| 105 | certificate, you can concatenate the two into a single file and the |
| 106 | individual components will still be easily accessible. |
| 107 | |
| 108 | If you have a single file that holds both your private key and your |
| 109 | cert, you can hand it off to the "[fossil server](/help?cmd=server)" |
| 110 | command using the --tls-cert-file option. Like this: |
| 111 | |
| 112 | > ~~~ |
| 113 | fossil server --port 443 --tls-cert-file mycert.pem /home/www/myproject.fossil |
| 114 | ~~~ |
| 115 | |
| 116 | The command above is sufficient to run a fully-encrypted web site for |
| 117 | the "myproject.fossil" Fossil repository. This command must be run as |
| 118 | root, since it wants to listen on TCP port 443, and only root processes are |
| 119 | allowed to do that. This is safe, however, since before reading any |
| 120 | information off of the wire, Fossil will put itself inside a chroot jail |
| 121 | at /home/www and drop all root privileges. |
| 122 | |
| 123 | ## The ACME Protocol |
| 124 | |
| 125 | The [ACME Protocol][2] is used to prove to a CA that you control a |
| 126 | website. CAs require proof that you control a domain before they |
| @@ -172,34 +184,7 @@ | |
| 172 | named "/home/www/.well-known" and put token files there, which the CA |
| 173 | will verify. Then certbot will store your new cert in a particular file. |
| 174 | |
| 175 | Once certbot has obtained your cert, then you can concatenate that |
| 176 | cert with your private key and run Fossil in SSL/TLS mode as shown above. |
| 177 | |
| 178 | ## Separate Cert And Private Key Files Using Settings |
| 179 | |
| 180 | If you do not want to concatenate your cert and private key, you can |
| 181 | tell Fossil about the files separately using settings. Run a command |
| 182 | like this on your repository: |
| 183 | |
| 184 | > ~~~ |
| 185 | fossil ssl-config load-cert --filename CERT-FILE.pem PRIVATE-KEY.pem |
| 186 | ~~~ |
| 187 | |
| 188 | Substitute whatever filenames are appropriate in the command above, of |
| 189 | course. Run "[fossil ssl-config](/help?cmd=ssl-config)" by itself to see |
| 190 | the resulting configuration. Once you have done this, you can then |
| 191 | restart your TLS server using just: |
| 192 | |
| 193 | > ~~~ |
| 194 | fossil server --port 443 --tls /home/www/myproject.fossil |
| 195 | ~~~ |
| 196 | |
| 197 | Note however that this technique only works if you are serving a single |
| 198 | repository from your website. If the argument to your "fossil server" command |
| 199 | is the name of a directory that contains many Fossil repositories, then |
| 200 | there is no one repository in which to put this setting, and so you have |
| 201 | to specify the location of the combined cert and private key file using |
| 202 | the --tls-cert-file option on the command-line. |
| 203 | |
| 204 | |
| 205 | [2]: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment |
| 206 |
| --- www/ssl-server.md | |
| +++ www/ssl-server.md | |
| @@ -28,25 +28,27 @@ | |
| 28 | obtaining a CA-signed certificate. |
| 29 | |
| 30 | ## Usage |
| 31 | |
| 32 | To put any of the Fossil server commands into SSL/TLS mode, simply |
| 33 | add the "--cert" command-line option. |
| 34 | |
| 35 | > ~~~ |
| 36 | fossil ui --cert unsafe-builtin |
| 37 | ~~~ |
| 38 | |
| 39 | The --cert option is what tells Fossil to use TLS encryption. |
| 40 | Normally, the argument to --cert is the name of a file containing |
| 41 | the certificate (the "fullchain.pem" file) for the website. In this |
| 42 | example, the magic name "unsafe-builtin" is used, which causes Fossil |
| 43 | to use a self-signed cert rather than a real cert obtained from a |
| 44 | [Certificate Authority](https://en.wikipedia.org/wiki/Certificate_authority) |
| 45 | or "CA". As the name implies, this self-signed cert is not secure and |
| 46 | should only be used for testing. Your web-browser will complain bitterly |
| 47 | and will refuse to display the pages using the "unsafe-builtin" cert. |
| 48 | Firefox will allow you to click an "I know the risks" button and continue. |
| 49 | Other web browsers will stubornly refuse to display the page, under the theory |
| 50 | that weak encryption is worse than no encryption at all. Continue reading |
| 51 | to see how to solve this. |
| 52 | |
| 53 | ## About Certs |
| 54 | |
| @@ -71,13 +73,13 @@ | |
| 73 | can verify it. But the private key is kept strictly private and is never |
| 74 | shared with anyone. |
| 75 | |
| 76 | ## How To Tell Fossil About Your Cert And Private Key |
| 77 | |
| 78 | If you do not have your own cert and private key, you can ask Fossil |
| 79 | to use "unsafe-builtin", which is a self-signed cert that is built into |
| 80 | Fossil. This is wildly insecure, since the private key is not really private - |
| 81 | it is [in plain sight](/info/c2a7b14c3f541edb96?ln=89-116) in the Fossil |
| 82 | source tree for anybody to read. <b>Never add the private key that is |
| 83 | built into Fossil to your OS's trust store</b> as doing so will severely |
| 84 | compromise your computer. The built-in cert is only useful for testing. |
| 85 | If you want actual security, you will need to come up with your own private |
| @@ -105,22 +107,32 @@ | |
| 107 | certificate, you can concatenate the two into a single file and the |
| 108 | individual components will still be easily accessible. |
| 109 | |
| 110 | If you have a single file that holds both your private key and your |
| 111 | cert, you can hand it off to the "[fossil server](/help?cmd=server)" |
| 112 | command using the --cert option. Like this: |
| 113 | |
| 114 | > ~~~ |
| 115 | fossil server --port 443 --cert mycert.pem /home/www/myproject.fossil |
| 116 | ~~~ |
| 117 | |
| 118 | The command above is sufficient to run a fully-encrypted web site for |
| 119 | the "myproject.fossil" Fossil repository. This command must be run as |
| 120 | root, since it wants to listen on TCP port 443, and only root processes are |
| 121 | allowed to do that. This is safe, however, since before reading any |
| 122 | information off of the wire, Fossil will put itself inside a chroot jail |
| 123 | at /home/www and drop all root privileges. |
| 124 | |
| 125 | ### Keeping The Cert And Private Key In Separate Files |
| 126 | |
| 127 | If you do not want to combine your cert and private key into a single |
| 128 | big PEM file, you can keep them separate using the --pkey option to |
| 129 | Fossil. |
| 130 | |
| 131 | > ~~~ |
| 132 | fossil server --port 443 --cert fullchain.pem --pkey privkey.pem /home/www/myproject.fossil |
| 133 | ~~~ |
| 134 | |
| 135 | ## The ACME Protocol |
| 136 | |
| 137 | The [ACME Protocol][2] is used to prove to a CA that you control a |
| 138 | website. CAs require proof that you control a domain before they |
| @@ -172,34 +184,7 @@ | |
| 184 | named "/home/www/.well-known" and put token files there, which the CA |
| 185 | will verify. Then certbot will store your new cert in a particular file. |
| 186 | |
| 187 | Once certbot has obtained your cert, then you can concatenate that |
| 188 | cert with your private key and run Fossil in SSL/TLS mode as shown above. |
| 189 | |
| 190 | [2]: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment |
| 191 |