=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) [[site:trac/|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: [[http://blitiri.com.ar/p/darcsweb/|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 [[http://www.w3.org/CGI/|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//