Configuration file

The main configuration file is usually named /etc/ocsigenserver/ocsigenserver.conf. It contains the port(s) on which you want to run the server (usually 80), the protocol to use (HTTP or HTTPS), the location of log files, many settings for the server, the extensions to be loaded, the OCaml libraries you need for your Web sites, the configuration of each Web site, etc. One default configuration file should be provided by your distribution.

If you compiled Ocsigen yourself, two default configuration files are generated:

Basic layout of the configuration file

The configuration file is an XML file. Its layout is the following:

<ocsigen>

  <server>

    <!-- General setting -->
    <port>80</port>

    <logdir>...</logdir>
    <datadir>...</datadir>
    <commandpipe>...</commandpipe>

    <user>...</user>
    <group>...</group>


    <!-- Extensions to be loaded: -->
    <extension module=.../>
    <extension module=...>
      <!-- Options for the extension -->
      ...
    </extension>

    <!-- You can also use Findlib to load an extension and its dependencies: -->
    <findlib path=.../>
    <extension findlib-package=.../>

    <!-- Libraries needed by Web sites: -->
    <require module=.../> <!-- <require is equivalent to <extension> -->
    <require findlib-package=.../>
    <require module=...>
      <!-- Options for the library -->
      ...
    </require>

    <!-- Libraries needed by Web sites, when you want them to be reloaded
         every times you reload the config files: -->
    <library module=.../>
    <library findlib-package=.../>
    <library module=...>
      <!-- Options for the library -->
      ...
    </library>

    <!-- Inclusion of all external configuration files matching *.conf
     from this directory (in alphabetical order): -->
    <extconf dir=... />

    <!-- Virtual hosts configuration: -->
    <host defaulthostname=... hostfilter=...>

      <!-- configuration for the site at the root -->
      ...

      <site path=...>
        <!-- configuration for the first sub-site -->
        <!-- Warning: it was <site dir=...> before 0.99.4 -->
        ...
      </site>

      <site path=...>
        <!-- configuration for another sub-site -->
        ...
      </site>
    </host>

    <host defaulthostname=... hostfilter=...>
      <!-- configuration for the second virtual host -->
      ...
    </host>

    ...

  </server>

</ocsigen>

Here is a simple example:

<ocsigen>
  <server>

    <port>127.0.0.1:80</port>

    <logdir>/var/log/ocsigenserver</logdir>
    <datadir>/var/lib/ocsigenserver</datadir>
    <commandpipe>/var/run/ocsigenserver/command</commandpipe>

    <user>www-data</user>
    <group>www-data</group>

    <charset>utf-8</charset>

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

    <extension findlib-package="ocsigenserver.ext.ocsipersist-sqlite"/>
    <!-- sqlite3.cma will be loaded automatically using findlib -->

    <extension findlib-package="eliom.server"/>
    <!-- Eliom's dependencies will be loaded automatically using findlib -->

    <extconf dir="/etc/ocsigenserver/conf.d" />

    <host charset="utf-8" hostfilter="www.mywonderfulwebsite.org">

      <static dir="/var/www/ocsigenserver" />

      <site path="tuto">
        <eliom module="/usr/local/lib/ocaml/tutoeliom/tutoeliom.cmo" />
        <static dir="/var/www/tutorial" />
      </site>

    </host>

  </server>

</ocsigen>

Here is another example, for use as unprivileged user toto on port 8000. We use the PostgreSQL (version >= 9.5) backend for ocsipersist. Note that the ocsipersist-database under the specified name (default: "ocsipersist") needs to exist. To create it run psql and execute CREATE TABLE ocsipersist;.

<ocsigen>
  <server>

    <port>8000</port>

    <logdir>/home/toto/var/log/ocsigenserver</logdir>
    <datadir>/home/toto/var/lib/ocsigenserver</datadir>
    <commandpipe>/home/toto/var/run/ocsigenserver_command</commandpipe>

    <user>toto</user>
    <group>toto</group>

    <charset>utf-8</charset>

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

    <extension findlib-package="ocsigenserver.ext.ocsipersist-pgsql">
      <database <!-- optional, as each of the following attributes are -->
        port="3000"
        user="toto"
        password="toto's secret"
      />
    </extension>
    <!-- pa_pgsql.cma will be loaded automatically using findlib -->

    <extension findlib-package="ocsigenserver.ext.eliom"/>
    <!-- Eliom's dependencies will be loaded automatically using findlib -->

    <extconf dir="/home/toto/etc/ocsigenserver/conf.d" />

    <host>

      <static dir="/home/toto/var/www/ocsigenserver" />

      <site path="tuto">
        <eliom module="/usr/local/lib/ocsigenserver/tutoeliom.cmo" />
        <static dir="/home/toto/var/www/ocsigenserver/tutorial" />
        <!-- Module's path coul be relative but static dir must be absolute -->
      </site>

    </host>

  </server>

</ocsigen>

Details about settings

<port> : port and protocol

The port on which the server is listening. You can have several <port>lines if you want to listen on several ports.

<port> has one optional attribute called protocol. Its value may be either HTTP (default) or HTTPS if you want to use HTTPS on that port. The default port is 80 for HTTP, and 443 for HTTPS.

You can make the server bind on a specific address:

    <port>127.0.0.1:80</port>

To make the server listen on all IPv4 interfaces (and only them):

    <port>*:80</port>

To make the server listen on all IPv6 interfaces (and only them):

    <port>[::]:80</port>

To make the server listen on all IPv4 and IPv6 interfaces:

   <port>80</port>

Warning: with versions < 1.3.1, the two previous variants were equivalent and would make the server listen on all IPv6 interfaces, and on IPv4 interfaces as well depending on the operating system (more specifically, the default value of IPV6_V6ONLY). This OS-dependent behaviour has been fixed in version 1.3.1.

You can also make the server bind on a specific IPv6 address (it must be between brackets):

    <port>[2001:660:3001:4002::10]:80</port>

If you want to use HTTPS, you need to specify a certificate to use, and a private key, as follows:

    <ssl>
       <certificate>path_to/cert.pem</certificate>
       <privatekey>path_to/privkey.pem</privatekey>
    </ssl>

Use the tools provided by openssl to create a 1024-bit private key to use when creating your CA.:

    openssl genrsa -des3 -out privkey.pem 1024

To create a master certificate based on this key, to use when signing other certificates:

    openssl req -new -x509 -days 1001 -key privkey.pem -out cert.pem

If you don't want to be asked for a password at start-up, you can uncrypt the private key (if you consider it is safe ...):

    openssl rsa -in privkey.pem -out privkey-unsec.pem

<logdir> : log files directory

The directory for log files. Usually /var/log/ocsigenserver. Ocsigenserver is using three log files: access.log where all requests are logged, errors.log for error messages, and warnings.log for warnings.

Example :

<logdir>/var/log/ocsigenserver</logdir>

<datadir> : directory for server data

This directory is used to store data used by the server or extensions (for example persistent data). Usually /var/lib/ocsigenserver.

Example :

<datadir>/var/lib/ocsigenserver</datadir>

<syslog> : log to syslog

Specifies which syslog facility to use, instead of logging to files. This option is mutually exclusive with <logdir>.

Example:

<syslog>Local7</syslog>

<user> and <group> : user who runs the server

If the server is launched by root, it will change itself the user and group for the process, for security reasons. Create a group and a user for Ocsigenserver or use an existing user of your