From 2a1524a9b5786459786a4b86e5b2f09d1041e53d Mon Sep 17 00:00:00 2001 From: Keith Gaughan Date: Sat, 23 Nov 2024 19:40:01 +0000 Subject: [PATCH] Sync waitress-serve's docs with waitress.serve() A number of options aren't documented on the command line interface. These settings are usable via waitress-serve already, but are not documented. See the comment raised by @merwok on #451. --- docs/runner.rst | 92 +++++++++++++++++++++++++++++++++++++ src/waitress/runner.py | 101 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 188 insertions(+), 5 deletions(-) diff --git a/docs/runner.rst b/docs/runner.rst index 70c00227..6d687f88 100644 --- a/docs/runner.rst +++ b/docs/runner.rst @@ -94,6 +94,19 @@ Common options: A wildcard for the hostname is also supported and will bind to both IPv4/IPv6 depending on whether they are enabled or disabled. +``--server-name=NAME`` + This is the value that will be placed in the WSGI environment as + ``SERVER_NAME``, the only time that this value is used in the WSGI + environment for a request is if the client sent a HTTP/1.0 request without + a ``Host`` header set, and no other proxy headers. + + The default is value is ``waitress.invalid``, if your WSGI application is + creating URL's that include this as the hostname and you are using a + reverse proxy setup, you may want to validate that your reverse proxy is + sending the appropriate headers. + + In most situations you will not need to set this value. + ``--[no-]ipv4`` Toggle on/off IPv4 support. @@ -130,6 +143,73 @@ Common options: Server identity used in the 'Server' header in responses. Default is 'waitress'. +``--trusted-proxy=IP`` + IP address of a remote peer allowed to override various WSGI environment + variables using proxy headers. + + For unix sockets, set this value to ``localhost`` instead of an IP address. + + The value ``*`` (wildcard) may be used to signify that all remote peers are + to be trusted. + +``--trusted-proxy-count=INT`` + How many proxies we trust when chained. For example, + + ``X-Forwarded-For: 192.0.2.1, "[2001:db8::1]"`` + + or + + ``Forwarded: for=192.0.2.1, For="[2001:db8::1]"`` + + means there were (potentially), two proxies involved. If we know there is + only 1 valid proxy, then that initial IP address "192.0.2.1" is not trusted + and we completely ignore it. + + If there are two trusted proxies in the path, this value should be set to + 2. If there are more proxies, this value should be set higher. + + Default: ``1`` + +``--trusted_proxy_headers=LIST`` + Which of the proxy headers should we trust, this is a set where you + either specify "forwarded" or one or more of "x-forwarded-host", "x-forwarded-for", + "x-forwarded-proto", "x-forwarded-port", "x-forwarded-by". + + This list of trusted headers is used when ``trusted_proxy`` is set and will + allow waitress to modify the WSGI environment using the values provided by + the proxy. + + .. warning:: + It is an error to set this value without setting ``--trusted-proxy``. + + .. warning:: + If ``--trusted-proxy`` is set, the default is ``x-forwarded-proto`` to + match older versions of Waitress. Users should explicitly opt-in by + selecting the headers to be trusted as future versions of waitress will + use an empty default. + +``--[no-]log-untrusted-proxy-headers`` + Should waitress log warning messages about proxy headers that are being + sent from upstream that are not trusted by ``--trusted-proxy-headers`` but + are being cleared due to ``--clear-untrusted-proxy-headers``? + + This may be useful for debugging if you expect your upstream proxy server + to only send specific headers. + + .. warning:: + It is a no-op to set this value without also setting + ``--clear-untrusted-proxy-headers`` and ``--trusted-proxy`` + +``--[no-]clear-untrusted-proxy-headers`` + This tells Waitress to remove any untrusted proxy headers ("Forwarded", + "X-Forwared-For", "X-Forwarded-By", "X-Forwarded-Host", "X-Forwarded-Port", + "X-Forwarded-Proto") not explicitly allowed by ``--trusted-proxy-headers``. + + This is active by default. + + .. warning:: + It is an error to set this value without setting ``--trusted-proxy``. + Tuning options: ``--threads=INT`` @@ -174,6 +254,18 @@ Tuning options: 120. 'Inactive' is defined as 'has received no data from the client and has sent no data to the client'. +``--channel-request-lookahead=INT`` + Sets the amount of requests we can continue to read from the socket, while + we are processing current requests. The default value won't allow any + lookahead, increase it above ``0`` to enable. + + When enabled this inserts a callable ``waitress.client_disconnected`` into + the environment that allows the task to check if the client disconnected + while waiting for the response at strategic points in the execution and to + cancel the operation. + + Default: ``0`` + ``--[no-]log-socket-errors`` Toggle whether premature client disconnect tracebacks ought to be logged. On by default. diff --git a/src/waitress/runner.py b/src/waitress/runner.py index 8d8de4cd..90f42970 100644 --- a/src/waitress/runner.py +++ b/src/waitress/runner.py @@ -63,6 +63,19 @@ A wildcard for the hostname is also supported and will bind to both IPv4/IPv6 depending on whether they are enabled or disabled. + --server-name=NAME + This is the value that will be placed in the WSGI environment as + ``SERVER_NAME``, the only time that this value is used in the WSGI + environment for a request is if the client sent a HTTP/1.0 request + without a ``Host`` header set, and no other proxy headers. + + The default is value is ``waitress.invalid``, if your WSGI application + is creating URL's that include this as the hostname and you are using a + reverse proxy setup, you may want to validate that your reverse proxy + is sending the appropriate headers. + + In most situations you will not need to set this value. + --[no-]ipv4 Toggle on/off IPv4 support. @@ -97,16 +110,82 @@ Default wsgi.url_scheme value, default is 'http'. --url-prefix=STR - The ``SCRIPT_NAME`` WSGI environment value. Setting this to anything - except the empty string will cause the WSGI ``SCRIPT_NAME`` value to be + The 'SCRIPT_NAME' WSGI environment value. Setting this to anything + except the empty string will cause the WSGI 'SCRIPT_NAME' value to be the value passed minus any trailing slashes you add, and it will cause - the ``PATH_INFO`` of any request which is prefixed with this value to - be stripped of the prefix. Default is the empty string. + the 'PATH_INFO' of any request which is prefixed with this value to be + stripped of the prefix. Default is the empty string. --ident=STR Server identity used in the 'Server' header in responses. Default is 'waitress'. + --trusted-proxy=IP + IP address of a remote peer allowed to override various WSGI environment + variables using proxy headers. + + For unix sockets, set this value to 'localhost' instead of an IP + address. + + The value '*' (wildcard) may be used to signify that all remote peers + are to be trusted. + + --trusted-proxy-count=INT + How many proxies we trust when chained. For example, + + X-Forwarded-For: 192.0.2.1, "[2001:db8::1]" + + or + + Forwarded: for=192.0.2.1, For="[2001:db8::1]" + + means there were (potentially), two proxies involved. If we know there + is only 1 valid proxy, then that initial IP address "192.0.2.1" is not + trusted and we completely ignore it. + + If there are two trusted proxies in the path, this value should be set + to 2. If there are more proxies, this value should be set higher. + + Default: 1 + + --trusted_proxy_headers=LIST + Which of the proxy headers should we trust, this is a set where you + either specify "forwarded" or one or more of "x-forwarded-host", + "x-forwarded-for", "x-forwarded-proto", "x-forwarded-port", + "x-forwarded-by". + + This list of trusted headers is used when 'trusted_proxy' is set and + will allow waitress to modify the WSGI environment using the values + provided by the proxy. + + It is an error to set this value without setting --trusted-proxy. + + WARNING: If --trusted-proxy is set, the default is 'x-forwarded-proto' + to match older versions of Waitress. Users should explicitly opt-in by + selecting the headers to be trusted as future versions of waitress will + use an empty default. + + --[no-]log-untrusted-proxy-headers + Should waitress log warning messages about proxy headers that are being + sent from upstream that are not trusted by --trusted-proxy-headers but + are being cleared due to --clear-untrusted-proxy-headers? + + This may be useful for debugging if you expect your upstream proxy + server to only send specific headers. + + It is a no-op to set this value without also setting + --clear-untrusted-proxy-headers and --trusted-proxy. + + --[no-]clear-untrusted-proxy-headers + This tells Waitress to remove any untrusted proxy headers ("Forwarded", + "X-Forwared-For", "X-Forwarded-By", "X-Forwarded-Host", + "X-Forwarded-Port", "X-Forwarded-Proto") not explicitly allowed by + --trusted-proxy-headers. + + This is active by default. + + It is an error to set this value without setting --trusted-proxy. + Tuning options: --threads=INT @@ -149,6 +228,18 @@ Default is 120. 'Inactive' is defined as 'has received no data from the client and has sent no data to the client'. + --channel-request-lookahead=INT + Sets the amount of requests we can continue to read from the socket, + while we are processing current requests. The default value won't allow + any lookahead, increase it above '0' to enable. + + When enabled this inserts a callable 'waitress.client_disconnected' + into the environment that allows the task to check if the client + disconnected while waiting for the response at strategic points in the + execution and to cancel the operation. + + Default: '0' + --[no-]log-socket-errors Toggle whether premature client disconnect tracebacks ought to be logged. On by default. @@ -168,7 +259,7 @@ The timeout value in seconds passed to asyncore.loop(). Default is 1. --asyncore-use-poll - The use_poll argument passed to ``asyncore.loop()``. Helps overcome + The use_poll argument passed to asyncore.loop(). Helps overcome open file descriptors limit. Default is False. --channel-request-lookahead=INT