# Module Netcgi_apache

    module Netcgi_apache: sig .. end

Netcgi Apache "mod" connector.

See the `Netcgi_mod.setup` section at the end of this file to know how to configure Apache.

    module Apache: sig .. end

Interface to Apache API.

    module Handler: sig .. end

Registering Apache handlers.

    class type cgi = object .. end

The usual `cgi` class with an additional method to access Apache specificities.

    val run : ?config:Netcgi.config ->
           ?output_type:Netcgi.output_type ->
           ?arg_store:Netcgi.arg_store ->
           ?exn_handler:Netcgi.exn_handler -> (cgi -> unit) -> unit

`run f` register the function `f` as a main function of the script. Each call to the script will execute `f cgi`. The code outside `f` will be executed only once (when the script is loaded into memory) which allows to cache database connections, etc. (The code stays in memory unless you restart the server or the file changes on disk.)
`config` : Default: `Netcgi.default_config`
`output_type` : Default: ``Direct ""`
`arg_store` : Default: ``Automatic` for all arguments.
`exn_handler` : See `Netcgi.exn_handler`. Default: delegate all exceptions to the default handler.

## Setup

### Apache 1.3

You need to put in an Apache configuration file (we recommend /etc/apache/conf.d/netcgi_apache.conf) the following lines:

        LoadModule netcgi_module /usr/lib/apache/1.3/mod_netcgi_apache.so
        NetcgiRequire netcgi2-apache

### Apache 2.2 or later

You need to put in an Apache configuration file (we recommend /etc/apache2/mods-available/netcgi_apache.load) the following line:

        LoadModule netcgi_module /usr/lib/apache2/modules/mod_netcgi_apache.so
        NetcgiRequire netcgi2-apache

and make a symbolic link from /etc/apache2/mods-enabled/ to it to actually enable it. Subsequent configuration is recommended to be in /etc/apache2/mods-available/netcgi_apache.conf (also to be linked to /etc/apache2/mods-enabled/).

### Loading libraries

If your scripts depend on other libraries, you need to load them using `NetcgiLoad`. More specifically, if your library is x.cma and is in the subdirectory y of standard OCaml directory (given by `ocamlc -where`), use

        NetcgiLoad y/x.cma

If x.cma is not in a subdirectory of `ocamlc -where`, you need to specify the full path.

### Interaction with findlib

Libraries managed with findlib are specially supported. In order to load a library "lib" just use

        NetcgiRequire lib

Findlib-managed libraries are automatically found.

For special configurations one can also set Findlib predicates:

        NetcgiPredicates p1,p2,p3,...

### Multi-threading

If you need multi-threading call

        NetcgiThread

as the very first directive after `LoadModule`, even before `NetcgiRequire netcgi2-apache` (otherwise a number of critical sections remain unprotected in Ocamlnet, and you'll experience crashes).

### Installing scripts

You need also to tell Apache how to detect whether a script is to be handled by netcgi_apache, either by putting them in a special directory (here /caml-bin/):

        Alias /caml-bin/ /path/to/your/scripts/
        <Location /caml-bin>
          SetHandler ocaml-bytecode
          NetcgiHandler Netcgi_apache.bytecode
          Options ExecCGI
          Allow from all
        </Location>

or by distinguishing them by their extension (here `.cma`):

        NetcgiHandler Netcgi_apache.bytecode
        AddHandler ocaml-bytecode .cma

### Compiling scripts

If your script reside in the file `x.ml`, compile it to `x.cmo` or `x.cma`. If your script depends on other libraries, you may either load them with `NetcgiLoad` (see above) or include them in `x.cma`. You need not include the `netcgi_apache.cma`, `netcgi.cma`, `netstring.cma`, `netsys.cma`, or `pcre.cma` modules as these are already loaded into Apache (see above).