Dedicated routers

class uwsgiconf.options.routing_routers.RouterBase(on=None)
Parameters:on (SocketShared|str) – Activates the router on the given address.
class uwsgiconf.options.routing_routers.Forwarder(*args)
class uwsgiconf.options.routing_routers.ForwarderPath(sockets_dir)

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

Examples:
  • /tmp/sockets/
  • /tmp/sockets/%s/uwsgi.sock
Parameters:sockets_dir (str) – UNIX sockets directory. Allows %s to denote key (domain).
class uwsgiconf.options.routing_routers.ForwarderCode(script, func, *, modifier=None)

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!

Parameters:
  • script (str) – Script (module for Python) name to get function from.
  • func (str) – Function name.
  • modifier (Modifier) – Routing modifier.
class uwsgiconf.options.routing_routers.ForwarderCache(cache_name=None)

Uses uWSGI cache to get target nodes from.

Parameters:cache_name (str) – Cache name to use.
class uwsgiconf.options.routing_routers.ForwarderSocket(socket)

Forwards request to the specified uwsgi socket.

Parameters:socket (str) – Socket filepath.
class uwsgiconf.options.routing_routers.ForwarderSubscriptionServer(address)

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().

Parameters:address (str) – Address (including port) to run the subscription server on.
class uwsgiconf.options.routing_routers.RouterHttp(on=None, *, forward_to=None)

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

The server can be used in two ways:

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

Activates the router on the given address.

Parameters:
  • on (SocketShared|str) – Activates the router on the given address.
  • forward_to (Forwarder|str|list[str]) – Where to forward requests. Expects a forwarder instance or one or more node names.
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, keepalive=None, resubscribe_addresses=None)
Parameters:
  • workers (int) – Number of worker processes to spawn.
  • zerg_server (str) – Attach the router to a zerg server.
  • fallback_node (str) – Fallback to the specified node in case of error.
  • concurrent_events (int) –

    Set the maximum number of concurrent events router can manage.

    Default: system dependent.

  • cheap_mode (bool) – 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 of the nodes go down, the router will return in cheap mode.
  • stats_server (str) – Router stats server address to run at.
  • quiet (bool) – Do not report failed connections to instances.
  • buffer_size (int) – Set internal buffer size in bytes. Default: page size.
  • keepalive (int) –

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

    Note

    See http11 socket type for an alternative.

  • resubscribe_addresses (str|list[str]) – Forward subscriptions to the specified subscription server.
set_connections_params(*, harakiri=None, timeout_socket=None, retry_delay=None, timeout_headers=None, timeout_backend=None)

Sets connection-related parameters.

Parameters:
  • harakiri (int) – Set gateway harakiri timeout (seconds).
  • timeout_socket (int) –

    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.

  • retry_delay (int) – Retry connections to dead static nodes after the specified amount of seconds. Default: 30.
  • timeout_headers (int) –

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

    Default: socket_timeout.

  • timeout_backend (int) –

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

    Default: socket_timeout.
set_manage_params(*, chunked_input=None, chunked_output=None, gzip=None, websockets=None, source_method=None, rtsp=None, proxy_protocol=None)

Allows enabling various automatic management mechanics.

Parameters:
  • chunked_input (bool) – Automatically detect chunked input requests and put the session in raw mode.
  • chunked_output (bool) – Automatically transform output to chunked encoding during HTTP 1.1 keepalive (if needed).
  • gzip (bool) – Automatically gzip content if uWSGI-Encoding header is set to gzip, but content size (Content-Length/Transfer-Encoding) and Content-Encoding are not specified.
  • websockets (bool) – Automatically detect websockets connections and put the session in raw mode.
  • source_method (bool) –

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

  • rtsp (bool) – Allow the HTTP router to detect RTSP and chunked requests automatically.
  • proxy_protocol (bool) – Allows the HTTP router to manage PROXY1 protocol requests, such as those made by Haproxy or Amazon Elastic Load Balancer (ELB).
set_owner_params(uid=None, gid=None)

Drop http router privileges to specified user and group.

Parameters:
  • uid (str|int) – Set uid to the specified username or uid.
  • gid (str|int) – Set gid to the specified groupname or gid.
class uwsgiconf.options.routing_routers.RouterHttps(on, *, cert, key, ciphers=None, client_ca=None, session_context=None, use_spdy=None, export_cert_var=None)

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

The server can be used in two ways:

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

Binds https router to run on the given address.

Parameters:
class uwsgiconf.options.routing_routers.RouterSsl(on, cert, key, forward_to=None, ciphers=None, client_ca=None, session_context=None, use_sni=None)

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

Supports SNI for implementing virtual hosting.

Activates the router on the given address.

Parameters:
set_connections_params(harakiri=None, timeout_socket=None, retry_delay=None, retry_max=None)

Sets connection-related parameters.

Parameters:
  • harakiri (int) – Set gateway harakiri timeout (seconds).
  • timeout_socket (int) – Node socket timeout (seconds). Default: 60.
  • retry_delay (int) – Retry connections to dead static nodes after the specified amount of seconds. Default: 30.
  • retry_max (int) – Maximum number of retries/fallbacks to other nodes. Default: 3.
class uwsgiconf.options.routing_routers.RouterFast(on=None, *, forward_to=None)

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.

Activates the router on the given address.

Parameters:
  • on (SocketShared|str) – Activates the router on the given address.
  • forward_to (Forwarder|str|list[str]) – Where to forward requests. Expects a forwarder instance or one or more node names.
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)
Parameters:
  • workers (int) – Number of worker processes to spawn.
  • zerg_server (str) – Attach the router to a zerg server.
  • fallback_node (str) – Fallback to the specified node in case of error.
  • concurrent_events (int) –

    Set the maximum number of concurrent events router can manage.

    Default: system dependent.

  • cheap_mode (bool) – 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 of the nodes go down, the router will return in cheap mode.
  • stats_server (str) – Router stats server address to run at.
  • quiet (bool) – Do not report failed connections to instances.
  • buffer_size (int) – Set internal buffer size in bytes. Default: page size.
  • fallback_nokey (bool) – Move to fallback node even if a subscription key is not found.
  • subscription_key (str) – Skip uwsgi parsing and directly set a key.
  • emperor_command_socket (str) –

    Set the emperor command socket that will receive spawn commands.

    See .empire.set_emperor_command_params().
set_resubscription_params(addresses=None, bind_to=None)

You can specify a dgram address (udp or unix) on which all of 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.

Parameters:
  • addresses (str|list[str]) – Forward subscriptions to the specified subscription server.
  • bind_to (str|list[str]) – Bind to the specified address when re-subscribing.
set_connections_params(harakiri=None, timeout_socket=None, retry_delay=None, retry_max=None, defer=None)

Sets connection-related parameters.

Parameters:
  • harakiri (int) – Set gateway harakiri timeout (seconds).
  • timeout_socket (int) – Node socket timeout (seconds). Default: 60.
  • retry_delay (int) – Retry connections to dead static nodes after the specified amount of seconds. Default: 30.
  • retry_max (int) – Maximum number of retries/fallbacks to other nodes. Default: 3
  • defer (int) – Defer connection delay, seconds. Default: 5.
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.

Parameters:
  • size (int) – The size (in bytes) of the request body after which the body will be stored to disk (as a temporary file) instead of memory.
  • store_dir (str) – Put buffered files to the specified directory. Default: TMPDIR, /tmp/
set_owner_params(uid=None, gid=None)

Drop http router privileges to specified user and group.

Parameters:
  • uid (str|int) – Set uid to the specified username or uid.
  • gid (str|int) – Set gid to the specified groupname or gid.
class uwsgiconf.options.routing_routers.RouterRaw(on=None, *, forward_to=None)

A pure-TCP load balancer.

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

Activates the router on the given address.

Parameters:
  • on (SocketShared|str) – Activates the router on the given address.
  • forward_to (Forwarder|str|list[str]) – Where to forward requests. Expects a forwarder instance or one or more node names.
set_connections_params(harakiri=None, timeout_socket=None, retry_delay=None, retry_max=None, use_xclient=None)

Sets connection-related parameters.

Parameters:
  • harakiri (int) – Set gateway harakiri timeout (seconds).
  • timeout_socket (int) – Node socket timeout (seconds). Default: 60.
  • retry_delay (int) – Retry connections to dead static nodes after the specified amount of seconds. Default: 30.
  • retry_max (int) – Maximum number of retries/fallbacks to other nodes. Default: 3.
  • use_xclient (bool) – Use the xclient protocol to pass the client address.
class uwsgiconf.options.routing_routers.RouterForkPty(on=None, undeferred=False)

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.

Binds router to run on the given address.

Parameters:
  • on (SocketShared|str) – Activates the router on the given address.
  • undeferred (bool) – Run router in undeferred mode.
set_basic_params(*, workers=None, zerg_server=None, fallback_node=None, concurrent_events=None, cheap_mode=None, stats_server=None, run_command=None)
Parameters:
  • workers (int) – Number of worker processes to spawn.
  • zerg_server (str) – Attach the router to a zerg server.
  • fallback_node (str) – Fallback to the specified node in case of error.
  • concurrent_events (int) –

    Set the maximum number of concurrent events router can manage.

    Default: system dependent.

  • cheap_mode (bool) – 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 of the nodes go down, the router will return in cheap mode.
  • stats_server (str) – Router stats server address to run at.
  • run_command (str) – Run the specified command on every connection. Default: /bin/sh.
set_connections_params(*, harakiri=None, timeout_socket=None)

Sets connection-related parameters.

Parameters:
  • harakiri (int) – Set gateway harakiri timeout (seconds).
  • timeout_socket (int) – Node socket timeout (seconds). Default: 60.
set_window_params(cols=None, rows=None)

Sets pty window params.

Parameters:
  • cols (int) –
  • rows (int) –
class uwsgiconf.options.routing_routers.RouterTunTap(on=None, *, device=None, stats_server=None, gateway=None)

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.

Passing params will create a router device.

Parameters:
  • on (str) – Socket file.
  • device (str) – Device name.
  • stats_server (str) – Router stats server address to run at.
  • gateway (str) – Gateway address.
set_basic_params(*, use_credentials=None, stats_server=None)
Parameters:
  • use_credentials (str) – Enable check of SCM_CREDENTIALS for tuntap client/server.
  • stats_server (str) – Router stats server address to run at.
register_route(src, dst, *, gateway)

Adds a routing rule to the tuntap router.

Parameters:
  • src (str) – Source/mask.
  • dst (str) – Destination/mask.
  • gateway (str) – Gateway address.
device_connect(socket, *, device_name)

Add a tuntap device to the instance.

To be used in a vassal.

Parameters:
  • socket (str) –

    Router socket.

    Example: /run/tuntap_router.socket.

  • device_name (str) –

    Device.

    Example: uwsgi0.
device_add_rule(*, direction, action, src, dst, target=None)

Adds a tuntap device rule.

To be used in a vassal.

Parameters:
  • direction (str) –

    Direction:

    • in
    • out.
  • action (str) –

    Action:

    • allow
    • deny
    • route
    • gateway.
  • src (str) – Source/mask.
  • dst (str) – Destination/mask.
  • target (str) –

    Depends on action.

    • Route / Gateway: Accept addr:port
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”.

Parameters:
  • direction (str) –

    Direction:

    • in
    • out
  • action (str) –

    Action:

    • allow
    • deny
  • src (str) – Source/mask.
  • dst (str) – Destination/mask