ENG 10 Configuration File - an-tao/drogon Wiki

Original URL: https://github.com/an-tao/drogon/wiki/ENG-10-Configuration-File

You can control various behaviors of the Http server by configuring various parameters through multiple interfaces of the DrogonAppFramework instance. However, using a configuration file is a better way for the following reasons:

Based on these additional benefits, it is recommended that application developers use configuration files to configure various parameters of the application.

The configuration file can be loaded very simply by calling the loadConfigFile() interface before calling the run() interface. The parameter of the loadConfigFile() method is the file name of the configuration file, for example:

int main()

The above program loads the configuration file config.json and then runs the application. The specific listening port, log output, database configuration and so on can be configured by the configuration file. In fact, this program can basically be the entire code of the main file of the web application.

Configuration File Details

An example of a configuration file is at the top level of the source directory, config.example.json. If you use the drogon_ctl create project command to create a project, you can also find the file config.json with the same content in the project directory. So, you basically don't need to create a new configuration file but make some changes to this file to complete the configuration of the web application.

The file is in JSON format and supports comments. You can comment out the unneeded configuration items with the c++ comment symbols /**/ and //.

After commenting out a configuration option, the framework initializes it with default values. The default value for each option can be found in the comments in the configuration file.


The ssl option is to configure SSL files of the https service as follows:

  "ssl": {
    "cert": "../../trantor/trantor/tests/server.pem",
    "key": "../../trantor/trantor/tests/server.pem",
      ["Options", "Compression"],
      ["min_protocol", "TLSv1.2"]

Where cert is the path of the certificate file and key is the path of the private key file. If a file contains both a certificate and a private key, the two paths can be made the same. The file is in PEM encoding format.

conf are optional SSL options that are directly passed into SSL_CONF_cmd to allow low level configuration of the encryption. The options must be one or two element arrays.


As the name implies, the listeners option is to configure listeners for the web application. It is a JSON array type. Each JSON object represents a listener. The specific configuration is as follows:

"listeners": [
      "address": "",
      "port": 80,
      "https": false
      "address": "",
      "port": 443,
      "https": true,
      "cert": "",
      "key": ""

Among them:


This option is used to configure the database client. It is a JSON array type. Each JSON object represents a separate database client. The specific configuration is as follows:

      "rdbms": "postgresql",
      "host": "",
      "port": 5432,
      "dbname": "test",
      "user": "",
      "passwd": "",
      "is_fast": false,
      "connection_number": 1,
      "file_name": ""

Among them:


Suboption belonging to the app option, an integer, the default value is 1, indicating the number of IO threads, which has a clear impact on network concurrency. This number is not as big as possible. Users who understand the non-blocking I/O principle should know that this value should be the same as the number of processors that he expects network IO to occupy. If the value is set to 0, the number of IO threads will be the number of all hardware cores.

"threads_num": 16,

The above example shows that network IO uses 16 threads and can run up to 16 CPU cores under high load conditions.


Session-related options are also children of the app option, controlling whether session is used and the session timeout. Such as:

"enable_session": true,
"session_timeout": 1200,

Among them:


The suboption of the app option, a string, indicates the document path corresponding to the Http root directory, and is the root path of the static file download. The default value is "./", which indicates the current path of the program running. such as:

"document_root": "./",


The child of the app option, a string, represents the default path for uploading files. The default value is "uploads". If the value is not starting with /, ./ or ../, and this value is not .or..`, then this path is the relative path of the previous document_root entry, otherwise it is an absolute path or a relative path to the current directory. Such as:



The suboption of the app option, an array of strings, with default values ​​as follows, indicates the static file download type supported by the framework. If the requested static file extension is outside of these types, the framework will return a 404 error.

"file_types": [


The suboption of the app option, a dictionary of strings to strings or an array of strings. Declares how file extenstions are mapped to new MIME types (i.e. for those not recognized by default) when sending static files. Note that this options merely registers the MIME. The framework still sends a 404 if the extensoin is not in file_types described above.

"mime" : {
  "text/markdown": "md",
  "text/gemini": ["gmi", "gemini"]

Connection number control

The children of the app option have two options, as follows:

 "max_connections": 100000,
 "max_connections_per_ip": 0,

Among them:

Log option

The child of the app item, a JSON object, controls the behavior of the log output as follows:

 "log": {
      "log_path": "./",
      "logfile_base_name": "",
      "log_size_limit": 100000000,
      "log_level": "TRACE"

Among them:

Note: Drogon's file log uses a non-blocking output structure that can achieve a log output of millions of lines per second and can be used with confidence.

Application control

They are also children of the app option and have two options, as follows:

    "run_as_daemon": false,
    "relaunch_on_error": false,

Among them:


The suboption of app option, boolean, indicates whether the linux system call sendfile is used when sending the file. The default value is true. Using sendfile can improve the sending efficiency and reduce the memory usage of large files. as follows:

"use_sendfile": true,

Note: Even if this option is true, the sendfile system call will not be used, because the use of sendfile for small files is not necessarily cost-effective, and the framework will decide whether to adopt it according to its own optimization strategy.


The app suboption, boolean, default value is true, indicating whether the body of the Http response uses compressed transmission. When it is true, compression is used in the following cases:

The configuration example is as follows:

"use_gzip": true,


The app suboption, integer value, in seconds, indicates the cache time of the static file, that is, for the repeated request for the file during this time, the framework will return the response directly from the memory without reading the file system. The default value is 5 seconds, 0 means always cache (only read the file system once, use with caution), negative value means no cache. as follows:

 "static_files_cache_time": 5,


The app suboption, an array of JSON objects, each representing a mapping from the Http path to the HttpSimpleController, this configuration is just an alternative, not necessarily configured here, see HttpSimpleController. The specific configuration is as follows:

"simple_controllers_map": [
        "path": "/path/name",
        "controller": "controllerClassName",
        "http_methods": ["get","post"],
        "filters": ["FilterClassName"]

Among them:

Idle connection timeout control

The app suboption, integer value, in seconds, the default value is 60. When a connection exceeds this time without any reading and writing, the connection will be forcibly disconnected. as follows:


Dynamic view loading

The sub-options of the app, which control the enabling and the path of the dynamic view, have two options, as follows:


Among them:

See View

Server header field

The sub-option of the app configures the server header field of all responses sent by the framework. The default value is an empty string. When this option is empty, the framework automatically generates a header field of the form Server: drogon/version string. It's as follows:

"server_header_field": ""

Keepalive requests

The keepalive_requests option sets the maximum number of requests that can be served through one keep-alive connection. After the maximum number of requests are made, the connection is closed. The default value of 0 means no limit. It's as follows:

"keepalive_requests": 0

Pipelining requests

The pipelining_requests sets the maximum number of unhandled requests that can be cached in pipelining buffer. After the maximum number of requests are made, the connection is closed. The default value of 0 means no limit. For details about pipelining, please see the rfc2616- It's as follows:

"pipelining_requests": 0

11 drogon_ctl Command