Skip to content

Dedicated routers

Classes

ForwarderCache

1
ForwarderCache(cache_name: str | None = None)

Forwarder

Uses uWSGI cache to get target nodes from.

alias 

1
.alias: str = ''

Alias to address this value.

args_joiner 

1
.args_joiner: str = ' '

Symbol to join arguments with.

name_separator 

1
.name_separator: str = ':'

Separator to add after name portion.

name_separator_strip 

1
.name_separator_strip: bool = False

Strip leading and trailing name separator from the result.

plugin 

1
.plugin: bool | str = False

Indication this option group belongs to a plugin.

ForwarderCode

1
ForwarderCode(script: str, func: str, modifier: Modifier = None)

Forwarder

Forwards requests to nodes returned by a function.

This allows using user defined functions to calculate. Function must accept key (domain).

Warning

Remember to not put blocking code in your functions. The router is totally non-blocking, do not ruin it!

alias 

1
.alias: str = ''

Alias to address this value.

name_separator 

1
.name_separator: str = ':'

Separator to add after name portion.

name_separator_strip 

1
.name_separator_strip: bool = False

Strip leading and trailing name separator from the result.

plugin 

1
.plugin: bool | str = False

Indication this option group belongs to a plugin.

ForwarderPath

1
ForwarderPath(sockets_dir: str)

Forwarder

Use the specified base (allows %s pattern) for mapping requests to UNIX sockets.

Examples: * /tmp/sockets/ * /tmp/sockets/%s/uwsgi.sock

alias 

1
.alias: str = ''

Alias to address this value.

args_joiner 

1
.args_joiner: str = ' '

Symbol to join arguments with.

name_separator 

1
.name_separator: str = ':'

Separator to add after name portion.

name_separator_strip 

1
.name_separator_strip: bool = False

Strip leading and trailing name separator from the result.

plugin 

1
.plugin: bool | str = False

Indication this option group belongs to a plugin.

ForwarderSocket

1
ForwarderSocket(socket: str)

Forwarder

Forwards request to the specified uwsgi socket.

alias 

1
.alias: str = ''

Alias to address this value.

args_joiner 

1
.args_joiner: str = ' '

Symbol to join arguments with.

name_separator 

1
.name_separator: str = ':'

Separator to add after name portion.

name_separator_strip 

1
.name_separator_strip: bool = False

Strip leading and trailing name separator from the result.

plugin 

1
.plugin: bool | str = False

Indication this option group belongs to a plugin.

ForwarderSubscriptionServer

1
ForwarderSubscriptionServer(address: str)

Forwarder

Forwards requests to nodes returned by the subscription server.

Subscriptions are simple UDP packets that instruct the router which domain maps to which instance or instances.

To subscribe to such a subscription server use .subscriptions.subscribe().

alias 

1
.alias: str = ''

Alias to address this value.

args_joiner 

1
.args_joiner: str = ' '

Symbol to join arguments with.

name_separator 

1
.name_separator: str = ':'

Separator to add after name portion.

name_separator_strip 

1
.name_separator_strip: bool = False

Strip leading and trailing name separator from the result.

plugin 

1
.plugin: bool | str = False

Indication this option group belongs to a plugin.

RouterFast

1
RouterFast(on: StrShaSoc = None, forward_to: ForwStrlist = None)

_RouterWithForwarders

A proxy/load-balancer/router speaking the uwsgi protocol.

You can put it between your webserver and real uWSGI instances to have more control over the routing of HTTP requests to your application servers.

name 

1
.name: str = ''

Name to represent the group.

set_basic_params

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
.set_basic_params(
    workers=None, 
    zerg_server=None, 
    fallback_node=None, 
    concurrent_events=None, 
    cheap_mode=None, 
    stats_server=None, 
    quiet=None, 
    buffer_size=None, 
    fallback_nokey=None, 
    subscription_key=None, 
    emperor_command_socket=None
)

set_connections_params

1
2
3
4
5
6
7
.set_connections_params(
    harakiri=None, 
    timeout_socket=None, 
    retry_delay=None, 
    retry_max=None, 
    defer=None
)

Sets connection-related parameters.

set_owner_params

1
.set_owner_params(uid=None, gid=None)

Drop http router privileges to specified user and group.

set_postbuffering_params

1
.set_postbuffering_params(size=None, store_dir=None)

Sets buffering params.

Web-proxies like nginx are "buffered", so they wait til the whole request (and its body) has been read, and then it sends it to the backends.

set_resubscription_params

1
.set_resubscription_params(addresses=None, bind_to=None)

You can specify a dgram address (udp or unix) on which all the subscriptions request will be forwarded to (obviously changing the node address to the router one).

The system could be useful to build 'federated' setup.

forwarders 

1
.forwarders()

Forwarders are kind of registries containing information on where to forward requests.

RouterForkPty

1
RouterForkPty(on: StrShaSoc = None, undeferred=False)

_RouterCommon

Allows allocation of pseudoterminals in jails.

Dealing with containers is now a common deployment pattern. One of the most annoying tasks when dealing with jails/namespaces is 'attaching' to already running instances. The forkpty router aims at simplifyng the process giving a pseudoterminal server to your uWSGI instances. A client connect to the socket exposed by the forkpty router and get a new pseudoterminal connected to a process (generally a shell, but can be whatever you want).

Note

To be used in cooperation with pty plugin.

name 

1
.name: str = ''

Name to represent the group.

set_basic_params

1
2
3
4
5
6
7
8
9
.set_basic_params(
    workers=None, 
    zerg_server=None, 
    fallback_node=None, 
    concurrent_events=None, 
    cheap_mode=None, 
    stats_server=None, 
    run_command=None
)

set_connections_params

1
.set_connections_params(harakiri=None, timeout_socket=None)

Sets connection-related parameters.

set_window_params

1
.set_window_params(cols=None, rows=None)

Sets pty window params.

RouterHttp

1
RouterHttp(on: StrShaSoc = None, forward_to: ForwStrlist = None)

_RouterWithForwarders

uWSGI includes an HTTP router/proxy/load-balancer that can forward requests to uWSGI workers.

The server can be used in two ways:

1
2
3
4
* embedded - automatically spawn workers and setup the communication socket
* standalone - you have to specify the address of a uwsgi socket to connect to

    See `subscribe_to` argument to `.set_basic_params()`

Note

If you want to go massive (virtualhosting and zero-conf scaling) combine the HTTP router with the uWSGI Subscription Server.

name 

1
.name: str = ''

Name to represent the group.

set_basic_params

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
.set_basic_params(
    workers: int | None = None,  # (1)!
    zerg_server: str | None = None,  # (2)!
    fallback_node: str | None = None,  # (3)!
    concurrent_events: int | None = None,  # (4)!
    cheap_mode: bool | None = None,  # (5)!
    stats_server: str | None = None,  # (6)!
    quiet: bool | None = None,  # (7)!
    buffer_size: int | None = None,  # (8)!
    keepalive: int | None = None,  # (9)!
    resubscribe_addresses: Strlist = None,  # (10)!
)

  1. Number of worker processes to spawn.

  2. Attach the router to a zerg server.

  3. Fallback to the specified node in case of error.

  4. Set the maximum number of concurrent events router can manage.

    1
    Default: system dependent.

  5. Enables cheap mode. When the router is in cheap mode, it will not respond to requests until a node is available. This means that when there are no nodes subscribed, only your local app (if any) will respond. When all the nodes go down, the router will return in cheap mode.

  6. Router stats server address to run at.

  7. Do not report failed connections to instances.

  8. Set internal buffer size in bytes. Default: page size.

  9. Allows holding the connection open even if the request has a body.

    1
2
3
    * <http://uwsgi.readthedocs.io/en/latest/HTTP.html#http-keep-alive>

.. note:: See http11 socket type for an alternative.

  10. Forward subscriptions to the specified subscription server.

set_connections_params

1
2
3
4
5
6
7
.set_connections_params(
    harakiri: int | None = None,  # (1)!
    timeout_socket: int | None = None,  # (2)!
    retry_delay: int | None = None,  # (3)!
    timeout_headers: int | None = None,  # (4)!
    timeout_backend: int | None = None,  # (5)!
)

  1. Set gateway harakiri timeout (seconds).

  2. Node socket timeout (seconds). Used to set the SPDY timeout. This is the maximum amount of inactivity after the SPDY connection is closed.

    Default: 60.

  3. Retry connections to dead static nodes after the specified amount of seconds. Default: 30.

  4. Defines the timeout (seconds) while waiting for http headers.

    1
    Default: `socket_timeout`.

  5. Defines the timeout (seconds) when connecting to backend instances.

    1
    Default: `socket_timeout`.

Sets connection-related parameters.

set_manage_params

1
2
3
4
5
6
7
8
9
.set_manage_params(
    chunked_input: bool | None = None,  # (1)!
    chunked_output: bool | None = None,  # (2)!
    gzip: bool | None = None,  # (3)!
    websockets: bool | None = None,  # (4)!
    source_method: bool | None = None,  # (5)!
    rtsp: bool | None = None,  # (6)!
    proxy_protocol: bool | None = None,  # (7)!
)

  1. Automatically detect chunked input requests and put the session in raw mode.

  2. Automatically transform output to chunked encoding during HTTP 1.1 keepalive (if needed).

  3. Automatically gzip content if uWSGI-Encoding header is set to gzip, but content size (Content-Length/Transfer-Encoding) and Content-Encoding are not specified.

  4. Automatically detect websockets connections and put the session in raw mode.

  5. Automatically put the session in raw mode for SOURCE HTTP method.

    1
    * <http://uwsgi.readthedocs.io/en/latest/Changelog-2.0.5.html#icecast2-protocol-helpers>

  6. Allow the HTTP router to detect RTSP and chunked requests automatically.

  7. Allows the HTTP router to manage PROXY1 protocol requests, such as those made by Haproxy or Amazon Elastic Load Balancer (ELB).

Allows enabling various automatic management mechanics.

set_owner_params

1
2
3
4
.set_owner_params(
    uid: Strint = None,  # (1)!
    gid: Strint = None,  # (2)!
)

  1. Set uid to the specified username or uid.

  2. Set gid to the specified groupname or gid.

Drop http router privileges to specified user and group.

forwarders 

1
.forwarders()

Forwarders are kind of registries containing information on where to forward requests.

RouterHttps

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
RouterHttps(
    on: StrShaSoc, 
    cert: str, 
    key: str, 
    ciphers: str | None = None, 
    client_ca: str | None = None, 
    session_context: str | None = None, 
    use_spdy: bool | None = None, 
    export_cert_var: bool | None = None
)

RouterHttp

uWSGI includes an HTTPS router/proxy/load-balancer that can forward requests to uWSGI workers.

The server can be used in two ways:

1
2
3
4
* embedded - automatically spawn workers and setup the communication socket
* standalone - you have to specify the address of a uwsgi socket to connect to

    See `subscribe_to` argument to `.set_basic_params()`

Note

If you want to go massive (virtualhosting and zero-conf scaling) combine the HTTP router with the uWSGI Subscription Server.

name 

1
.name: str = ''

Name to represent the group.

set_basic_params 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
.set_basic_params(
    workers: int | None = None,  # (1)!
    zerg_server: str | None = None,  # (2)!
    fallback_node: str | None = None,  # (3)!
    concurrent_events: int | None = None,  # (4)!
    cheap_mode: bool | None = None,  # (5)!
    stats_server: str | None = None,  # (6)!
    quiet: bool | None = None,  # (7)!
    buffer_size: int | None = None,  # (8)!
    keepalive: int | None = None,  # (9)!
    resubscribe_addresses: Strlist = None,  # (10)!
)

  1. Number of worker processes to spawn.

  2. Attach the router to a zerg server.

  3. Fallback to the specified node in case of error.

  4. Set the maximum number of concurrent events router can manage.

    1
    Default: system dependent.

  5. Enables cheap mode. When the router is in cheap mode, it will not respond to requests until a node is available. This means that when there are no nodes subscribed, only your local app (if any) will respond. When all the nodes go down, the router will return in cheap mode.

  6. Router stats server address to run at.

  7. Do not report failed connections to instances.

  8. Set internal buffer size in bytes. Default: page size.

  9. Allows holding the connection open even if the request has a body.

    1
2
3
    * <http://uwsgi.readthedocs.io/en/latest/HTTP.html#http-keep-alive>

.. note:: See http11 socket type for an alternative.

  10. Forward subscriptions to the specified subscription server.

set_connections_params 

1
2
3
4
5
6
7
.set_connections_params(
    harakiri: int | None = None,  # (1)!
    timeout_socket: int | None = None,  # (2)!
    retry_delay: int | None = None,  # (3)!
    timeout_headers: int | None = None,  # (4)!
    timeout_backend: int | None = None,  # (5)!
)

  1. Set gateway harakiri timeout (seconds).

  2. Node socket timeout (seconds). Used to set the SPDY timeout. This is the maximum amount of inactivity after the SPDY connection is closed.

    Default: 60.

  3. Retry connections to dead static nodes after the specified amount of seconds. Default: 30.

  4. Defines the timeout (seconds) while waiting for http headers.

    1
    Default: `socket_timeout`.

  5. Defines the timeout (seconds) when connecting to backend instances.

    1
    Default: `socket_timeout`.

Sets connection-related parameters.

set_manage_params 

1
2
3
4
5
6
7
8
9
.set_manage_params(
    chunked_input: bool | None = None,  # (1)!
    chunked_output: bool | None = None,  # (2)!
    gzip: bool | None = None,  # (3)!
    websockets: bool | None = None,  # (4)!
    source_method: bool | None = None,  # (5)!
    rtsp: bool | None = None,  # (6)!
    proxy_protocol: bool | None = None,  # (7)!
)

  1. Automatically detect chunked input requests and put the session in raw mode.

  2. Automatically transform output to chunked encoding during HTTP 1.1 keepalive (if needed).

  3. Automatically gzip content if uWSGI-Encoding header is set to gzip, but content size (Content-Length/Transfer-Encoding) and Content-Encoding are not specified.

  4. Automatically detect websockets connections and put the session in raw mode.

  5. Automatically put the session in raw mode for SOURCE HTTP method.

    1
    * <http://uwsgi.readthedocs.io/en/latest/Changelog-2.0.5.html#icecast2-protocol-helpers>

  6. Allow the HTTP router to detect RTSP and chunked requests automatically.

  7. Allows the HTTP router to manage PROXY1 protocol requests, such as those made by Haproxy or Amazon Elastic Load Balancer (ELB).

Allows enabling various automatic management mechanics.

set_owner_params 

1
2
3
4
.set_owner_params(
    uid: Strint = None,  # (1)!
    gid: Strint = None,  # (2)!
)

  1. Set uid to the specified username or uid.

  2. Set gid to the specified groupname or gid.

Drop http router privileges to specified user and group.

forwarders 

1
.forwarders()

Forwarders are kind of registries containing information on where to forward requests.

RouterRaw

1
RouterRaw(on: StrShaSoc = None, forward_to: ForwStrlist = None)

_RouterWithForwarders

A pure-TCP load balancer.

Can be used to load balance between the various HTTPS routers.

name 

1
.name: str = ''

Name to represent the group.

set_basic_params 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
.set_basic_params(
    workers: int | None = None,  # (1)!
    zerg_server: str | None = None,  # (2)!
    fallback_node: str | None = None,  # (3)!
    concurrent_events: int | None = None,  # (4)!
    cheap_mode: bool | None = None,  # (5)!
    stats_server: str | None = None,  # (6)!
    quiet: bool | None = None,  # (7)!
    buffer_size: int | None = None,  # (8)!
)

  1. Number of worker processes to spawn.

  2. Attach the router to a zerg server.

  3. Fallback to the specified node in case of error.

  4. Set the maximum number of concurrent events router can manage.

    1
    Default: system dependent.

  5. Enables cheap mode. When the router is in cheap mode, it will not respond to requests until a node is available. This means that when there are no nodes subscribed, only your local app (if any) will respond. When all the nodes go down, the router will return in cheap mode.

  6. Router stats server address to run at.

  7. Do not report failed connections to instances.

  8. Set the internal buffer size (default: page size).

set_connections_params

1
2
3
4
5
6
7
.set_connections_params(
    harakiri=None, 
    timeout_socket=None, 
    retry_delay=None, 
    retry_max=None, 
    use_xclient=None
)

Sets connection-related parameters.

forwarders 

1
.forwarders()

Forwarders are kind of registries containing information on where to forward requests.

RouterSsl

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
RouterSsl(
    on: StrShaSoc, 
    forward_to: ForwStrlist = None, 
    cert: str, 
    key: str, 
    ciphers: str | None = None, 
    client_ca: str | None = None, 
    session_context: str | None = None, 
    use_sni: bool | None = None
)

_RouterWithForwarders

Works in the same way as the RouterRaw, but will terminate ssl connections.

Supports SNI for implementing virtual hosting.

name 

1
.name: str = ''

Name to represent the group.

set_basic_params 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
.set_basic_params(
    workers: int | None = None,  # (1)!
    zerg_server: str | None = None,  # (2)!
    fallback_node: str | None = None,  # (3)!
    concurrent_events: int | None = None,  # (4)!
    cheap_mode: bool | None = None,  # (5)!
    stats_server: str | None = None,  # (6)!
    quiet: bool | None = None,  # (7)!
    buffer_size: int | None = None,  # (8)!
)

  1. Number of worker processes to spawn.

  2. Attach the router to a zerg server.

  3. Fallback to the specified node in case of error.

  4. Set the maximum number of concurrent events router can manage.

    1
    Default: system dependent.

  5. Enables cheap mode. When the router is in cheap mode, it will not respond to requests until a node is available. This means that when there are no nodes subscribed, only your local app (if any) will respond. When all the nodes go down, the router will return in cheap mode.

  6. Router stats server address to run at.

  7. Do not report failed connections to instances.

  8. Set the internal buffer size (default: page size).

set_connections_params

1
2
3
4
5
6
.set_connections_params(
    harakiri: int | None = None,  # (1)!
    timeout_socket: int | None = None,  # (2)!
    retry_delay: int | None = None,  # (3)!
    retry_max: int | None = None,  # (4)!
)

  1. Set gateway harakiri timeout (seconds).

  2. Node socket timeout (seconds). Default: 60.

  3. Retry connections to dead static nodes after the specified amount of seconds. Default: 30.

  4. Maximum number of retries/fallbacks to other nodes. Default: 3.

Sets connection-related parameters.

forwarders 

1
.forwarders()

Forwarders are kind of registries containing information on where to forward requests.

RouterTunTap

1
2
3
4
5
6
RouterTunTap(
    on=None, 
    device=None, 
    stats_server=None, 
    gateway=None
)

RouterBase

The tuntap router is a non-blocking highly optimized ip router translating from tuntap device to socket streams.

Allows full user-space networking in jails.

It is meant as a replacement for the currently available networking namespaces approaches. Compared to veth or macvlan it is really simple and allows total control over the routing subsystem (in addition to a simple customizable firewalling engine).

Generally you spawn the tuntap router in the Emperor instance. Vassals will run in new namespaces in which they create a tuntap device attached to the tuntap router. UNIX sockets are the only way to connect to the tuntap router after jailing.

Vassals should connect to tuntap device.

name 

1
.name: str = ''

Name to represent the group.

add_firewall_rule

1
.add_firewall_rule(direction, action, src=None, dst=None)

Adds a firewall rule to the router.

The TunTap router includes a very simple firewall for governing vassal's traffic. The first matching rule stops the chain, if no rule applies, the policy is "allow".

device_add_rule

1
2
3
4
5
6
7
.device_add_rule(
    direction, 
    action, 
    src, 
    dst, 
    target=None
)

Adds a tuntap device rule.

To be used in a vassal.

device_connect

1
.device_connect(socket, device_name)

Add a tuntap device to the instance.

To be used in a vassal.

register_route

1
.register_route(src, dst, gateway)

Adds a routing rule to the tuntap router.

set_basic_params

1
.set_basic_params(use_credentials=None, stats_server=None)