Main  /  Edit version 3  /  Edit version 4  /   /  Users Area

Difference "CppCMS Configuration" ver. 3 versus ver. 4


CppCMS configuration file is used to define different
aspects of the process that may be changes without recompiling
an application.
- [Server API](#server-api)
- [CppCMS Server Mod](#server-mod)
- [Gzip Compression](#gzip)
- [Cache](#cache)
- [Sessions](#sessions)
- [Templates](#templates)
- [Localization](#locale)
- [Localization](#locale)
## <span id="server-api"></span>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:
- Many web servers do not support connection via UNIX domain sockets and auto start.
- SCGI web server implementation are usually more buggy in comparison to FastCGI.
It should be used if no FastCGI API is available, or libcppcms compiled without fastcgi support.
[CGI]( -- may be used only in three cases:
- Web server do not support fastcgi and scgi and there is no option to use `cgi-fcgi` "connector"
- Debugging
- CppCMS application is heavy CPU bounded, thus the time required for fork+exec is negligible.
### API Parameters
- `server.socket` -- FastCGI or SCGI socket. For Unix Domain socket, specify path
For TCP sockets specify "[IP]:port" for example
Default socket is Standard Input -- 0. It is used when web server starts
FastCGI/SCGI application.
- `server.buffer` -- How many requests can be "on-hold" -- actually parameters for listen(2)
it is also used for internal buffer size of "mod-thread"
server.buffer = 100
Default is 1.
## <span id="server-mod"></span>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"
- **`process`** -- CppCMS application runs in single thread, this is the simplest and quite safe mod. If application crashes, only one session is aborted. However, every shared data should pass through IPC -- cache, sessions etc.
- **`thread`** -- CppCMS runs as single process, all application instances run in thread pool. This can be used for best performance. Drawbacks -- in case of crash, all CppCMS server goes down.
Parameters: `server.threads` --- the size of thread pool. Default is 5 threads.
- **`prefork`** -- CppCMS spawns process pool that execute queries, when "parent" process controls
this poll. Every application run in its own process as single thread.
If application crashes, missing process is automatically "reforked" by parent providing
best degree of safety. Also, the iterations limit can be set to force processes die and
prevent memory and resources leaks in "hard way".
- `server.iterations_limit` -- the number of interations that each process can procced before
respawning. Default: unlimited.
- `server.procs` -- the size of workers pool. Default: 5 worker processes.
## <span id="gzip"></span>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.
## <span id="cache"></span>Cache
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 avalilible for forked processes.
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
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
## <span id="sessions"></span>Sessions
### 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.
#### Notes:
- Timeout is valid even for "browser" session expiration. If user does not close the browser, it behaves like "renew" period.
- Session expiration period is accurate up to 10% of time.
_Rationale:_ if the information withing the session is not changed, the data is not updated in order to reduce database updates that only require update of expiration timestamp. Thus, if the data is not updated, the expiration timestamp is updated only if more then 1/10 of the time had passed.
- Expiration period is stored as a part of session data, even if cookies storage is used.
session.expire = "fixed"
session.timeout = 1209600 # two weeks in seconds
## <span id="templates"></span>Templates
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"
## <span id="locale"></span>Localization
CppCMS uses it's own implementation of [gettext]( that allows
using different locales withing same process.
It has following parameters
- `locale.dir` -- the path to directory with dictionaries.
For example if your dictionary is stored under
then you need specify:
locale.dir = "/usr/share/locale"
- `locale.lang_list` -- the list of supported languages. Locale "en" is the "default" -- inline code without dictionary.
- `locale.lang_default` -- the default language. If not specified the first language in the list "lang\_list" is the default one.
- `locale.domain_list` -- the list of supported domains.
- `locale.domain_default` -- the default domain. If not specified, the first in `domain_list` is used.
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