<!--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. |
- `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. |
