<!--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". |
|
|
## 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, never use this in production environment** |
|
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 "0.0.0.0". |
|
### 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. |
|
Note: you may specify either port and ip or socket, you can't specify both. |
|
### 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. |
|
### 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. |
|
## 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. |
|
|
## 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.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 |
|
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`. |
|
|
## 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. |
|
### cache.limit |
|
The number of cached items used by `thread_shared` cache backend. |
|
### 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.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. |
|
Note: all logs are done using `LOG_USER` facility. |
|
|
## localization |
|
These are options for localizing CppCMS based software. |
|
### localization.encoding |
|
Define the default encoding, if not specified, use system default encoding. |
|
### localization.locales |
|
The list of locales that should be supported - list of strings. If not specified use 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. |
|
### 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. |
|
Thus, 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 |
|
**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 |
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. |
