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