<!--toc--> |
|
## General |
|
CppCMS configuration file is a simple text file |
that holds all data in [JSON](http://json.org/) 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" ] |
} |
} |
|
|
Each option we would describe by its full path from the root, for example `service.api` is the above case is "http". |
|
## Application data |
|
Configuration data for the CppCMS application can also sit in this file. |
The CppCMS will not use any of the following prefixes: |
|
- `app` |
- `data` |
- `conf` |
- Any Capital letter (.i.e. MyApp) |
- Underscore "_" |
|
So any application data that resides in any of those 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. |
|
- `fastcgi` - use FastCGI protocol |
- `scgi` - use SCGI protocol |
- `http` - use HTTP protocol. Use this only for |
debugging or in embedded environments. |
|
Note, you need also provide [`http.script_names`](#http.script_names) or [`http.script`](#http.script) options, optionally [`file_server`](#file_server) definitions |
|
### 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 is listens |
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`](#service) object but |
receives only [`api`](#service.api), [`ip`](#service.ip), [`port`](#service.port) and [`socket`](#service.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: |
|
- 0 means no fork is executed, default |
- 1 means that one child process is forked and the parent supervises and and would restart if in case of crash. |
- \>1 several processes are forked and try to accept incoming connections. |
|
### service.backlog |
|
The second parameter to `listen()` system call, by default it is twice of size of [`service.worker_threads`](#service.worker_threads). |
|
It is good idea to set it to high values if you experience problems in connecting to server. |
|
### 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.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. |
|
### service.reactor |
|
Specifies the asynchronous event handling API that |
should be used. |
|
- "epoll" - default on Linux |
- "devpoll" - `/dev/poll` reactor, default on Solaris |
- "kqueue" - default on Mac OS X and FreeBSD |
- "select" - default on Windows and Cygwin |
- "poll" - default on other POSIX platforms. |
|
If the API that was chosen is not supported by your |
platform the default would be in use. |
|
### 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 1024KM (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](http://en.wikipedia.org/wiki/Chroot) on Wikipeida. |
|
### 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: |
|
- "console" - default |
- "install" - install service to run with its current parameters |
- "uninstall" - uninstall the service |
- "run" - run the service - should be specified when the application runs as WinNT service. |
|
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`](#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: |
|
- `regex` - string the regular expression pattern to match |
- `pattern` - string the pattern to substitute. The `$0` to `$9` markers are replaced with captured subexpressions. `$$` can be used to write a `$` symbol. |
- `final` - boolean - default true. Says if to stop substitution of the pattern matches. If it is set to `false` the rewriting will continue with next patterns. |
|
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.cuncurrency\_hint |
### 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`](#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: |
|
- `thread_shared` - the backed that can be shared between |
multiple threads only. |
|
Suitable when [`service.worker_processes`](#service.worker_processes) <= 1. It's size is controlled by [`cache.limit`](#cache.limit) parameter. |
- `process_shared` - the backend that is suitable in case of both single and multiple process modes. It's size is controlled by [`cache.memory`](#cache.memory) parameter. |
|
Note: not available on Windows. |
|
|
### 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 transfered 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) |
|
#### 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`](#cache.tcp.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 sevirity are: |
|
- emergency |
- alert |
- critical |
- error |
- warning |
- notice |
- info |
- debug |
|
### 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: |
|
- `icu` - ICU based localization - most powerful one |
- `std` - C++ standard library based |
- `posix` - POSIX 2008 API based (like strftime\_l, newlocale) (Linux and Mac OS X only) |
- `winapi` - Windows API based (Windows/Cygwin only) |
|
|
### 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](#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: |
|
- "libfoo.so" on Linux, BSD or Solaris, |
- "libfoo.dylib" on Mac OS X |
- "foo.dll" or MSVC/Windows |
- "libfoo.dll" under MinGW |
- "cygfoo.dll" under Cygwin |
|
If you want to change this pattern you can set this value |
to "prefix{1}suffux", 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 storages 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: |
|
|
- "fixed" - the session would expire in [`timeout`](#session.timeout) seconds from the moment it was created. |
- "renew" - the session would expire in [`timeout`](#session.timeout) seconds from the last visit of user. Note, the time-stamp is not updated every visit for performance reasons, only if the more then 10% of the maximal amount of time had passed since. |
- "browser" - keep the session as long as browser is opened. |
|
Note: timeout is managed in same way as in "renew" policy, so it may expire even if the browser still try to hold the session. |
|
### 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.client |
|
Describes the client side sessions storage |
|
You can use two methods: |
|
- Specifying `session.client.hmac` with |
`session.client.hmac_key` or |
`session.client.hmac_key_file` |
for MAC signature |
|
And optionally `session.client.cbc` with |
`session.client.cbc_key` |
or `session.client.cbc_key_file` |
for additional encryption if required. |
|
- Specifying `session.client.encryptor` |
with |
`session.client.key` or |
`session.client.key_file` |
|
In case of AES encryption the keys for signature |
and encryption would be generated from a single key. |
|
|
The first method is recommended |
|
Either one of these methods must be set when [`session.location`](#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: |
|
- `hmac`, `hmac-sha1` - use SHA1-HMAC, 160 bit signature |
- `hmac-md5` - use MD5-HMAC, considered less sequre |
- `hmac-shaXXX` - use SHA2-HMAC where XXX is 224, 256, 384 or 512 is the digest and signature length in bits. |
|
Note: CppCMS should be compiled with libgcrpyt or OpenSSL to use sha2 signature. |
|
Encryption option - prevent both content changes and hides the information stored in the session: |
|
- `aes`, `aes128` - use AES128 encryption |
- `aes192` - use AES192 encryption |
- `aes256` - use AES256 encryption |
|
Note: CppCMS should be compiled with libgcrypt or OpenSSL to use this encryption. |
|
#### session.client.key |
|
The mandatory parameters for client side storage - it should be hexadecimal character unique token used for signature or encryption. |
|
- `aes128`, `aes192` and `aes256` requires at least 32, 48 and 64 hexadecimal digits key length accordingly. The key is used for generation of the hey for both hmac and aes. |
- `hmac` family requires at least 32 hexadecimal digits key length |
|
#### 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`](#session.location) is "server" or "both". The options are: |
|
- "files" - use file system to save session information. |
|
Please read also documentation of [`session.server.dir`](#session.server.dir) and [`session.server.shared`](#session.server.shared). |
- "memory" - use process memory to save session information. |
|
Notes: |
|
- It is useful for debugging, not in production as all information is lost when process goes down. |
- It can be used only when [`service.worker_processes`](#service.worker_processes) <= 1 |
|
- "network" - use `cppcms_scale` to handle session information. |
|
Please read also documentation of [`session.server.ips`](#session.server.ips) and [`session.server.ports`](#session.server.ports). |
|
- "external" - Use your own session storage module loaded from shared object or DLL. |
|
See: [`session.server.shared_object`](#session.server.shared_object) and [`session.server.settings`](#session.server.settings) for details. |
|
#### 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: |
|
- ip - the target host ip, mandatory |
- port - the target host port, madatory |
- host - the perl-compatible regular expression that matches `HTTP_HOST` CGI variable |
- script\_name - the perl-compatible regular expression that matches `SCRIPT_NAME` CGI variable |
- path\_info - the perl-compatible regular expression that matches `PATH_INFO` CGI variable |
|
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+)" |
} |
] |
} |
|
|
## 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 |
