From 3e265d43199e4f915cd40ebd0ceebe3d6cf23f65 Mon Sep 17 00:00:00 2001 From: Randall Leeds Date: Tue, 3 Jul 2018 13:02:41 -0700 Subject: [PATCH] Regenerate settings documentation --- docs/source/settings.rst | 1219 +++++++++++++++++++------------------- 1 file changed, 605 insertions(+), 614 deletions(-) diff --git a/docs/source/settings.rst b/docs/source/settings.rst index e13e39fd..5665e534 100644 --- a/docs/source/settings.rst +++ b/docs/source/settings.rst @@ -42,278 +42,6 @@ application specific configuration. Loading the config from a Python module requires the ``python:`` prefix. -Server Socket -------------- - -.. _bind: - -bind -~~~~ - -* ``-b ADDRESS, --bind ADDRESS`` -* ``['127.0.0.1:8000']`` - -The socket to bind. - -A string of the form: ``HOST``, ``HOST:PORT``, ``unix:PATH``. An IP is -a valid ``HOST``. - -Multiple addresses can be bound. ex.:: - - $ gunicorn -b 127.0.0.1:8000 -b [::1]:8000 test:app - -will bind the `test:app` application on localhost both on ipv6 -and ipv4 interfaces. - -.. _backlog: - -backlog -~~~~~~~ - -* ``--backlog INT`` -* ``2048`` - -The maximum number of pending connections. - -This refers to the number of clients that can be waiting to be served. -Exceeding this number results in the client getting an error when -attempting to connect. It should only affect servers under significant -load. - -Must be a positive integer. Generally set in the 64-2048 range. - -Worker Processes ----------------- - -.. _workers: - -workers -~~~~~~~ - -* ``-w INT, --workers INT`` -* ``1`` - -The number of worker processes for handling requests. - -A positive integer generally in the ``2-4 x $(NUM_CORES)`` range. -You'll want to vary this a bit to find the best for your particular -application's work load. - -By default, the value of the ``WEB_CONCURRENCY`` environment variable. -If it is not defined, the default is ``1``. - -.. _worker-class: - -worker_class -~~~~~~~~~~~~ - -* ``-k STRING, --worker-class STRING`` -* ``sync`` - -The type of workers to use. - -The default class (``sync``) should handle most "normal" types of -workloads. You'll want to read :doc:`design` for information on when -you might want to choose one of the other worker classes. Required -libraries may be installed using setuptools' ``extra_require`` feature. - -A string referring to one of the following bundled classes: - -* ``sync`` -* ``eventlet`` - Requires eventlet >= 0.9.7 (or install it via - ``pip install gunicorn[eventlet]``) -* ``gevent`` - Requires gevent >= 0.13 (or install it via - ``pip install gunicorn[gevent]``) -* ``tornado`` - Requires tornado >= 0.2 (or install it via - ``pip install gunicorn[tornado]``) -* ``gthread`` - Python 2 requires the futures package to be installed - (or install it via ``pip install gunicorn[gthread]``) -* ``gaiohttp`` - Deprecated. - -Optionally, you can provide your own worker by giving Gunicorn a -Python path to a subclass of ``gunicorn.workers.base.Worker``. -This alternative syntax will load the gevent class: -``gunicorn.workers.ggevent.GeventWorker``. - -.. deprecated:: 19.8 - The ``gaiohttp`` worker is deprecated. Please use - ``aiohttp.worker.GunicornWebWorker`` instead. See - :ref:`asyncio-workers` for more information on how to use it. - -.. _threads: - -threads -~~~~~~~ - -* ``--threads INT`` -* ``1`` - -The number of worker threads for handling requests. - -Run each worker with the specified number of threads. - -A positive integer generally in the ``2-4 x $(NUM_CORES)`` range. -You'll want to vary this a bit to find the best for your particular -application's work load. - -If it is not defined, the default is ``1``. - -This setting only affects the Gthread worker type. - -.. note:: - If you try to use the ``sync`` worker type and set the ``threads`` - setting to more than 1, the ``gthread`` worker type will be used - instead. - -.. _worker-connections: - -worker_connections -~~~~~~~~~~~~~~~~~~ - -* ``--worker-connections INT`` -* ``1000`` - -The maximum number of simultaneous clients. - -This setting only affects the Eventlet and Gevent worker types. - -.. _max-requests: - -max_requests -~~~~~~~~~~~~ - -* ``--max-requests INT`` -* ``0`` - -The maximum number of requests a worker will process before restarting. - -Any value greater than zero will limit the number of requests a work -will process before automatically restarting. This is a simple method -to help limit the damage of memory leaks. - -If this is set to zero (the default) then the automatic worker -restarts are disabled. - -.. _max-requests-jitter: - -max_requests_jitter -~~~~~~~~~~~~~~~~~~~ - -* ``--max-requests-jitter INT`` -* ``0`` - -The maximum jitter to add to the *max_requests* setting. - -The jitter causes the restart per worker to be randomized by -``randint(0, max_requests_jitter)``. This is intended to stagger worker -restarts to avoid all workers restarting at the same time. - -.. versionadded:: 19.2 - -.. _timeout: - -timeout -~~~~~~~ - -* ``-t INT, --timeout INT`` -* ``30`` - -Workers silent for more than this many seconds are killed and restarted. - -Generally set to thirty seconds. Only set this noticeably higher if -you're sure of the repercussions for sync workers. For the non sync -workers it just means that the worker process is still communicating and -is not tied to the length of time required to handle a single request. - -.. _graceful-timeout: - -graceful_timeout -~~~~~~~~~~~~~~~~ - -* ``--graceful-timeout INT`` -* ``30`` - -Timeout for graceful workers restart. - -After receiving a restart signal, workers have this much time to finish -serving requests. Workers still alive after the timeout (starting from -the receipt of the restart signal) are force killed. - -.. _keepalive: - -keepalive -~~~~~~~~~ - -* ``--keep-alive INT`` -* ``2`` - -The number of seconds to wait for requests on a Keep-Alive connection. - -Generally set in the 1-5 seconds range for servers with direct connection -to the client (e.g. when you don't have separate load balancer). When -Gunicorn is deployed behind a load balancer, it often makes sense to -set this to a higher value. - -.. note:: - ``sync`` worker does not support persistent connections and will - ignore this option. - -Security --------- - -.. _limit-request-line: - -limit_request_line -~~~~~~~~~~~~~~~~~~ - -* ``--limit-request-line INT`` -* ``4094`` - -The maximum size of HTTP request line in bytes. - -This parameter is used to limit the allowed size of a client's -HTTP request-line. Since the request-line consists of the HTTP -method, URI, and protocol version, this directive places a -restriction on the length of a request-URI allowed for a request -on the server. A server needs this value to be large enough to -hold any of its resource names, including any information that -might be passed in the query part of a GET request. Value is a number -from 0 (unlimited) to 8190. - -This parameter can be used to prevent any DDOS attack. - -.. _limit-request-fields: - -limit_request_fields -~~~~~~~~~~~~~~~~~~~~ - -* ``--limit-request-fields INT`` -* ``100`` - -Limit the number of HTTP headers fields in a request. - -This parameter is used to limit the number of headers in a request to -prevent DDOS attack. Used with the *limit_request_field_size* it allows -more safety. By default this value is 100 and can't be larger than -32768. - -.. _limit-request-field-size: - -limit_request_field_size -~~~~~~~~~~~~~~~~~~~~~~~~ - -* ``--limit-request-field_size INT`` -* ``8190`` - -Limit the allowed size of an HTTP request header field. - -Value is a positive number or 0. Setting it to 0 will allow unlimited -header field sizes. - -.. warning:: - Setting this parameter to a very high or unlimited value can open - up for DDOS attacks. - Debugging --------- @@ -395,239 +123,6 @@ check_config Check the configuration. -Server Mechanics ----------------- - -.. _preload-app: - -preload_app -~~~~~~~~~~~ - -* ``--preload`` -* ``False`` - -Load application code before the worker processes are forked. - -By preloading an application you can save some RAM resources as well as -speed up server boot times. Although, if you defer application loading -to each worker process, you can reload your application code easily by -restarting workers. - -.. _sendfile: - -sendfile -~~~~~~~~ - -* ``--no-sendfile`` -* ``None`` - -Disables the use of ``sendfile()``. - -If not set, the value of the ``SENDFILE`` environment variable is used -to enable or disable its usage. - -.. versionadded:: 19.2 -.. versionchanged:: 19.4 - Swapped ``--sendfile`` with ``--no-sendfile`` to actually allow - disabling. -.. versionchanged:: 19.6 - added support for the ``SENDFILE`` environment variable - -.. _reuse-port: - -reuse_port -~~~~~~~~~~ - -* ``--reuse-port`` -* ``False`` - -Set the ``SO_REUSEPORT`` flag on the listening socket. - -.. versionadded:: 19.8 - -.. _chdir: - -chdir -~~~~~ - -* ``--chdir`` -* ``/usr/src/app`` - -Chdir to specified directory before apps loading. - -.. _daemon: - -daemon -~~~~~~ - -* ``-D, --daemon`` -* ``False`` - -Daemonize the Gunicorn process. - -Detaches the server from the controlling terminal and enters the -background. - -.. _raw-env: - -raw_env -~~~~~~~ - -* ``-e ENV, --env ENV`` -* ``[]`` - -Set environment variable (key=value). - -Pass variables to the execution environment. Ex.:: - - $ gunicorn -b 127.0.0.1:8000 --env FOO=1 test:app - -and test for the foo variable environment in your application. - -.. _pidfile: - -pidfile -~~~~~~~ - -* ``-p FILE, --pid FILE`` -* ``None`` - -A filename to use for the PID file. - -If not set, no PID file will be written. - -.. _worker-tmp-dir: - -worker_tmp_dir -~~~~~~~~~~~~~~ - -* ``--worker-tmp-dir DIR`` -* ``None`` - -A directory to use for the worker heartbeat temporary file. - -If not set, the default temporary directory will be used. - -.. note:: - The current heartbeat system involves calling ``os.fchmod`` on - temporary file handlers and may block a worker for arbitrary time - if the directory is on a disk-backed filesystem. - - See :ref:`blocking-os-fchmod` for more detailed information - and a solution for avoiding this problem. - -.. _user: - -user -~~~~ - -* ``-u USER, --user USER`` -* ``501`` - -Switch worker processes to run as this user. - -A valid user id (as an integer) or the name of a user that can be -retrieved with a call to ``pwd.getpwnam(value)`` or ``None`` to not -change the worker process user. - -.. _group: - -group -~~~~~ - -* ``-g GROUP, --group GROUP`` -* ``20`` - -Switch worker process to run as this group. - -A valid group id (as an integer) or the name of a user that can be -retrieved with a call to ``pwd.getgrnam(value)`` or ``None`` to not -change the worker processes group. - -.. _umask: - -umask -~~~~~ - -* ``-m INT, --umask INT`` -* ``0`` - -A bit mask for the file mode on files written by Gunicorn. - -Note that this affects unix socket permissions. - -A valid value for the ``os.umask(mode)`` call or a string compatible -with ``int(value, 0)`` (``0`` means Python guesses the base, so values -like ``0``, ``0xFF``, ``0022`` are valid for decimal, hex, and octal -representations) - -.. _initgroups: - -initgroups -~~~~~~~~~~ - -* ``--initgroups`` -* ``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 -group id. - -.. versionadded:: 19.7 - -.. _tmp-upload-dir: - -tmp_upload_dir -~~~~~~~~~~~~~~ - -* ``None`` - -Directory to store temporary request data as they are read. - -This may disappear in the near future. - -This path should be writable by the process permissions set for Gunicorn -workers. If not specified, Gunicorn will choose a system generated -temporary directory. - -.. _secure-scheme-headers: - -secure_scheme_headers -~~~~~~~~~~~~~~~~~~~~~ - -* ``{'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 -``wsgi.url_scheme`` to ``https``, so your application can tell that the -request is secure. - -The dictionary should map upper-case header names to exact string -values. The value comparisons are case-sensitive, unlike the header -names, so make sure they're exactly what your front-end proxy sends -when handling HTTPS requests. - -It is important that your front-end proxy configuration ensures that -the headers defined here can not be passed directly from the client. - -.. _forwarded-allow-ips: - -forwarded_allow_ips -~~~~~~~~~~~~~~~~~~~ - -* ``--forwarded-allow-ips STRING`` -* ``127.0.0.1`` - -Front-end's IPs from which allowed to handle set secure headers. -(comma separate). - -Set to ``*`` to disable checking of Front-end IPs (useful for setups -where you don't know in advance the IP address of Front-end, but -you still trust the environment). - -By default, the value of the ``FORWARDED_ALLOW_IPS`` environment -variable. If it is not defined, the default is ``"127.0.0.1"``. - Logging ------- @@ -905,36 +400,148 @@ default_proc_name Internal setting that is adjusted for each type of application. -Server Mechanics ----------------- +SSL +--- -.. _pythonpath: +.. _keyfile: -pythonpath -~~~~~~~~~~ +keyfile +~~~~~~~ -* ``--pythonpath STRING`` +* ``--keyfile FILE`` * ``None`` -A comma-separated list of directories to add to the Python path. +SSL key file -e.g. -``'/home/djangoprojects/myproject,/home/python/mylibrary'``. +.. _certfile: -.. _paste: +certfile +~~~~~~~~ -paste -~~~~~ - -* ``--paste STRING, --paster STRING`` +* ``--certfile FILE`` * ``None`` -Load a PasteDeploy config file. The argument may contain a ``#`` -symbol followed by the name of an app section from the config file, -e.g. ``production.ini#admin``. +SSL certificate file -At this time, using alternate server blocks is not supported. Use the -command line arguments to control server configuration instead. +.. _ssl-version: + +ssl_version +~~~~~~~~~~~ + +* ``--ssl-version`` +* ``_SSLMethod.PROTOCOL_TLS`` + +SSL version to use (see stdlib ssl module's) + +.. versionchanged:: 19.7 + The default value has been changed from ``ssl.PROTOCOL_TLSv1`` to + ``ssl.PROTOCOL_SSLv23``. + +.. _cert-reqs: + +cert_reqs +~~~~~~~~~ + +* ``--cert-reqs`` +* ``VerifyMode.CERT_NONE`` + +Whether client certificate is required (see stdlib ssl module's) + +.. _ca-certs: + +ca_certs +~~~~~~~~ + +* ``--ca-certs FILE`` +* ``None`` + +CA certificates file + +.. _suppress-ragged-eofs: + +suppress_ragged_eofs +~~~~~~~~~~~~~~~~~~~~ + +* ``--suppress-ragged-eofs`` +* ``True`` + +Suppress ragged EOFs (see stdlib ssl module's) + +.. _do-handshake-on-connect: + +do_handshake_on_connect +~~~~~~~~~~~~~~~~~~~~~~~ + +* ``--do-handshake-on-connect`` +* ``False`` + +Whether to perform SSL handshake on socket connect (see stdlib ssl module's) + +.. _ciphers: + +ciphers +~~~~~~~ + +* ``--ciphers`` +* ``TLSv1`` + +Ciphers to use (see stdlib ssl module's) + +Security +-------- + +.. _limit-request-line: + +limit_request_line +~~~~~~~~~~~~~~~~~~ + +* ``--limit-request-line INT`` +* ``4094`` + +The maximum size of HTTP request line in bytes. + +This parameter is used to limit the allowed size of a client's +HTTP request-line. Since the request-line consists of the HTTP +method, URI, and protocol version, this directive places a +restriction on the length of a request-URI allowed for a request +on the server. A server needs this value to be large enough to +hold any of its resource names, including any information that +might be passed in the query part of a GET request. Value is a number +from 0 (unlimited) to 8190. + +This parameter can be used to prevent any DDOS attack. + +.. _limit-request-fields: + +limit_request_fields +~~~~~~~~~~~~~~~~~~~~ + +* ``--limit-request-fields INT`` +* ``100`` + +Limit the number of HTTP headers fields in a request. + +This parameter is used to limit the number of headers in a request to +prevent DDOS attack. Used with the *limit_request_field_size* it allows +more safety. By default this value is 100 and can't be larger than +32768. + +.. _limit-request-field-size: + +limit_request_field_size +~~~~~~~~~~~~~~~~~~~~~~~~ + +* ``--limit-request-field_size INT`` +* ``8190`` + +Limit the allowed size of an HTTP request header field. + +Value is a positive number or 0. Setting it to 0 will allow unlimited +header field sizes. + +.. warning:: + Setting this parameter to a very high or unlimited value can open + up for DDOS attacks. Server Hooks ------------ @@ -1169,6 +776,264 @@ The callable needs to accept a single instance variable for the Arbiter. Server Mechanics ---------------- +.. _preload-app: + +preload_app +~~~~~~~~~~~ + +* ``--preload`` +* ``False`` + +Load application code before the worker processes are forked. + +By preloading an application you can save some RAM resources as well as +speed up server boot times. Although, if you defer application loading +to each worker process, you can reload your application code easily by +restarting workers. + +.. _sendfile: + +sendfile +~~~~~~~~ + +* ``--no-sendfile`` +* ``None`` + +Disables the use of ``sendfile()``. + +If not set, the value of the ``SENDFILE`` environment variable is used +to enable or disable its usage. + +.. versionadded:: 19.2 +.. versionchanged:: 19.4 + Swapped ``--sendfile`` with ``--no-sendfile`` to actually allow + disabling. +.. versionchanged:: 19.6 + added support for the ``SENDFILE`` environment variable + +.. _reuse-port: + +reuse_port +~~~~~~~~~~ + +* ``--reuse-port`` +* ``False`` + +Set the ``SO_REUSEPORT`` flag on the listening socket. + +.. versionadded:: 19.8 + +.. _chdir: + +chdir +~~~~~ + +* ``--chdir`` +* ``/usr/src/app`` + +Chdir to specified directory before apps loading. + +.. _daemon: + +daemon +~~~~~~ + +* ``-D, --daemon`` +* ``False`` + +Daemonize the Gunicorn process. + +Detaches the server from the controlling terminal and enters the +background. + +.. _raw-env: + +raw_env +~~~~~~~ + +* ``-e ENV, --env ENV`` +* ``[]`` + +Set environment variable (key=value). + +Pass variables to the execution environment. Ex.:: + + $ gunicorn -b 127.0.0.1:8000 --env FOO=1 test:app + +and test for the foo variable environment in your application. + +.. _pidfile: + +pidfile +~~~~~~~ + +* ``-p FILE, --pid FILE`` +* ``None`` + +A filename to use for the PID file. + +If not set, no PID file will be written. + +.. _worker-tmp-dir: + +worker_tmp_dir +~~~~~~~~~~~~~~ + +* ``--worker-tmp-dir DIR`` +* ``None`` + +A directory to use for the worker heartbeat temporary file. + +If not set, the default temporary directory will be used. + +.. note:: + The current heartbeat system involves calling ``os.fchmod`` on + temporary file handlers and may block a worker for arbitrary time + if the directory is on a disk-backed filesystem. + + See :ref:`blocking-os-fchmod` for more detailed information + and a solution for avoiding this problem. + +.. _user: + +user +~~~~ + +* ``-u USER, --user USER`` +* ``501`` + +Switch worker processes to run as this user. + +A valid user id (as an integer) or the name of a user that can be +retrieved with a call to ``pwd.getpwnam(value)`` or ``None`` to not +change the worker process user. + +.. _group: + +group +~~~~~ + +* ``-g GROUP, --group GROUP`` +* ``20`` + +Switch worker process to run as this group. + +A valid group id (as an integer) or the name of a user that can be +retrieved with a call to ``pwd.getgrnam(value)`` or ``None`` to not +change the worker processes group. + +.. _umask: + +umask +~~~~~ + +* ``-m INT, --umask INT`` +* ``0`` + +A bit mask for the file mode on files written by Gunicorn. + +Note that this affects unix socket permissions. + +A valid value for the ``os.umask(mode)`` call or a string compatible +with ``int(value, 0)`` (``0`` means Python guesses the base, so values +like ``0``, ``0xFF``, ``0022`` are valid for decimal, hex, and octal +representations) + +.. _initgroups: + +initgroups +~~~~~~~~~~ + +* ``--initgroups`` +* ``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 +group id. + +.. versionadded:: 19.7 + +.. _tmp-upload-dir: + +tmp_upload_dir +~~~~~~~~~~~~~~ + +* ``None`` + +Directory to store temporary request data as they are read. + +This may disappear in the near future. + +This path should be writable by the process permissions set for Gunicorn +workers. If not specified, Gunicorn will choose a system generated +temporary directory. + +.. _secure-scheme-headers: + +secure_scheme_headers +~~~~~~~~~~~~~~~~~~~~~ + +* ``{'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 +``wsgi.url_scheme`` to ``https``, so your application can tell that the +request is secure. + +The dictionary should map upper-case header names to exact string +values. The value comparisons are case-sensitive, unlike the header +names, so make sure they're exactly what your front-end proxy sends +when handling HTTPS requests. + +It is important that your front-end proxy configuration ensures that +the headers defined here can not be passed directly from the client. + +.. _forwarded-allow-ips: + +forwarded_allow_ips +~~~~~~~~~~~~~~~~~~~ + +* ``--forwarded-allow-ips STRING`` +* ``127.0.0.1`` + +Front-end's IPs from which allowed to handle set secure headers. +(comma separate). + +Set to ``*`` to disable checking of Front-end IPs (useful for setups +where you don't know in advance the IP address of Front-end, but +you still trust the environment). + +By default, the value of the ``FORWARDED_ALLOW_IPS`` environment +variable. If it is not defined, the default is ``"127.0.0.1"``. + +.. _pythonpath: + +pythonpath +~~~~~~~~~~ + +* ``--pythonpath STRING`` +* ``None`` + +A comma-separated list of directories to add to the Python path. + +e.g. +``'/home/djangoprojects/myproject,/home/python/mylibrary'``. + +.. _paste: + +paste +~~~~~ + +* ``--paste STRING, --paster STRING`` +* ``None`` + +Load a PasteDeploy config file. The argument may contain a ``#`` +symbol followed by the name of an app section from the config file, +e.g. ``production.ini#admin``. + +At this time, using alternate server blocks is not supported. Use the +command line arguments to control server configuration instead. + .. _proxy-protocol: proxy_protocol @@ -1207,96 +1072,6 @@ Set to ``*`` to disable checking of Front-end IPs (useful for setups where you don't know in advance the IP address of Front-end, but you still trust the environment) -SSL ---- - -.. _keyfile: - -keyfile -~~~~~~~ - -* ``--keyfile FILE`` -* ``None`` - -SSL key file - -.. _certfile: - -certfile -~~~~~~~~ - -* ``--certfile FILE`` -* ``None`` - -SSL certificate file - -.. _ssl-version: - -ssl_version -~~~~~~~~~~~ - -* ``--ssl-version`` -* ``_SSLMethod.PROTOCOL_TLS`` - -SSL version to use (see stdlib ssl module's) - -.. versionchanged:: 19.7 - The default value has been changed from ``ssl.PROTOCOL_TLSv1`` to - ``ssl.PROTOCOL_SSLv23``. - -.. _cert-reqs: - -cert_reqs -~~~~~~~~~ - -* ``--cert-reqs`` -* ``VerifyMode.CERT_NONE`` - -Whether client certificate is required (see stdlib ssl module's) - -.. _ca-certs: - -ca_certs -~~~~~~~~ - -* ``--ca-certs FILE`` -* ``None`` - -CA certificates file - -.. _suppress-ragged-eofs: - -suppress_ragged_eofs -~~~~~~~~~~~~~~~~~~~~ - -* ``--suppress-ragged-eofs`` -* ``True`` - -Suppress ragged EOFs (see stdlib ssl module's) - -.. _do-handshake-on-connect: - -do_handshake_on_connect -~~~~~~~~~~~~~~~~~~~~~~~ - -* ``--do-handshake-on-connect`` -* ``False`` - -Whether to perform SSL handshake on socket connect (see stdlib ssl module's) - -.. _ciphers: - -ciphers -~~~~~~~ - -* ``--ciphers`` -* ``TLSv1`` - -Ciphers to use (see stdlib ssl module's) - -Server Mechanics ----------------- - .. _raw-paste-global-conf: raw_paste_global_conf @@ -1315,3 +1090,219 @@ The variables are passed to the the PasteDeploy entrypoint. Example:: .. versionadded:: 19.7 +Server Socket +------------- + +.. _bind: + +bind +~~~~ + +* ``-b ADDRESS, --bind ADDRESS`` +* ``['127.0.0.1:8000']`` + +The socket to bind. + +A string of the form: ``HOST``, ``HOST:PORT``, ``unix:PATH``. An IP is +a valid ``HOST``. + +Multiple addresses can be bound. ex.:: + + $ gunicorn -b 127.0.0.1:8000 -b [::1]:8000 test:app + +will bind the `test:app` application on localhost both on ipv6 +and ipv4 interfaces. + +.. _backlog: + +backlog +~~~~~~~ + +* ``--backlog INT`` +* ``2048`` + +The maximum number of pending connections. + +This refers to the number of clients that can be waiting to be served. +Exceeding this number results in the client getting an error when +attempting to connect. It should only affect servers under significant +load. + +Must be a positive integer. Generally set in the 64-2048 range. + +Worker Processes +---------------- + +.. _workers: + +workers +~~~~~~~ + +* ``-w INT, --workers INT`` +* ``1`` + +The number of worker processes for handling requests. + +A positive integer generally in the ``2-4 x $(NUM_CORES)`` range. +You'll want to vary this a bit to find the best for your particular +application's work load. + +By default, the value of the ``WEB_CONCURRENCY`` environment variable. +If it is not defined, the default is ``1``. + +.. _worker-class: + +worker_class +~~~~~~~~~~~~ + +* ``-k STRING, --worker-class STRING`` +* ``sync`` + +The type of workers to use. + +The default class (``sync``) should handle most "normal" types of +workloads. You'll want to read :doc:`design` for information on when +you might want to choose one of the other worker classes. Required +libraries may be installed using setuptools' ``extra_require`` feature. + +A string referring to one of the following bundled classes: + +* ``sync`` +* ``eventlet`` - Requires eventlet >= 0.9.7 (or install it via + ``pip install gunicorn[eventlet]``) +* ``gevent`` - Requires gevent >= 0.13 (or install it via + ``pip install gunicorn[gevent]``) +* ``tornado`` - Requires tornado >= 0.2 (or install it via + ``pip install gunicorn[tornado]``) +* ``gthread`` - Python 2 requires the futures package to be installed + (or install it via ``pip install gunicorn[gthread]``) +* ``gaiohttp`` - Deprecated. + +Optionally, you can provide your own worker by giving Gunicorn a +Python path to a subclass of ``gunicorn.workers.base.Worker``. +This alternative syntax will load the gevent class: +``gunicorn.workers.ggevent.GeventWorker``. + +.. deprecated:: 19.8 + The ``gaiohttp`` worker is deprecated. Please use + ``aiohttp.worker.GunicornWebWorker`` instead. See + :ref:`asyncio-workers` for more information on how to use it. + +.. _threads: + +threads +~~~~~~~ + +* ``--threads INT`` +* ``1`` + +The number of worker threads for handling requests. + +Run each worker with the specified number of threads. + +A positive integer generally in the ``2-4 x $(NUM_CORES)`` range. +You'll want to vary this a bit to find the best for your particular +application's work load. + +If it is not defined, the default is ``1``. + +This setting only affects the Gthread worker type. + +.. note:: + If you try to use the ``sync`` worker type and set the ``threads`` + setting to more than 1, the ``gthread`` worker type will be used + instead. + +.. _worker-connections: + +worker_connections +~~~~~~~~~~~~~~~~~~ + +* ``--worker-connections INT`` +* ``1000`` + +The maximum number of simultaneous clients. + +This setting only affects the Eventlet and Gevent worker types. + +.. _max-requests: + +max_requests +~~~~~~~~~~~~ + +* ``--max-requests INT`` +* ``0`` + +The maximum number of requests a worker will process before restarting. + +Any value greater than zero will limit the number of requests a work +will process before automatically restarting. This is a simple method +to help limit the damage of memory leaks. + +If this is set to zero (the default) then the automatic worker +restarts are disabled. + +.. _max-requests-jitter: + +max_requests_jitter +~~~~~~~~~~~~~~~~~~~ + +* ``--max-requests-jitter INT`` +* ``0`` + +The maximum jitter to add to the *max_requests* setting. + +The jitter causes the restart per worker to be randomized by +``randint(0, max_requests_jitter)``. This is intended to stagger worker +restarts to avoid all workers restarting at the same time. + +.. versionadded:: 19.2 + +.. _timeout: + +timeout +~~~~~~~ + +* ``-t INT, --timeout INT`` +* ``30`` + +Workers silent for more than this many seconds are killed and restarted. + +Generally set to thirty seconds. Only set this noticeably higher if +you're sure of the repercussions for sync workers. For the non sync +workers it just means that the worker process is still communicating and +is not tied to the length of time required to handle a single request. + +.. _graceful-timeout: + +graceful_timeout +~~~~~~~~~~~~~~~~ + +* ``--graceful-timeout INT`` +* ``30`` + +Timeout for graceful workers restart. + +After receiving a restart signal, workers have this much time to finish +serving requests. Workers still alive after the timeout (starting from +the receipt of the restart signal) are force killed. + +.. _keepalive: + +keepalive +~~~~~~~~~ + +* ``--keep-alive INT`` +* ``2`` + +The number of seconds to wait for requests on a Keep-Alive connection. + +Generally set in the 1-5 seconds range for servers with direct connection +to the client (e.g. when you don't have separate load balancer). When +Gunicorn is deployed behind a load balancer, it often makes sense to +set this to a higher value. + +.. note:: + ``sync`` worker does not support persistent connections and will + ignore this option. +