Main  /  Edit  /  History  /   /  Users Area

CppCMS 1.x.x Configuration


CppCMS configuration file is a simple text file that holds all data in JSON format.

It is actually a single JSON object that holds all CppCMS configuration, usually it is passed to application using switch -c file_name.js

The syntax of the JSON format is slightly extended to support C++ like comments // and allows extra comma separator before ] or } for simplicity.

For example:

    "service" : {
        "api" : "http",
        "port" : 8080,
        // "port" : 8000,
    "http" : {
        "script_names" : [ "/hello" ]

We will describe each option by its full path from the root, for example service.api in the above case is "http".

Application data

Configuration data for the CppCMS application can also sit in this file. CppCMS does not use any of the following prefixes:

So any application data that resides in any of those path is CppCMS conflict free. For example:

   "application" : {
      // user specific data
      "connection_string" : "sqlite3:db=test.db",
      "allow_login" : true
   "service" : { 



This options specifies the API the CppCMS application communicates with client or web server.


This option defines the IPv4/IPv6 IP the application should listen on. By default it listens on "".


This option defines the port the application should listen on, default is 8080.


This option defines the Unix domain socket that the application should listen on.

  1. You may specify either port and ip or socket, you can't specify both.
  2. When the application is started by web server you need to specify special value "stdin" that tells you to use standard input file handler as socket.


You may specify a list of listeners that use different kinds of APIs or listen on different ports. These are objects similar to service object but receives only api, ip, port and socket options.

You can specify either service.list or service.api but not both!

For example:

  "service" : {
     "list" : [
       { "api" : "http" , "port" : 8080 },
       { "api" : "http" , "port" : 8000 }


The number of worker threads per process. Default is 5 * number of CPUs. For example quad core it would be 20 threads.


The number of forked worker processes. This option is relevant only for POSIX platforms.



The second parameter to listen() system call, by default it is twice of size of service.worker_threads.

It is good idea to set it to high values if you experience problems in connecting to server.


Size of socket output buffer defined by setsockopt SO_SNDBUF


Size of socket input buffer defined by setsockopt SO_RCVBUF


User application objects are generally cached in special pool for future faster reuse, this parameter defines maximal number of applications that can be cached there.

By default it is twice of size of service.worker_threads.


By default CppCMS application installs signal handlers for SIGINT, SIGTERM and SIGUSR1 that cause the application to shutdown properly. Note: under Windows it uses SetConsoleCtrlHandler for this purpose.

You may disable this in case of your own exit handling by setting this parameter to true.


By default CppCMS sends X-Powered-By: CppCMS/X.Y.Z handler in response, this can be disabled by setting this parameter to true.

Note: please don't turn this option on, let the world know that you use CppCMS.


Specifies the asynchronous event handling API that should be used.

If the API that was chosen is not supported by your platform the default would be in use.


The default size of the output buffer that is used for caching output stream. Default 16,384.


Default: false

Send the HTTP headers in response rather then CGI ones.

Useful for broken SCGI connectors like isapi_scgi


These settings have various aspects on the security of the application.


The maximal size of POST data in KB. Default is 1024KB (1MB)


The maximal size of multipart/form_data POST in KB (i.e. maximal allowed upload size). Default is 64MB.


When files are uploaded for efficiency, small files are generally stored in memory and big ones are saved in files.

This is the limit on the file size to be stored in memory in bytes. Default is 128 KB.


The location of temporary upload files. By default they are saved in the temporary directory defined by TEMP or TMP environment variable, or if they undefined it would use /tmp as a path for temporary files.

You may specify other path.

Note: when you use safe_to member function of cppcms::http::file it first tries to move file to new location rather then copy. So if you plan to upload huge files it is good idea to put uploads_path and the final path where use files are stored on same file system and mount point.


When the exception is thrown by user application and this parameter set to true its message what() would be displayed in 500 Internal Server error page, it is useful for debugging. However it should never be used in production environment.

The default value is false


This section describes options related to CSRF prevention tools

It is implemented in CppCMS starting from 0.99.10


Default: false;

Enable CSRF prevention tools. This means:

  1. Every session newly created session would include a special session specific token.
  2. Upon POST request and basic_widget::load call this token is validated against POST information.

    The tokens should be provided using <% csrf %> template command.

If the token is not valid the exception would be thrown.

It is strongly recommended to set this option to true


Default: true

Automatically check the CSRF token upon form widgets loading. If it is set to false user should validate tokens manually.

Expose the CSRF token in cookie for client side JavaScript applications.

Generally the token value would be set as cookie cppcms_token__crf see.


Options for support Unix daemons - or services.

Note these options are not supported on Windows and Cygwin


Create daemon process - fork off and become session leader. Default: false


File name for lock file for this daemon. This file contains the process ID of the daemon that allows you to kill it.

It is recommended to use this option.


The unprivileged user that this daemon should run under. It is recommended to use this option if the service is started with root privileges.

The unprivileged group that this daemon should run under. It is recommended to use this option if the service is started with root privileges.


Chroot to specific directory - extra security option that limits an access to specific tree. See chroot on Wikipedia.


Set maximal number of open file descriptors, it is useful for applications that handle many simulations connections.

Default: not changed


Options for support Windows services.

Implemented starting from CppCMS 0.99.10.

Note these options are supported only on native Windows builds (not Cygwin)

For detailed descriptions of meaning of different parameters see the CreateService function description:


This option is settable only via command line parameters.

Never put it into configuration file, variants are:

It is used in this way:

Install the service:

myapp.exe -c c:/app/config.js --winservice-mode=install

Uninstall the service:

myapp.exe -c c:/app/config.js --winservice-mode=uninstall

The service will run by the service manager as

myapp.exe -c c:/app/config.js --winservice-mode=run

If mode is not specified it would run as ordinary console application.

The name of the service - the service identification

Same as lpServiceName

Mandatory when winservice.mode is install or uninstall


The name of the service how it is shown in user interface.

Mandatory for winservice.mode = install

Same as lpDisplayName


Options are auto and demand - start the service with the system boot or on demand.

Same as dwStartType

Default is auto


The user the service will run under, optional.

Same as lpServiceStartName


The password for user the service will run under, optional.

Same as lpPassword


HTTP backend specific settings


The name of script that the application runs on. Actually it is what the SCRIPT_NAME CGI variable should be.

If you using HTTP backend you need to specify one.

The script name is matched against requested URL and if it matches its beginning it is used for dispatch application.

For example:

  "http" : { "script" : "/my_cool_app" }


Same as http.script but receives as parameter a list of scripts so if you want to specify several.

  "http" : { 
    "script_names" : [ "/foo", "/bar" ] 


Default 30.

The number of seconds to keep the idle connection alive, i.e. the connection that is blocking on read or on write other the connection that is waiting for client side disconnect using cppcms::http::context::async_on_peer_reset()

Implemented in CppCMS 0.99.10


The array of URL rewriting rules that are applied on the incoming url (the part between request method and HTTP protocol)

Each entry is an object with following properties:

For example, following rules allow to run "message board" example in the root of the web server:

"rewrite" : [
  { "regex" : "/media(/.*)?", "pattern" : "$0" },
  { "regex" : "/favion\\.ico", "pattern" : "$0" },
  { "regex" : ".*" , "pattern" : "/mb$0" }

Implemented in CppCMS 0.99.11


This settings are used to change behavior of setting CGI variables REMOTE_ADDR and REMOTE_HOST to the correct values provided by special headers.


Set it to true to change the CGI variables to values given by proxy.


List of headers that should be treated like remote host IPs. The default header is X-Forwarded-For. For example:

remote_addr_headers : [ "X-Real-IP" ]



Special setting for concurrency ability of FastCGI server that may be queried by some web servers. Default is the total number of threads application uses (in all started processes).


This are settings of simple internal file server that can be used for debug purposes.

Don't use it in production as you don't use service.api = "http" in production.


By default it is disabled. You should enable it explicitly by setting this value to true


The document root for the file server. Default is current working directory - i.e. ".".

Note, files outside this directory would not be served even if symbolic links inside this directory point to other location outside document_root


Specify location of the definition of Apache like mime.types file in format:

content/type ext1 [ext2 ...] 

Where comment is line starting with #. For example:

# Comment

application/postscript ps ai eps espi epsf eps2 eps3
application/pdf pdf


Allow compression of uploaded text files like html files.

By default disabled. To enable set it to true.


The name of the file that is displayed upon directory read. Default is index.html.

Implemented in CppCMS 0.99.10


Default false

Setting it to true allows to list files in directories unless index file is provided.

Implemented in CppCMS 0.99.10


The array of objects with two string properties url and path that defines alias to other directories outside document_root

For example:

"file_server" : {
  "enable": true,
  "document_root" : "/var/www",
  "alias" : [
    { "url" : "/icons" , "path" : "/usr/share/icons" },
    { "url" : "/app/uploads", "path": "/var/app/data" }

Such that accessing /icons/image.png would read the file /usr/share/icons/image.png and getting /apps/uploads/file.txt" would access/var/app/data/file.txt`.

Implemented in CppCMS 0.99.10


The settings of caching system


The backend that is used by cache, default is none. There are two options:


The amount of memory used by process_shared cache in KB. Default is 16MB. Note: the maximal size of item stored in cache is 5% of the cache size.


The number of cached items used by thread_shared cache backend, default 64.


The definitions of distributed cache backend. Note, if both cache.tcp defined and cache.backend is defined then the cache.backend would be used as L1 cache allowing to reduce round trip to cache servers for most used items.

So if the item that is present on cache server is same that is stored on local cache the item would not be transferred over network.


The list of strings that represent IPv4 or IPv6 IPs of the cache servers. For example:

"ips" : [ "" , "" ]

Note: the cache nodes should be specified in same order for all cache clients as their order is important - its index is result of hashing the key.

See also cache.tcp.ports


The list of numbers that represent ports that cache servers listen on, for example

"ports" : [ 5300, 5300 ]

Note, the number of ports should match the number of ips.


This settings control the gzip compression of the output data when client sends Accept-Encoding that supports gzip.

It is strongly recommended to use them especially with caching. So it is turned on by default.


Enable gzip compression. Default true


The size of buffer used. Default is zlib's default value.


The compression level, default is zlib's default value.

Note this has very high effect on performance.

If you have high cache hit ratio, it is good to use default value that gives good compression in reasonable time.

However reducing compression level to 1 can significantly increase compression speed by increasing the size by about 10%. So in many cases when the cache hit ratio is not high it is good idea to use fastest possible compression.


This defines various logging settings. The logging is done via booster::log library.


The minimal level of messages that should be logged. Default is error available levels according to their severity are:


Log messages to standard error. It is set to true if no other methods are defined.


Logging to special log file

The name of log file. Must be set in order to enable logging to file.


Set it to true in order to always append to existing file and not overwrite. Default is false.


Enables files rotation. Each time the log file is opened the older file is renamed to file_name.1 and this file renamed to file_name.2. This value specifies the maximal number of files that are saved.


The timezone that is used to specify the time in the log.

Default is empty - local time. Time zone can be specified in a format "GMT+XX:YY" for example "GMT+2" or "GMT-3:30". Also "GMT" is valid well.

Supported starting from CppCMS 0.99.11


Enable syslog logging. Relevant only for POSIX platforms.


Enable syslog - default is false.

Specify syslog id string. Default is none. See man openlog,


The list of strings defining logging options. The options are LOG_CONS, LOG_NDELAY, LOG_NOWAIT, LOG_ODELAY, LOG_PERROR and LOG_PID. See man openlog for mode details, default is none, 0 passed as option parameter to openlog.

Note: all logs are done using LOG_USER facility.


These are options for localizing CppCMS based software.


Define the default localization backend, if not specified, Booster.Locale default backend is used usually icu.

Possible values:


The list of locales that should be loaded by default - list of strings. If not specified uses system locale. The first one is the default one.

For example:

"locales" : [ "en_US.UTF-8", "he_IL.UTF-8", "ru_RU.UTF-8" ]

The en_US.UTF-8 is the default locale.

Note: you must always specify encoding.


This specifies the location of gettext catalogs.


The list of paths to the location of gettext catalogs, for example:

"paths" : [ "/usr/share/locale" , "/usr/local/share/locale" ]

The list of message domains that should be loaded, the first one is default one. For example:

"domains" : [ "mywebapp" ]


By default, the encoding is added to Content-Type http header, this can be disabled by setting this option to false.


This section describes the options for dynamic loading of views from shared objects or DLLs.


The list of paths where the shared object should be searched, for example:

"paths" : [ "/usr/lib/myapp", "/usr/local/lib/myapp" ]


The list of skins that should be loaded. Each skin refers to platform independent version of dynamically loaded library.

See views.shared_object_pattern for naming convention.

Note: under ELF platforms like Linux you need to specify -rdynamic flag to linker when building main application in order to make sure that loaded libraries can resolve symbols correctly.


This option allows to reload shared libraries/DLLs automatically when they updated without restarting an application.

By default it is set to false as it has quite serious performance impacts, don't use it in production environment.

How does this work?

When you run your application you load views as shared libraries and when you update the template and recompile the view, next time you access page this library would be reloaded and updated template would be rendered.

Note: under Microsoft Windows the DLL is copied to temporary file in order to prevent locking of DLL, otherwise you would not be able to compile it. This not an issue under POSIX platforms where shared library in use can be unlinked.


The default skin that is rendered. If only one skin exists, then is used by default, otherwise this option should be specified or each rendering would require explicit definition of skin.


The pattern that is used to format the view name from the skin.

By default, skin "foo" refers to:

If you want to change this pattern you can set this value to "prefix{1}suffix", for example:


Then the foo skin would be searched in libfoo.dll

This option is supported starting from CppCMS 0.99.11


This section describes all options needed for session management.


This defines the location of session data storage, the default is "none" - no sessions are supported, the options are:

  1. "client" - the session data is stored on client side using signed or encrypted cookies.
  2. "server" - the session data is stored on server side while cookie holds session id.
  3. "both" - the session data is stored on client side if possible (if the data is small enough) otherwise it stored on server side.

Note: Not all session storage are equivalent. When the data is stored on client side there is no true option to invalidate user session as user can always restore the old cookie, the session may be truly invalidated only by timeout.

So if you implement a game "Who Wants to Be a Millionaire?" or Captcha protection, it is good idea to store the data on server side.

When using "both" storage you may explicitly request to store data on server side in special cases when true invalidation is needed.


The default expiration time on newly created session in seconds, the default is 24 hours.


Session expiration mode, default is "browser", available modes are:


The maximal size of data in bytes that can be stored on client side.

Note, don't set it to 4k as it is not equivalent to cookie size. When converting data to cookie it would be generally base64 encoded and some meta data would be added. Also more cookies may be held on this host.

Set it with care, default is 2048.


CppCMS session management is entirely cookies based, it does not use URL, POST data or any other method to hold the state, only cookies. So cookies should be allowed on client side to support session management by CppCMS.


Specify session cookie domain, default unset.


Specify session cookie path, default is "/" so it is visible for entire domain.


Specify the prefix for cookies used for session, default is "cppcms_session". It is good idea to change it if you run more then one CppCMS application on same host.

Specify secure option for cookies, by default false - the meaning is that this cookie would be sent only over HTTPS protocol.


Options: "both", "max-age" , "expires"

Default: "both"

If "max-age" selected only Max-Age=seconds property of the session cookies would define their expiration period. If "expires" given, the Expires=date-time option is given, it is calculated from the current time + the age of cookie.

If "both" - which is default - both Max-Age and Expires properties are given. Note: all browsers that support Max-Age would ignore Expires if Max-Age is given, and IE ignores Max-Age in general.


Default: 0

If the expiration method is "both" or "expires" the cookie expiration date and time should be calculated. However due to clock skew or invalid time zone settings on the client side the valid date may occur in past or occur very soon such that cookies may be effectively removed to early or not being set at all.

Setting this value to non-zero would add an additional life time to cookie (but not to session!) such that even if the time zone settings are not correct or there is a clock skew exits the cookie would live for time_shift seconds more than actual session.


Describes the client side sessions storage

You can use two methods:

The first method is recommended

Either one of these methods must be set when session.location is "client" or "both".


The hash-based message authentication code algorithm for validation of the data stored in cookies.

Options are: md5, sha1, sha192, sha256, sha384, sha512

SHA family is recommended.

Note: CppCMS should be compiled with libgcrpyt or OpenSSL to use sha2 hmac (shaXXX family).


The secret hexadecimal key for the above authentication algorithm


The path to the file that contains secret hexadecimal key for the above authentication algorithm


The encryption algorithm for the cookies. It should be used when confidential information should be stored at client side (that client should not know about its content)

Options: aes, aes128, aes192, aes256

Note: CppCMS should be compiled with libgcrypt or OpenSSL to use this encryption.


The secret hexadecimal key for the above encryption algorithm


The path to the file that contains secret hexadecimal key for the above encryption algorithm


Signature options - prevent the session content from being changed, but does not encrypt it:

Encryption option - prevent both content changes and hides the information stored in the session:


The mandatory parameters for client side storage - it should be hexadecimal character unique token used for signature or encryption.


Same as above but the key stored in file in hexadecimal representation.


Describes server side storage

Defines type of storage used. Should be defined if session.location is "server" or "both". The options are:


The directory where session files are stored, By default is it "/cppcms_sessions" under system temporary directory defined by environment variables "TEMP", "TMP" or POSIX "/tmp".

Note: the file system where this directory is located has strong impact on server side performance. "ext3" is known to be very fast for this purpose when systems like "XFS" is known to be very slow.

You should peek the system where files creation is very fast.

Note for Windows users: Make sure you don't run anti-virus on this directory unless you want to have extremely slow performance.


This option is provided for POSIX operating systems only, under Windows file locking is always used.

By default CppCMS does not use file locking for synchronizing access to files data, it prefers to use mutex, however if you want to share the data with several independent processes or to sore the data over NFS, you need to turn this option ON.

Note: NFS should recent enough to support file locking for safe access.


The list of ip addresses of the cppcms_scale servers

Note: this list should be identical for all servers using it.


The list of ports addresses of the cppcms_scale servers in the same order as ips are given and have the same size.

Note: this list should be identical for all servers using it.


The path to the shared object or DLL that would be used for session handling.

For example:


This shared object or DLL should include following function

extern "C" {
  cppcms::sessions::session_storage_factory *sessions_generator(cppcms::json::value const &options)

That creates a session storage object using configuration options defined in session.server.settings as parameter.


Same as above but allows to specify platform independent name like "cppdb_storage" that is automatically converted to for example "" or to "cppdb_storage.dll" depending on the platform.


Allows to use non-standard shared object/dll entry point.

The default entry point is "sessions_generator", it allows to use different one, however the signature should be yet the same.


The parameter passed to the sessions_generator() function that can be used to configure the module.


Defines the frequency of "garbage collection" for collecting data of sessions that had timeout in seconds. By default it is disabled.

It is good idea to have this turned on when using server side storage. However the frequency depends on your application needs and it is performance/space trade-off.


CppCMS provides some basic facilities for automatic forwarding connections to other hosts in network, this may be used when several nodes in cluster want to ensure that specific request come to a single node only.

All connections are forwarded as SCGI requests, so application that expects forwarder request should listen on SCGI protocol as well.


Is a list of forwarding rules each one of them consists of objects with following properties:

If request matches the required regular expressions it is forwarder to other host.

For example:

"forwarding" : {
 "rules" : [
      "ip" : "",
      "port" : 5483,
      "script_name" : "/shared/app",
      "path_info" : "/request/(\\d+)"


New in 1.2


Array of strings - paths to search the plugins, if not defined uses system path.


Array of strings list of modules to be loaded - translates to shared object names for example "foo" translates to "" on Linux


Use non standard pattern for shared objects for example "mod_{1}.so" will translate module "foo" to ""


Various non-categorized options.


Default false.

By default url_mapper creates an invalid url:


The behavior can be changed to throwing an exception by setting the value of this variable to true

Implemented in CppCMS 0.99.12

CppCMS Template System | Top | Event Loop


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