Main  /  Edit  /  History  /   /  Users Area

CppCMS Configuration

CppCMS configuration file is used to define different aspects of the process that may be changes without recompiling an application.

CppCMS Server API -- server.api

Setting API

This parameter is mandatory. CppCMS supports three most popular web server APIs: FastCGI, SCGI and CGI. Values of server.api are "fastcgi", "scgi", and "cgi" accordingly.

For example:

server.api = "fastcgi"

Choosing API

FastCGI is the most reliable and recommended API. It has best web servers support and usually has most stable implementations.

Notes: libcppcms should be compiled with fastcgi library.

SCGI is simple alternative to FastCGI. It is quite common due to very simple specifications that allow easy implementation.

However it has it's own drawbacks:

It should be used if no FastCGI API is available, or libcppcms compiled without fastcgi support.

CGI -- may be used only in three cases:

API Parameters

CppCMS Server Mod -- server.mod

Unless server.api is CGI, this parameter is mandatory. Three modes are availible: "process", "thread" and "prefork". For example

server.mod = "prefork"

GZip Compression

Today, most of browsers accept gzip compressed pages sending header "Accept-Encoding: gzip". If the browser supports "gzip", the output page is automatically compressed and sent do it, saving server bandwith. More then that, when caching is enabled, the cached page is storred in both compressed and uncompressed formats. This allows send cached page much faster --- without recompressing their content.

Gzip compression is enabled by default. To disable it (not recommended) use:

gzip.enable = 0

Compression level has significant impact on the performacne of the system. Thus, if your application does not use cache or has high cache miss ratio, reducing compression level to minimal would significanly increase performance (up to twice), while the size of output would chagne in about 10%.

gzip.level = 1 # Minimal

Compression buffer size can be defined as well using gzip.buffer. The size in bytes.


There are several backends for caching in CppCMS. They are defined by parameter cache.backend"

  1. threaded -- cache for an application that runs in single process, usually mod-thread. All its internal data placed in single process.

    Parameters: cache.limit -- number of entries that are stored in cache. Default 100.

    For example

      cache.backed = "threaded"
      cache.limit = 10000
  2. fork -- cache for an application that runs in mod-prefork. The data is placed in shared memory available for forked processes.

    Parameters: cache.memsize -- the size of shared memory region in KB.

    Note: Entries bigger than 5% of the size are not stored.

    For example:

      cache.backend = "fork"
      cache.memsize = 65536 # 64 MB
  3. tcp -- distributed cache system. It can be used with all available working modes. It works similarly to memcached, but provides more powerful feature, like dependencies tracking.


    • cache.ips -- the list of IPs of cache servers.
    • cache.ports -- the list of ports of cache servers.

    For example:

      cache.backend = "tcp"
      cache.ips = { "" "" }
      cache.ports = { 6010 6010 }

    Note: All entries are equally distributed over all servers. It is important to define same order of of parameters for each CppCMS server running in the network, because each key has unique mapping to specific server.


Configure location of session storage

CppCMS supports three major variants of session storage: client, server and both. They are defined by setting parameter session.location

  1. client -- store session information entirely at client side using cookies.
  2. server -- store session information entirely at server side, when client sides holds only session ID in the cookies.
  3. both -- combination of both methods depending on the size of the data that should be stored. If the data size is behind certain threshold, use server side storage, otherwise use client side.

    This threshold is controlled by session.client_size_limit configuration parameter. The default value us 2048 bytes.

  4. none -- sessions backend is disabled -- default.

For example:

session.location = "both"
session.client_size_limit = 512

Note: This limit represents the size of actual data. The real cookies size is about 4/3 bigger, because of base64 encoding.

Default session expiration

Session expiration is controlled by session.expire parameters. There are three ways the session can expire:

  1. browser -- the session expires when the browser is closed. This is the default expiration method.
  2. renew -- the session is stored for certain time period. If user visits the site again, its expiration period is extended.
  3. fixed -- once the session is created it will expire after limited period of time, whether user visits the site and whether not. It is useful to force user re-login each fixed period of time.

The expiration time is defined by parameter session.timeout (in seconds). The default is 24 hours --- 24*3600 seconds.



session.expire = "fixed"
session.timeout = 1209600     # two weeks in seconds

Cookies options

Client side storage configuration.

Client side storage has two options for securing information in cookies:

The encryption method is defined by parameter session.cookies_encryptor.

Each of this method uses private key of 128 bits long. It should be defined as 32 hexadecimal digits number in parameter session.cookies_key.

CppCMS provides utility cppcms_make_key that creates such key for you using /dev/random OS interface.

For example:

session.cookies_encryptor = "hmac"
session.cookies_key = "29b6f071ad58703b8c6a2115d88d3b2e"

Server side storage configuration

There are four server side backends for session management. The backend defined in parameter session.backend:

  1. files -- store session information in files. This is default server side storage.
  2. tcp -- use distributed session storage that is accessed via TCP/IP
  3. sqlite -- store session in Sqlite3 database.
  4. cache -- use cache as session information storage.

Thare is an option to use CppCMS cache system to improve performance of session storage. Additional cache layer can be turned on for file and sqlite backends by setting parameter:

session.server_enable_cache = 1

You have an option to use it, but in most of cases it is not really required.

Files backend options

For example:

session.backend = "files"
session.files_dir = "/var/data/cms/sessions"
session.files_comp = "thread"
session.files_gc_frequency = 600 # 10 minutes

Sqlite3 Backend Options

Note: In generally user should define session.sqlite_db paremeter only. Most of other parameters are preconfigured with default values suitable for most of applications. They are still accessable for advanced users for fine performance tuning.

For example


Cache backend storage

It is very simple and unreliable backend because the data may be removed from the cache when it becomes full. Also the data is lost when application stops.

It can be used mostly for testing and debugging purposes. When using this backend, cache should be turned on.

Distributed over TCP storage

It has only two parameters:

Its configuration is very similar to TCP cache backend.

Note: Make sure that the order of the servers and their number is the same for all CppCMS servers. Otherwise different application would try to look for same session on different TCP servers.

For example:

session.tcp_ips = { "" "" }
session.tcp_ports = { 3000 3000 }


If your application loads templates dynamicly from shared objects, you should define, the list of directories where the lookup should be performed. For example:

templates.dirs = { "/usr/local/lib/blog/" "/opt/views" }

CppCMS would look in this directories for files ending with ".so" under various UNIXes or ".dll" under Cygwin and try to load the templates.

If on your OS uses different extension, you may specify it with: templates.ext. For example:

templates.ext = ".dlib"


CppCMS uses it's own implementation of gettext that allows using different locales withing same process.

It has following parameters

For example:

locale.dir = "/usr/share/locale"
locale.lang_list = { "en" "ru" "he" }
locale.lang_default = "he"
locale.domain_list = { "wiki" "wiki_views" }
locale.domain_default = "wiki"



CppCMS is a web development framework for performance demanding applications.

Support This Project Logo

Поддержать проект

CppCMS needs You


Main Page

Valid CSS | Valid XHTML 1.0