doc/tips/dot_cgi.mdwn

   1 [[!meta date="2009-01-12 20:01:03 -0500"]]
   2
   3 It's common to name the [[cgi]] "ikiwiki.cgi", and put it somewhere
   4 like `~/public_html/ikiwiki.cgi`, or `/var/www/wiki/ikiwiki.cgi`.
   5
   6 If you do that, you may find that when trying to edit a page in your wiki,
   7 you see the raw contents of the ikiwiki.cgi program. Or get a permission
   8 denied problem.
   9
  10 This is because web servers are generally not configured to run cgi scripts
  11 unless they're in `/usr/lib/cgi-bin/`. While you can put ikiwiki.cgi in
  12 there if you like, it's better to configure your web server to
  13 run `.cgi`  programs from anywhere.
  14
  15 These instructions are for Debian systems, but the basic
  16 configuration changes should work anywhere.
  17
  18 [[!toc]]
  19
  20 ## apache 2
  21
  22 * Make sure the cgi module is loaded. (Ie, `a2enmod cgi`).
  23   Note that the cgid module will not work.
  24
  25 * Edit /etc/apache2/apache2.conf (or /etc/apache2/mods-available/mime.conf)
  26   and add a line like this:
  27
  28         AddHandler cgi-script .cgi
  29
  30 * Find the "Options" line for the directory where you've put the
  31   ikiwiki.cgi, and add "ExecCGI" to the list of options. For example, if
  32   ikiwiki.cgi is in /var/www/, edit `/etc/apache2/sites-enabled/000-default`
  33   and add it to the "Options" line in the "Directory /var/www/" stanza.
  34   Or, if you've put it in a `~/public_html`, edit
  35   `/etc/apache2/mods-available/userdir.conf`.
  36
  37 * If your wiki is in `~/public_html` and does not appear when you enter the URL given by the installer, check that you have
  38   the userdir mod enabled (there should be simlinks to userdir.load and userdir.conf in /etc/apache2/modes-enabled).  If not,
  39   run `a2enmod userdir` and reload apache2.
  40
  41 * You may also want to enable the [[plugins/404]] plugin.
  42   To make apache use it, the apache config file will need a further
  43   modification to make it use ikiwiki's CGI as the apache 404 handler.
  44   Something like this, with the path adjusted to where you've put the CGI:
  45
  46         ErrorDocument 404 /cgi-bin/ikiwiki.cgi
  47
  48 * 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](https://bugzilla.redhat.com/show_bug.cgi?id=1341658))
  49
  50 ## lighttpd
  51
  52 Here is how to enable cgi on [lighttpd](http://www.lighttpd.net/) and
  53 configure it in order to execute ikiwiki.cgi wherever it is located.
  54
  55 * Activate cgi by linking `/etc/lighttpd/conf-available/10-cgi.conf` into `/etc/lighttpd/conf-enabled` ([doc](http://trac.lighttpd.net/trac/wiki/Docs%3AModCGI)).
  56
  57 * Create `/etc/lighttpd/conf-available/90-ikiwiki-cgi.conf` and add a line like this:
  58
  59     cgi.assign = ( "ikiwiki.cgi"  => "", )
  60
  61 * Activate ikiwiki-cgi by linking `/etc/lighttpd/conf-available/90-ikiwiki-cgi.conf` into `/etc/lighttpd/conf-enabled`.
  62
  63 * Restart lighttpd server with something like `/etc/init.d/lighttpd restart`.
  64
  65 Note that the first part enables cgi server wide but depending on default
  66 configuration, it may be not enough. The second part creates a specific
  67 rule that allow `ikiwiki.cgi` to be executed.
  68
  69 **Warning:** I only use this lighttpd configuration on my development
  70 server (offline). I am not sure of how secure this approach is.
  71 If you have any thought about it, feel free to let me know.
  72
  73 ## nginx
  74
  75 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.
  76
  77 In Linux, you will need the spawn-fcgi and fcgiwrap packages and start
  78 them with:
  79
  80     spawn-fcgi -s /tmp/fcgi.socket -n -- /usr/sbin/fcgiwrap
  81
  82 This needs to be ran as your user. It can be added to `inittab` or
  83 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.:
  84
  85     chmod a+w /tmp/fcgi.socket
  86
  87 If you have [systemd](https://en.wikipedia.org/wiki/Systemd), you may use a service file like so:
  88
  89 Edit/create a service file (in Debian it would be: `sudo vim /lib/systemd/system/ikiwiki.service`
  90
  91 Content of `ikiwiki.service`:
  92
  93     [Unit]
  94     Description=Ikiwiki fcgi socket wrap
  95     After=network.target
  96
  97     [Service]
  98     Type=simple
  99     User=www-data
 100     Group=www-data
 101     ExecStart=/usr/bin/spawn-fcgi -s /tmp/fcgi.socket -n -- /usr/sbin/fcgiwrap
 102
 103     [Install]
 104     WantedBy=multi-user.target
 105
 106 Then run:
 107
 108     # This enables the service at startup
 109     sudo systemctl enable ikiwiki.service
 110     # This attempts to start the service
 111     sudo systemctl start ikiwiki.service
 112
 113 Then you need an nginx config plugged in that wrapper. Here's an
 114 example virtual host configuration:
 115
 116     server {
 117         #listen   80; ## listen for ipv4; this line is default and implied
 118         #listen   [::]:80 default_server ipv6only=on; ## listen for ipv6
 119
 120         root /home/anarcat/public_html/wiki.reseaulibre.ca/;
 121         index index.html index.htm;
 122
 123         # Make site accessible from http://localhost/
 124         server_name wiki.reseaulibre.ca;
 125
 126         location / {
 127                 try_files $uri $uri/ /index.html;
 128         }
 129         location /ikiwiki.cgi {
 130                 fastcgi_pass  unix:/tmp/fcgi.socket;
 131                 fastcgi_index ikiwiki.cgi;
 132                 fastcgi_param SCRIPT_FILENAME   /home/anarcat/public_html/ikiwiki.cgi;
 133                 fastcgi_param  DOCUMENT_ROOT      /home/anarcat/public_html/wiki.reseaulibre.ca;
 134                 include /etc/nginx/fastcgi_params;
 135         }
 136     }
 137
 138 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|todo/fastcgi_or_modperl_installation_instructions]] would be great. ;) --[[anarcat]]
 139
 140 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:
 141
 142         location / {
 143                 try_files $uri $uri/ =404;
 144         }
 145
 146         # Max size of file upload
 147         client_max_body_size 10m;
 148
 149         location ~ .cgi {
 150                 #gzip off is recommended in /usr/share/doc/fcgiwrap/README.Debian
 151                 gzip off;
 152                 fastcgi_pass unix:/var/run/fcgiwrap.socket;
 153                 include /etc/nginx/fastcgi_params;
 154         }
 155
 156 Here's a [[complete site.conf|tips/nginx]] for nginx if that helps.
 157
 158 ## boa
 159
 160 Edit /etc/boa/boa.conf and make sure the following line is not commented:
 161
 162     AddType application/x-httpd-cgi cgi