Fossil SCM

fossil-scm / www / server / any / cgi.md
Source Blame History 115 lines
f146e21… drh 1 # Serving via CGI
f146e21… drh 2
f146e21… drh 3 A Fossil server can be run from most ordinary web servers as a CGI
f146e21… drh 4 program. This feature allows Fossil to seamlessly integrate into a
43fb402… drh 5 larger website. The [self-hosting Fossil repository web
43fb402… drh 6 site](../../selfhost.wiki) is implemented using CGI. See the
43fb402… drh 7 [How CGI Works](../../aboutcgi.wiki) page for background information
43fb402… drh 8 on the CGI protocol.
f146e21… drh 9
f146e21… drh 10 To run Fossil as CGI, create a CGI script (here called "repo") in the
f146e21… drh 11 CGI directory of your web server with content like this:
f146e21… drh 12
8a1ba49… wyoung 13 #!/usr/bin/fossil
8a1ba49… wyoung 14 repository: /home/fossil/repo.fossil
f146e21… drh 15
f146e21… drh 16 Adjust the paths appropriately. It may be necessary to set certain
f146e21… drh 17 permissions on this file or to modify an `.htaccess` file or make other
f146e21… drh 18 server-specific changes. Consult the documentation for your particular
f146e21… drh 19 web server. The following permissions are *normally* required, but,
f146e21… drh 20 again, may be different for a particular configuration:
f146e21… drh 21
f146e21… drh 22 * The Fossil binary (`/usr/bin/fossil` in the example above)
f146e21… drh 23 must be readable/executable.
f146e21… drh 24
f146e21… drh 25 * *All* directories leading up to the Fossil binary must be readable
f146e21… drh 26 by the process which executes the CGI.
f146e21… drh 27
f146e21… drh 28 * The CGI script must be executable for the user under which it will
f146e21… drh 29 run, which often differs from the one running the web server.
f146e21… drh 30 Consult your site's documentation or the web server’s system
f146e21… drh 31 administrator.
f146e21… drh 32
f146e21… drh 33 * *All* directories leading to the CGI script must be readable by the
f146e21… drh 34 web server.
f146e21… drh 35
f146e21… drh 36 * The repository file *and* the directory containing it must be
f146e21… drh 37 writable by the same account which executes the Fossil binary.
f146e21… drh 38 (This might differ from the user the web server normally runs
f146e21… drh 39 under.) The directory holding the repository file(s) needs to be
62ad4e4… stephan 40 writable so that SQLite can write its journal files. When using
62ad4e4… stephan 41 another access control system, such as AppArmor or SELinux, it may
62ad4e4… stephan 42 be necessary to explicitly permit that account to read and write
62ad4e4… stephan 43 the necessary files.
f146e21… drh 44
f146e21… drh 45 * Fossil must be able to create temporary files in a
f146e21… drh 46 [directory that varies by host OS](../../env-opts.md#temp). When the
f146e21… drh 47 CGI process is operating [within a chroot](../../chroot.md),
f146e21… drh 48 ensure that this directory exists and is readable/writeable by the
f146e21… drh 49 user who executes the Fossil binary.
f146e21… drh 50
f146e21… drh 51 Once the CGI script is set up correctly, and assuming your server is
f146e21… drh 52 also set correctly, you should be able to access your repository with a
f146e21… drh 53 URL like: <b>http://mydomain.org/cgi-bin/repo</b> This is assuming you
f146e21… drh 54 are running a web server like Apache that uses a “`cgi-bin`” directory
f146e21… drh 55 for scripts like our “`repo`” example.
f146e21… drh 56
f146e21… drh 57 To serve multiple repositories from a directory using CGI, use the
f146e21… drh 58 "directory:" tag in the CGI script rather than "repository:". You
f146e21… drh 59 might also want to add a "notfound:" tag to tell where to redirect if
f146e21… drh 60 the particular repository requested by the URL is not found:
f146e21… drh 61
8a1ba49… wyoung 62 #!/usr/bin/fossil
8a1ba49… wyoung 63 directory: /home/fossil/repos
8a1ba49… wyoung 64 notfound: http://url-to-go-to-if-repo-not-found/
f146e21… drh 65
f146e21… drh 66 Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b>
f146e21… drh 67 will serve up the repository `/home/fossil/repos/XYZ.fossil` if it
f146e21… drh 68 exists.
f146e21… drh 69
f146e21… drh 70 Additional options available to the CGI script are [documented
f146e21… drh 71 separately](../../cgi.wiki).
f146e21… drh 72
cd93413… danield 73 #### CGI with Apache behind an Nginx proxy
cd93413… danield 74
cd93413… danield 75 For the case where the Fossil repositories live on a computer, itself behind
cd93413… danield 76 an Internet-facing machine that employs Nginx to reverse proxy HTTP(S) requests
cd93413… danield 77 and take care of the TLS part of the connections in a transparent manner for
cd93413… danield 78 the downstream web servers, the CGI parameter `HTTPS=on` might not be set.
cd93413… danield 79 However, Fossil in CGI mode needs it in order to generate the correct links.
cd93413… danield 80
cd93413… danield 81 Apache can be instructed to pass this parameter further to the CGI scripts for
cd93413… danield 82 TLS connections with a stanza like
cd93413… danield 83
8a1ba49… wyoung 84 SetEnvIf X-Forwarded-Proto "https" HTTPS=on
8a1ba49… wyoung 85
cd93413… danield 86 in its config file section for CGI, provided that
cd93413… danield 87
8a1ba49… wyoung 88 proxy_set_header X-Forwarded-Proto $scheme;
8a1ba49… wyoung 89
cd93413… danield 90 has been be added in the relevant proxying section of the Nginx config file.
cd93413… danield 91
f146e21… drh 92 *[Return to the top-level Fossil server article.](../)*
586dc75… stephan 93
586dc75… stephan 94 #### Apache mod_cgi and `CONTENT_LENGTH`
586dc75… stephan 95
9af5f38… stephan 96 At some point in its 2.4.x family, Apache's `mod_cgi` stopped relaying
9af5f38… stephan 97 the Content-Length header in the HTTP reply from CGIs back to clients.
d0f4288… stephan 98 However, Fossil clients prior to 2024-04-17 depended on seeing the
05181e4… drh 99 Content-Length header and were unable to handle HTTP replies without
d0f4288… stephan 100 one. The change in Apache behavior caused "fossil clone" and "fossil
d0f4288… stephan 101 sync" to stop working. There are two possible fixes to this problem:
05181e4… drh 102
05181e4… drh 103 1. Restore legacy behavior in Apache by adding
05181e4… drh 104 the following to the Apache configuration, scoped to the `<Directory>`
05181e4… drh 105 entry or entries in which fossil is being served via CGI:
05181e4… drh 106 <blockquote><pre>
05181e4… drh 107 &lt;Directory ...&gt;
05181e4… drh 108 SetEnv ap_trust_cgilike_cl "yes"
05181e4… drh 109 &lt;/Directory&gt;
05181e4… drh 110 </pre></blockquote>
05181e4… drh 111
05181e4… drh 112 2. Upgrade your Fossil client to any trunk check-in after 2024-04-17,
05181e4… drh 113 as Fossil was upgraded to be able to deal with the missing
05181e4… drh 114 Content-Length field by
05181e4… drh 115 [check-in a8e33fb161f45b65](/info/a8e33fb161f45b65).

Keyboard Shortcuts

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