initial commitHEADmaster

1 files changed, 117 insertions, 0 deletions

diff --git a/www/server/any/cgi.md b/www/server/any/cgi.md
new file mode 100644
index 0000000..79ede92
--- /dev/null
+++ b/www/server/any/cgi.md
@@ -0,0 +1,117 @@
+# Serving via CGI
+
+A Fossil server can be run from most ordinary web servers as a CGI
+program.  This feature allows Fossil to seamlessly integrate into a
+larger website.  The [self-hosting Fossil repository web
+site](../../selfhost.wiki) is implemented using CGI.  See the
+[How CGI Works](../../aboutcgi.wiki) page for background information
+on the CGI protocol.
+
+To run Fossil as CGI, create a CGI script (here called "repo") in the
+CGI directory of your web server with content like this:
+
+    #!/usr/bin/fossil
+    repository: /home/fossil/repo.fossil
+
+Adjust the paths appropriately.  It may be necessary to set certain
+permissions on this file or to modify an `.htaccess` file or make other
+server-specific changes.  Consult the documentation for your particular
+web server. The following permissions are *normally* required, but,
+again, may be different for a particular configuration:
+
+*   The Fossil binary (`/usr/bin/fossil` in the example above)
+    must be readable/executable.
+
+*   *All* directories leading up to the Fossil binary must be readable
+    by the process which executes the CGI.
+
+*   The CGI script must be executable for the user under which it will
+    run, which often differs from the one running the web server.
+    Consult your site's documentation or the web server’s system
+    administrator.
+
+*   *All* directories leading to the CGI script must be readable by the
+    web server.
+
+*   The repository file *and* the directory containing it must be
+    writable by the same account which executes the Fossil binary.
+    (This might differ from the user the web server normally runs
+    under.) The directory holding the repository file(s) needs to be
+    writable so that SQLite can write its journal files. When using
+    another access control system, such as AppArmor or SELinux, it may
+    be necessary to explicitly permit that account to read and write
+    the necessary files. Also verify a possible _systemd_ sandboxing of
+    the web server service, especially the combination of _ProtectSystem_,
+    _ProtectHome_, and _ReadWriteDirectories_/_ReadWritePaths_. 
+
+*   Fossil must be able to create temporary files in a
+    [directory that varies by host OS](../../env-opts.md#temp). When the
+    CGI process is operating [within a chroot](../../chroot.md),
+    ensure that this directory exists and is readable/writeable by the
+    user who executes the Fossil binary.
+
+Once the CGI script is set up correctly, and assuming your server is
+also set correctly, you should be able to access your repository with a
+URL like: <b>http://mydomain.org/cgi-bin/repo</b> This is assuming you
+are running a web server like Apache that uses a “`cgi-bin`” directory
+for scripts like our “`repo`” example.
+
+To serve multiple repositories from a directory using CGI, use the
+"directory:" tag in the CGI script rather than "repository:".  You
+might also want to add a "notfound:" tag to tell where to redirect if
+the particular repository requested by the URL is not found:
+
+    #!/usr/bin/fossil
+    directory: /home/fossil/repos
+    notfound: http://url-to-go-to-if-repo-not-found/
+
+Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b>
+will serve up the repository `/home/fossil/repos/XYZ.fossil` if it
+exists.
+
+Additional options available to the CGI script are [documented
+separately](../../cgi.wiki).
+
+#### CGI with Apache behind an Nginx proxy
+
+For the case where the Fossil repositories live on a computer, itself behind
+an Internet-facing machine that employs Nginx to reverse proxy HTTP(S) requests
+and take care of the TLS part of the connections in a transparent manner for
+the downstream web servers, the CGI parameter `HTTPS=on` might not be set.
+However, Fossil in CGI mode needs it in order to generate the correct links.
+
+Apache can be instructed to pass this parameter further to the CGI scripts for
+TLS connections with a stanza like
+
+    SetEnvIf X-Forwarded-Proto "https" HTTPS=on
+
+in its config file section for CGI, provided that
+
+    proxy_set_header  X-Forwarded-Proto $scheme;
+
+has been be added in the relevant proxying section of the Nginx config file.
+
+*[Return to the top-level Fossil server article.](../)*
+
+#### Apache mod_cgi and `CONTENT_LENGTH`
+
+At some point in its 2.4.x family, Apache's `mod_cgi` stopped relaying
+the Content-Length header in the HTTP reply from CGIs back to clients.
+However, Fossil clients prior to 2024-04-17 depended on seeing the
+Content-Length header and were unable to handle HTTP replies without
+one.  The change in Apache behavior caused "fossil clone" and "fossil
+sync" to stop working.  There are two possible fixes to this problem:
+
+  1.  Restore legacy behavior in Apache by adding
+      the following to the Apache configuration, scoped to the `<Directory>`
+      entry or entries in which fossil is being served via CGI:
+      <blockquote><pre>
+      &lt;Directory ...&gt;
+         SetEnv ap_trust_cgilike_cl "yes"
+      &lt;/Directory&gt;
+      </pre></blockquote>
+
+  2.  Upgrade your Fossil client to any trunk check-in after 2024-04-17,
+      as Fossil was upgraded to be able to deal with the missing
+      Content-Length field by
+      [check-in a8e33fb161f45b65](/info/a8e33fb161f45b65).