ikiwiki/ tips/ dot cgi

It's common to name the cgi "ikiwiki.cgi", and put it somewhere like `~/public_html/ikiwiki.cgi`, or `/var/www/wiki/ikiwiki.cgi`.

If you do that, you may find that when trying to edit a page in your wiki, you see the raw contents of the ikiwiki.cgi program. Or get a permission denied problem.

This is because web servers are generally not configured to run cgi scripts unless they're in `/usr/lib/cgi-bin/`. While you can put ikiwiki.cgi in there if you like, it's better to configure your web server to run `.cgi` programs from anywhere.

These instructions are for Debian systems, but the basic configuration changes should work anywhere.

## apache 2

- Make sure the cgi module is loaded. (Ie, `a2enmod cgi`). Note that the cgid module will not work.

- Edit /etc/apache2/apache2.conf (or /etc/apache2/mods-available/mime.conf) and add a line like this:

  AddHandler cgi-script .cgi

- Find the "Options" line for the directory where you've put the ikiwiki.cgi, and add "ExecCGI" to the list of options. For example, if ikiwiki.cgi is in /var/www/, edit `/etc/apache2/sites-enabled/000-default` and add it to the "Options" line in the "Directory /var/www/" stanza. Or, if you've put it in a `~/public_html`, edit `/etc/apache2/mods-available/userdir.conf`.

- If your wiki is in `~/public_html` and does not appear when you enter the URL given by the installer, check that you have the userdir mod enabled (there should be simlinks to userdir.load and userdir.conf in /etc/apache2/modes-enabled). If not, run `a2enmod userdir` and reload apache2.

- You may also want to enable the 404 plugin. To make apache use it, the apache config file will need a further modification to make it use ikiwiki's CGI as the apache 404 handler. Something like this, with the path adjusted to where you've put the CGI:

  ErrorDocument 404 /cgi-bin/ikiwiki.cgi

- On Fedora (and RHEL, CentOS, and derivatives) you may need to change CGI mode from `06755` to `755` as suid/sgid bit is prohibited by `suexec`. (Bug 1341568)

## lighttpd

Here is how to enable cgi on lighttpd and configure it in order to execute ikiwiki.cgi wherever it is located.

- Activate cgi by linking `/etc/lighttpd/conf-available/10-cgi.conf` into `/etc/lighttpd/conf-enabled` (doc).

- Create `/etc/lighttpd/conf-available/90-ikiwiki-cgi.conf` and add a line like this:

  cgi.assign = ( "ikiwiki.cgi" => "", )

- Activate ikiwiki-cgi by linking `/etc/lighttpd/conf-available/90-ikiwiki-cgi.conf` into `/etc/lighttpd/conf-enabled`.

- Restart lighttpd server with something like `/etc/init.d/lighttpd restart`.

Note that the first part enables cgi server wide but depending on default configuration, it may be not enough. The second part creates a specific rule that allow `ikiwiki.cgi` to be executed.

Warning: I only use this lighttpd configuration on my development server (offline). I am not sure of how secure this approach is. If you have any thought about it, feel free to let me know.

## nginx

To run CGI under nginx, you need to use a FastCGI wrapper. The wrapper must be started somehow just like any other FastCGI program. You can use launchd on OSX.

In Linux, you will need the spawn-fcgi and fcgiwrap packages and start them with:

    spawn-fcgi -s /tmp/fcgi.socket -n -- /usr/sbin/fcgiwrap

This needs to be ran as your user. It can be added to `inittab` or made into a startup script in `init.d`. You may also need to make this file writable by the webserver, if that's running as a different user, e.g.:

    chmod a+w /tmp/fcgi.socket

If you have systemd, you may use a service file like so:

Edit/create a service file (in Debian it would be: `sudo vim /lib/systemd/system/ikiwiki.service`

Content of `ikiwiki.service`:

    [Unit]
    Description=Ikiwiki fcgi socket wrap
    After=network.target

    [Service]
    Type=simple
    User=www-data
    Group=www-data
    ExecStart=/usr/bin/spawn-fcgi -s /tmp/fcgi.socket -n -- /usr/sbin/fcgiwrap

    [Install]
    WantedBy=multi-user.target

Then run:

    # This enables the service at startup
    sudo systemctl enable ikiwiki.service
    # This attempts to start the service
    sudo systemctl start ikiwiki.service

Then you need an nginx config plugged in that wrapper. Here's an example virtual host configuration:

    server {
        #listen   80; ## listen for ipv4; this line is default and implied
        #listen   [::]:80 default_server ipv6only=on; ## listen for ipv6

        root /home/anarcat/public_html/wiki.reseaulibre.ca/;
        index index.html index.htm;

        # Make site accessible from http://localhost/
        server_name wiki.reseaulibre.ca;

        location / {
                try_files $uri $uri/ /index.html;
        }
        location /ikiwiki.cgi {
                fastcgi_pass  unix:/tmp/fcgi.socket;
                fastcgi_index ikiwiki.cgi;
                fastcgi_param SCRIPT_FILENAME   /home/anarcat/public_html/ikiwiki.cgi;
                fastcgi_param  DOCUMENT_ROOT      /home/anarcat/public_html/wiki.reseaulibre.ca;
                include /etc/nginx/fastcgi_params;
        }
    }

Also, note that the `/tmp/fcgi.socket` file needs to be writable by the webserver. I am also unsure as to the security of this setup, as I am using this only on my dev server. Needless to say that real fastcgi support would be great. --anarcat

2016-09-23 alexjj: On Debian Jessie creating the fcgi ikiwiki.service is not necessary. Install fcgiwrap, it'll auto start the fcgiwrap systemd service and then add the parameters in the virtual host:

        location / {
                try_files $uri $uri/ =404;
        }

        # Max size of file upload
        client_max_body_size 10m;

        location ~ .cgi {
                #gzip off is recommended in /usr/share/doc/fcgiwrap/README.Debian
                gzip off;
                fastcgi_pass unix:/var/run/fcgiwrap.socket;
                include /etc/nginx/fastcgi_params;
        }

Here's a complete site.conf for nginx if that helps.

## boa

Edit /etc/boa/boa.conf and make sure the following line is not commented:

    AddType application/x-httpd-cgi cgi

# Caddy

add a block to Caddyfile like this

    www.myexample.net {
        root * /home/ikiwiki/public_html/myexample
        file_server

        reverse_proxy /ikiwiki.cgi unix//var/run/fcgiwrap.socket {
                transport fastcgi {
                        root /home/ikiwiki/public_html/myexample
                        env SCRIPT_FILENAME /home/ikiwiki/public_html/myexample/ikiwiki.cgi
                }
        }

        encode zstd gzip
    }