Main  /  Edit version 56  /  Edit version 57  /   /  Users Area

Difference "CppCMS 1.x.x Configuration" ver. 56 versus ver. 57

Content:

<!--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.
_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.
- "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.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 1024KM (1MB)
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](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.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

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