Arguments to waitress.serve

Here are the arguments you can pass to the waitress.serve function or use in PasteDeploy configuration (interchangeably):

host

Hostname or IP address (string) on which to listen, default 0.0.0.0, which means "all IP addresses on this host".

Warning

May not be used with listen

port

TCP port (integer) on which to listen, default 8080

Warning

May not be used with listen

listen

Tell waitress to listen on combinations of host:port arguments. Combinations should be a quoted, space-delimited list, as in the following examples.

listen="127.0.0.1:8080 [::1]:8080"
listen="*:8080 *:6543"

A wildcard for the hostname is also supported and will bind to both IPv4/IPv6 depending on whether they are enabled or disabled.

IPv6 IP addresses are supported by surrounding the IP address with brackets.

New in version 1.0.

server_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.

Default: waitress.invalid

New in version 2.0.

ipv4

Enable or disable IPv4 (boolean)

ipv6

Enable or disable IPv6 (boolean)

unix_socket

Path of Unix socket (string). If a socket path is specified, a Unix domain socket is made instead of the usual inet domain socket.

Not available on Windows.

Default: None

unix_socket_perms

Octal permissions to use for the Unix domain socket (string). Only used if unix_socket is not None.

Default: '600'

sockets

A list of sockets. The sockets can be either Internet or UNIX sockets and have to be bound. Internet and UNIX sockets cannot be mixed. If the socket list is not empty, waitress creates one server for each socket.

Default: []

New in version 1.1.1.

Warning

May not be used with listen, host, port or unix_socket

threads

The number of threads used to process application logic (integer).

Default: 4

trusted_proxy

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.

Default: None

trusted_proxy_count

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

New in version 1.2.0.

trusted_proxy_headers

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.

New in version 1.2.0.

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.

Warning

It is an error to set this value without setting trusted_proxy.

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.

Default: False

New in version 1.2.0.

Warning

It is a no-op to set this value without also setting clear_untrusted_proxy_headers and trusted_proxy

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.

Default: False

New in version 1.2.0.

Warning

The default value is set to False for backwards compatibility. In future versions of Waitress this default will be changed to True. Warnings will be raised unless the user explicitly provides a value for this option, allowing the user to opt-in to the new safety features automatically.

Warning

It is an error to set this value without setting trusted_proxy.

url_scheme

The value of wsgi.url_scheme in the environ. This can be overridden per-request by the value of the X_FORWARDED_PROTO header, but only if the client address matches trusted_proxy.

Default: http

ident

Server identity (string) used in "Server:" header in responses.

Default: waitress

backlog

The value waitress passes to pass to socket.listen() (integer). This is the maximum number of incoming TCP connections that will wait in an OS queue for an available channel. From listen(1): "If a connection request arrives when the queue is full, the client may receive an error with an indication of ECONNREFUSED or, if the underlying protocol supports retransmission, the request may be ignored so that a later reattempt at connection succeeds."

Default: 1024

recv_bytes

The argument waitress passes to socket.recv() (integer).

Default: 8192

send_bytes

The number of bytes to send to socket.send() (integer). Multiples of 9000 should avoid partly-filled TCP packets, but don't set this larger than the TCP write buffer size. In Linux, /proc/sys/net/ipv4/tcp_wmem controls the minimum, default, and maximum sizes of TCP write buffers.

Default: 1

Deprecated since version 1.3.

outbuf_overflow

A tempfile should be created if the pending output is larger than outbuf_overflow, which is measured in bytes. The default is conservative.

Default: 1048576 (1MB)

outbuf_high_watermark

The app_iter will pause when pending output is larger than this value and will resume once enough data is written to the socket to fall below this threshold.

Default: 16777216 (16MB)

inbuf_overflow

A tempfile should be created if the pending input is larger than inbuf_overflow, which is measured in bytes. The default is conservative.

Default: 524288 (512K)

connection_limit

Stop creating new channels if too many are already active (integer). Each channel consumes at least one file descriptor, and, depending on the input and output body sizes, potentially up to three, plus whatever file descriptors your application logic happens to open. The default is conservative, but you may need to increase the number of file descriptors available to the Waitress process on most platforms in order to safely change it (see ulimit -a "open files" setting). Note that this doesn't control the maximum number of TCP connections that can be waiting for processing; the backlog argument controls that.

Default: 100

cleanup_interval

Minimum seconds between cleaning up inactive channels (integer). See also channel_timeout.

Default: 30

channel_timeout

Maximum seconds to leave an inactive connection open (integer). "Inactive" is defined as "has received no data from a client and has sent no data to a client".

Default: 120

log_socket_errors

Set to False to not log premature client disconnect tracebacks.

Default: True

max_request_header_size

Maximum number of bytes of all request headers combined (integer).

Default: 262144 (256K)

max_request_body_size

Maximum number of bytes in request body (integer).

Default: 1073741824 (1GB)

expose_tracebacks

Set to True to expose tracebacks of unhandled exceptions to client.

Default: False

asyncore_loop_timeout

The timeout value (seconds) passed to asyncore.loop to run the mainloop.

Default: 1

New in version 0.8.3.

asyncore_use_poll

Set to True to switch from using select() to poll() in asyncore.loop. By default asyncore.loop() uses select() which has a limit of 1024 file descriptors. select() and poll() provide basically the same functionality, but poll() doesn't have the file descriptors limit.

Default: False

New in version 0.8.6.

url_prefix

String: the value used as the WSGI SCRIPT_NAME 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: ''