<!--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. |
|
|
## 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" ] |
|
|
## 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 |
### 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 |
### 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`. |
|
|
