The uWSGI FastRouter

For advanced setups uWSGI includes the “fastrouter” plugin, a proxy/load-balancer/router speaking the uwsgi protocol. It is built in by default. 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.

Getting started

First of all you have to run the fastrouter, binding it to a specific address. Multiple addresses are supportd as well.

uwsgi --fastrouter --fastrouter /tmp/uwsgi.sock --fastrouter @foobar


This is the most useless Fastrouter setup in the world.

Congratulations! You have just run the most useless Fastrouter setup in the world. Simply binding the fastrouter to a couple of addresses will not instruct it on how to route requests. To give it intelligence you have to tell it how to route requests.

Way 1: –fastrouter-use-base

This option will tell the fastrouter to connect to a UNIX socket with the same name of the requested host in a specified directory.

uwsgi --fastrouter --fastrouter-use-base /tmp/sockets

If you receive a request for the fastrouter will forward the request to /tmp/sockets/

Way 2: –fastrouter-use-pattern

Same as the previous setup but you will be able to use a pattern, with %s mapping to the requested key/hostname.

uwsgi --fastrouter --fastrouter-use-base /tmp/sockets/%s/uwsgi.sock

Requests for will be mapped to /tmp/sockets/

Way 3: –fastrouter-use-cache

You can store the key/value mappings in the uWSGI cache. Choose a way to fill the cache, for instance a Python script like this...

import uwsgi
# Requests for on port 8000 will go to
uwsgi.cache_set("", "")
# Requests for will go to with the modifier1 set to 5 (perl/PSGI)
uwsgi.cache_set("", ",5")

Then run your Fastrouter-enabled server, telling it to run the script first.

uwsgi --fastrouter --fastrouter-use-cache --cache 100 --file

Way 4: –fastrouter-subscription-server

This is probably one of the best way for massive auto-scaling hosting. It uses the subscription server to allow instances to announce themselves and subscribe to the fastrouter.

uwsgi --fastrouter --fastrouter-subscription-server

This will spawn a subscription server on address port 7000

Now you can spawn your instances subscribing to the fastrouter:

uwsgi --socket :3031 -M --subscribe-to
uwsgi --socket :3032 -M --subscribe-to,5 --subscribe-to

As you probably noted, you can subscribe to multiple fastrouters, with multiple keys. Multiple instances subscribing to the same fastrouter with the same key will automatically get load balanced and monitored. Handy, isn’t it? Like with the caching key/value store, modifier1 can be set with a comma. (,5 above) Another feature of the subscription system is avoiding to choose ports. You can bind instances to random port and the subscription system will send the real value to the subscription server.

uwsgi --socket -M --subscribe-to

Mapping files

If you need to specify a massive amount of keys, you can use a mapping file instead.

# mappings.txt,5
uwsgi --socket :3031 -M --subscribe-to

Way 5: –fastrouter-use-code-string

If Darth Vader wears a t-shirt with your face (and in some other corner cases too), you can customize the fastrouter with code-driven mappings. Choose a uWSGI-supported language (like Python or Lua) and define your mapping function.

def get(key):
    return ''
uwsgi --fastrouter --fastrouter-use-code-string

This will instruct the fastrouter to load the script using plugin (modifier1) 0 and call the ‘get’ global, passing it the key. In the previous example you will always route requests to Let’s create a more advanced system, for fun!

domains = {}
domains[''] = {'nodes': ('', ''), 'node': 0}
domains[''] = {'nodes': (',5', ',5'), 'node': 0}


def get(key):
    if key not in domains:
        return DEFAULT_NODE

    # get the node to forward requests to
    nodes = domains[key]['nodes']
    current_node = domains[key]['node']
    value = nodes[current_node]

    # round robin :P
    next_node = current_node + 1
    if next_node >= len(nodes):
        next_node = 0

    domains[key]['node'] = next_node

    return value
uwsgi --fastrouter --fastrouter-use-code-string

With only few lines we have implemented round-robin load-balancing with a fallback node. Pow! You could add some form of node monitoring, starting threads in the script, or other insane things. (Be sure to add them to the docs!)


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

Cheap mode and shared sockets

A common setup is having a webserver/proxy connected to a fastrouter and a series of uWSGI instances subscribed to it. Normally you’d use the webserver node as a uWSGI instance node. This node will subscribe to the local fastrouter. Well... don’t waste cycles on that! Shared sockets are a way to share sockets among various uWSGI components. Let’s use that to share a socket between the fastrouter and uWSGI instance.

;create a shared socket (the webserver will connect to it)
shared-socket =

; bind the fastrouter to the shared socket
fastrouter = =0
; bind an instance to the same socket
socket = =0

; having a master is always a good thing...
master = true
; our subscription server
fastrouter-subscription-server =
; our app
wsgi-file = /var/www/myheavyapp.wsgi
; a bunch of processes
processes = 4
; and put the fastrouter in cheap mode
fastrouter-cheap = true

With this setup your requests will go directly to your app (no proxy overhead) or to the fastrouter (to pass requests to remote nodes). When the fastrouter 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 will respond. When all of the nodes go down, the fastrouter will return in cheap mode. Seeing a pattern? Another step to awesome autoscaling.


  • The fastrouter uses the following vars (in order of precedence) to choose a key to use:
    • UWSGI_FASTROUTER_KEY - the most versatile, as it doesn’t depend on the request in any way
  • You can increase the number of async events the fastrouter can manage (by default it is system-dependent) using –fastrouter-events

You can change the default timeout with –fastrouter-timeout By default the fastrouter will set fd socket passing when used over unix sockets. If you do not want it add –no-fd-passing