Main  /  Edit  /  History  /   /  Users Area

CppCMS 1.x.x Configuration

General

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" : { 
      ...
   },
   ...
}

service

service.api

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

service.ip

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

service.port

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

service.socket

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.

service.list

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 }
     ]
  }
}

service.worker_threads

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

service.worker_processes

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

Values:

service.backlog

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.

service.sndbuf

Size of socket output buffer defined by setsockopt SO_SNDBUF

service.rcvbuf

Size of socket input buffer defined by setsockopt SO_RCVBUF

service.applications_pool_size

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.

service.disable_global_exit_handling

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.

service.disable_xpowered_by

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.

service.reactor

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.

service.output_buffer_size

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

service.generate_http_headers

Default: false

Send the HTTP headers in response rather then CGI ones.

Useful for broken SCGI connectors like isapi_scgi

security

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

security.content_length_limit

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

security.multipart_form_data_limit

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

security.file_in_memory_limit

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.

security.uploads_path

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.

security.display_error_message

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

security.csrf

This section describes options related to CSRF prevention tools

It is implemented in CppCMS starting from 0.99.10

security.csrf.enable

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

security.csrf.automatic

Default: true

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

security.csrf.exposed

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

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

daemon

Options for support Unix daemons - or services.

Note these options are not supported on Windows and Cygwin

daemon.enable

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

daemon.lock

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.

daemon.user

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

daemon.group

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

daemon.chroot

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

daemon.fdlimit

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

Default: not changed

winservice

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:

http://msdn.microsoft.com/en-us/library/ms682450(v=vs.85).aspx

winservice.mode

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.

winservice.name

The name of the service - the service identification

Same as lpServiceName

Mandatory when winservice.mode is install or uninstall

winservice.display_name

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

Mandatory for winservice.mode = install

Same as lpDisplayName

winservice.start

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

Same as dwStartType

Default is auto

winservice.username

The user the service will run under, optional.

Same as lpServiceStartName

winservice.password

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

Same as lpPassword

http

HTTP backend specific settings

http.script

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" }
}

http.script_names

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

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

http.timeout

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

http.rewrite

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

http.proxy

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

http.proxy.behind

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

http.proxy.remote_addr_headers

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" ]

fastcgi

fastcgi.concurrency_hint

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).

file_server

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.

file_server.enable

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

file_server.document_root

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

file_server.mime_types

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

file_server.allow_deflate

Allow compression of uploaded text files like html files.

By default disabled. To enable set it to true.

file_server.index

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

Implemented in CppCMS 0.99.10

file_server.listing

Default false

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

Implemented in CppCMS 0.99.10

file_server.alias

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

cache

The settings of caching system

cache.backend

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

cache.memory

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.

cache.limit

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

cache.tcp

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.

cache.tcp.ips

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

"ips" : [ "192.168.1.15" , "192.168.1.16" ]

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

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.

gzip

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.

gzip.enable

Enable gzip compression. Default true

gzip.buffer

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

gzip.level

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.

logging

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

logging.level

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

logging.stderr

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

logging.file

Logging to special log file

logging.file.name

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

logging.file.append

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

logging.file.max_files

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.

logging.file.timezone

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

logging.syslog

Enable syslog logging. Relevant only for POSIX platforms.

logging.syslog.enable

Enable syslog - default is false.

logging.syslog.id

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

logging.syslog.options

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.

localization

These are options for localizing CppCMS based software.

localization.backend

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

Possible values:

localization.locales

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.

localization.messages

This specifies the location of gettext catalogs.

localization.messages.paths

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

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

localization.messages.domains

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

"domains" : [ "mywebapp" ]

localization.disable_charset_in_content_type

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

views

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

views.paths

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

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

views.skins

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.

views.auto_reload

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.

views.default_skin

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.

views.shared_object_pattern

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:

lib{1}.dll

Then the foo skin would be searched in libfoo.dll

This option is supported starting from CppCMS 0.99.11

session

This section describes all options needed for session management.

session.location

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.

session.timeout

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

session.expire

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

session.client_size_limit

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.

session.cookies

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.

session.cookies.domain

Specify session cookie domain, default unset.

session.cookies.path

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

session.cookies.prefix

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.

session.cookies.secure

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

session.cookies.expiration_method

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.

session.cookies.time_shift

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.

session.client

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".

session.client.hmac

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).

session.client.hmac_key

The secret hexadecimal key for the above authentication algorithm

session.client.hmac_key_file

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

session.client.cbc

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.

session.client.cbc_key

The secret hexadecimal key for the above encryption algorithm

session.client.cbc_key_file

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

session.client.encryptor

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:

session.client.key

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

session.client.key_file

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

session.server

Describes server side storage

session.server.storage

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

session.server.dir

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.

session.server.shared

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.

session.server.ips

The list of ip addresses of the cppcms_scale servers

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

session.server.ports

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.

session.server.shared_object

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

For example:

/opt/modules/libcppdb_storage.so

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.

session.server.module

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

session.server.entry_point

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.

session.server.settings

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

session.gc

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.

forwarding

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.

forwarding.rules

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" : "192.168.1.113",
      "port" : 5483,
      "script_name" : "/shared/app",
      "path_info" : "/request/(\\d+)"
    }
  ]
}

plugin

New in 1.2

plugin.paths

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

plugin.modules

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

plugin.shared_object_pattern

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

misc

Various non-categorized options.

misk.invalid_url_throws

Default false.

By default url_mapper creates an invalid url:

/this_is_an_invalid_url_generated_by_url_mapper

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 →

About

CppCMS is a web development framework for performance demanding applications.

Support This Project

SourceForge.net Logo

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

CppCMS needs You

Navigation

Main Page

Valid CSS | Valid XHTML 1.0