CGImod

CGImod is a module for running CGI scripts with ocsigen. It is in beta version. Submit your bugs, feature wishes (or any enhancement/mistake in the documentation) here.

CGImod

What is cgimod?

Cgimod is a module for Ocsigen that allows you to run CGI scripts on your server. It is also the only way to run PHP scripts on Ocsigen, through php5-cgi.

What do I need to use cgimod?

You need a working Ocsigen installation. If you want to run PHP scripts, you need php5-cgi too.

How do I use cgimod?

First, load the extension in the configuration file:

<extension findlib-package="ocsigenserver.ext.cgimod" />

Alternatively, if you do not want to use findlib, you need to load cgimod explicitly:

<extension module="/path/to/cgimod.cmo" />

How do I configure cgimod?

You can set the timeout value for CGI scripts globally, using:

  <extension findlib-package="ocsigenserver.ext.cgimod" >
    <cgitimeout value="30" /> <!-- optionnal -->
  </extension>

Next, you have to specify which scripts you wish to execute, in which host/site, and how. There are several ways to do that. Choose one which suits your needs and stick with it — it's very easy to get lost so keep things as simple as you can!

+ The easy way: useful if you just want a "cgi-bin" directory.

  <site dir="whatever">
    <!-- ... -->
    <cgi root="cgi-bin" dir="/usr/lib/cgi-bin/" />
    <!-- ... -->
  </site>

When someone reaches http://yoursite/whatever/cgi-bin/exec.sh, then /usr/lib/cgi-bin/exec.sh is executed.

+ The regexp way: useful if you want to specify the name of the script to be executed.

  <site dir="whatever">
    <cgi regexp="cgi-bin/([^/]*)"
          dir="/usr/lib/cgi-bin/"
          script="\1" />
  </site>

This is the same example using regexps. The "regexp" part matches the url, "dir" is the physical directory containing the scripts and "script" is the name of the script to execute. Here, "\1" makes reference to the first (parenthesized) subexpression in "regexp" (and of course you can use "\2", "\3", for the second, third, etc.). Warning: until recently, the syntax was $1, $2, etc.

End your regexps with $ if you want them to match the full URL.

Here is another example:

  <site dir="">
    <cgi regexp="darcsweb"
          dir="/usr/lib/cgi-bin/"
          script="darcsweb.cgi" />
  </site>

Note: Darcsweb is a clean web interface for darcs, written in Python.

+ The exec way: useful for PHP (and other script languages)

  <site dir="">
    <!-- To use PHP as a CGI module: -->
    <!-- WARNING:
    remember to put the most generic regexp at the end! -->

    <!-- First, take care of implicit index.php -->
    <cgi regexp="(.*)/"
         dir="/var/www/\1"
         script="index.php"
         exec="/usr/bin/php5-cgi"/>

    <!-- Then, execute every other .php -->
    <cgi regexp="((.*)/)?([^/]*).php"
         dir="/var/www/\2"
         script="\3.php"
         exec="/usr/bin/php5-cgi"/>
  </site>

Just like the previous one, but you can execute the script through some interpreter (here, php5-cgi) instead of launching it directly.

How do I set my own environment variables?

Use <setenv var="" val="" /> inside <cgi>.

Here is an example for setting up trac:

  <!-- Trac -->
  <site dir="trac" charset="utf-8">
       <static dir="/var/www/ocsigen/site/trac" />

       <!-- An example defining its own environment variable: -->
       <cgi regexp=""
            dir="/usr/share/trac/cgi-bin"
            script="trac.cgi" >

            <setenv var="TRAC_ENV" val="/var/www/trac" />
    </cgi>
  </site>

Limitations

The CGI spec is very short and ambiguous. We tried to follow it as closely as we could, but this was not enough. Some environment variables are expected by most scripts but absent from the spec, and some variables present in the spec are very mysterious (PATH_TRANSLATED for example). We did our best — don't hesitate to fill a bug report in case of problems.

The regexp part is quite intricate and some mysterious bugs happen from time to time for some users. Once again, report any reproductible problem!

Morever, cgimod does not support FastCGI, which makes it barely usable under heavy load (particularly for PHP).

Page written by Gabriel Kerneis