Ocsigen

Server

Home

Doc

Eliom

Js_of_ocaml

Server

Lwt

Tyxml

Start

Warning: Reason support is experimental. We are looking for beta-tester and contributors.

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.

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>

    <!-- 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 system (e.g. www-data).

Example : 

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

<charset> : default charset for pages

Example: 

<charset>utf-8</charset>

<uploaddir> : directory where files are uploaded

If you want to allow the users to upload files on the server, add this option.

Example: 

<uploaddir>/var/upload</uploaddir>

By default, no directory is specified and uploading is forbidden. Note that the server will remove the files after the request has been served. If the service (the script) want to keep the file, it must create a new hard link on the file itself.

You can specify the maximum size of uploaded files using <maxuploadfilesize>. For example : 

<maxuploadfilesize>2MB</maxuploadfilesize>

The value may be "infinity" or written using SI or binary units, e.g. 10 10B 10kB 10kiB 10MiB 10TB ... (or 10o 10ko ...) (default in bytes when no unit is specified)

Warning: the maximum size of files is also limited by <maxrequestbodysize>.

Starting from Ocsigenserver 1.3, you can redefine the options <uploaddir> and <maxuploadfilesize> on each host or inside <site> tags. The syntax is the same as above. There are however some limitations; please read carefully the documentation of the module Extendconfiguration before using this functionality.

<maxrequestbodysize> : maximum size of the body of incoming requests

Example: 

<maxrequestbodysize>100MB</maxrequestbodysize>

The value may be "infinity" or written using SI or binary units, e.g. 10 10B 10kB 10kiB 10MiB 10TB ... (or 10o 10ko ...) (default in bytes when no unit is specified)

<mimefile> : MIME type file

The file associating file name extensions to their MIME type. Example: 

<mimefile>/etc/ocsigenserver/mime.types</mimefile>

<debugmode/> : Error messages in pages

Use this option for debugging your Web sites. Full error messages will be written in Error 500 pages. Example: 

<debugmode/>

<usedefaulthostname/> : Do not trust Host HTTP header for absolute links

(From Ocsigenserver 1.2) Use this option if you do not trust the Host HTTP header for building absolute links, CGI scripts and redirections. The default hostname set in the configuration file will be used instead. (Same as Apache's UseCanonicalName option). Example: 

<usedefaulthostname/>

<maxconnected> : Maximum number of simultaneous connections

Example: 

<maxconnected>500</maxconnected>

<timeout> : Timeout for connections

Written in seconds. If the client does not say anything during that amount of time, the connection will be closed. Example: 

<timeout>20</timeout>

<keepalivetimeout> : Timeout for Keep-Alive

Amount of time (in seconds) the server will wait for subsequent requests on a persistent connection. Example: 

<keepalivetimeout>10</keepalivetimeout>

<shutdowntimeout> : Timeout for graceful shutdown From version 1.3

Amount of time (in seconds) the server will wait for current requests to terminate before ending the process, when you use the "graceful shutdown" server command (see below). 

<shutdowntimeout>10</shutdowntimeout>

Other possible value: notimeout if you don't want to wait all connections even if it takes time.

<netbuffersize> : Size of the input buffer

Size of the input buffer (sockets). It is also the maximum size of headers and post data. Example: 

<netbuffersize>8192B</netbuffersize>

<filebuffersize> : Size of the buffer for sending files

Size of the buffer for reading files to send. Example: 

<filebuffersize>8192B</filebuffersize>

<minthreads> <maxthreads> : Size of the preemptive thread pool

Even if Ocsigenserver is implemented with cooperative threads, web site programmers may want to detach some computation to other preemptive threads. To do that, Ocsigenserver has a pool of preemptive threads running, waiting for computation to do. This options allow to set the size of this pool. Example: 

<minthreads>10</minthreads>
<maxthreads>1000</maxthreads>

<maxdetachedcomputationsqueued> : Size of the queue of waiting detached computations

If the pool of preemptive threads is full, new detached computations will wait for one thread to become available. This is the size of the waiting queue. Only integer values allowed here. Example: 

<maxdetachedcomputationsqueued>100</maxdetachedcomputationsqueued>

<maxretries> : Maximum number of retries for the same request

To prevent looping requests, for example after a rewrite of the request, the number of retries is limited to this number. Example: 

<maxretries>10</maxretries>

<commandpipe> : The pipe used to give orders to the server

Ocsigenserver is waiting for orders on a pipe. Write the orders on the pipe. This option allows to set the name of the pipe. Example: 

<commandpipe>/var/run/ocsigenserver_command</commandpipe>

Each extension can define its own orders.

Predefined orders:

  • reload: will reload the configuration file. Extensions will not be reloaded but all other modules will be reloaded (for example Eliom web sites) (see below for more information).
  • gc: will trigger a heap compaction
  • shutdown: will shutdown the server when all the current rerquests are fulfilled (see below for more information)
  • reopen_logs: will reopen the logs files (see logrotate configuration for an example of use)
  • clearcache: will empty all the caches defined by the module Ocsigen_cache

<extconf> : Splitting the configuration file

If your configuration is complex, it is recommended to split the configuration file into several files. The following command will include all external configuration files matching *.conf from this directory (in alphabetical order): 

<extconf dir="..."/>

Loading extensions and libraries

<extension> : Loading extensions and libraries

Ocsigenserver does not do anything without some extensions loaded. For example, you need the extension staticmod for serving static pages. Extensions are loaded dynamically when launching the server. Specify the extensions and libraries you want using the tag <extension>.

Warning: The order in which extensions are loaded is usually not significant (from 0.99.4) (but if you have dependencies between the modules). Extensions will try to handle requests in the order in which the options are written inside <host>.

If you want to run a Web site with Eliom, you probably need the extensions Staticmod and Eliom, the first one to generate static pages, the second one for dynamic pages.

If you don't have any extension, no page will be generated.

Extensions will not be reloaded if you ask the server to reread the configuration file. And they will be loaded only once, even if you have several times the same extension. For example if you are using <extconf> to configure several websites in several configuration files, you can put all the dependencies in each file.

Some extensions take parameters between <extension> and </extension>

Example of use: 

<extension module="/opt/godi/lib/ocaml/site-lib/ocsigenserver/staticmod.cma"/>

(From version 1.0) Extensions can also be loaded using Findlib. If you specify a package which has dependencies, these dependencies will also be loaded, without parameters. Dependencies are always loaded only once, so you can safely load several extensions which have a shared dependency.

If you don't want to clutter your installation with a lot of Ocsigen-specific packages, you can put them outside the default search path (for example, something below /usr/local/lib/ocsigenserver), and extend the search path in the configuration file. Here, "search path" has the same semantics as in Findlib. For example, you might have the following line in your configuration file if you compiled and installed Ocsigenserver on your own: 

<findlib path="/usr/local/lib/ocsigenserver/METAS"/>

Extensions shipped with Ocsigen Server are available as subpackages of ocsigenserver.ext (this package is in an extended search path). For example: 

<extension findlib-package="ocsigenserver.ext.deflatemod">

This will load deflatemod, and its dependency camlzip (if not already loaded).

<require> : Loading libraries

From version 1.0, <require> is a synonymous for <extension>.

<library> : Loading libraries

If you want to load other OCaml libraries for your extensions or Website, use <extension> if you do not want them to be reloaded each time the configuration file is reread, or <library> if you need them to be reloaded every time. Extensions like CGImod or Staticmod or Eliom can not be loaded with <library>. Use <library> only for the modules you want to be able to reload without shutting down the server.

Libraries may take parameters between <library> and </library>.

Example of use: 

<library module="/opt/godi/lib/ocaml/site-lib/mysite/mylib.cma"/>

As in <extension>, you can also use findlib-package= instead of module=. However, remember that dependencies will always be loaded only once (only the last file of the package itself may be reloaded several times).

Virtual host and site configuration

<host> : Virtual host setting

It is possible to have several virtual hosts on the same server. For example if your server has two host names, you may want to serve different Web sites for each of them. Note that this feature is based on the Host: HTTP header, which is not mandatory in HTTP/1.0.

The attribute defaulthostname is just an information about the hostname, that can be used for example by services to create absolute links. If you want to create virtual hosts for several domain names, use the hostfilter attribute to filter on the Host HTTP header. You may specify several hostnames, and the optional hostfilter field may contain '*' (wildcard). Example: 

<host defaulthostname="www.mysite.com" hostfilter="www.mysite.com *.org" charset="utf-8"> ... </host>

The charset attribute is the default charset for your pages. All attributes are optional, but we recommend to set at least defaulthostname.

If you do not want to send any charset, explicitely: charset="". In that case, browsers usually use html meta-data (when present).

Warning: Before version 1.2.0, hostfilter was called: name (or aliases).

It is also possible to set the default ports for http and https, and default protocol using defaulthttpport, defaulthttpsport and defaultprotocol=. These arguments may be used by extensions (like Eliom) if they need to create absolute links. Example: 

<host defaulthostname="www.mywebsite.org" hostfilter="*.org" defaulthttpport="8080" defaulthttpsport="4433" defaultprotocol="https"> ... </host>

Inside <host>, write the configuration for your main (root) site. These options depend on the extensions loaded. See the documentation about the extensions to know what to put here. It is also possible to define here several subsites, using <site> (see below).

<site> : Configuring sub-sites

In each virtual host, it is possible to define several sub-sites (in sub-paths) between <site> and </site>. <site> has an attribute dir to set the home directory for the site. You can also set the default charset for the site using the charset attribute. The options between <site> and </site> are exactly the same as those you can can put between <host> and </host>. They depend on the extensions you loaded. It is also possible to define sub-sites inside sub-sites.

Example of use: 

<site path="mysite"> ... </site>

Reloading the configuration file

To reload the modules of the configuration file without stoping the server, write the command reload in the server's command pipe (usually /var/run/ocsigenserver_command. For example: 

echo reload > /var/run/ocsigenserver_command

Form version 1.3, it is possible to give the name of the configuration file as parameter: 

echo reload /etc/ocsigenserver/ocsigenserver.conf.2 > /var/run/ocsigenserver_command

Most distributions have a special command to do that automatically (for the default configuration file), usually: 

/etc/init.d/ocsigenserver reload

The configuration file will be reloaded, and the changes will be taken into account if possible. For example it is not possible to change the port numbers without stoping the server for now. Extensions and libraries loaded using <extension> will not be reloaded.

Graceful shutdown (From version 1.3)

To end the server cleanly, use the shutdown command, for example: 

echo shutdown > /var/run/ocsigenserver_command

No new connection will be accepted, but all current requests will be terminated (with a timeout). Then the server process will end.

You can specify the timeout as parameter (in second): 

echo shutdown 10 > /var/run/ocsigenserver_command

It means that the server process will end after at most 10 seconds, even if some connexions are still alive. If you do not want any timeout, do: 

echo shutdown notimeout > /var/run/ocsigenserver_command

In that case, the server will wait for all the connections to terminate, even if it takes a lot of time.

The default timeout value can be set in the configuration file (see shutdowntimeout option above).