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