diff --git a/docs/source/settings.rst b/docs/source/settings.rst index 81b3c774..205c18b6 100644 --- a/docs/source/settings.rst +++ b/docs/source/settings.rst @@ -25,11 +25,11 @@ Config File .. _config: -config -~~~~~~ +``config`` +~~~~~~~~~~ -* ``-c CONFIG, --config CONFIG`` -* ``./gunicorn.conf.py`` +**Command line:** ``-c CONFIG`` or ``--config CONFIG`` +**Default:** ``'./gunicorn.conf.py'`` The Gunicorn config file. @@ -47,10 +47,10 @@ directory where gunicorn is being run. .. _wsgi-app: -wsgi_app -~~~~~~~~ +``wsgi_app`` +~~~~~~~~~~~~ -* ``None`` +**Default:** ``None`` A WSGI application path in pattern ``$(MODULE_NAME):$(VARIABLE_NAME)``. @@ -61,11 +61,11 @@ Debugging .. _reload: -reload -~~~~~~ +``reload`` +~~~~~~~~~~ -* ``--reload`` -* ``False`` +**Command line:** ``--reload`` +**Default:** ``False`` Restart workers when code changes. @@ -86,29 +86,29 @@ because it consumes less system resources. .. _reload-engine: -reload_engine -~~~~~~~~~~~~~ +``reload_engine`` +~~~~~~~~~~~~~~~~~ -* ``--reload-engine STRING`` -* ``auto`` +**Command line:** ``--reload-engine STRING`` +**Default:** ``auto`` The implementation that should be used to power :ref:`reload`. Valid engines are: -* 'auto' -* 'poll' -* 'inotify' (requires inotify) +* ``'auto'`` +* ``'poll'`` +* ``'inotify'`` (requires inotify) .. versionadded:: 19.7 .. _reload-extra-files: -reload_extra_files -~~~~~~~~~~~~~~~~~~ +``reload_extra_files`` +~~~~~~~~~~~~~~~~~~~~~~ -* ``--reload-extra-file FILES`` -* ``[]`` +**Command line:** ``--reload-extra-file FILES`` +**Default:** ``[]`` Extends :ref:`reload` option to also watch and reload on additional files (e.g., templates, configurations, specifications, etc.). @@ -117,11 +117,11 @@ Extends :ref:`reload` option to also watch and reload on additional files .. _spew: -spew -~~~~ +``spew`` +~~~~~~~~ -* ``--spew`` -* ``False`` +**Command line:** ``--spew`` +**Default:** ``False`` Install a trace function that spews every line executed by the server. @@ -129,21 +129,22 @@ This is the nuclear option. .. _check-config: -check_config -~~~~~~~~~~~~ +``check_config`` +~~~~~~~~~~~~~~~~ -* ``--check-config`` -* ``False`` +**Command line:** ``--check-config`` +**Default:** ``False`` -Check the configuration. +Check the configuration and exit. The exit status is 0 if the configuration is +correct, and 1 if the configuration is incorrect. .. _print-config: -print_config -~~~~~~~~~~~~ +``print_config`` +~~~~~~~~~~~~~~~~ -* ``--print-config`` -* ``False`` +**Command line:** ``--print-config`` +**Default:** ``False`` Print the configuration settings as fully resolved. Implies :ref:`check-config`. @@ -152,11 +153,11 @@ Logging .. _accesslog: -accesslog -~~~~~~~~~ +``accesslog`` +~~~~~~~~~~~~~ -* ``--access-logfile FILE`` -* ``None`` +**Command line:** ``--access-logfile FILE`` +**Default:** ``None`` The Access log file to write to. @@ -164,11 +165,11 @@ The Access log file to write to. .. _disable-redirect-access-to-syslog: -disable_redirect_access_to_syslog -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``disable_redirect_access_to_syslog`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* ``--disable-redirect-access-to-syslog`` -* ``False`` +**Command line:** ``--disable-redirect-access-to-syslog`` +**Default:** ``False`` Disable redirect access logs to syslog. @@ -176,11 +177,11 @@ Disable redirect access logs to syslog. .. _access-log-format: -access_log_format -~~~~~~~~~~~~~~~~~ +``access_log_format`` +~~~~~~~~~~~~~~~~~~~~~ -* ``--access-logformat STRING`` -* ``%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"`` +**Command line:** ``--access-logformat STRING`` +**Default:** ``'%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"'`` The access log format. @@ -218,11 +219,11 @@ Use lowercase for header and environment variable names, and put .. _errorlog: -errorlog -~~~~~~~~ +``errorlog`` +~~~~~~~~~~~~ -* ``--error-logfile FILE, --log-file FILE`` -* ``-`` +**Command line:** ``--error-logfile FILE`` or ``--log-file FILE`` +**Default:** ``'-'`` The Error log file to write to. @@ -233,29 +234,29 @@ Using ``'-'`` for FILE makes gunicorn log to stderr. .. _loglevel: -loglevel -~~~~~~~~ +``loglevel`` +~~~~~~~~~~~~ -* ``--log-level LEVEL`` -* ``info`` +**Command line:** ``--log-level LEVEL`` +**Default:** ``'info'`` The granularity of Error log outputs. Valid level names are: -* debug -* info -* warning -* error -* critical +* ``'debug'`` +* ``'info'`` +* ``'warning'`` +* ``'error'`` +* ``'critical'`` .. _capture-output: -capture_output -~~~~~~~~~~~~~~ +``capture_output`` +~~~~~~~~~~~~~~~~~~ -* ``--capture-output`` -* ``False`` +**Command line:** ``--capture-output`` +**Default:** ``False`` Redirect stdout/stderr to specified file in :ref:`errorlog`. @@ -266,24 +267,24 @@ Redirect stdout/stderr to specified file in :ref:`errorlog`. logger_class ~~~~~~~~~~~~ -* ``--logger-class STRING`` -* ``gunicorn.glogging.Logger`` +**Command line:** ``--logger-class STRING`` +**Default:** ``'gunicorn.glogging.Logger'`` The logger you want to use to log events in Gunicorn. -The default class (``gunicorn.glogging.Logger``) handle most of +The default class (``gunicorn.glogging.Logger``) handles most normal usages in logging. It provides error and access logging. You can provide your own logger by giving Gunicorn a -Python path to a subclass like ``gunicorn.glogging.Logger``. +Python path to a subclass of ``gunicorn.glogging.Logger``. .. _logconfig: -logconfig -~~~~~~~~~ +``logconfig`` +~~~~~~~~~~~~~ -* ``--log-config FILE`` -* ``None`` +**Command line:** ``--log-config FILE`` +**Default:** ``None`` The log config file to use. Gunicorn uses the standard Python logging module's Configuration @@ -291,11 +292,11 @@ file format. .. _logconfig-dict: -logconfig_dict -~~~~~~~~~~~~~~ +``logconfig_dict`` +~~~~~~~~~~~~~~~~~~ -* ``--log-config-dict`` -* ``{}`` +**Command line:** ``--log-config-dict`` +**Default:** ``{}`` The log config dictionary to use, using the standard Python logging module's dictionary configuration format. This option @@ -308,11 +309,11 @@ Format: https://docs.python.org/3/library/logging.config.html#logging.config.dic .. _syslog-addr: -syslog_addr -~~~~~~~~~~~ +``syslog_addr`` +~~~~~~~~~~~~~~~ -* ``--log-syslog-to SYSLOG_ADDR`` -* ``unix:///var/run/syslog`` +**Command line:** ``--log-syslog-to SYSLOG_ADDR`` +**Default:** ``'unix:///var/run/syslog'`` Address to send syslog messages. @@ -326,11 +327,11 @@ Address is a string of the form: .. _syslog: -syslog -~~~~~~ +``syslog`` +~~~~~~~~~~ -* ``--log-syslog`` -* ``False`` +**Command line:** ``--log-syslog`` +**Default:** ``False`` Send *Gunicorn* logs to syslog. @@ -340,11 +341,11 @@ Send *Gunicorn* logs to syslog. .. _syslog-prefix: -syslog_prefix -~~~~~~~~~~~~~ +``syslog_prefix`` +~~~~~~~~~~~~~~~~~ -* ``--log-syslog-prefix SYSLOG_PREFIX`` -* ``None`` +**Command line:** ``--log-syslog-prefix SYSLOG_PREFIX`` +**Default:** ``None`` Makes Gunicorn use the parameter as program-name in the syslog entries. @@ -353,21 +354,21 @@ program name is the name of the process. .. _syslog-facility: -syslog_facility -~~~~~~~~~~~~~~~ +``syslog_facility`` +~~~~~~~~~~~~~~~~~~~ -* ``--log-syslog-facility SYSLOG_FACILITY`` -* ``user`` +**Command line:** ``--log-syslog-facility SYSLOG_FACILITY`` +**Default:** ``'user'`` Syslog facility name .. _enable-stdio-inheritance: -enable_stdio_inheritance -~~~~~~~~~~~~~~~~~~~~~~~~ +``enable_stdio_inheritance`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* ``-R, --enable-stdio-inheritance`` -* ``False`` +**Command line:** ``-R, --enable-stdio-inheritance`` +**Default:** ``False`` Enable stdio inheritance. @@ -378,11 +379,11 @@ environment variable ``PYTHONUNBUFFERED`` . .. _statsd-host: -statsd_host -~~~~~~~~~~~ +``statsd_host`` +~~~~~~~~~~~~~~~ -* ``--statsd-host STATSD_ADDR`` -* ``None`` +**Command line:** ``--statsd-host STATSD_ADDR`` +**Default:** ``None`` ``host:port`` of the statsd server to log to. @@ -390,23 +391,24 @@ statsd_host .. _dogstatsd-tags: -dogstatsd_tags -~~~~~~~~~~~~~~ +``dogstatsd_tags`` +~~~~~~~~~~~~~~~~~~ -* ``--dogstatsd-tags DOGSTATSD_TAGS`` -* ``(empty string)`` +**Command line:** ``--dogstatsd-tags DOGSTATSD_TAGS`` +**Default:** ``''`` -A comma-delimited list of datadog statsd (dogstatsd) tags to append to statsd metrics. +A comma-delimited list of datadog statsd (dogstatsd) tags to append to statsd +metrics. .. versionadded:: 20 .. _statsd-prefix: -statsd_prefix -~~~~~~~~~~~~~ +``statsd_prefix`` +~~~~~~~~~~~~~~~~~ -* ``--statsd-prefix STATSD_PREFIX`` -* ``(empty string)`` +**Command line:** ``--statsd-prefix STATSD_PREFIX`` +**Default:** ``''`` Prefix to use when emitting statsd metrics (a trailing ``.`` is added, if not provided). @@ -418,11 +420,11 @@ Process Naming .. _proc-name: -proc_name -~~~~~~~~~ +``proc_name`` +~~~~~~~~~~~~~ -* ``-n STRING, --name STRING`` -* ``None`` +**Command line:** ``-n STRING, --name STRING`` +**Default:** ``None`` A base to use with setproctitle for process naming. @@ -435,10 +437,10 @@ If not set, the *default_proc_name* setting will be used. .. _default-proc-name: -default_proc_name -~~~~~~~~~~~~~~~~~ +``default_proc_name`` +~~~~~~~~~~~~~~~~~~~~~ -* ``gunicorn`` +**Default:** ``'gunicorn'`` Internal setting that is adjusted for each type of application. @@ -447,31 +449,31 @@ SSL .. _keyfile: -keyfile -~~~~~~~ +``keyfile`` +~~~~~~~~~~~ -* ``--keyfile FILE`` -* ``None`` +**Command line:** ``--keyfile FILE`` +**Default:** ``None`` -SSL key file +Path to the SSL key file. .. _certfile: -certfile -~~~~~~~~ +``certfile`` +~~~~~~~~~~~~ -* ``--certfile FILE`` -* ``None`` +**Command line:** ``--certfile FILE`` +**Default:** ``None`` -SSL certificate file +Path to the SSL certificate file. .. _ssl-version: -ssl_version -~~~~~~~~~~~ +``ssl_version`` +~~~~~~~~~~~~~~~ -* ``--ssl-version`` -* ``_SSLMethod.PROTOCOL_TLS`` +**Command line:** ``--ssl-version`` +**Default:** ``_SSLMethod.PROTOCOL_TLS`` SSL version to use. @@ -499,51 +501,51 @@ TLS_SERVER Auto-negotiate the highest protocol version like TLS, .. _cert-reqs: -cert_reqs -~~~~~~~~~ +``cert_reqs`` +~~~~~~~~~~~~~ -* ``--cert-reqs`` -* ``VerifyMode.CERT_NONE`` +**Command line:** ``--cert-reqs`` +**Default:** ``VerifyMode.CERT_NONE`` -Whether client certificate is required (see stdlib ssl module's) +Whether client certificate is required (see stdlib ssl module's). .. _ca-certs: -ca_certs -~~~~~~~~ +``ca_certs`` +~~~~~~~~~~~~ * ``--ca-certs FILE`` * ``None`` -CA certificates file +Path to the CA certificates file. .. _suppress-ragged-eofs: -suppress_ragged_eofs -~~~~~~~~~~~~~~~~~~~~ +``suppress_ragged_eofs`` +~~~~~~~~~~~~~~~~~~~~~~~~ -* ``--suppress-ragged-eofs`` -* ``True`` +**Command line:** ``--suppress-ragged-eofs`` +**Default:** ``True`` Suppress ragged EOFs (see stdlib ssl module's) .. _do-handshake-on-connect: -do_handshake_on_connect -~~~~~~~~~~~~~~~~~~~~~~~ +``do_handshake_on_connect`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* ``--do-handshake-on-connect`` -* ``False`` +**Command line:** ``--do-handshake-on-connect`` +**Default:** ``False`` Whether to perform SSL handshake on socket connect (see stdlib ssl module's) .. _ciphers: -ciphers -~~~~~~~ +``ciphers`` +~~~~~~~~~~~ -* ``--ciphers`` -* ``None`` +**Command line:** ``--ciphers`` +**Default:** ``None`` SSL Cipher suite to use, in the format of an OpenSSL cipher list. @@ -565,11 +567,11 @@ Security .. _limit-request-line: -limit_request_line -~~~~~~~~~~~~~~~~~~ +``limit_request_line`` +~~~~~~~~~~~~~~~~~~~~~~ -* ``--limit-request-line INT`` -* ``4094`` +**Command line:** ``--limit-request-line INT`` +**Default:** ``4094`` The maximum size of HTTP request line in bytes. @@ -586,11 +588,11 @@ This parameter can be used to prevent any DDOS attack. .. _limit-request-fields: -limit_request_fields -~~~~~~~~~~~~~~~~~~~~ +``limit_request_fields`` +~~~~~~~~~~~~~~~~~~~~~~~~ -* ``--limit-request-fields INT`` -* ``100`` +**Command line:** ``--limit-request-fields INT`` +**Default:** ``100`` Limit the number of HTTP headers fields in a request. @@ -601,11 +603,11 @@ more safety. By default this value is 100 and can't be larger than .. _limit-request-field-size: -limit_request_field_size -~~~~~~~~~~~~~~~~~~~~~~~~ +``limit_request_field_size`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* ``--limit-request-field_size INT`` -* ``8190`` +**Command line:** ``--limit-request-field_size INT`` +**Default:** ``8190`` Limit the allowed size of an HTTP request header field. @@ -619,15 +621,20 @@ header field sizes. Server Hooks ------------ +Define these functions with these names in your configuration file and Gunicorn +will call them at the appropriate times during the server lifecycle. + .. _on-starting: -on_starting -~~~~~~~~~~~ +``on_starting`` +~~~~~~~~~~~~~~~ -* :: +Signature: - def on_starting(server): - pass +.. code-block:: python + + def on_starting(server): + pass Called just before the master process is initialized. @@ -635,13 +642,15 @@ The callable needs to accept a single instance variable for the Arbiter. .. _on-reload: -on_reload -~~~~~~~~~ +``on_reload`` +~~~~~~~~~~~~~ -* :: +Signature: - def on_reload(server): - pass +.. code-block:: python + + def on_reload(server): + pass Called to recycle workers during a reload via SIGHUP. @@ -649,13 +658,15 @@ The callable needs to accept a single instance variable for the Arbiter. .. _when-ready: -when_ready -~~~~~~~~~~ +``when_ready`` +~~~~~~~~~~~~~~ -* :: +Signature: - def when_ready(server): - pass +.. code-block:: python + + def when_ready(server): + pass Called just after the server is started. @@ -663,13 +674,15 @@ The callable needs to accept a single instance variable for the Arbiter. .. _pre-fork: -pre_fork -~~~~~~~~ +``pre_fork`` +~~~~~~~~~~~~ -* :: +Signature: - def pre_fork(server, worker): - pass +.. code-block:: python + + def pre_fork(server, worker): + pass Called just before a worker is forked. @@ -678,13 +691,15 @@ new Worker. .. _post-fork: -post_fork -~~~~~~~~~ +``post_fork`` +~~~~~~~~~~~~~ -* :: +Signature: - def post_fork(server, worker): - pass +.. code-block:: python + + def post_fork(server, worker): + pass Called just after a worker has been forked. @@ -693,13 +708,15 @@ new Worker. .. _post-worker-init: -post_worker_init -~~~~~~~~~~~~~~~~ +``post_worker_init`` +~~~~~~~~~~~~~~~~~~~~ -* :: +Signature: - def post_worker_init(worker): - pass +.. code-block:: python + + def post_worker_init(worker): + pass Called just after a worker has initialized the application. @@ -708,13 +725,15 @@ Worker. .. _worker-int: -worker_int -~~~~~~~~~~ +``worker_int`` +~~~~~~~~~~~~~~ -* :: +Signature: - def worker_int(worker): - pass +.. code-block:: python + + def worker_int(worker): + pass Called just after a worker exited on SIGINT or SIGQUIT. @@ -723,13 +742,15 @@ Worker. .. _worker-abort: -worker_abort -~~~~~~~~~~~~ +``worker_abort`` +~~~~~~~~~~~~~~~~ -* :: +Signature: - def worker_abort(worker): - pass +.. code-block:: python + + def worker_abort(worker): + pass Called when a worker received the SIGABRT signal. @@ -740,13 +761,15 @@ Worker. .. _pre-exec: -pre_exec -~~~~~~~~ +``pre_exec`` +~~~~~~~~~~~~ -* :: +Signature: - def pre_exec(server): - pass +.. code-block:: python + + def pre_exec(server): + pass Called just before a new master process is forked. @@ -754,13 +777,15 @@ The callable needs to accept a single instance variable for the Arbiter. .. _pre-request: -pre_request -~~~~~~~~~~~ +``pre_request`` +~~~~~~~~~~~~~~~ -* :: +Signature: - def pre_request(worker, req): - worker.log.debug("%s %s" % (req.method, req.path)) +.. code-block:: python + + def pre_request(worker, req): + worker.log.debug("%s %s" % (req.method, req.path)) Called just before a worker processes the request. @@ -769,13 +794,15 @@ the Request. .. _post-request: -post_request -~~~~~~~~~~~~ +``post_request`` +~~~~~~~~~~~~~~~~ -* :: +Signature: - def post_request(worker, req, environ, resp): - pass +.. code-block:: python + + def post_request(worker, req, environ, resp): + pass Called after a worker processes the request. @@ -784,13 +811,15 @@ the Request. .. _child-exit: -child_exit -~~~~~~~~~~ +``child_exit`` +~~~~~~~~~~~~~~ -* :: +Signature: - def child_exit(server, worker): - pass +.. code-block:: python + + def child_exit(server, worker): + pass Called just after a worker has been exited, in the master process. @@ -801,13 +830,15 @@ the just-exited Worker. .. _worker-exit: -worker_exit -~~~~~~~~~~~ +``worker_exit`` +~~~~~~~~~~~~~~~ -* :: +Signature: - def worker_exit(server, worker): - pass +.. code-block:: python + + def worker_exit(server, worker): + pass Called just after a worker has been exited, in the worker process. @@ -816,13 +847,15 @@ the just-exited Worker. .. _nworkers-changed: -nworkers_changed -~~~~~~~~~~~~~~~~ +``nworkers_changed`` +~~~~~~~~~~~~~~~~~~~~ -* :: +Signature: - def nworkers_changed(server, new_value, old_value): - pass +.. code-block:: python + + def nworkers_changed(server, new_value, old_value): + pass Called just after *num_workers* has been changed. @@ -834,13 +867,15 @@ be ``None``. .. _on-exit: -on_exit -~~~~~~~ +``on_exit`` +~~~~~~~~~~~ -* :: +Signature: - def on_exit(server): - pass +.. code-block:: python + + def on_exit(server): + pass Called just before exiting Gunicorn. @@ -851,11 +886,11 @@ Server Mechanics .. _preload-app: -preload_app -~~~~~~~~~~~ +``preload_app`` +~~~~~~~~~~~~~~~ -* ``--preload`` -* ``False`` +**Command line:** ``--preload`` +**Default:** ``False`` Load application code before the worker processes are forked. @@ -866,11 +901,11 @@ restarting workers. .. _sendfile: -sendfile -~~~~~~~~ +``sendfile`` +~~~~~~~~~~~~ -* ``--no-sendfile`` -* ``None`` +**Command line:** ``--no-sendfile`` +**Default:** ``None`` Disables the use of ``sendfile()``. @@ -886,11 +921,11 @@ to enable or disable its usage. .. _reuse-port: -reuse_port -~~~~~~~~~~ +``reuse_port`` +~~~~~~~~~~~~~~ -* ``--reuse-port`` -* ``False`` +**Command line:** ``--reuse-port`` +**Default:** ``False`` Set the ``SO_REUSEPORT`` flag on the listening socket. @@ -898,21 +933,21 @@ Set the ``SO_REUSEPORT`` flag on the listening socket. .. _chdir: -chdir -~~~~~ +``chdir`` +~~~~~~~~~ -* ``--chdir`` -* ``/usr/src/app`` +**Command line:** ``--chdir`` +**Default:** ``'/usr/src/app'`` -Chdir to specified directory before apps loading. +Change to the specified directory before loading apps. .. _daemon: -daemon -~~~~~~ +``daemon`` +~~~~~~~~~~ -* ``-D, --daemon`` -* ``False`` +**Command line:** ``-D`` or ``--daemon`` +**Default:** ``False`` Daemonize the Gunicorn process. @@ -921,27 +956,35 @@ background. .. _raw-env: -raw_env -~~~~~~~ +``raw_env`` +~~~~~~~~~~~ -* ``-e ENV, --env ENV`` -* ``[]`` +**Command line:** ``-e ENV`` or ``--env ENV`` +**Default:** ``[]`` -Set environment variable (key=value). +Set environment variables in the execution environment. -Pass variables to the execution environment. Ex.:: +Should be a list of strings in the ``key=value`` format. + +For example: + +.. code-block:: console $ gunicorn -b 127.0.0.1:8000 --env FOO=1 test:app -and test for the foo variable environment in your application. +Or in the configuration file: + +.. code-block:: python + + raw_env = ["FOO=1"] .. _pidfile: -pidfile -~~~~~~~ +``pidfile`` +~~~~~~~~~~~ -* ``-p FILE, --pid FILE`` -* ``None`` +**Command line:** ``-p FILE`` or ``--pid FILE`` +**Default:** ``None`` A filename to use for the PID file. @@ -949,11 +992,11 @@ If not set, no PID file will be written. .. _worker-tmp-dir: -worker_tmp_dir -~~~~~~~~~~~~~~ +``worker_tmp_dir`` +~~~~~~~~~~~~~~~~~~ -* ``--worker-tmp-dir DIR`` -* ``None`` +**Command line:** ``--worker-tmp-dir DIR`` +**Default:** ``None`` A directory to use for the worker heartbeat temporary file. @@ -969,11 +1012,11 @@ If not set, the default temporary directory will be used. .. _user: -user -~~~~ +``user`` +~~~~~~~~ -* ``-u USER, --user USER`` -* ``501`` +**Command line:** ``-u USER`` or ``--user USER`` +**Default:** ``501`` Switch worker processes to run as this user. @@ -983,11 +1026,11 @@ change the worker process user. .. _group: -group -~~~~~ +``group`` +~~~~~~~~~ -* ``-g GROUP, --group GROUP`` -* ``20`` +**Command line:** ``-g GROUP`` or ``--group GROUP`` +**Default:** ``20`` Switch worker process to run as this group. @@ -997,11 +1040,11 @@ change the worker processes group. .. _umask: -umask -~~~~~ +``umask`` +~~~~~~~~~ -* ``-m INT, --umask INT`` -* ``0`` +**Command line:** ``-m INT`` or ``--umask INT`` +**Default:** ``0`` A bit mask for the file mode on files written by Gunicorn. @@ -1014,11 +1057,11 @@ representations) .. _initgroups: -initgroups -~~~~~~~~~~ +``initgroups`` +~~~~~~~~~~~~~~ -* ``--initgroups`` -* ``False`` +**Command line:** ``--initgroups`` +**Default:** ``False`` If true, set the worker process's group access list with all of the groups of which the specified username is a member, plus the specified @@ -1028,10 +1071,10 @@ group id. .. _tmp-upload-dir: -tmp_upload_dir -~~~~~~~~~~~~~~ +``tmp_upload_dir`` +~~~~~~~~~~~~~~~~~~ -* ``None`` +**Default:** ``None`` Directory to store temporary request data as they are read. @@ -1043,10 +1086,10 @@ temporary directory. .. _secure-scheme-headers: -secure_scheme_headers -~~~~~~~~~~~~~~~~~~~~~ +``secure_scheme_headers`` +~~~~~~~~~~~~~~~~~~~~~~~~~ -* ``{'X-FORWARDED-PROTOCOL': 'ssl', 'X-FORWARDED-PROTO': 'https', 'X-FORWARDED-SSL': 'on'}`` +**Default:** ``{'X-FORWARDED-PROTOCOL': 'ssl', 'X-FORWARDED-PROTO': 'https', 'X-FORWARDED-SSL': 'on'}`` A dictionary containing headers and values that the front-end proxy uses to indicate HTTPS requests. These tell Gunicorn to set @@ -1063,11 +1106,11 @@ the headers defined here can not be passed directly from the client. .. _forwarded-allow-ips: -forwarded_allow_ips -~~~~~~~~~~~~~~~~~~~ +``forwarded_allow_ips`` +~~~~~~~~~~~~~~~~~~~~~~~ -* ``--forwarded-allow-ips STRING`` -* ``127.0.0.1`` +**Command line:** ``--forwarded-allow-ips STRING`` +**Default:** ``'127.0.0.1'`` Front-end's IPs from which allowed to handle set secure headers. (comma separate). @@ -1081,11 +1124,11 @@ variable. If it is not defined, the default is ``"127.0.0.1"``. .. _pythonpath: -pythonpath -~~~~~~~~~~ +``pythonpath`` +~~~~~~~~~~~~~~ -* ``--pythonpath STRING`` -* ``None`` +**Command line:** ``--pythonpath STRING`` +**Default:** ``None`` A comma-separated list of directories to add to the Python path. @@ -1094,11 +1137,11 @@ e.g. .. _paste: -paste -~~~~~ +``paste`` +~~~~~~~~~ -* ``--paste STRING, --paster STRING`` -* ``None`` +**Command line:** ``--paste STRING`` or ``--paster STRING`` +**Default:** ``None`` Load a PasteDeploy config file. The argument may contain a ``#`` symbol followed by the name of an app section from the config file, @@ -1109,11 +1152,11 @@ command line arguments to control server configuration instead. .. _proxy-protocol: -proxy_protocol -~~~~~~~~~~~~~~ +``proxy_protocol`` +~~~~~~~~~~~~~~~~~~ -* ``--proxy-protocol`` -* ``False`` +**Command line:** ``--proxy-protocol`` +**Default:** ``False`` Enable detect PROXY protocol (PROXY mode). @@ -1133,11 +1176,11 @@ Example for stunnel config:: .. _proxy-allow-ips: -proxy_allow_ips -~~~~~~~~~~~~~~~ +``proxy_allow_ips`` +~~~~~~~~~~~~~~~~~~~ -* ``--proxy-allow-from`` -* ``127.0.0.1`` +**Command line:** ``--proxy-allow-from`` +**Default:** ``'127.0.0.1'`` Front-end's IPs from which allowed accept proxy requests (comma separate). @@ -1147,11 +1190,11 @@ you still trust the environment) .. _raw-paste-global-conf: -raw_paste_global_conf -~~~~~~~~~~~~~~~~~~~~~ +``raw_paste_global_conf`` +~~~~~~~~~~~~~~~~~~~~~~~~~ -* ``--paste-global CONF`` -* ``[]`` +**Command line:** ``--paste-global CONF`` +**Default:** ``[]`` Set a PasteDeploy global config variable in ``key=value`` form. @@ -1165,11 +1208,11 @@ The variables are passed to the the PasteDeploy entrypoint. Example:: .. _strip-header-spaces: -strip_header_spaces -~~~~~~~~~~~~~~~~~~~ +``strip_header_spaces`` +~~~~~~~~~~~~~~~~~~~~~~~ -* ``--strip-header-spaces`` -* ``False`` +**Command line:** ``--strip-header-spaces`` +**Default:** ``False`` Strip spaces present between the header name and the the ``:``. @@ -1183,11 +1226,11 @@ Server Socket .. _bind: -bind -~~~~ +``bind`` +~~~~~~~~ -* ``-b ADDRESS, --bind ADDRESS`` -* ``['127.0.0.1:8000']`` +**Command line:** ``-b ADDRESS, --bind ADDRESS`` +**Default:** ``['127.0.0.1:8000']`` The socket to bind. @@ -1210,11 +1253,11 @@ is ``['127.0.0.1:8000']``. .. _backlog: -backlog -~~~~~~~ +``backlog`` +~~~~~~~~~~~ -* ``--backlog INT`` -* ``2048`` +**Command line:** ``--backlog INT`` +**Default:** ``2048`` The maximum number of pending connections. @@ -1230,11 +1273,11 @@ Worker Processes .. _workers: -workers -~~~~~~~ +``workers`` +~~~~~~~~~~~ -* ``-w INT, --workers INT`` -* ``1`` +**Command line:** ``-w INT, --workers INT`` +**Default:** ``1`` The number of worker processes for handling requests. @@ -1247,11 +1290,11 @@ If it is not defined, the default is ``1``. .. _worker-class: -worker_class -~~~~~~~~~~~~ +``worker_class`` +~~~~~~~~~~~~~~~~ -* ``-k STRING, --worker-class STRING`` -* ``sync`` +**Command line:** ``-k STRING`` or ``--worker-class STRING`` +**Default:** ``'sync'`` The type of workers to use. @@ -1279,11 +1322,11 @@ This alternative syntax will load the gevent class: .. _threads: -threads -~~~~~~~ +``threads`` +~~~~~~~~~~~ -* ``--threads INT`` -* ``1`` +**Command line:** ``--threads INT`` +**Default:** ``1`` The number of worker threads for handling requests. @@ -1304,11 +1347,11 @@ This setting only affects the Gthread worker type. .. _worker-connections: -worker_connections -~~~~~~~~~~~~~~~~~~ +``worker_connections`` +~~~~~~~~~~~~~~~~~~~~~~ -* ``--worker-connections INT`` -* ``1000`` +**Command line:** ``--worker-connections INT`` +**Default:** ``1000`` The maximum number of simultaneous clients. @@ -1316,11 +1359,11 @@ This setting only affects the Eventlet and Gevent worker types. .. _max-requests: -max_requests -~~~~~~~~~~~~ +``max_requests`` +~~~~~~~~~~~~~~~~ -* ``--max-requests INT`` -* ``0`` +**Command line:** ``--max-requests INT`` +**Default:** ``0`` The maximum number of requests a worker will process before restarting. @@ -1333,11 +1376,11 @@ restarts are disabled. .. _max-requests-jitter: -max_requests_jitter -~~~~~~~~~~~~~~~~~~~ +``max_requests_jitter`` +~~~~~~~~~~~~~~~~~~~~~~~ -* ``--max-requests-jitter INT`` -* ``0`` +**Command line:** ``--max-requests-jitter INT`` +**Default:** ``0`` The maximum jitter to add to the *max_requests* setting. @@ -1349,11 +1392,11 @@ restarts to avoid all workers restarting at the same time. .. _timeout: -timeout -~~~~~~~ +``timeout`` +~~~~~~~~~~~ -* ``-t INT, --timeout INT`` -* ``30`` +**Command line:** ``-t INT`` or ``--timeout INT`` +**Default:** ``30`` Workers silent for more than this many seconds are killed and restarted. @@ -1368,11 +1411,11 @@ single request. .. _graceful-timeout: -graceful_timeout -~~~~~~~~~~~~~~~~ +``graceful_timeout`` +~~~~~~~~~~~~~~~~~~~~ -* ``--graceful-timeout INT`` -* ``30`` +**Command line:** ``--graceful-timeout INT`` +**Default:** ``30`` Timeout for graceful workers restart. @@ -1382,11 +1425,11 @@ the receipt of the restart signal) are force killed. .. _keepalive: -keepalive -~~~~~~~~~ +``keepalive`` +~~~~~~~~~~~~~ -* ``--keep-alive INT`` -* ``2`` +**Command line:** ``--keep-alive INT`` +**Default:** ``2`` The number of seconds to wait for requests on a Keep-Alive connection.