Fossil SCM
Wiki formatting fix pass on www/server.wiki in preparation for more substantial changes: removed all explicit <p> tags where they don't affect rendering; changed all <a name...><h2> with <h2 id=...>; added whitespace; moved <blockquote> tags down to their own line since they're key to the page layout.
Commit
3406f0eb2da2779743e63b95f75670306aea2a770bbc0a5176d9db5e308adf69
Parent
a2ef43104ffee42…
1 file changed
+113
-101
+113
-101
| --- www/server.wiki | ||
| +++ www/server.wiki | ||
| @@ -1,39 +1,53 @@ | ||
| 1 | 1 | <title>How To Configure A Fossil Server</title> |
| 2 | -<h2>Introduction</h2><blockquote> | |
| 3 | -<p>A server is not necessary to use Fossil, but a server does help in collaborating with | |
| 2 | + | |
| 3 | +<h2>Introduction</h2> | |
| 4 | + | |
| 5 | +<blockquote> | |
| 6 | +A server is not necessary to use Fossil, but a server does help in collaborating with | |
| 4 | 7 | peers. A Fossil server also works well as a complete website for a project. |
| 5 | 8 | For example, the complete [https://www.fossil-scm.org/] website, including the |
| 6 | 9 | page you are now reading, |
| 7 | 10 | is just a Fossil server displaying the content of the |
| 8 | -self-hosting repository for Fossil.</p> | |
| 9 | -<p>This article is a guide for setting up your own Fossil server. | |
| 10 | -<p>See "[./aboutcgi.wiki|How CGI Works In Fossil]" for background | |
| 11 | +self-hosting repository for Fossil. | |
| 12 | + | |
| 13 | +This article is a guide for setting up your own Fossil server. | |
| 14 | + | |
| 15 | +See "[./aboutcgi.wiki|How CGI Works In Fossil]" for background | |
| 11 | 16 | information on the underlying CGI technology. |
| 12 | 17 | See "[./sync.wiki|The Fossil Sync Protocol]" for information on the |
| 13 | -wire protocol used for client/server communication.</p> | |
| 18 | +wire protocol used for client/server communication. | |
| 14 | 19 | </blockquote> |
| 15 | -<h2>Overview</h2><blockquote> | |
| 20 | + | |
| 21 | +<h2>Overview</h2> | |
| 22 | + | |
| 23 | +<blockquote> | |
| 16 | 24 | There are basically four ways to set up a Fossil server: |
| 25 | + | |
| 17 | 26 | <ol> |
| 18 | -<li>A stand-alone server | |
| 19 | -<li>Using inetd or xinetd or stunnel | |
| 20 | -<li>CGI | |
| 21 | -<li>SCGI (a.k.a. SimpleCGI) | |
| 27 | + <li>A stand-alone server | |
| 28 | + <li>Using inetd or xinetd or stunnel | |
| 29 | + <li>CGI | |
| 30 | + <li>SCGI (a.k.a. SimpleCGI) | |
| 22 | 31 | </ol> |
| 32 | + | |
| 23 | 33 | Each of these can serve either a single repository, or a directory hierarchy |
| 24 | 34 | containing many repositories with names ending in ".fossil". |
| 25 | 35 | </blockquote> |
| 26 | -<a name="standalone"></a> | |
| 27 | -<h2>Standalone server</h2><blockquote> | |
| 36 | + | |
| 37 | + | |
| 38 | +<h2 id="standalone">Standalone server</h2> | |
| 39 | + | |
| 40 | +<blockquote> | |
| 28 | 41 | The easiest way to set up a Fossil server is to use either the |
| 29 | 42 | [/help/server|server] or the [/help/ui|ui] commands: |
| 43 | + | |
| 30 | 44 | <ul> |
| 31 | -<li><b>fossil server</b> <i>REPOSITORY</i> | |
| 32 | -<li><b>fossil ui</b> <i>REPOSITORY</i> | |
| 45 | + <li><b>fossil server</b> <i>REPOSITORY</i> | |
| 46 | + <li><b>fossil ui</b> <i>REPOSITORY</i> | |
| 33 | 47 | </ul> |
| 34 | -<p> | |
| 48 | + | |
| 35 | 49 | The <i>REPOSITORY</i> argument is either the name of the repository file, or |
| 36 | 50 | a directory containing many repositories. |
| 37 | 51 | Both of these commands start a Fossil server, usually on TCP port 8080, though |
| 38 | 52 | a higher numbered port might also be used if 8080 is already occupied. You can |
| 39 | 53 | access these using URLs of the form <b>http://localhost:8080/</b>, or if |
| @@ -43,61 +57,65 @@ | ||
| 43 | 57 | The difference between "ui" and "server" is that "ui" will |
| 44 | 58 | also start a web browser and point it |
| 45 | 59 | to the URL mentioned above, and the "ui" command binds to |
| 46 | 60 | the loopback IP address (127.0.0.1) only so that the "ui" command cannot be |
| 47 | 61 | used to serve content to a different machine. |
| 48 | -</p> | |
| 49 | -<p> | |
| 62 | + | |
| 50 | 63 | If one of the commands above is run from within an open checkout, |
| 51 | 64 | then the <i>REPOSITORY</i> argument can be omitted and the checkout is used as |
| 52 | 65 | the repository. |
| 53 | -</p> | |
| 54 | -<p> | |
| 66 | + | |
| 55 | 67 | Both commands have additional command-line options that can be used to refine |
| 56 | 68 | their behavior. See the [/help/server|online documentation] for an overview. |
| 57 | -</p> | |
| 58 | 69 | </blockquote> |
| 59 | -<a name="inetd"></a> | |
| 60 | -<h2>Fossil as an inetd/xinetd or stunnel service</h2><blockquote> | |
| 61 | -<p> | |
| 70 | + | |
| 71 | + | |
| 72 | +<h2 id="inetd">Fossil as an inetd/xinetd or stunnel service</h2> | |
| 73 | + | |
| 74 | +<blockquote> | |
| 75 | + | |
| 62 | 76 | A Fossil server can be launched on-demand by inetd or xinetd using |
| 63 | 77 | the [/help/http|fossil http] command. To launch Fossil from inetd, modify |
| 64 | 78 | your inetd configuration file (typically "/etc/inetd.conf") to contain a |
| 65 | 79 | line something like this: |
| 80 | + | |
| 66 | 81 | <blockquote> |
| 67 | 82 | <pre> |
| 68 | 83 | 80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil |
| 69 | 84 | </pre> |
| 70 | 85 | </blockquote> |
| 86 | + | |
| 71 | 87 | In this example, you are telling "inetd" that when an incoming connection |
| 72 | 88 | appears on TCP port "80", that it should launch the binary "/usr/bin/fossil" |
| 73 | 89 | program with the arguments shown. |
| 74 | 90 | Obviously you will |
| 75 | 91 | need to modify the pathnames for your particular setup. |
| 76 | 92 | The final argument is either the name of the fossil repository to be served, |
| 77 | 93 | or a directory containing multiple repositories. |
| 78 | -</p> | |
| 79 | -<p> | |
| 94 | + | |
| 95 | + | |
| 80 | 96 | If you use a non-standard TCP port on |
| 81 | 97 | systems where the port-specification must be a symbolic name and cannot be |
| 82 | 98 | numeric, add the desired name and port to /etc/services. For example, if |
| 83 | 99 | you want your Fossil server running on TCP port 12345 instead of 80, you |
| 84 | 100 | will need to add: |
| 101 | + | |
| 85 | 102 | <blockquote> |
| 86 | 103 | <pre> |
| 87 | 104 | fossil 12345/tcp #fossil server |
| 88 | 105 | </pre> |
| 89 | 106 | </blockquote> |
| 107 | + | |
| 90 | 108 | and use the symbolic name ('fossil' in this example) instead of the numeral ('12345') |
| 91 | 109 | in inetd.conf. For details, see the relevant section in your system's documentation, e.g. |
| 92 | 110 | the [https://www.freebsd.org/doc/en/books/handbook/network-inetd.html|FreeBSD Handbook] in |
| 93 | 111 | case you use FreeBSD. |
| 94 | -</p> | |
| 95 | -<p> | |
| 112 | + | |
| 96 | 113 | If your system is running xinetd, then the configuration is likely to be |
| 97 | 114 | in the file "/etc/xinetd.conf" or in a subfile of "/etc/xinetd.d". |
| 98 | -An xinetd configuration file will appear like this:</p> | |
| 115 | +An xinetd configuration file will appear like this: | |
| 116 | + | |
| 99 | 117 | <blockquote> |
| 100 | 118 | <pre> |
| 101 | 119 | service http |
| 102 | 120 | { |
| 103 | 121 | port = 80 |
| @@ -107,193 +125,182 @@ | ||
| 107 | 125 | server = /usr/bin/fossil |
| 108 | 126 | server_args = http /home/fossil/repos/ |
| 109 | 127 | } |
| 110 | 128 | </pre> |
| 111 | 129 | </blockquote> |
| 112 | -<p> | |
| 130 | + | |
| 113 | 131 | The xinetd example above has Fossil configured to serve multiple |
| 114 | 132 | repositories, contained under the "/home/fossil/repos/" directory. |
| 115 | -</p> | |
| 116 | -<p> | |
| 133 | + | |
| 117 | 134 | In both cases notice that Fossil was launched as root. This is not required, |
| 118 | 135 | but if it is done, then Fossil will automatically put itself into a chroot |
| 119 | 136 | jail for the user who owns the fossil repository before reading any information |
| 120 | 137 | off of the wire. |
| 121 | -</p> | |
| 122 | -<p> | |
| 138 | + | |
| 123 | 139 | Inetd or xinetd must be enabled, and must be (re)started whenever their configuration |
| 124 | 140 | changes - consult your system's documentation for details. |
| 125 | -</p> | |
| 126 | -<p> | |
| 141 | + | |
| 127 | 142 | [https://www.stunnel.org/ | Stunnel version 5] is an inetd-like process that |
| 128 | 143 | accepts and decodes SSL-encrypted connections. Fossil can be run directly from |
| 129 | 144 | stunnel in a manner similar to inetd and xinetd. This can be used to provide |
| 130 | 145 | a secure link to a Fossil project. The configuration needed to get stunnel5 |
| 131 | 146 | to invoke Fossil is very similar to the inetd and xinetd examples shown above. |
| 132 | 147 | The relevant parts of an stunnel configuration might look something |
| 133 | 148 | like the following: |
| 149 | + | |
| 134 | 150 | <blockquote><pre><nowiki> |
| 135 | 151 | [https] |
| 136 | 152 | accept = www.ubercool-project.org:443 |
| 137 | 153 | TIMEOUTclose = 0 |
| 138 | 154 | exec = /usr/bin/fossil |
| 139 | 155 | execargs = /usr/bin/fossil http /home/fossil/ubercool.fossil --https |
| 140 | 156 | </nowiki></pre></blockquote> |
| 157 | + | |
| 141 | 158 | See the stunnel5 documentation for further details about the /etc/stunnel/stunnel.conf |
| 142 | 159 | configuration file. Note that the [/help/http|fossil http] command should include |
| 143 | 160 | the --https option to let Fossil know to use "https" instead of "http" as the scheme |
| 144 | 161 | on generated hyperlinks. |
| 145 | -<p> | |
| 162 | + | |
| 146 | 163 | Using inetd or xinetd or stunnel is a more complex setup |
| 147 | 164 | than the "standalone" server, but it has the |
| 148 | 165 | advantage of only using system resources when an actual connection is |
| 149 | 166 | attempted. If no-one ever connects to that port, a Fossil server will |
| 150 | 167 | not (automatically) run. It has the disadvantage of requiring "root" access |
| 151 | 168 | and therefore may not normally be available to lower-priced "shared" servers |
| 152 | 169 | on the internet. |
| 153 | -</p> | |
| 154 | 170 | </blockquote> |
| 155 | -<a name="cgi"></a> | |
| 156 | -<h2>Fossil as CGI</h2><blockquote> | |
| 157 | -<p> | |
| 171 | + | |
| 172 | +<h2 id="cgi">Fossil as CGI</h2> | |
| 173 | + | |
| 174 | +<blockquote> | |
| 175 | + | |
| 158 | 176 | A Fossil server can also be run from an ordinary web server as a CGI program. |
| 159 | 177 | This feature allows Fossil to be seamlessly integrated into a larger website. |
| 160 | 178 | CGI is how the [./selfhost.wiki | self-hosting fossil repositories] are |
| 161 | 179 | implemented. |
| 162 | -</p> | |
| 163 | -<p> | |
| 180 | + | |
| 164 | 181 | To run Fossil as CGI, create a CGI script (here called "repo") in the CGI directory |
| 165 | 182 | of your web server and having content like this: |
| 183 | + | |
| 166 | 184 | <blockquote><pre> |
| 167 | 185 | #!/usr/bin/fossil |
| 168 | 186 | repository: /home/fossil/repo.fossil |
| 169 | 187 | </pre></blockquote> |
| 170 | -</p> | |
| 171 | 188 | |
| 172 | -<p> | |
| 173 | 189 | As always, adjust your paths appropriately. |
| 174 | 190 | It may be necessary to set permissions properly, or to modify an ".htaccess" |
| 175 | 191 | file or make other server-specific changes. Consult the documentation |
| 176 | 192 | for your particular web server. In particular, the following permissions are |
| 177 | 193 | <em>normally</em> required (but, again, may be different for a particular |
| 178 | 194 | configuration): |
| 179 | 195 | |
| 180 | 196 | <ul> |
| 181 | -<li>The Fossil binary (/usr/bin/fossil in the example above) | |
| 182 | -must be readable/executable, and ALL directories leading up to it | |
| 183 | -must be readable by the process which executes the CGI.</li> | |
| 184 | -<li>ALL directories leading to the CGI script must also be readable and the CGI | |
| 185 | -script itself must be executable for the user under which it will run (which often differs | |
| 186 | -from the one running the web server - consult your site's documentation or administrator).</li> | |
| 187 | -<li>The repository file AND the directory containing it must be writable by the same account | |
| 188 | -which executes the Fossil binary (again, this might differ from the WWW user). The directory | |
| 189 | -needs to be writable so that sqlite can write its journal files.</li> | |
| 190 | -<li>Fossil must be able to create temporary files, the default directory | |
| 191 | -for which depends on the OS. When the CGI process is operating within | |
| 192 | -a chroot, ensure that this directory exists and is readable/writeable | |
| 193 | -by the user who executes the Fossil binary.</li> | |
| 197 | + <li>The Fossil binary (/usr/bin/fossil in the example above) | |
| 198 | + must be readable/executable, and ALL directories leading up to it | |
| 199 | + must be readable by the process which executes the CGI.</li> | |
| 200 | + <li>ALL directories leading to the CGI script must also be readable and the CGI | |
| 201 | + script itself must be executable for the user under which it will run (which often differs | |
| 202 | + from the one running the web server - consult your site's documentation or administrator).</li> | |
| 203 | + <li>The repository file AND the directory containing it must be writable by the same account | |
| 204 | + which executes the Fossil binary (again, this might differ from the WWW user). The directory | |
| 205 | + needs to be writable so that sqlite can write its journal files.</li> | |
| 206 | + <li>Fossil must be able to create temporary files, the default directory | |
| 207 | + for which depends on the OS. When the CGI process is operating within | |
| 208 | + a chroot, ensure that this directory exists and is readable/writeable | |
| 209 | + by the user who executes the Fossil binary.</li> | |
| 194 | 210 | </ul> |
| 195 | -</p> | |
| 196 | 211 | |
| 197 | -<p> | |
| 198 | 212 | Once the script is set up correctly, and assuming your server is also set |
| 199 | 213 | correctly, you should be able to access your repository with a URL like: |
| 200 | 214 | <b>http://mydomain.org/cgi-bin/repo</b> (assuming the "repo" script is |
| 201 | 215 | accessible under "cgi-bin", which would be a typical deployment on Apache |
| 202 | 216 | for instance). |
| 203 | -</p> | |
| 204 | -<p> | |
| 217 | + | |
| 205 | 218 | To serve multiple repositories from a directory using CGI, use the "directory:" |
| 206 | 219 | tag in the CGI script rather than "repository:". You might also want to add |
| 207 | 220 | a "notfound:" tag to tell where to redirect if the particular repository requested |
| 208 | 221 | by the URL is not found: |
| 222 | + | |
| 209 | 223 | <blockquote><pre> |
| 210 | 224 | #!/usr/bin/fossil |
| 211 | 225 | directory: /home/fossil/repos |
| 212 | 226 | notfound: http://url-to-go-to-if-repo-not-found/ |
| 213 | 227 | </pre></blockquote> |
| 214 | -</p> | |
| 215 | -<p> | |
| 228 | + | |
| 216 | 229 | Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b> |
| 217 | 230 | will serve up the repository "/home/fossil/repos/XYZ.fossil" (if it exists). |
| 218 | -</p> | |
| 219 | -<p> | |
| 231 | + | |
| 220 | 232 | Additional options available to the CGI script are documented in the |
| 221 | 233 | source code. As of 2017-07-02, the available options are described at |
| 222 | 234 | [/artifact/9a52a07b?ln=1777-1824|main.c lines 1777 through 1824]. |
| 223 | -</p> | |
| 224 | 235 | </blockquote> |
| 225 | 236 | |
| 226 | -<a name="scgi"></a> | |
| 227 | -<h2>Fossil as SCGI</h2><blockquote> | |
| 237 | +<h2 id="scgi">Fossil as SCGI</h2> | |
| 238 | +<blockquote> | |
| 228 | 239 | |
| 229 | -<p> | |
| 230 | 240 | The [/help/server|fossil server] command, described above as a way of |
| 231 | 241 | starting a stand-alone web server, can also be used for SCGI. Simply add |
| 232 | 242 | the --scgi command-line option and the stand-alone server will interpret |
| 233 | 243 | and respond to the SimpleCGI or SCGI protocol rather than raw HTTP. This can |
| 234 | 244 | be used in combination with a webserver (such as [http://nginx.org|Nginx]) |
| 235 | 245 | that does not support CGI. A typical Nginx configuration to support SCGI |
| 236 | 246 | with Fossil would look something like this: |
| 247 | + | |
| 237 | 248 | <blockquote><pre> |
| 238 | 249 | location /demo_project/ { |
| 239 | 250 | include scgi_params; |
| 240 | 251 | scgi_pass localhost:9000; |
| 241 | 252 | scgi_param SCRIPT_NAME "/demo_project"; |
| 242 | 253 | scgi_param HTTPS "on"; |
| 243 | 254 | } |
| 244 | 255 | </pre></blockquote> |
| 245 | -<p> | |
| 256 | + | |
| 246 | 257 | Note that Fossil requires the SCRIPT_NAME variable |
| 247 | 258 | in order to function properly, but Nginx does not provide this |
| 248 | 259 | variable by default. |
| 249 | 260 | So it is necessary to provide the SCRIPT_NAME parameter in the configuration. |
| 250 | 261 | Failure to do this will cause Fossil to return an error. |
| 251 | -</p> | |
| 252 | -<p> | |
| 262 | + | |
| 253 | 263 | All of the features of the stand-alone server mode described above, |
| 254 | 264 | such as the ability to serve a directory full of Fossil repositories |
| 255 | 265 | rather than just a single repository, work the same way in SCGI mode. |
| 256 | -</p> | |
| 257 | -<p> | |
| 266 | + | |
| 258 | 267 | For security, it is probably a good idea to add the --localhost option |
| 259 | 268 | to the [/help/server|fossil server] command to prevent Fossil from accepting |
| 260 | 269 | off-site connections. And one might want to specify the listening TCP port |
| 261 | 270 | number, rather than letting Fossil choose one for itself, just to avoid |
| 262 | 271 | ambiguity. A typical command to start a Fossil SCGI server |
| 263 | 272 | would be something like this: |
| 273 | + | |
| 264 | 274 | <blockquote><pre> |
| 265 | 275 | fossil server $REPOSITORY --scgi --localhost --port 9000 |
| 266 | 276 | </pre></blockquote> |
| 267 | 277 | </blockquote> |
| 268 | 278 | |
| 269 | -<h2>Securing a repository with SSL</h2><blockquote> | |
| 270 | -<p> | |
| 279 | +<h2 id="tls">Securing a repository with SSL</h2> | |
| 280 | + | |
| 281 | +<blockquote> | |
| 271 | 282 | Using either CGI or SCGI, it is trivial to use SSL to |
| 272 | 283 | secure the server. Simply set up the Fossil CGI scripts etc. as above, |
| 273 | 284 | but modify the Apache (or IIS, etc.) server to require SSL (that is, a |
| 274 | 285 | URL with "https://") in order to access the CGI script directory. This |
| 275 | 286 | may also be accomplished (on Apache, at least) using appropriate |
| 276 | 287 | ".htaccess" rules. |
| 277 | -</p> | |
| 278 | -<p> | |
| 288 | + | |
| 279 | 289 | If you are using "inetd" to serve your repository, then you simply need |
| 280 | 290 | to add "/usr/bin/stunnel" (perhaps on a different path, depending on your |
| 281 | 291 | setup) before the command line to launch Fossil. |
| 282 | -</p> | |
| 283 | -<p> | |
| 292 | + | |
| 284 | 293 | At this stage, the standalone server (e.g. "fossil server") does not |
| 285 | 294 | support SSL. |
| 286 | -</p> | |
| 287 | -<p> | |
| 295 | + | |
| 288 | 296 | For more information, see <a href="./ssl.wiki">Using SSL with Fossil</a>. |
| 289 | -</p> | |
| 290 | 297 | </blockquote> |
| 291 | 298 | |
| 292 | -<a name="loadmgmt"></a> | |
| 293 | -<h2>Managing Server Load</h2><blockquote> | |
| 294 | -<p> | |
| 299 | +<h2 id="loadmgmt">Managing Server Load</h2> | |
| 300 | + | |
| 301 | +<blockquote> | |
| 295 | 302 | A Fossil server is very efficient and normally presents a very light |
| 296 | 303 | load on the server. |
| 297 | 304 | The Fossil [./selfhost.wiki | self-hosting server] is a 1/24th slice VM at |
| 298 | 305 | [http://www.linode.com | Linode.com] hosting 65 other repositories in |
| 299 | 306 | addition to Fossil (and including some very high-traffic sites such |
| @@ -300,73 +307,78 @@ | ||
| 300 | 307 | as [http://www.sqlite.org] and [http://system.data.sqlite.org]) and |
| 301 | 308 | it has a typical load of 0.05 to 0.1. A single HTTP request to Fossil |
| 302 | 309 | normally takes less than 10 milliseconds of CPU time to complete. So |
| 303 | 310 | requests can be arriving at a continuous rate of 20 or more per second |
| 304 | 311 | and the CPU can still be mostly idle. |
| 305 | -<p> | |
| 312 | + | |
| 306 | 313 | However, there are some Fossil web pages that can consume large |
| 307 | 314 | amounts of CPU time, especially on repositories with a large number |
| 308 | 315 | of files or with long revision histories. High CPU usage pages include |
| 309 | 316 | [/help?cmd=/zip | /zip], [/help?cmd=/tarball | /tarball], |
| 310 | 317 | [/help?cmd=/annotate | /annotate] and others. On very large repositories, |
| 311 | 318 | these commands can take 15 seconds or more of CPU time. |
| 312 | 319 | If these kinds of requests arrive too quickly, the load average on the |
| 313 | 320 | server can grow dramatically, making the server unresponsive. |
| 314 | -<p> | |
| 321 | + | |
| 315 | 322 | Fossil provides two capabilities to help avoid server overload problems |
| 316 | 323 | due to excessive requests to expensive pages: |
| 324 | + | |
| 317 | 325 | <ol> |
| 318 | -<li><p>An optional cache is available that remembers the 10 most recently | |
| 319 | - requested /zip or /tarball pages and returns the precomputed answer | |
| 320 | - if the same page is requested again. | |
| 321 | -<li><p>Page requests can be configured to fail with a | |
| 322 | - [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4 | "503 Server Overload"] | |
| 323 | - HTTP error if an expensive request is received while the host load | |
| 324 | - average is too high. | |
| 326 | + <li><p>An optional cache is available that remembers the 10 most recently | |
| 327 | + requested /zip or /tarball pages and returns the precomputed answer | |
| 328 | + if the same page is requested again.</p> | |
| 329 | + <li><p>Page requests can be configured to fail with a | |
| 330 | + [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4 | "503 Server Overload"] | |
| 331 | + HTTP error if an expensive request is received while the host load | |
| 332 | + average is too high.</p> | |
| 325 | 333 | </ol> |
| 334 | + | |
| 326 | 335 | Both of these load-control mechanisms are turned off by default, but they |
| 327 | 336 | are recommended for high-traffic sites. |
| 328 | -<p> | |
| 337 | + | |
| 329 | 338 | The webpage cache is activated using the [/help?cmd=cache|fossil cache init] |
| 330 | 339 | command-line on the server. Add a -R option to specify the specific repository |
| 331 | 340 | for which to enable caching. If running this command as root, be sure to |
| 332 | 341 | "chown" the cache database (which is a separate file in the same directory |
| 333 | 342 | and with the same name as the repository but with the suffix changed to ".cache") |
| 334 | 343 | to give it write permission for the userid of the webserver. |
| 335 | -<p> | |
| 344 | + | |
| 336 | 345 | To activate the server load control feature |
| 337 | 346 | visit the /Admin/Access setup page in the administrative web |
| 338 | 347 | interface and in the "<b>Server Load Average Limit</b>" box |
| 339 | 348 | enter the load average threshold above which "503 Server |
| 340 | 349 | Overload" replies will be issued for expensive requests. On the |
| 341 | 350 | self-host Fossil server, that value is set to 1.5. But you could easily |
| 342 | 351 | set it higher on a multi-core server. |
| 343 | -<p> | |
| 352 | + | |
| 344 | 353 | The maximum load average can also be set on the command line using |
| 345 | 354 | commands like this: |
| 346 | 355 | <blockquote><pre> |
| 347 | 356 | fossil set max-loadavg 1.5 |
| 348 | 357 | fossil all set max-loadavg 1.5 |
| 349 | 358 | </pre></blockquote> |
| 359 | + | |
| 350 | 360 | The second form is especially useful for changing the maximum load average |
| 351 | 361 | simultaneously on a large number of repositories. |
| 352 | -<p> | |
| 362 | + | |
| 353 | 363 | Note that this load-average limiting feature is only available on operating |
| 354 | 364 | systems that support the "getloadavg()" API. Most modern Unix systems have |
| 355 | 365 | this interface, but Windows does not, so the feature will not work on Windows. |
| 356 | 366 | Note also that Linux implements "getloadavg()" by accessing the "/proc/loadavg" |
| 357 | 367 | file in the "proc" virtual filesystem. If you are running a Fossil instance |
| 358 | 368 | inside a chroot() jail on Linux, you will need to make the "/proc" file |
| 359 | 369 | system available inside that jail in order for this feature to work. On |
| 360 | 370 | the [./selfhost.wiki|self-hosting Fossil repositories], this was accomplished |
| 361 | 371 | by adding a line to the "/etc/fstab" file that looks like: |
| 372 | + | |
| 362 | 373 | <blockquote><pre> |
| 363 | 374 | chroot_jail_proc /home/www/proc proc ro 0 0 |
| 364 | 375 | </pre></blockquote> |
| 376 | + | |
| 365 | 377 | The /home/www/proc pathname should be adjusted so that the "/proc" component is |
| 366 | 378 | in the root of the chroot jail, of course. |
| 367 | -<p> | |
| 379 | + | |
| 368 | 380 | To see if the load-average limiter is functional, visit the [/test_env] page |
| 369 | 381 | of the server to view the current load average. If the value for the load |
| 370 | 382 | average is greater than zero, that means that it is possible to activate |
| 371 | 383 | the load-average limiter on that repository. If the load average shows |
| 372 | 384 | exactly "0.0", then that means that Fossil is unable to find the load average |
| 373 | 385 |
| --- www/server.wiki | |
| +++ www/server.wiki | |
| @@ -1,39 +1,53 @@ | |
| 1 | <title>How To Configure A Fossil Server</title> |
| 2 | <h2>Introduction</h2><blockquote> |
| 3 | <p>A server is not necessary to use Fossil, but a server does help in collaborating with |
| 4 | peers. A Fossil server also works well as a complete website for a project. |
| 5 | For example, the complete [https://www.fossil-scm.org/] website, including the |
| 6 | page you are now reading, |
| 7 | is just a Fossil server displaying the content of the |
| 8 | self-hosting repository for Fossil.</p> |
| 9 | <p>This article is a guide for setting up your own Fossil server. |
| 10 | <p>See "[./aboutcgi.wiki|How CGI Works In Fossil]" for background |
| 11 | information on the underlying CGI technology. |
| 12 | See "[./sync.wiki|The Fossil Sync Protocol]" for information on the |
| 13 | wire protocol used for client/server communication.</p> |
| 14 | </blockquote> |
| 15 | <h2>Overview</h2><blockquote> |
| 16 | There are basically four ways to set up a Fossil server: |
| 17 | <ol> |
| 18 | <li>A stand-alone server |
| 19 | <li>Using inetd or xinetd or stunnel |
| 20 | <li>CGI |
| 21 | <li>SCGI (a.k.a. SimpleCGI) |
| 22 | </ol> |
| 23 | Each of these can serve either a single repository, or a directory hierarchy |
| 24 | containing many repositories with names ending in ".fossil". |
| 25 | </blockquote> |
| 26 | <a name="standalone"></a> |
| 27 | <h2>Standalone server</h2><blockquote> |
| 28 | The easiest way to set up a Fossil server is to use either the |
| 29 | [/help/server|server] or the [/help/ui|ui] commands: |
| 30 | <ul> |
| 31 | <li><b>fossil server</b> <i>REPOSITORY</i> |
| 32 | <li><b>fossil ui</b> <i>REPOSITORY</i> |
| 33 | </ul> |
| 34 | <p> |
| 35 | The <i>REPOSITORY</i> argument is either the name of the repository file, or |
| 36 | a directory containing many repositories. |
| 37 | Both of these commands start a Fossil server, usually on TCP port 8080, though |
| 38 | a higher numbered port might also be used if 8080 is already occupied. You can |
| 39 | access these using URLs of the form <b>http://localhost:8080/</b>, or if |
| @@ -43,61 +57,65 @@ | |
| 43 | The difference between "ui" and "server" is that "ui" will |
| 44 | also start a web browser and point it |
| 45 | to the URL mentioned above, and the "ui" command binds to |
| 46 | the loopback IP address (127.0.0.1) only so that the "ui" command cannot be |
| 47 | used to serve content to a different machine. |
| 48 | </p> |
| 49 | <p> |
| 50 | If one of the commands above is run from within an open checkout, |
| 51 | then the <i>REPOSITORY</i> argument can be omitted and the checkout is used as |
| 52 | the repository. |
| 53 | </p> |
| 54 | <p> |
| 55 | Both commands have additional command-line options that can be used to refine |
| 56 | their behavior. See the [/help/server|online documentation] for an overview. |
| 57 | </p> |
| 58 | </blockquote> |
| 59 | <a name="inetd"></a> |
| 60 | <h2>Fossil as an inetd/xinetd or stunnel service</h2><blockquote> |
| 61 | <p> |
| 62 | A Fossil server can be launched on-demand by inetd or xinetd using |
| 63 | the [/help/http|fossil http] command. To launch Fossil from inetd, modify |
| 64 | your inetd configuration file (typically "/etc/inetd.conf") to contain a |
| 65 | line something like this: |
| 66 | <blockquote> |
| 67 | <pre> |
| 68 | 80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil |
| 69 | </pre> |
| 70 | </blockquote> |
| 71 | In this example, you are telling "inetd" that when an incoming connection |
| 72 | appears on TCP port "80", that it should launch the binary "/usr/bin/fossil" |
| 73 | program with the arguments shown. |
| 74 | Obviously you will |
| 75 | need to modify the pathnames for your particular setup. |
| 76 | The final argument is either the name of the fossil repository to be served, |
| 77 | or a directory containing multiple repositories. |
| 78 | </p> |
| 79 | <p> |
| 80 | If you use a non-standard TCP port on |
| 81 | systems where the port-specification must be a symbolic name and cannot be |
| 82 | numeric, add the desired name and port to /etc/services. For example, if |
| 83 | you want your Fossil server running on TCP port 12345 instead of 80, you |
| 84 | will need to add: |
| 85 | <blockquote> |
| 86 | <pre> |
| 87 | fossil 12345/tcp #fossil server |
| 88 | </pre> |
| 89 | </blockquote> |
| 90 | and use the symbolic name ('fossil' in this example) instead of the numeral ('12345') |
| 91 | in inetd.conf. For details, see the relevant section in your system's documentation, e.g. |
| 92 | the [https://www.freebsd.org/doc/en/books/handbook/network-inetd.html|FreeBSD Handbook] in |
| 93 | case you use FreeBSD. |
| 94 | </p> |
| 95 | <p> |
| 96 | If your system is running xinetd, then the configuration is likely to be |
| 97 | in the file "/etc/xinetd.conf" or in a subfile of "/etc/xinetd.d". |
| 98 | An xinetd configuration file will appear like this:</p> |
| 99 | <blockquote> |
| 100 | <pre> |
| 101 | service http |
| 102 | { |
| 103 | port = 80 |
| @@ -107,193 +125,182 @@ | |
| 107 | server = /usr/bin/fossil |
| 108 | server_args = http /home/fossil/repos/ |
| 109 | } |
| 110 | </pre> |
| 111 | </blockquote> |
| 112 | <p> |
| 113 | The xinetd example above has Fossil configured to serve multiple |
| 114 | repositories, contained under the "/home/fossil/repos/" directory. |
| 115 | </p> |
| 116 | <p> |
| 117 | In both cases notice that Fossil was launched as root. This is not required, |
| 118 | but if it is done, then Fossil will automatically put itself into a chroot |
| 119 | jail for the user who owns the fossil repository before reading any information |
| 120 | off of the wire. |
| 121 | </p> |
| 122 | <p> |
| 123 | Inetd or xinetd must be enabled, and must be (re)started whenever their configuration |
| 124 | changes - consult your system's documentation for details. |
| 125 | </p> |
| 126 | <p> |
| 127 | [https://www.stunnel.org/ | Stunnel version 5] is an inetd-like process that |
| 128 | accepts and decodes SSL-encrypted connections. Fossil can be run directly from |
| 129 | stunnel in a manner similar to inetd and xinetd. This can be used to provide |
| 130 | a secure link to a Fossil project. The configuration needed to get stunnel5 |
| 131 | to invoke Fossil is very similar to the inetd and xinetd examples shown above. |
| 132 | The relevant parts of an stunnel configuration might look something |
| 133 | like the following: |
| 134 | <blockquote><pre><nowiki> |
| 135 | [https] |
| 136 | accept = www.ubercool-project.org:443 |
| 137 | TIMEOUTclose = 0 |
| 138 | exec = /usr/bin/fossil |
| 139 | execargs = /usr/bin/fossil http /home/fossil/ubercool.fossil --https |
| 140 | </nowiki></pre></blockquote> |
| 141 | See the stunnel5 documentation for further details about the /etc/stunnel/stunnel.conf |
| 142 | configuration file. Note that the [/help/http|fossil http] command should include |
| 143 | the --https option to let Fossil know to use "https" instead of "http" as the scheme |
| 144 | on generated hyperlinks. |
| 145 | <p> |
| 146 | Using inetd or xinetd or stunnel is a more complex setup |
| 147 | than the "standalone" server, but it has the |
| 148 | advantage of only using system resources when an actual connection is |
| 149 | attempted. If no-one ever connects to that port, a Fossil server will |
| 150 | not (automatically) run. It has the disadvantage of requiring "root" access |
| 151 | and therefore may not normally be available to lower-priced "shared" servers |
| 152 | on the internet. |
| 153 | </p> |
| 154 | </blockquote> |
| 155 | <a name="cgi"></a> |
| 156 | <h2>Fossil as CGI</h2><blockquote> |
| 157 | <p> |
| 158 | A Fossil server can also be run from an ordinary web server as a CGI program. |
| 159 | This feature allows Fossil to be seamlessly integrated into a larger website. |
| 160 | CGI is how the [./selfhost.wiki | self-hosting fossil repositories] are |
| 161 | implemented. |
| 162 | </p> |
| 163 | <p> |
| 164 | To run Fossil as CGI, create a CGI script (here called "repo") in the CGI directory |
| 165 | of your web server and having content like this: |
| 166 | <blockquote><pre> |
| 167 | #!/usr/bin/fossil |
| 168 | repository: /home/fossil/repo.fossil |
| 169 | </pre></blockquote> |
| 170 | </p> |
| 171 | |
| 172 | <p> |
| 173 | As always, adjust your paths appropriately. |
| 174 | It may be necessary to set permissions properly, or to modify an ".htaccess" |
| 175 | file or make other server-specific changes. Consult the documentation |
| 176 | for your particular web server. In particular, the following permissions are |
| 177 | <em>normally</em> required (but, again, may be different for a particular |
| 178 | configuration): |
| 179 | |
| 180 | <ul> |
| 181 | <li>The Fossil binary (/usr/bin/fossil in the example above) |
| 182 | must be readable/executable, and ALL directories leading up to it |
| 183 | must be readable by the process which executes the CGI.</li> |
| 184 | <li>ALL directories leading to the CGI script must also be readable and the CGI |
| 185 | script itself must be executable for the user under which it will run (which often differs |
| 186 | from the one running the web server - consult your site's documentation or administrator).</li> |
| 187 | <li>The repository file AND the directory containing it must be writable by the same account |
| 188 | which executes the Fossil binary (again, this might differ from the WWW user). The directory |
| 189 | needs to be writable so that sqlite can write its journal files.</li> |
| 190 | <li>Fossil must be able to create temporary files, the default directory |
| 191 | for which depends on the OS. When the CGI process is operating within |
| 192 | a chroot, ensure that this directory exists and is readable/writeable |
| 193 | by the user who executes the Fossil binary.</li> |
| 194 | </ul> |
| 195 | </p> |
| 196 | |
| 197 | <p> |
| 198 | Once the script is set up correctly, and assuming your server is also set |
| 199 | correctly, you should be able to access your repository with a URL like: |
| 200 | <b>http://mydomain.org/cgi-bin/repo</b> (assuming the "repo" script is |
| 201 | accessible under "cgi-bin", which would be a typical deployment on Apache |
| 202 | for instance). |
| 203 | </p> |
| 204 | <p> |
| 205 | To serve multiple repositories from a directory using CGI, use the "directory:" |
| 206 | tag in the CGI script rather than "repository:". You might also want to add |
| 207 | a "notfound:" tag to tell where to redirect if the particular repository requested |
| 208 | by the URL is not found: |
| 209 | <blockquote><pre> |
| 210 | #!/usr/bin/fossil |
| 211 | directory: /home/fossil/repos |
| 212 | notfound: http://url-to-go-to-if-repo-not-found/ |
| 213 | </pre></blockquote> |
| 214 | </p> |
| 215 | <p> |
| 216 | Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b> |
| 217 | will serve up the repository "/home/fossil/repos/XYZ.fossil" (if it exists). |
| 218 | </p> |
| 219 | <p> |
| 220 | Additional options available to the CGI script are documented in the |
| 221 | source code. As of 2017-07-02, the available options are described at |
| 222 | [/artifact/9a52a07b?ln=1777-1824|main.c lines 1777 through 1824]. |
| 223 | </p> |
| 224 | </blockquote> |
| 225 | |
| 226 | <a name="scgi"></a> |
| 227 | <h2>Fossil as SCGI</h2><blockquote> |
| 228 | |
| 229 | <p> |
| 230 | The [/help/server|fossil server] command, described above as a way of |
| 231 | starting a stand-alone web server, can also be used for SCGI. Simply add |
| 232 | the --scgi command-line option and the stand-alone server will interpret |
| 233 | and respond to the SimpleCGI or SCGI protocol rather than raw HTTP. This can |
| 234 | be used in combination with a webserver (such as [http://nginx.org|Nginx]) |
| 235 | that does not support CGI. A typical Nginx configuration to support SCGI |
| 236 | with Fossil would look something like this: |
| 237 | <blockquote><pre> |
| 238 | location /demo_project/ { |
| 239 | include scgi_params; |
| 240 | scgi_pass localhost:9000; |
| 241 | scgi_param SCRIPT_NAME "/demo_project"; |
| 242 | scgi_param HTTPS "on"; |
| 243 | } |
| 244 | </pre></blockquote> |
| 245 | <p> |
| 246 | Note that Fossil requires the SCRIPT_NAME variable |
| 247 | in order to function properly, but Nginx does not provide this |
| 248 | variable by default. |
| 249 | So it is necessary to provide the SCRIPT_NAME parameter in the configuration. |
| 250 | Failure to do this will cause Fossil to return an error. |
| 251 | </p> |
| 252 | <p> |
| 253 | All of the features of the stand-alone server mode described above, |
| 254 | such as the ability to serve a directory full of Fossil repositories |
| 255 | rather than just a single repository, work the same way in SCGI mode. |
| 256 | </p> |
| 257 | <p> |
| 258 | For security, it is probably a good idea to add the --localhost option |
| 259 | to the [/help/server|fossil server] command to prevent Fossil from accepting |
| 260 | off-site connections. And one might want to specify the listening TCP port |
| 261 | number, rather than letting Fossil choose one for itself, just to avoid |
| 262 | ambiguity. A typical command to start a Fossil SCGI server |
| 263 | would be something like this: |
| 264 | <blockquote><pre> |
| 265 | fossil server $REPOSITORY --scgi --localhost --port 9000 |
| 266 | </pre></blockquote> |
| 267 | </blockquote> |
| 268 | |
| 269 | <h2>Securing a repository with SSL</h2><blockquote> |
| 270 | <p> |
| 271 | Using either CGI or SCGI, it is trivial to use SSL to |
| 272 | secure the server. Simply set up the Fossil CGI scripts etc. as above, |
| 273 | but modify the Apache (or IIS, etc.) server to require SSL (that is, a |
| 274 | URL with "https://") in order to access the CGI script directory. This |
| 275 | may also be accomplished (on Apache, at least) using appropriate |
| 276 | ".htaccess" rules. |
| 277 | </p> |
| 278 | <p> |
| 279 | If you are using "inetd" to serve your repository, then you simply need |
| 280 | to add "/usr/bin/stunnel" (perhaps on a different path, depending on your |
| 281 | setup) before the command line to launch Fossil. |
| 282 | </p> |
| 283 | <p> |
| 284 | At this stage, the standalone server (e.g. "fossil server") does not |
| 285 | support SSL. |
| 286 | </p> |
| 287 | <p> |
| 288 | For more information, see <a href="./ssl.wiki">Using SSL with Fossil</a>. |
| 289 | </p> |
| 290 | </blockquote> |
| 291 | |
| 292 | <a name="loadmgmt"></a> |
| 293 | <h2>Managing Server Load</h2><blockquote> |
| 294 | <p> |
| 295 | A Fossil server is very efficient and normally presents a very light |
| 296 | load on the server. |
| 297 | The Fossil [./selfhost.wiki | self-hosting server] is a 1/24th slice VM at |
| 298 | [http://www.linode.com | Linode.com] hosting 65 other repositories in |
| 299 | addition to Fossil (and including some very high-traffic sites such |
| @@ -300,73 +307,78 @@ | |
| 300 | as [http://www.sqlite.org] and [http://system.data.sqlite.org]) and |
| 301 | it has a typical load of 0.05 to 0.1. A single HTTP request to Fossil |
| 302 | normally takes less than 10 milliseconds of CPU time to complete. So |
| 303 | requests can be arriving at a continuous rate of 20 or more per second |
| 304 | and the CPU can still be mostly idle. |
| 305 | <p> |
| 306 | However, there are some Fossil web pages that can consume large |
| 307 | amounts of CPU time, especially on repositories with a large number |
| 308 | of files or with long revision histories. High CPU usage pages include |
| 309 | [/help?cmd=/zip | /zip], [/help?cmd=/tarball | /tarball], |
| 310 | [/help?cmd=/annotate | /annotate] and others. On very large repositories, |
| 311 | these commands can take 15 seconds or more of CPU time. |
| 312 | If these kinds of requests arrive too quickly, the load average on the |
| 313 | server can grow dramatically, making the server unresponsive. |
| 314 | <p> |
| 315 | Fossil provides two capabilities to help avoid server overload problems |
| 316 | due to excessive requests to expensive pages: |
| 317 | <ol> |
| 318 | <li><p>An optional cache is available that remembers the 10 most recently |
| 319 | requested /zip or /tarball pages and returns the precomputed answer |
| 320 | if the same page is requested again. |
| 321 | <li><p>Page requests can be configured to fail with a |
| 322 | [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4 | "503 Server Overload"] |
| 323 | HTTP error if an expensive request is received while the host load |
| 324 | average is too high. |
| 325 | </ol> |
| 326 | Both of these load-control mechanisms are turned off by default, but they |
| 327 | are recommended for high-traffic sites. |
| 328 | <p> |
| 329 | The webpage cache is activated using the [/help?cmd=cache|fossil cache init] |
| 330 | command-line on the server. Add a -R option to specify the specific repository |
| 331 | for which to enable caching. If running this command as root, be sure to |
| 332 | "chown" the cache database (which is a separate file in the same directory |
| 333 | and with the same name as the repository but with the suffix changed to ".cache") |
| 334 | to give it write permission for the userid of the webserver. |
| 335 | <p> |
| 336 | To activate the server load control feature |
| 337 | visit the /Admin/Access setup page in the administrative web |
| 338 | interface and in the "<b>Server Load Average Limit</b>" box |
| 339 | enter the load average threshold above which "503 Server |
| 340 | Overload" replies will be issued for expensive requests. On the |
| 341 | self-host Fossil server, that value is set to 1.5. But you could easily |
| 342 | set it higher on a multi-core server. |
| 343 | <p> |
| 344 | The maximum load average can also be set on the command line using |
| 345 | commands like this: |
| 346 | <blockquote><pre> |
| 347 | fossil set max-loadavg 1.5 |
| 348 | fossil all set max-loadavg 1.5 |
| 349 | </pre></blockquote> |
| 350 | The second form is especially useful for changing the maximum load average |
| 351 | simultaneously on a large number of repositories. |
| 352 | <p> |
| 353 | Note that this load-average limiting feature is only available on operating |
| 354 | systems that support the "getloadavg()" API. Most modern Unix systems have |
| 355 | this interface, but Windows does not, so the feature will not work on Windows. |
| 356 | Note also that Linux implements "getloadavg()" by accessing the "/proc/loadavg" |
| 357 | file in the "proc" virtual filesystem. If you are running a Fossil instance |
| 358 | inside a chroot() jail on Linux, you will need to make the "/proc" file |
| 359 | system available inside that jail in order for this feature to work. On |
| 360 | the [./selfhost.wiki|self-hosting Fossil repositories], this was accomplished |
| 361 | by adding a line to the "/etc/fstab" file that looks like: |
| 362 | <blockquote><pre> |
| 363 | chroot_jail_proc /home/www/proc proc ro 0 0 |
| 364 | </pre></blockquote> |
| 365 | The /home/www/proc pathname should be adjusted so that the "/proc" component is |
| 366 | in the root of the chroot jail, of course. |
| 367 | <p> |
| 368 | To see if the load-average limiter is functional, visit the [/test_env] page |
| 369 | of the server to view the current load average. If the value for the load |
| 370 | average is greater than zero, that means that it is possible to activate |
| 371 | the load-average limiter on that repository. If the load average shows |
| 372 | exactly "0.0", then that means that Fossil is unable to find the load average |
| 373 |
| --- www/server.wiki | |
| +++ www/server.wiki | |
| @@ -1,39 +1,53 @@ | |
| 1 | <title>How To Configure A Fossil Server</title> |
| 2 | |
| 3 | <h2>Introduction</h2> |
| 4 | |
| 5 | <blockquote> |
| 6 | A server is not necessary to use Fossil, but a server does help in collaborating with |
| 7 | peers. A Fossil server also works well as a complete website for a project. |
| 8 | For example, the complete [https://www.fossil-scm.org/] website, including the |
| 9 | page you are now reading, |
| 10 | is just a Fossil server displaying the content of the |
| 11 | self-hosting repository for Fossil. |
| 12 | |
| 13 | This article is a guide for setting up your own Fossil server. |
| 14 | |
| 15 | See "[./aboutcgi.wiki|How CGI Works In Fossil]" for background |
| 16 | information on the underlying CGI technology. |
| 17 | See "[./sync.wiki|The Fossil Sync Protocol]" for information on the |
| 18 | wire protocol used for client/server communication. |
| 19 | </blockquote> |
| 20 | |
| 21 | <h2>Overview</h2> |
| 22 | |
| 23 | <blockquote> |
| 24 | There are basically four ways to set up a Fossil server: |
| 25 | |
| 26 | <ol> |
| 27 | <li>A stand-alone server |
| 28 | <li>Using inetd or xinetd or stunnel |
| 29 | <li>CGI |
| 30 | <li>SCGI (a.k.a. SimpleCGI) |
| 31 | </ol> |
| 32 | |
| 33 | Each of these can serve either a single repository, or a directory hierarchy |
| 34 | containing many repositories with names ending in ".fossil". |
| 35 | </blockquote> |
| 36 | |
| 37 | |
| 38 | <h2 id="standalone">Standalone server</h2> |
| 39 | |
| 40 | <blockquote> |
| 41 | The easiest way to set up a Fossil server is to use either the |
| 42 | [/help/server|server] or the [/help/ui|ui] commands: |
| 43 | |
| 44 | <ul> |
| 45 | <li><b>fossil server</b> <i>REPOSITORY</i> |
| 46 | <li><b>fossil ui</b> <i>REPOSITORY</i> |
| 47 | </ul> |
| 48 | |
| 49 | The <i>REPOSITORY</i> argument is either the name of the repository file, or |
| 50 | a directory containing many repositories. |
| 51 | Both of these commands start a Fossil server, usually on TCP port 8080, though |
| 52 | a higher numbered port might also be used if 8080 is already occupied. You can |
| 53 | access these using URLs of the form <b>http://localhost:8080/</b>, or if |
| @@ -43,61 +57,65 @@ | |
| 57 | The difference between "ui" and "server" is that "ui" will |
| 58 | also start a web browser and point it |
| 59 | to the URL mentioned above, and the "ui" command binds to |
| 60 | the loopback IP address (127.0.0.1) only so that the "ui" command cannot be |
| 61 | used to serve content to a different machine. |
| 62 | |
| 63 | If one of the commands above is run from within an open checkout, |
| 64 | then the <i>REPOSITORY</i> argument can be omitted and the checkout is used as |
| 65 | the repository. |
| 66 | |
| 67 | Both commands have additional command-line options that can be used to refine |
| 68 | their behavior. See the [/help/server|online documentation] for an overview. |
| 69 | </blockquote> |
| 70 | |
| 71 | |
| 72 | <h2 id="inetd">Fossil as an inetd/xinetd or stunnel service</h2> |
| 73 | |
| 74 | <blockquote> |
| 75 | |
| 76 | A Fossil server can be launched on-demand by inetd or xinetd using |
| 77 | the [/help/http|fossil http] command. To launch Fossil from inetd, modify |
| 78 | your inetd configuration file (typically "/etc/inetd.conf") to contain a |
| 79 | line something like this: |
| 80 | |
| 81 | <blockquote> |
| 82 | <pre> |
| 83 | 80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil |
| 84 | </pre> |
| 85 | </blockquote> |
| 86 | |
| 87 | In this example, you are telling "inetd" that when an incoming connection |
| 88 | appears on TCP port "80", that it should launch the binary "/usr/bin/fossil" |
| 89 | program with the arguments shown. |
| 90 | Obviously you will |
| 91 | need to modify the pathnames for your particular setup. |
| 92 | The final argument is either the name of the fossil repository to be served, |
| 93 | or a directory containing multiple repositories. |
| 94 | |
| 95 | |
| 96 | If you use a non-standard TCP port on |
| 97 | systems where the port-specification must be a symbolic name and cannot be |
| 98 | numeric, add the desired name and port to /etc/services. For example, if |
| 99 | you want your Fossil server running on TCP port 12345 instead of 80, you |
| 100 | will need to add: |
| 101 | |
| 102 | <blockquote> |
| 103 | <pre> |
| 104 | fossil 12345/tcp #fossil server |
| 105 | </pre> |
| 106 | </blockquote> |
| 107 | |
| 108 | and use the symbolic name ('fossil' in this example) instead of the numeral ('12345') |
| 109 | in inetd.conf. For details, see the relevant section in your system's documentation, e.g. |
| 110 | the [https://www.freebsd.org/doc/en/books/handbook/network-inetd.html|FreeBSD Handbook] in |
| 111 | case you use FreeBSD. |
| 112 | |
| 113 | If your system is running xinetd, then the configuration is likely to be |
| 114 | in the file "/etc/xinetd.conf" or in a subfile of "/etc/xinetd.d". |
| 115 | An xinetd configuration file will appear like this: |
| 116 | |
| 117 | <blockquote> |
| 118 | <pre> |
| 119 | service http |
| 120 | { |
| 121 | port = 80 |
| @@ -107,193 +125,182 @@ | |
| 125 | server = /usr/bin/fossil |
| 126 | server_args = http /home/fossil/repos/ |
| 127 | } |
| 128 | </pre> |
| 129 | </blockquote> |
| 130 | |
| 131 | The xinetd example above has Fossil configured to serve multiple |
| 132 | repositories, contained under the "/home/fossil/repos/" directory. |
| 133 | |
| 134 | In both cases notice that Fossil was launched as root. This is not required, |
| 135 | but if it is done, then Fossil will automatically put itself into a chroot |
| 136 | jail for the user who owns the fossil repository before reading any information |
| 137 | off of the wire. |
| 138 | |
| 139 | Inetd or xinetd must be enabled, and must be (re)started whenever their configuration |
| 140 | changes - consult your system's documentation for details. |
| 141 | |
| 142 | [https://www.stunnel.org/ | Stunnel version 5] is an inetd-like process that |
| 143 | accepts and decodes SSL-encrypted connections. Fossil can be run directly from |
| 144 | stunnel in a manner similar to inetd and xinetd. This can be used to provide |
| 145 | a secure link to a Fossil project. The configuration needed to get stunnel5 |
| 146 | to invoke Fossil is very similar to the inetd and xinetd examples shown above. |
| 147 | The relevant parts of an stunnel configuration might look something |
| 148 | like the following: |
| 149 | |
| 150 | <blockquote><pre><nowiki> |
| 151 | [https] |
| 152 | accept = www.ubercool-project.org:443 |
| 153 | TIMEOUTclose = 0 |
| 154 | exec = /usr/bin/fossil |
| 155 | execargs = /usr/bin/fossil http /home/fossil/ubercool.fossil --https |
| 156 | </nowiki></pre></blockquote> |
| 157 | |
| 158 | See the stunnel5 documentation for further details about the /etc/stunnel/stunnel.conf |
| 159 | configuration file. Note that the [/help/http|fossil http] command should include |
| 160 | the --https option to let Fossil know to use "https" instead of "http" as the scheme |
| 161 | on generated hyperlinks. |
| 162 | |
| 163 | Using inetd or xinetd or stunnel is a more complex setup |
| 164 | than the "standalone" server, but it has the |
| 165 | advantage of only using system resources when an actual connection is |
| 166 | attempted. If no-one ever connects to that port, a Fossil server will |
| 167 | not (automatically) run. It has the disadvantage of requiring "root" access |
| 168 | and therefore may not normally be available to lower-priced "shared" servers |
| 169 | on the internet. |
| 170 | </blockquote> |
| 171 | |
| 172 | <h2 id="cgi">Fossil as CGI</h2> |
| 173 | |
| 174 | <blockquote> |
| 175 | |
| 176 | A Fossil server can also be run from an ordinary web server as a CGI program. |
| 177 | This feature allows Fossil to be seamlessly integrated into a larger website. |
| 178 | CGI is how the [./selfhost.wiki | self-hosting fossil repositories] are |
| 179 | implemented. |
| 180 | |
| 181 | To run Fossil as CGI, create a CGI script (here called "repo") in the CGI directory |
| 182 | of your web server and having content like this: |
| 183 | |
| 184 | <blockquote><pre> |
| 185 | #!/usr/bin/fossil |
| 186 | repository: /home/fossil/repo.fossil |
| 187 | </pre></blockquote> |
| 188 | |
| 189 | As always, adjust your paths appropriately. |
| 190 | It may be necessary to set permissions properly, or to modify an ".htaccess" |
| 191 | file or make other server-specific changes. Consult the documentation |
| 192 | for your particular web server. In particular, the following permissions are |
| 193 | <em>normally</em> required (but, again, may be different for a particular |
| 194 | configuration): |
| 195 | |
| 196 | <ul> |
| 197 | <li>The Fossil binary (/usr/bin/fossil in the example above) |
| 198 | must be readable/executable, and ALL directories leading up to it |
| 199 | must be readable by the process which executes the CGI.</li> |
| 200 | <li>ALL directories leading to the CGI script must also be readable and the CGI |
| 201 | script itself must be executable for the user under which it will run (which often differs |
| 202 | from the one running the web server - consult your site's documentation or administrator).</li> |
| 203 | <li>The repository file AND the directory containing it must be writable by the same account |
| 204 | which executes the Fossil binary (again, this might differ from the WWW user). The directory |
| 205 | needs to be writable so that sqlite can write its journal files.</li> |
| 206 | <li>Fossil must be able to create temporary files, the default directory |
| 207 | for which depends on the OS. When the CGI process is operating within |
| 208 | a chroot, ensure that this directory exists and is readable/writeable |
| 209 | by the user who executes the Fossil binary.</li> |
| 210 | </ul> |
| 211 | |
| 212 | Once the script is set up correctly, and assuming your server is also set |
| 213 | correctly, you should be able to access your repository with a URL like: |
| 214 | <b>http://mydomain.org/cgi-bin/repo</b> (assuming the "repo" script is |
| 215 | accessible under "cgi-bin", which would be a typical deployment on Apache |
| 216 | for instance). |
| 217 | |
| 218 | To serve multiple repositories from a directory using CGI, use the "directory:" |
| 219 | tag in the CGI script rather than "repository:". You might also want to add |
| 220 | a "notfound:" tag to tell where to redirect if the particular repository requested |
| 221 | by the URL is not found: |
| 222 | |
| 223 | <blockquote><pre> |
| 224 | #!/usr/bin/fossil |
| 225 | directory: /home/fossil/repos |
| 226 | notfound: http://url-to-go-to-if-repo-not-found/ |
| 227 | </pre></blockquote> |
| 228 | |
| 229 | Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b> |
| 230 | will serve up the repository "/home/fossil/repos/XYZ.fossil" (if it exists). |
| 231 | |
| 232 | Additional options available to the CGI script are documented in the |
| 233 | source code. As of 2017-07-02, the available options are described at |
| 234 | [/artifact/9a52a07b?ln=1777-1824|main.c lines 1777 through 1824]. |
| 235 | </blockquote> |
| 236 | |
| 237 | <h2 id="scgi">Fossil as SCGI</h2> |
| 238 | <blockquote> |
| 239 | |
| 240 | The [/help/server|fossil server] command, described above as a way of |
| 241 | starting a stand-alone web server, can also be used for SCGI. Simply add |
| 242 | the --scgi command-line option and the stand-alone server will interpret |
| 243 | and respond to the SimpleCGI or SCGI protocol rather than raw HTTP. This can |
| 244 | be used in combination with a webserver (such as [http://nginx.org|Nginx]) |
| 245 | that does not support CGI. A typical Nginx configuration to support SCGI |
| 246 | with Fossil would look something like this: |
| 247 | |
| 248 | <blockquote><pre> |
| 249 | location /demo_project/ { |
| 250 | include scgi_params; |
| 251 | scgi_pass localhost:9000; |
| 252 | scgi_param SCRIPT_NAME "/demo_project"; |
| 253 | scgi_param HTTPS "on"; |
| 254 | } |
| 255 | </pre></blockquote> |
| 256 | |
| 257 | Note that Fossil requires the SCRIPT_NAME variable |
| 258 | in order to function properly, but Nginx does not provide this |
| 259 | variable by default. |
| 260 | So it is necessary to provide the SCRIPT_NAME parameter in the configuration. |
| 261 | Failure to do this will cause Fossil to return an error. |
| 262 | |
| 263 | All of the features of the stand-alone server mode described above, |
| 264 | such as the ability to serve a directory full of Fossil repositories |
| 265 | rather than just a single repository, work the same way in SCGI mode. |
| 266 | |
| 267 | For security, it is probably a good idea to add the --localhost option |
| 268 | to the [/help/server|fossil server] command to prevent Fossil from accepting |
| 269 | off-site connections. And one might want to specify the listening TCP port |
| 270 | number, rather than letting Fossil choose one for itself, just to avoid |
| 271 | ambiguity. A typical command to start a Fossil SCGI server |
| 272 | would be something like this: |
| 273 | |
| 274 | <blockquote><pre> |
| 275 | fossil server $REPOSITORY --scgi --localhost --port 9000 |
| 276 | </pre></blockquote> |
| 277 | </blockquote> |
| 278 | |
| 279 | <h2 id="tls">Securing a repository with SSL</h2> |
| 280 | |
| 281 | <blockquote> |
| 282 | Using either CGI or SCGI, it is trivial to use SSL to |
| 283 | secure the server. Simply set up the Fossil CGI scripts etc. as above, |
| 284 | but modify the Apache (or IIS, etc.) server to require SSL (that is, a |
| 285 | URL with "https://") in order to access the CGI script directory. This |
| 286 | may also be accomplished (on Apache, at least) using appropriate |
| 287 | ".htaccess" rules. |
| 288 | |
| 289 | If you are using "inetd" to serve your repository, then you simply need |
| 290 | to add "/usr/bin/stunnel" (perhaps on a different path, depending on your |
| 291 | setup) before the command line to launch Fossil. |
| 292 | |
| 293 | At this stage, the standalone server (e.g. "fossil server") does not |
| 294 | support SSL. |
| 295 | |
| 296 | For more information, see <a href="./ssl.wiki">Using SSL with Fossil</a>. |
| 297 | </blockquote> |
| 298 | |
| 299 | <h2 id="loadmgmt">Managing Server Load</h2> |
| 300 | |
| 301 | <blockquote> |
| 302 | A Fossil server is very efficient and normally presents a very light |
| 303 | load on the server. |
| 304 | The Fossil [./selfhost.wiki | self-hosting server] is a 1/24th slice VM at |
| 305 | [http://www.linode.com | Linode.com] hosting 65 other repositories in |
| 306 | addition to Fossil (and including some very high-traffic sites such |
| @@ -300,73 +307,78 @@ | |
| 307 | as [http://www.sqlite.org] and [http://system.data.sqlite.org]) and |
| 308 | it has a typical load of 0.05 to 0.1. A single HTTP request to Fossil |
| 309 | normally takes less than 10 milliseconds of CPU time to complete. So |
| 310 | requests can be arriving at a continuous rate of 20 or more per second |
| 311 | and the CPU can still be mostly idle. |
| 312 | |
| 313 | However, there are some Fossil web pages that can consume large |
| 314 | amounts of CPU time, especially on repositories with a large number |
| 315 | of files or with long revision histories. High CPU usage pages include |
| 316 | [/help?cmd=/zip | /zip], [/help?cmd=/tarball | /tarball], |
| 317 | [/help?cmd=/annotate | /annotate] and others. On very large repositories, |
| 318 | these commands can take 15 seconds or more of CPU time. |
| 319 | If these kinds of requests arrive too quickly, the load average on the |
| 320 | server can grow dramatically, making the server unresponsive. |
| 321 | |
| 322 | Fossil provides two capabilities to help avoid server overload problems |
| 323 | due to excessive requests to expensive pages: |
| 324 | |
| 325 | <ol> |
| 326 | <li><p>An optional cache is available that remembers the 10 most recently |
| 327 | requested /zip or /tarball pages and returns the precomputed answer |
| 328 | if the same page is requested again.</p> |
| 329 | <li><p>Page requests can be configured to fail with a |
| 330 | [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4 | "503 Server Overload"] |
| 331 | HTTP error if an expensive request is received while the host load |
| 332 | average is too high.</p> |
| 333 | </ol> |
| 334 | |
| 335 | Both of these load-control mechanisms are turned off by default, but they |
| 336 | are recommended for high-traffic sites. |
| 337 | |
| 338 | The webpage cache is activated using the [/help?cmd=cache|fossil cache init] |
| 339 | command-line on the server. Add a -R option to specify the specific repository |
| 340 | for which to enable caching. If running this command as root, be sure to |
| 341 | "chown" the cache database (which is a separate file in the same directory |
| 342 | and with the same name as the repository but with the suffix changed to ".cache") |
| 343 | to give it write permission for the userid of the webserver. |
| 344 | |
| 345 | To activate the server load control feature |
| 346 | visit the /Admin/Access setup page in the administrative web |
| 347 | interface and in the "<b>Server Load Average Limit</b>" box |
| 348 | enter the load average threshold above which "503 Server |
| 349 | Overload" replies will be issued for expensive requests. On the |
| 350 | self-host Fossil server, that value is set to 1.5. But you could easily |
| 351 | set it higher on a multi-core server. |
| 352 | |
| 353 | The maximum load average can also be set on the command line using |
| 354 | commands like this: |
| 355 | <blockquote><pre> |
| 356 | fossil set max-loadavg 1.5 |
| 357 | fossil all set max-loadavg 1.5 |
| 358 | </pre></blockquote> |
| 359 | |
| 360 | The second form is especially useful for changing the maximum load average |
| 361 | simultaneously on a large number of repositories. |
| 362 | |
| 363 | Note that this load-average limiting feature is only available on operating |
| 364 | systems that support the "getloadavg()" API. Most modern Unix systems have |
| 365 | this interface, but Windows does not, so the feature will not work on Windows. |
| 366 | Note also that Linux implements "getloadavg()" by accessing the "/proc/loadavg" |
| 367 | file in the "proc" virtual filesystem. If you are running a Fossil instance |
| 368 | inside a chroot() jail on Linux, you will need to make the "/proc" file |
| 369 | system available inside that jail in order for this feature to work. On |
| 370 | the [./selfhost.wiki|self-hosting Fossil repositories], this was accomplished |
| 371 | by adding a line to the "/etc/fstab" file that looks like: |
| 372 | |
| 373 | <blockquote><pre> |
| 374 | chroot_jail_proc /home/www/proc proc ro 0 0 |
| 375 | </pre></blockquote> |
| 376 | |
| 377 | The /home/www/proc pathname should be adjusted so that the "/proc" component is |
| 378 | in the root of the chroot jail, of course. |
| 379 | |
| 380 | To see if the load-average limiter is functional, visit the [/test_env] page |
| 381 | of the server to view the current load average. If the value for the load |
| 382 | average is greater than zero, that means that it is possible to activate |
| 383 | the load-average limiter on that repository. If the load average shows |
| 384 | exactly "0.0", then that means that Fossil is unable to find the load average |
| 385 |