diff --git a/docs/source/settings.rst b/docs/source/settings.rst index 4e0c11877..9d7194df7 100644 --- a/docs/source/settings.rst +++ b/docs/source/settings.rst @@ -210,7 +210,7 @@ H protocol s status B response length b response length or ``'-'`` (CLF format) -f referrer +f referer a user agent T request time in seconds M request time in milliseconds @@ -347,7 +347,7 @@ Format: https://docs.python.org/3/library/logging.config.html#logging.config.jso **Command line:** ``--log-syslog-to SYSLOG_ADDR`` -**Default:** ``'unix:///var/run/syslog'`` +**Default:** ``'udp://localhost:514'`` Address to send syslog messages. @@ -527,7 +527,7 @@ SSL certificate file SSL version to use (see stdlib ssl module's). -.. deprecated:: 20.2 +.. deprecated:: 21.0 The option is deprecated and it is currently ignored. Use :ref:`ssl-context` instead. ============= ============ @@ -569,7 +569,7 @@ Whether client certificate is required (see stdlib ssl module's) =========== =========================== --cert-reqs Description =========== =========================== -`0` no client verification +`0` no client veirifcation `1` ssl.CERT_OPTIONAL `2` ssl.CERT_REQUIRED =========== =========================== @@ -982,7 +982,7 @@ Following example shows a configuration file that sets the minimum TLS version t context.minimum_version = ssl.TLSVersion.TLSv1_3 return context -.. versionadded:: 20.2 +.. versionadded:: 21.0 Server Mechanics ---------------- @@ -1232,17 +1232,18 @@ the headers defined here can not be passed directly from the client. **Command line:** ``--forwarded-allow-ips STRING`` -**Default:** ``'127.0.0.1'`` +**Default:** ``'127.0.0.1,::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 +Set to ``*`` to disable checking of Front-end IPs. This is useful for setups where you don't know in advance the IP address of Front-end, but -you still trust the environment). +instead have ensured via other means that none other than your +authorized Front-ends can access gunicorn. By default, the value of the ``FORWARDED_ALLOW_IPS`` environment -variable. If it is not defined, the default is ``"127.0.0.1"``. +variable. If it is not defined, the default is ``"127.0.0.1,::1"``. .. note:: @@ -1390,7 +1391,7 @@ Set a PasteDeploy global config variable in ``key=value`` form. The option can be specified multiple times. -The variables are passed to the the PasteDeploy entrypoint. Example:: +The variables are passed to the PasteDeploy entrypoint. Example:: $ gunicorn -b 127.0.0.1:8000 --paste development.ini --paste-global FOO=1 --paste-global BAR=2 @@ -1410,7 +1411,134 @@ Strip spaces present between the header name and the the ``:``. This is known to induce vulnerabilities and is not compliant with the HTTP/1.1 standard. See https://portswigger.net/research/http-desync-attacks-request-smuggling-reborn. -Use with care and only if necessary. +Use with care and only if necessary. May be removed in a future version. + +.. versionadded:: 20.0.1 + +.. _permit-unconventional-http-method: + +``permit_unconventional_http_method`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Command line:** ``--permit-unconventional-http-method`` + +**Default:** ``False`` + +Permit HTTP methods not matching conventions, such as IANA registration guidelines + +This permits request methods of length less than 3 or more than 20, +methods with lowercase characters or methods containing the # character. +HTTP methods are case sensitive by definition, and merely uppercase by convention. + +This option is provided to diagnose backwards-incompatible changes. + +Use with care and only if necessary. May be removed in a future version. + +.. versionadded:: 22.0.0 + +.. _permit-unconventional-http-version: + +``permit_unconventional_http_version`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Command line:** ``--permit-unconventional-http-version`` + +**Default:** ``False`` + +Permit HTTP version not matching conventions of 2023 + +This disables the refusal of likely malformed request lines. +It is unusual to specify HTTP 1 versions other than 1.0 and 1.1. + +This option is provided to diagnose backwards-incompatible changes. +Use with care and only if necessary. May be removed in a future version. + +.. versionadded:: 22.0.0 + +.. _casefold-http-method: + +``casefold_http_method`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +**Command line:** ``--casefold-http-method`` + +**Default:** ``False`` + +Transform received HTTP methods to uppercase + +HTTP methods are case sensitive by definition, and merely uppercase by convention. + +This option is provided because previous versions of gunicorn defaulted to this behaviour. + +Use with care and only if necessary. May be removed in a future version. + +.. versionadded:: 22.0.0 + +.. _forwarder-headers: + +``forwarder_headers`` +~~~~~~~~~~~~~~~~~~~~~ + +**Command line:** ``--forwarder-headers`` + +**Default:** ``'SCRIPT_NAME'`` + +A list containing upper-case header field names that the front-end proxy +sets, to be used in WSGI environment. + +If headers named in this list are not present in the request, they will be ignored. + +This option can be used to transfer SCRIPT_NAME and REMOTE_USER. + +It is important that your front-end proxy configuration ensures that +the headers defined here can not be passed directly from the client. + +.. _header-map: + +``header_map`` +~~~~~~~~~~~~~~ + +**Command line:** ``--header-map`` + +**Default:** ``'drop'`` + +Configure how header field names are mapped into environ + +Headers containing underscores are permitted by RFC9110, +but gunicorn joining headers of different names into +the same environment variable will dangerously confuse applications as to which is which. + +The safe default ``drop`` is to silently drop headers that cannot be unambiguously mapped. +The value ``refuse`` will return an error if a request contains *any* such header. +The value ``dangerous`` matches the previous, not advisable, behaviour of mapping different +header field names into the same environ name. + +If the source IP is permitted by ``forwarded-allow-ips``, *and* the header name is +present in ``forwarder-headers``, the header is mapped into environment regardless of +the state of this setting. + +Use with care and only if necessary and after considering if your problem could +instead be solved by specifically renaming or rewriting only the intended headers +on a proxy in front of Gunicorn. + +.. versionadded:: 22.0.0 + +.. _tolerate-dangerous-framing: + +``tolerate_dangerous_framing`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Command line:** ``--tolerate-dangerous-framing`` + +**Default:** ``False`` + +Process requests with both Transfer-Encoding and Content-Length + +This is known to induce vulnerabilities, but not strictly forbidden by RFC9112. + +Use with care and only if necessary. May be removed in a future version. + +.. versionadded:: 22.0.0 Server Socket -------------