The uWSGI project

The uWSGI project aims at developing a full stack for building hosting services.

Application servers (for various programming languages and protocols), proxies, process managers and monitors are all implemented using a common api and a common configuration style.

Thanks to its pluggable architecture it can be extended to support more platforms and languages.

Currently, you can write plugins in C, C++ and Objective-C.

The “WSGI” part in the name is a tribute to the namesake Python standard, as it has been the first developed plugin for the project.

Versatility, performance, low-resource usage and reliability are the strengths of the project (and the only rules followed).

Included components (updated to latest stable release)

The Core (implements configuration, processes management, sockets creation, monitoring, logging, shared memory areas, ipc, cluster membership and the uWSGI Subscription Server)

Request plugins (implement application server interfaces for various languages and platforms: WSGI, PSGI, Rack, Lua WSAPI, CGI, PHP, Go ...)

Gateways (implement load balancers, proxies and routers)

The Emperor (implements massive instances management and monitoring)

Loop engines (implement events and concurrency, components can be run in preforking, threaded, asynchronous/evented and green thread/coroutine modes. Various technologies are supported, including uGreen, Greenlet, Stackless, Gevent, Coro::AnyEvent, Tornado, Goroutines and Fibers)

Note

uWSGI is a very active project with a fast release cycle. For this reason the code and the documentation may not always be in sync. We try to make our best to have good documentation but it is a hard work. Sorry for that. If you are in trouble, the mailing list is the best source for help regarding uWSGI. Contributors for documentation (in addition to code) are always welcome.

Quickstarts

Quickstart for Python/WSGI applications

This quickstart will show you how to deploy simple WSGI applications and common web frameworks.

Python here is meant as CPython, for PyPy you need to use the specific plugin: The PyPy plugin, Jython support is under construction.

Note

You need at least uWSGI 1.4 to follow the quickstart. Anything older is no longer maintained and is highly buggy!

Installing uWSGI with Python support

Tip

When you start learning uWSGI, try to build from official sources: using distribution-supplied packages may bring you plenty of headaches. When things are clear, you can use modular builds (like the ones available in your distribution).

uWSGI is a (big) C application, so you need a C compiler (like gcc or clang) and the Python development headers.

On a Debian-based distro an

apt-get install build-essential python-dev

will be enough.

You have various ways to install uWSGI for Python:

  • via pip

    pip install uwsgi
    
  • using the network installer

    curl http://uwsgi.it/install | bash -s default /tmp/uwsgi
    

    (this will install the uWSGI binary into /tmp/uwsgi, feel free to change it).

  • via downloading a source tarball and “making” it

    wget https://projects.unbit.it/downloads/uwsgi-latest.tar.gz
    tar zxvf uwsgi-latest.tar.gz
    cd <dir>
    make
    

    (after the build you will have a uwsgi binary in the current directory).

Installing via your package distribution is not covered (would be impossible to make everyone happy), but all of the general rules apply.

One thing you may want to take into account when testing this quickstart with distro-supplied packages, is that very probably your distribution has built uWSGI in modular way (every feature is a different plugin that must be loaded). To complete this quickstart, you have to prepend --plugin python,http to the first series of examples, and --plugin python when the HTTP router is removed (if this doesn’t make sense to you, just continue reading).

The first WSGI application

Let’s start with a simple “Hello World” example:

def application(env, start_response):
    start_response('200 OK', [('Content-Type','text/html')])
    return [b"Hello World"]

(save it as foobar.py).

As you can see, it is composed of a single Python function. It is called “application” as this is the default function that the uWSGI Python loader will search for (but you can obviously customize it).

Deploy it on HTTP port 9090

Now start uWSGI to run an HTTP server/router passing requests to your WSGI application:

uwsgi --http :9090 --wsgi-file foobar.py

That’s all.

Note

Do not use --http when you have a frontend webserver or you are doing some form of benchmark, use --http-socket. Continue reading the quickstart to understand why.

Adding concurrency and monitoring

The first tuning you would like to make is adding concurrency (by default uWSGI starts with a single process and a single thread).

You can add more processes with the --processes option or more threads with the --threads option (or you can have both).

uwsgi --http :9090 --wsgi-file foobar.py --master --processes 4 --threads 2

This will spawn 4 processes (each with 2 threads), a master process (will respawn your processes when they die) and the HTTP router (seen before).

One important task is monitoring. Understanding what is going on is vital in production deployment. The stats subsystem allows you to export uWSGI’s internal statistics as JSON:

uwsgi --http :9090 --wsgi-file foobar.py --master --processes 4 --threads 2 --stats 127.0.0.1:9191

Make some request to your app and then telnet to the port 9191, you’ll get lots of fun information. You may want to use “uwsgitop” (just pip install it), which is a top-like tool for monitoring instances.

Attention

Bind the stats socket to a private address (unless you know what you are doing), otherwise everyone could access it!

Putting behind a full webserver

Even though uWSGI HTTP router is solid and high-performance, you may want to put your application behind a fully-capable webserver.

uWSGI natively speaks HTTP, FastCGI, SCGI and its specific protocol named “uwsgi” (yes, wrong naming choice). The best performing protocol is obviously uwsgi, already supported by nginx and Cherokee (while various Apache modules are available).

A common nginx config is the following:

location / {
    include uwsgi_params;
    uwsgi_pass 127.0.0.1:3031;
}

This means “pass every request to the server bound to port 3031 speaking the uwsgi protocol”.

Now we can spawn uWSGI to natively speak the uwsgi protocol:

uwsgi --socket 127.0.0.1:3031 --wsgi-file foobar.py --master --processes 4 --threads 2 --stats 127.0.0.1:9191

If you’ll run ps aux, you will see one process less. The HTTP router has been removed as our “workers” (the processes assigned to uWSGI) natively speak the uwsgi protocol.

If your proxy/webserver/router speaks HTTP, you have to tell uWSGI to natively speak the http protocol (this is different from –http that will spawn a proxy by itself):

uwsgi --http-socket 127.0.0.1:3031 --wsgi-file foobar.py --master --processes 4 --threads 2 --stats 127.0.0.1:9191

Automatically starting uWSGI on boot

If you are thinking about firing up vi and writing an init.d script for spawning uWSGI, just sit (and calm) down and make sure your system doesn’t offer a better (more modern) approach first.

Each distribution has chosen a startup system (Upstart, Systemd...) and there are tons of process managers available (supervisord, god, monit, circus...).

uWSGI will integrate very well with all of them (we hope), but if you plan to deploy a big number of apps check the uWSGI Emperor - it is more or less the dream of every devops engineer.

Deploying Django

Django is very probably the most used Python web framework around. Deploying it is pretty easy (we continue our configuration with 4 processes with 2 threads each).

We suppose the Django project is in /home/foobar/myproject:

uwsgi --socket 127.0.0.1:3031 --chdir /home/foobar/myproject/ --wsgi-file myproject/wsgi.py --master --processes 4 --threads 2 --stats 127.0.0.1:9191

(with --chdir we move to a specific directory). In Django this is required to correctly load modules.

Argh! What the hell is this?! Yes, you’re right, you’re right... dealing with such long command lines is unpractical, foolish and error-prone. Never fear! uWSGI supports various configuration styles. In this quickstart we will use .ini files.

[uwsgi]
socket = 127.0.0.1:3031
chdir = /home/foobar/myproject/
wsgi-file = myproject/wsgi.py
processes = 4
threads = 2
stats = 127.0.0.1:9191

A lot better!

Just run it:

uwsgi yourfile.ini

If the file /home/foobar/myproject/myproject/wsgi.py (or whatever you have called your project) does not exist, you are very probably using an old (< 1.4) version of Django. In such a case you need a little bit more configuration:

uwsgi --socket 127.0.0.1:3031 --chdir /home/foobar/myproject/ --pythonpath .. --env DJANGO_SETTINGS_MODULE=myproject.settings --module "django.core.handlers.wsgi:WSGIHandler()" --processes 4 --threads 2 --stats 127.0.0.1:9191

Or, using the .ini file:

[uwsgi]
socket = 127.0.0.1:3031
chdir = /home/foobar/myproject/
pythonpath = ..
env = DJANGO_SETTINGS_MODULE=myproject.settings
module = django.core.handlers.wsgi:WSGIHandler()
processes = 4
threads = 2
stats = 127.0.0.1:9191

Older (< 1.4) Django releases need to set env, module and the pythonpath (.. allow us to reach the myproject.settings module).

Deploying Flask

Flask is a popular Python web microframework.

Save the following example as myflaskapp.py:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def index():
    return "<span style='color:red'>I am app 1</span>"

Flask exports its WSGI function (the one we called “application” at the beginning of this quickstart) as “app”, so we need to instruct uWSGI to use it. We still continue to use the 4 processes/2 threads and the uwsgi socket as the base:

uwsgi --socket 127.0.0.1:3031 --wsgi-file myflaskapp.py --callable app --processes 4 --threads 2 --stats 127.0.0.1:9191

(the only addition is the --callable option).

Deploying web2py

Again a popular choice. Unzip the web2py source distribution on a directory of choice and write a uWSGI config file:

[uwsgi]
http = :9090
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8

Note

On recent web2py releases you may need to copy the wsgihandler.py script out of the handlers directory.

We used the HTTP router again. Just go to port 9090 with your browser and you will see the web2py welcome page.

Click on the administrative interface and... oops, it does not work as it requires HTTPS. Do not worry, the uWSGI router is HTTPS-capable (be sure you have OpenSSL development headers: install them and rebuild uWSGI, the build system will automatically detect it).

First of all generate your key and certificate:

openssl genrsa -out foobar.key 2048
openssl req -new -key foobar.key -out foobar.csr
openssl x509 -req -days 365 -in foobar.csr -signkey foobar.key -out foobar.crt

Now you have 2 files (well 3, counting the foobar.csr), foobar.key and foobar.crt. Change the uWSGI config:

[uwsgi]
https = :9090,foobar.crt,foobar.key
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8

Re-run uWSGI and connect to port 9090 using https:// with your browser.

A note on Python threads

If you start uWSGI without threads, the Python GIL will not be enabled, so threads generated by your application will never run. You may not like that choice, but remember that uWSGI is a language-independent server, so most of its choices are for maintaining it “agnostic”.

But do not worry, there are basically no choices made by the uWSGI developers that cannot be changed with an option.

If you want to maintain Python threads support without starting multiple threads for your application, just add the --enable-threads option (or enable-threads = true in ini style).

Virtualenvs

uWSGI can be configured to search for Python modules in a specific virtualenv.

Just add virtualenv = <path> to your options.

Security and availability

Always avoid running your uWSGI instances as root. You can drop privileges using the uid and gid options:

[uwsgi]
https = :9090,foobar.crt,foobar.key
uid = foo
gid = bar
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8

If you need to bind to privileged ports (like 443 for HTTPS), use shared sockets. They are created before dropping privileges and can be referenced with the =N syntax, where N is the socket number (starting from 0):

[uwsgi]
shared-socket = :443
https = =0,foobar.crt,foobar.key
uid = foo
gid = bar
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8

A common problem with webapp deployment is “stuck requests”. All of your threads/workers are stuck (blocked on request) and your app cannot accept more requests. To avoid that problem you can set a harakiri timer. It is a monitor (managed by the master process) that will destroy processes stuck for more than the specified number of seconds (choose harakiri value carefully). For example, you may want to destroy workers blocked for more than 30 seconds:

[uwsgi]
shared-socket = :443
https = =0,foobar.crt,foobar.key
uid = foo
gid = bar
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8
harakiri = 30

In addition to this, since uWSGI 1.9, the stats server exports the whole set of request variables, so you can see (in realtime) what your instance is doing (for each worker, thread or async core).

Offloading

The uWSGI offloading subsystem allows you to free your workers as soon as possible when some specific pattern matches and can be delegated to a pure-c thread. Examples are sending static file from the file system, transferring data from the network to the client and so on.

Offloading is very complex, but its use is transparent to the end user. If you want to try just add --offload-threads <n> where <n> is the number of threads to spawn (1 per CPU is a good value to start with).

When offload threads are enabled, all of the parts that can be optimized will be automatically detected.

Bonus: multiple Python versions for the same uWSGI binary

As we have seen, uWSGI is composed of a small core and various plugins. Plugins can be embedded in the binary or loaded dynamically. When you build uWSGI for Python, a series of plugins plus the Python one are embedded in the final binary.

This could be a problem if you want to support multiple Python versions without building a binary for each one.

The best approach would be having a little binary with the language-independent features built in, and one plugin for each Python version that will be loaded on-demand.

In the uWSGI source directory:

make PROFILE=nolang

This will build a uwsgi binary with all the default plugins built-in except the Python one.

Now, from the same directory, we start building Python plugins:

PYTHON=python3.4 ./uwsgi --build-plugin "plugins/python python34"
PYTHON=python2.7 ./uwsgi --build-plugin "plugins/python python27"
PYTHON=python2.6 ./uwsgi --build-plugin "plugins/python python26"

You will end up with three files: python34_plugin.so, python27_plugin.so, python26_plugin.so. Copy these into your desired directory. (By default, uWSGI searches for plugins in the current working directory.)

Now in your configurations files you can simply add (at the very top) the plugins-dir and plugin directives.

[uwsgi]
plugins-dir = <path_to_your_plugin_directory>
plugin = python26

This will load the python26_plugin.so plugin library from the directory into which you copied the plugins.

And now...

You should already be able to go into production with such few concepts, but uWSGI is an enormous project with hundreds of features and configurations. If you want to be a better sysadmin, continue reading the full docs.

Quickstart for perl/PSGI applications

The following instructions will guide you through installing and running a perl-based uWSGI distribution, aimed at running PSGI apps.

Installing uWSGI with Perl support

To build uWSGI you need a c compiler (gcc and clang are supported) and the python binary (it will only run the uwsgiconfig.py script that will execute the various compilation steps). As we are building a uWSGI binary with perl support we need perl development headers too (libperl-dev package on debian-based distros)

You can build uWSGI manually:

python uwsgiconfig.py --build psgi

that is the same as

UWSGI_PROFILE=psgi make

or using the network installer:

curl http://uwsgi.it/install | bash -s psgi /tmp/uwsgi

that will create a uWSGI binary in /tmp/uwsgi (feel free to change the path to whatever you want)

Note for distro packages

You distribution very probably contains a uWSGI package set. Those uWSGI packages tend to be highly modulars, so in addition to the core you need to install the required plugins. Plugins must be loaded in your configs. In the learning phase we strongly suggest to not use distribution packages to easily follow documentation and tutorials.

Once you feel comfortable with the “uWSGI way” you can choose the best approach for your deployments.

Your first PSGI app

save it to a file named myapp.pl

my $app = sub {
     my $env = shift;
     return [
             '200',
             [ 'Content-Type' => 'text/html' ],
             [ "<h1>Hello World</h1>" ],
     ];
};

then run it via uWSGI in http mode:

uwsgi --http :8080 --http-modifier1 5 --psgi myapp.pl

(remember to replace ‘uwsgi’ if it is not in your current $PATH)

or if you are using a modular build (like the one of your distro)

uwsgi --plugins http,psgi --http :8080 --http-modifier1 5 --psgi myapp.pl

Note

Do not use –http when you have a frontend webserver, use –http-socket. Continue reading the quickstart to understand why.

What is that ‘–http-modifier1 5’ thing ???

uWSGI supports various languages and platform. When the server receives a request it has to know where to ‘route’ it.

Each uWSGI plugin has an assigned number (the modifier), the perl/psgi one has the 5. So –http-modifier1 5 means “route to the psgi plugin”

Albeit uWSGI has a more “human-friendly” internal routing system using modifiers is the fastest way, so, if possible always use them

Using a full webserver: nginx

The supplied http router, is (yes, incredible) only a router. You can use it as a load balancer or a proxy, but if you need a full webserver (for efficiently serving static files or all of those task a webserver is good at), you can get rid of the uwsgi http router (remember to change –plugins http,psgi to –plugins psgi if you are using a modular build) and put your app behind nginx.

To communicate with nginx, uWSGI can use various protocol: http, uwsgi, fastcgi, scgi...

The most efficient one is the uwsgi one. Nginx includes uwsgi protocol support out of the box.

Run your psgi application on a uwsgi socket:

uwsgi --socket 127.0.0.1:3031 --psgi myapp.pl

then add a location stanza in your nginx config

location / {
    include uwsgi_params;
    uwsgi_pass 127.0.0.1:3031;
    uwsgi_modifier1 5;
}

Reload your nginx server, and it should start proxying requests to your uWSGI instance

Note that you do not need to configure uWSGI to set a specific modifier, nginx will do it using the uwsgi_modifier1 5; directive

If your proxy/webserver/router speaks HTTP, you have to tell uWSGI to natively speak the http protocol (this is different from –http that will spawn a proxy by itself):

uwsgi --http-socket 127.0.0.1:3031 --http-socket-modifier1 5 --psgi myapp.pl

as you can see we needed to specify the modifier1 to use, as the http protocol cannot carry this kind of information

Adding concurrency

You can give concurrency to to your app via multiprocess,multithreading or various async modes.

To spawn additional processes use the –processes option

uwsgi --socket 127.0.0.1:3031 --psgi myapp.pl --processes 4

To have additional threads use –threads

uwsgi --socket 127.0.0.1:3031 --psgi myapp.pl --threads 8

Or both if you feel exotic

uwsgi --socket 127.0.0.1:3031 --psgi myapp.pl --threads 8 --processes 4

A very common non-blocking/coroutine library in the perl world is Coro::AnyEvent. uWSGI can use it (even combined with multiprocessing) simply including the coroae plugin.

To build a uWSGI binary with coroae support just run

UWSGI_PROFILE=coroae make

or

curl http://uwsgi.it/install | bash -s coroae /tmp/uwsgi

you will end with a uWSGI binary including both the psgi and coroae plugins.

Now run your application in Coro::AnyEvent mode:

uwsgi --socket 127.0.0.1:3031 --psgi myapp.pl --coroae 1000 --processes 4

it will run 4 processes each able to manage up to 1000 coroutines (or Coro microthreads).

Adding robustness: the Master process

It is highly recommended to have the master process always running on productions apps.

It will constantly monitor your processes/threads and will add funny features like the The uWSGI Stats Server

To enable the master simply add –master

uwsgi --socket 127.0.0.1:3031 --psgi myapp.pl --processes 4 --master

Using config files

uWSGI has literally hundreds of options. Dealing with them via command line is basically silly, so try to always use config files. uWSGI supports various standards (xml, .ini, json, yaml...). Moving from one to another is pretty simple. The same options you can use via command line can be used on config files simply removing the -- prefix:

[uwsgi]
socket = 127.0.0.1:3031
psgi = myapp.pl
processes = 4
master = true

or xml:

<uwsgi>
  <socket>127.0.0.1:3031</socket>
  <psgi>myapp.pl</psgi>
  <processes>4</processes>
  <master/>
</uwsgi>

To run uWSGI using a config file, just specify it as argument:

uwsgi yourconfig.ini

if for some reason your config cannot end with the expected extension (.ini, .xml, .yml, .js) you can force the binary to use a specific parser in this way:

uwsgi --ini yourconfig.foo
uwsgi --xml yourconfig.foo
uwsgi --yaml yourconfig.foo

and so on

You can even pipe configs (using the dash to force reading from stdin):

perl myjsonconfig_generator.pl | uwsgi --json -

Accessing uWSGI options within application code

uWSGI options can be accessed within application code via uwsgi::opt.

my $uwsgi_opt = uwsgi::opt;
print $uwsgi_opt->{'http'};

Automatically starting uWSGI on boot

If you are thinking about writing some init.d script for spawning uWSGI, just sit (and calm) down and check if your system does not offer you a better (more modern) approach.

Each distribution has chosen a startup system (Upstart, Systemd...) and there are tons of process managers available (supervisord, god...).

uWSGI will integrate very well with all of them (we hope), but if you plan to deploy a big number of apps check the uWSGI Emperor it is the dream of every devops.

Security and availability

ALWAYS avoid running your uWSGI instances as root. You can drop privileges using the uid and gid options

[uwsgi]
socket = 127.0.0.1:3031
uid = foo
gid = bar
chdir = path_toyour_app
psgi = myapp.pl
master = true
processes = 8

A common problem with webapp deployment is “stuck requests”. All of your threads/workers are stuck blocked on a request and your app cannot accept more of them.

To avoid that problem you can set an harakiri timer. It is a monitor (managed by the master process) that will destroy processes stuck for more than the specified number of seconds

[uwsgi]
socket = 127.0.0.1:3031
uid = foo
gid = bar
chdir = path_toyour_app
psgi = myapp.pl
master = true
processes = 8
harakiri = 30

will destroy workers blocked for more than 30 seconds. Choose carefully the harakiri value !!!

In addition to this, since uWSGI 1.9, the stats server exports the whole set of request variables, so you can see (in realtime) what your instance is doing (for each worker, thread or async core)

Enabling the stats server is easy:

[uwsgi]
socket = 127.0.0.1:3031
uid = foo
gid = bar
chdir = path_toyour_app
psgi = myapp.pl
master = true
processes = 8
harakiri = 30
stats = 127.0.0.1:5000

just bind it to an address (UNIX or TCP) and just connect (you can use telnet too) to it to receive a JSON representation of your instance.

The uwsgitop application (you can find it in the official github repository) is an example of using the stats server to have a top-like realtime monitoring tool (with colors !!!)

Offloading

The uWSGI offloading subsystem allows you to free your workers as soon as possible when some specific pattern matches and can be delegated to a pure-c thread. Examples are sending static file from the filesystem, transferring data from the network to the client and so on.

Offloading is very complex, but its use is transparent to the end user. If you want to try just add –offload-threads <n> where <n> is the number of threads to spawn (one for cpu is a good value).

When offload threads are enabled, all of the parts that can be optimized will be automatically detected.

And now

You should already be able to go in production with such few concepts, but uWSGI is an enormous project with hundreds of features and configurations. If you want to be a better sysadmin, continue reading the full docs.

Quickstart for ruby/Rack applications

The following instructions will guide you through installing and running a Ruby-based uWSGI distribution aimed at running Rack apps.

Installing uWSGI with Ruby support

To build uWSGI you need a C compiler (gcc and clang are supported) and the Python binary (to run the uwsgiconfig.py script that will execute the various compilation steps).

As we are building an uWSGI binary with Ruby support we need the Ruby development headers too (the ruby-dev package on Debian-based distributions).

You can build uWSGI manually – all of these are equivalent:

make rack
UWSGI_PROFILE=rack make
make PROFILE=rack
python uwsgiconfig.py --build rack

But if you are lazy, you can download, build and install an uWSGI + Ruby binary in a single shot:

curl http://uwsgi.it/install | bash -s rack /tmp/uwsgi

Or in a more “Ruby-friendly” way:

gem install uwsgi

All of these methods build a “monolithic” uWSGI binary. The uWSGI project is composed by dozens of plugins. You can choose to build the server core and having a plugin for every feature (that you will load when needed), or you can build a single binary with all the features you need. This latter kind of build is called ‘monolithic’.

This quickstart assumes a monolithic binary (so you do not need to load plugins). If you prefer to use your package distributions (instead of building uWSGI from official sources), see below.

Note for distro packages

Your distribution very probably contains an uWSGI package set. Those uWSGI packages tend to be highly modular (and occasionally highly outdated), so in addition to the core you need to install the required plugins. Plugins must be loaded in your uWSGI configuration. In the learning phase we strongly suggest to not use distribution packages to easily follow documentation and tutorials.

Once you feel comfortable with the “uWSGI way” you can choose the best approach for your deployments.

As an example, the tutorial makes use of the “http” and “rack” plugins. If you are using a modular build be sure to load them with the --plugins http,rack option.

Your first Rack app

Rack is the standard way for writing Ruby web apps.

This is a standard Rack Hello world script (call it app.ru):

class App

  def call(environ)
    [200, {'Content-Type' => 'text/html'}, ['Hello']]
  end

end

run App.new

The .ru extension stands for “rackup”, which is the deployment tool included in the Rack distribution. Rackup uses a little DSL, so to use it into uWSGI you need to install the rack gem:

gem install rack

Now we are ready to deploy with uWSGI:

uwsgi --http :8080 --http-modifier1 7 --rack app.ru

(remember to replace ‘uwsgi’ if it is not in your current $PATH)

or if you are using a modular build (like the one of your distribution)

uwsgi --plugins http,rack --http :8080 --http-modifier1 7 --rack app.ru

With this command line we’ve spawned an HTTP proxy routing each request to a process (named the ‘worker’) that manages it and send back the response to the HTTP router (that sends back to the client).

If you are asking yourself why spawning two processes, it is because this is the normal architecture you will use in production (a frontline web server with a backend application server).

If you do not want to spawn the HTTP proxy and directly force the worker to answer HTTP requests just change the command line to

uwsgi --http-socket :8080 --http-socket-modifier1 7 --rack app.ru

now you have a single process managing requests (but remember that directly exposing the application server to the public is generally dangerous and less versatile).

What is that ‘–http-modifier1 7’ thing?

uWSGI supports various languages and platforms. When the server receives a request it has to know where to ‘route’ it.

Each uWSGI plugin has an assigned number (the modifier), the ruby/rack one has the 7. So --http-modifier1 7 means “route to the rack plugin”.

Though uWSGI also has a more “human-friendly” internal routing system using modifiers is the fastest way, so if at all possible always use them.

Using a full webserver: nginx

The supplied HTTP router, is (yes, astoundingly enough) only a router. You can use it as a load balancer or a proxy, but if you need a full web server (for efficiently serving static files or all of those task a webserver is good at), you can get rid of the uwsgi HTTP router (remember to change –plugins http,rack to –plugins rack if you are using a modular build) and put your app behind Nginx.

To communicate with Nginx, uWSGI can use various protocol: HTTP, uwsgi, FastCGI, SCGI, etc.

The most efficient one is the uwsgi one. Nginx includes uwsgi protocol support out of the box.

Run your rack application on an uwsgi socket:

uwsgi --socket 127.0.0.1:3031 --rack app.ru

then add a location stanza in your nginx config

location / {
    include uwsgi_params;
    uwsgi_pass 127.0.0.1:3031;
    uwsgi_modifier1 7;
}

Reload your nginx server, and it should start proxying requests to your uWSGI instance.

Note that you do not need to configure uWSGI to set a specific modifier, nginx will do it using the uwsgi_modifier1 5; directive.

Adding concurrency

With the previous example you deployed a stack being able to serve a single request at time.

To increase concurrency you need to add more processes. If you are hoping there is a magic math formula to find the right number of processes to spawn, well... we’re sorry. You need to experiment and monitor your app to find the right value. Take in account every single process is a complete copy of your app, so memory usage should be taken in account.

To add more processes just use the –processes <n> option:

uwsgi --socket 127.0.0.1:3031 --rack app.ru --processes 8

will spawn 8 processes.

Ruby 1.9/2.0 introduced an improved threads support and uWSGI supports it via the ‘rbthreads’ plugin. This plugin is automatically built when you compile the uWSGI+ruby (>=1.9) monolithic binary.

To add more threads:

uwsgi --socket 127.0.0.1:3031 --rack app.ru --rbthreads 4

or threads + processes

uwsgi --socket 127.0.0.1:3031 --rack app.ru --processes --rbthreads 4

There are other (generally more advanced/complex) ways to increase concurrency (for example ‘fibers’), but most of the time you will end up with a plain old multi-process or multi-thread models. If you are interested, check the complete documentation over at Rack.

Adding robustness: the Master process

It is highly recommended to have the uWSGI master process always running on productions apps.

It will constantly monitor your processes/threads and will add fun features like the The uWSGI Stats Server.

To enable the master simply add --master

uwsgi --socket 127.0.0.1:3031 --rack app.ru --processes 4 --master

Using config files

uWSGI has literally hundreds of options (but generally you will not use more than a dozens of them). Dealing with them via command line is basically silly, so try to always use config files.

uWSGI supports various standards (XML, INI, JSON, YAML, etc). Moving from one to another is pretty simple. The same options you can use via command line can be used with config files by simply removing the -- prefix:

[uwsgi]
socket = 127.0.0.1:3031
rack = app.ru
processes = 4
master = true

or xml:

<uwsgi>
  <socket>127.0.0.1:3031</socket>
  <rack>app.ru</rack>
  <processes>4</processes>
  <master/>
</uwsgi>

To run uWSGI using a config file, just specify it as argument:

uwsgi yourconfig.ini

if for some reason your config cannot end with the expected extension (.ini, .xml, .yml, .js) you can force the binary to use a specific parser in this way:

uwsgi --ini yourconfig.foo
uwsgi --xml yourconfig.foo
uwsgi --yaml yourconfig.foo

and so on.

You can even pipe configs (using the dash to force reading from stdin):

ruby myjsonconfig_generator.rb | uwsgi --json -

The fork() problem when you spawn multiple processes

uWSGI is “Perlish” in a way, there is nothing we can do to hide that. Most of its choices (starting from “There’s more than one way to do it”) came from the Perl world (and more generally from classical UNIX sysadmin approaches).

Sometimes this approach could lead to unexpected behaviors when applied to other languages/platforms.

One of the “problems” you can face when starting to learn uWSGI is its fork() usage.

By default uWSGI loads your application in the first spawned process and then fork() itself multiple times.

It means your app is loaded a single time and then copied.

While this approach speedups the start of the server, some application could have problems with this technique (especially those initializing db connections on startup, as the file descriptor of the connection will be inherited in the subprocesses).

If you are unsure about the brutal preforking used by uWSGI, just disable it with the --lazy-apps option. It will force uWSGI to completely load your app one time per each worker.

Deploying Sinatra

Let’s forget about fork(), and back to fun things. This time we’re deploying a Sinatra application:

require 'sinatra'

get '/hi' do
  "Hello World"
end

run Sinatra::Application

save it as config.ru and run as seen before:

[uwsgi]
socket = 127.0.0.1:3031
rack = config.ru
master = true
processes = 4
lazy-apps = true
uwsgi yourconf.ini

Well, maybe you already noted that basically nothing changed from the previous app.ru examples.

That is because basically every modern Rack app exposes itself as a .ru file (generally called config.ru), so there is no need for multiple options for loading applications (like for example in the Python/WSGI world).

Deploying RubyOnRails >= 3

Starting from 3.0, Rails is fully Rack compliant, and exposes a config.ru file you can directly load (like we did with Sinatra).

The only difference from Sinatra is that your project has a specific layout/convention expecting your current working directory is the one containing the project, so let’s add a chdir option:

[uwsgi]
socket = 127.0.0.1:3031
rack = config.ru
master = true
processes = 4
lazy-apps = true
chdir = <path_to_your_rails_app>
env = RAILS_ENV=production
uwsgi yourconf.ini

In addition to chdir we have added the ‘env’ option that set the RAILS_ENV environment variable.

Starting from 4.0, Rails support multiple threads (only for ruby 2.0):

[uwsgi]
socket = 127.0.0.1:3031
rack = config.ru
master = true
processes = 4
rbthreads = 2
lazy-apps = true
chdir = <path_to_your_rails_app>
env = RAILS_ENV=production

Deploying older RubyOnRails

Older Rails versions are not fully Rack-compliant. For such a reason a specific option is available in uWSGI to load older Rails apps (you will need the ‘thin’ gem too).

[uwsgi]
socket = 127.0.0.1:3031
master = true
processes = 4
lazy-apps = true
rails = <path_to_your_rails_app>
env = RAILS_ENV=production

So, in short, specify the rails option, passing the rails app directory as the argument, instead of a Rackup file.

Bundler and RVM

Bundler is the standard de-facto Ruby tool for managing dependencies. Basically you specify the gems needed by your app in the Gemfile text file and then you launch bundler to install them.

To allow uWSGI to honor bundler installations you only need to add:

rbrequire = rubygems
rbrequire = bundler/setup
env = BUNDLE_GEMFILE=<path_to_your_Gemfile>

(The first require stanza is not required for ruby 1.9/2.x.)

Basically those lines force uWSGI to load the bundler engine and to use the Gemfile specified in the BUNDLE_GEMFILE environment variable.

When using Bundler (like modern frameworks do) your common deployment configuration will be:

[uwsgi]
socket = 127.0.0.1:3031
rack = config.ru
master = true
processes = 4
lazy-apps = true
rbrequire = rubygems
rbrequire = bundler/setup
env = BUNDLE_GEMFILE=<path_to_your_Gemfile>

In addition to Bundler, RVM is another common tool.

It allows you to have multiple (independent) Ruby installations (with their gemsets) on a single system.

To instruct uWSGI to use the gemset of a specific RVM version just use the –gemset option:

[uwsgi]
socket = 127.0.0.1:3031
rack = config.ru
master = true
processes = 4
lazy-apps = true
rbrequire = rubygems
rbrequire = bundler/setup
env = BUNDLE_GEMFILE=<path_to_your_Gemfile>
gemset = ruby-2.0@foobar

Just pay attention you need a uWSGI binary (or a plugin if you are using a modular build) for every Ruby version (that’s Ruby version, not gemset!).

If you are interested, this is a list of commands to build the uWSGI core + 1 one plugin per every Ruby version installed in rvm:

# build the core
make nolang
# build plugin for 1.8.7
rvm use 1.8.7
./uwsgi --build-plugin "plugins/rack rack187"
# build for 1.9.2
rvm use 1.9.2
./uwsgi --build-plugin "plugins/rack rack192"
# and so on...

Then if you want to use ruby 1.9.2 with the @oops gemset:

[uwsgi]
plugins = ruby192
socket = 127.0.0.1:3031
rack = config.ru
master = true
processes = 4
lazy-apps = true
rbrequire = rubygems
rbrequire = bundler/setup
env = BUNDLE_GEMFILE=<path_to_your_Gemfile>
gemset = ruby-1.9.2@oops

Automatically starting uWSGI on boot

If you are thinking about firing up vi and writing an init.d script for spawning uWSGI, just sit (and calm) down and make sure your system doesn’t offer a better (more modern) approach first.

Each distribution has chosen a startup system (Upstart, Systemd...) and there are tons of process managers available (supervisord, god, monit, circus...).

uWSGI will integrate very well with all of them (we hope), but if you plan to deploy a big number of apps check the uWSGI Emperor - it is more or less the dream of every devops engineer.

Security and availability

ALWAYS avoid running your uWSGI instances as root. You can drop privileges using the uid and gid options.

[uwsgi]
socket = 127.0.0.1:3031
uid = foo
gid = bar
chdir = path_toyour_app
rack = app.ru
master = true
processes = 8

A common problem with webapp deployment is “stuck requests”. All of your threads/workers are stuck blocked on a request and your app cannot accept more of them.

To avoid that problem you can set an harakiri timer. It is a monitor (managed by the master process) that will destroy processes stuck for more than the specified number of seconds.

[uwsgi]
socket = 127.0.0.1:3031
uid = foo
gid = bar
chdir = path_toyour_app
rack = app.ru
master = true
processes = 8
harakiri = 30

This will destroy workers blocked for more than 30 seconds. Choose the harakiri value carefully!

In addition to this, since uWSGI 1.9, the stats server exports the whole set of request variables, so you can see (in real time) what your instance is doing (for each worker, thread or async core)

Enabling the stats server is easy:

[uwsgi]
socket = 127.0.0.1:3031
uid = foo
gid = bar
chdir = path_to_your_app
rack = app.ru
master = true
processes = 8
harakiri = 30
stats = 127.0.0.1:5000

just bind it to an address (UNIX or TCP) and just connect (you can use telnet too) to it to receive a JSON representation of your instance.

The uwsgitop application (you can find it in the official github repository) is an example of using the stats server to have a top-like realtime monitoring tool (with fancy colors!)

Memory usage

Low memory usage is one of the selling point of the whole uWSGI project.

Unfortunately being aggressive with memory by default could (read well: could) lead to some performance problems.

By default the uWSGI Rack plugin calls the Ruby GC (garbage collector) after every request. If you want to reduce this rate just add the --rb-gc-freq <n> option, where n is the number of requests after the GC is called.

If you plan to make benchmarks of uWSGI (or compare it with other solutions) take in account its use of GC.

Ruby can be a real memory devourer, so we prefer to be aggressive with memory by default instead of making hello-world benchmarkers happy.

Offloading

The uWSGI offloading subsystem allows you to free your workers as soon as possible when some specific pattern matches and can be delegated to a pure-c thread. Examples are sending static file from the file system, transferring data from the network to the client and so on.

Offloading is very complex, but its use is transparent to the end user. If you want to try just add --offload-threads <n> where <n> is the number of threads to spawn (1 per CPU is a good value to start with).

When offload threads are enabled, all of the parts that can be optimized will be automatically detected.

And now

You should already be able to go in production with such few concepts, but uWSGI is an enormous project with hundreds of features and configurations. If you want to be a better sysadmin, continue reading the full docs.

Welcome!

Snippets

This is a collection of some of the most “fun” uses of uWSGI features.

X-Sendfile emulation

Even if your frontend proxy/webserver does not support X-Sendfile (or cannot access your static resources) you can emulate it using uWSGI’s internal offloading (your process/thread will delegate the actual static file serving to offload threads).

[uwsgi]
...
; load router_static plugin (compiled in by default in monolithic profiles)
plugins = router_static
; spawn 2 offload threads
offload-threads = 2
; files under /private can be safely served
static-safe = /private
; collect the X-Sendfile response header as X_SENDFILE var
collect-header = X-Sendfile X_SENDFILE
; if X_SENDFILE is not empty, pass its value to the "static" routing action (it will automatically use offloading if available)
response-route-if-not = empty:${X_SENDFILE} static:${X_SENDFILE}

Force HTTPS

This will force HTTPS for the whole site.

[uwsgi]
...
; load router_redirect plugin (compiled in by default in monolithic profiles)
plugins = router_redirect
route-if-not = equal:${HTTPS};on redirect-permanent:https://${HTTP_HOST}${REQUEST_URI}

And this only for /admin

[uwsgi]
...
; load router_redirect plugin (compiled in by default in monolithic profiles)
plugins = router_redirect
route = ^/admin goto:https
; stop the chain
route-run = last:

route-label = https
route-if-not = equal:${HTTPS};on redirect-permanent:https://${HTTP_HOST}${REQUEST_URI}

Eventually you may want to send HSTS (HTTP Strict Transport Security) header too.

[uwsgi]
...
; load router_redirect plugin (compiled in by default in monolithic profiles)
plugins = router_redirect
route-if-not = equal:${HTTPS};on redirect-permanent:https://${HTTP_HOST}${REQUEST_URI}
route-if = equal:${HTTPS};on addheader:Strict-Transport-Security: max-age=31536000

Python Auto-reloading (DEVELOPMENT ONLY!)

In production you can monitor file/directory changes for triggering reloads (touch-reload, fs-reload...).

During development having a monitor for all of the loaded/used python modules can be handy. But please use it only during development.

The check is done by a thread that scans the modules list with the specified frequency:

[uwsgi]
...
py-autoreload = 2

will check for python modules changes every 2 seconds and eventually restart the instance.

And again:

Warning

Use this only in development.

Full-Stack CGI setup

This example spawned from a uWSGI mainling-list thread.

We have static files in /var/www and cgis in /var/cgi. Cgi will be accessed using the /cgi-bin mountpoint. So /var/cgi/foo.lua will be run on request to /cgi-bin/foo.lua

[uwsgi]
workdir = /var
ipaddress = 0.0.0.0

; start an http router on port 8080
http = %(ipaddress):8080
; enable the stats server on port 9191
stats = 127.0.0.1:9191
; spawn 2 threads in 4 processes (concurrency level: 8)
processes = 4
threads = 2
; drop privileges
uid = nobody
gid = nogroup

; serve static files in /var/www
static-index = index.html
static-index = index.htm
check-static = %(workdir)/www

; skip serving static files ending with .lua
static-skip-ext = .lua

; route requests to the CGI plugin
http-modifier1 = 9
; map /cgi-bin requests to /var/cgi
cgi = /cgi-bin=%(workdir)/cgi
; only .lua script can be executed
cgi-allowed-ext = .lua
; .lua files are executed with the 'lua' command (it avoids the need of giving execute permission to files)
cgi-helper = .lua=lua
; search for index.lua if a directory is requested
cgi-index = index.lua

Multiple flask apps in different mountpoints

Let’s write three flask apps:

#app1.py
from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello World! i am app1"
#app2.py
from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello World! i am app2"
#app3.py
from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello World! i am app3"

each will be mounted respectively in /app1, /app2, /app3

To mount an application with a specific “key” in uWSGI, you use the –mount option:

` --mount <mountpoint>=<app> `

in our case we want to mount 3 python apps, each keyed with what will be the WSGI SCRIPT_NAME variable:

[uwsgi]
plugin = python
mount = /app1=app1.py
mount = /app2=app2.py
mount = /app3=app3.py
; generally flask apps expose the 'app' callable instead of 'application'
callable = app

; tell uWSGI to rewrite PATH_INFO and SCRIPT_NAME according to mount-points
manage-script-name = true

; bind to a socket
socket = /var/run/uwsgi.sock

now directly point your webserver.proxy to the instance socket (without doing additional configurations)

Note: by default every app is loaded in a new python interpreter (that means a pretty-well isolated namespace for each app). If you want all of the app to be loaded in the same python vm, use the –single-interpreter option.

Another note: you may find reference to an obscure “modifier1 30” trick. It is deprecated and extremely ugly. uWSGI is able to rewrite request variables in lot of advanced ways

Final note: by default, the first loaded app is mounted as the “default one”. That app will be served when no mountpoint matches.

rbenv on OSX (should work on other platforms too)

install rbenv

brew update
brew install rbenv ruby-build

(do not set the magic line in .bash_profile as described in the classic howto, as we want to not clobber the environment, and allow uWSGI to get rid of it)

get a uWSGI tarball and build the ‘nolang’ version (it is a monolithic one without language plugins compiled in)

wget https://projects.unbit.it/downloads/uwsgi-latest.tar.gz
tar zxvf uwsgi-latest.tar.gz
cd uwsgi-xxx
make nolang

now start installing the ruby versions you need

rbenv install 1.9.3-p551
rbenv install 2.1.5

and install the gems you need (sinatra in this case):

# set the current ruby env
rbenv local 1.9.3-p551
# get the path of the gem binary
rbenv which gem
# /Users/roberta/.rbenv/versions/1.9.3-p551/bin/gem
/Users/roberta/.rbenv/versions/1.9.3-p551/bin/gem install sinatra
# from the uwsgi sources directory, build the rack plugin for 1.9.3-p551, naming it rack_193_plugin.so
# the trick here is changing PATH to find the right ruby binary during the build procedure
PATH=/Users/roberta/.rbenv/versions/1.9.3-p551/bin:$PATH ./uwsgi --build-plugin "plugins/rack rack_193"
# set ruby 2.1.5
rbenv local 2.1.5
rbenv which gem
# /Users/roberta/.rbenv/versions/2.1.5/bin/gem
/Users/roberta/.rbenv/versions/2.1.5/bin/gem install sinatra
PATH=/Users/roberta/.rbenv/versions/2.1.5/bin:$PATH ./uwsgi --build-plugin "plugins/rack rack_215"

now to switch from one ruby to another, just change the plugin:

[uwsgi]
plugin = rack_193
rack = config.ru
http-socket = :9090

or

[uwsgi]
plugin = rack_215
rack = config.ru
http-socket = :9090

ensure plugins are stored in the current working directory, or set the plugins-dir directive or specify them with absolute path like

[uwsgi]
plugin = /foobar/rack_215_plugin.so
rack = config.ru
http-socket = :9090

Authenticated WebSocket Proxy

App server identifies websocket traffic, authenticates/authorizes the user using whatever CGI variables against the app’s own policies/infrastructure, then offloads/proxies the request to a simple kafka-websocket backend.

First create auth_kafka.py:

from pprint import pprint

def application(environ, start_response):
    start_response('200 OK', [('Content-Type', 'text/plain')])
    return ['It Works!']

def auth_kafka(request_uri, http_cookie, http_authorization):
    pprint(locals())
    return 'true'

import uwsgi
uwsgi.register_rpc('auth_kafka', auth_kafka)

Then create auth_kafka.ini:

[uwsgi]

; setup
http-socket = 127.0.0.1:8000
master = true
module = auth_kafka

; critical! else worker timeouts apply to proxied websocket connections
offload-threads = 2

; match websocket protocol
kafka-ws-upgrade-regex = ^[Ww]eb[Ss]ocket$

; DRY place for websocket check
is-kafka-ws-request =  regexp:${HTTP_UPGRADE};%(kafka-ws-upgrade-regex)

; location of the kafka-ws server
kafka-ws-host = 127.0.0.1:7080

; base endpoint uri for websocket server
kafka-ws-endpoint-uri = /v2/broker/

; call auth_kafka(...); if AUTH_KAFKA gets set, request is good!
route-if = %(is-kafka-ws-request) rpcvar:AUTH_KAFKA auth_kafka ${REQUEST_URI} ${HTTP_COOKIE} ${HTTP_AUTHORIZATION}

; update request uri to websocket endpoint (rewrite only changes PATH_INFO?)
route-if-not = empty:${AUTH_KAFKA} seturi:%(kafka-ws-endpoint-uri)?${QUERY_STRING}

; route the request to our websocket server
route-if-not = empty:${AUTH_KAFKA} httpdumb:%(kafka-ws-host)

Start a “kafka-websocket” server:

nc -l -k -p 7080

Now go to http://127.0.0.1:8000 in a web browser! You should see Hello!. Open chrome inspector or firebug and type:

ws = new WebSocket('ws://127.0.0.1:8000/?subscribe=true')

You should see this request proxied to your nc command! This pattern allows the internal network to host a more-or-less wide-open/generic kafka -> websocket gateway and delegates auth needs to the app server. Using offload-threads means proxied requests do NOT block workers; using httpdumb prevents mangling the request (http action forces HTTP/1.0)

SELinux and uWSGI

SELinux allows you to isolate web application processes from each other, and limits each program to its purpose only. The applications can be placed into strongly isolated individual sandboxes, separating them from one another and from the underlying operating system. Since SELinux is implemented within the kernel, applications do not need to be specifically written or modified to work under SELinux. There is an SELinux security policy for web applications at github well suited for uWSGI. This security policy also supports the uWSGI emperor process running in one domain, and each web application’s worker processes running in a separate domain, requiring only minimal privileges for the worker processes even if Linux namespaces are used. Of course, there is no requirement for emperor mode, or Linux namespaces, to use SELinux with uWSGI.

On Linux it is possible to run each vassal with a dedicated view of the filesystems, ipc, uts, networking, pids and uids. Then each vassal can, for example, modify the filesystem layout, networking, and hostname without damaging the main system. With this setup, privileged tasks, like mounting filesystems, setting hostnames, configuring the network, and setting gid and uid of the worker processes can be done before changing the SELinux security context of the vassals’ process ensuring that only minimal privileges are required for the worker processes.

First configure, compile and load the SELinux web application security policy. Then, relabel the application files. Further information on how to configure web application policies can be found in the README.md included in the SELinux security policy for web applications. Finally, in each vassall’s configuration file, call the setcon function in libselinux to set the web application’s SELinux security context:

[uwsgi]
...
hook-as-user = callret:setcon system_u:system_r:webapp_id_t:s0

where id is the identity of the domain. Example, foo is the identity of the webapp_foo_t domain.

It may be required to load libselinux in the uWSGI address space with the –dlopen option:

/path/to/uwsgi --dlopen /path/to/libselinux.so

Table of Contents

Getting uWSGI

These are the current versions of uWSGI.

Release Date Link
Unstable/Development - https://github.com/unbit/uwsgi/
Stable/LTS 2017-03-30 https://projects.unbit.it/downloads/uwsgi-2.0.15.tar.gz
DOCS - https://github.com/unbit/uwsgi-docs/

uWSGI is also available as a package in several OS/distributions.

uWSGI has a really fast development cycle, so packages may not be up to date. Building it requires less than 30 seconds and very few dependencies (only Python interpreter, a C compiler/linker and the libs/headers for your language of choice)

Installing uWSGI

Installing from a distribution package

uWSGI is available as a package in several OS/distributions.

Installing from source

To build uWSGI you need Python and a C compiler (gcc and clang are supported). Depending on the languages you wish to support you will need their development headers. On a Debian/Ubuntu system you can install them (and the rest of the infrastructure required to build software) with:

apt-get install build-essential python

And if you want to build a binary with python/wsgi support (as an example)

apt-get install python-dev

On a Fedora/Redhat system you can install them with:

yum groupinstall "Development Tools"
yum install python

For python/wsgi support:

yum install python-devel

If you have a variant of make available in your system you can simply run make. If you do not have make (or want to have more control) simply run:

python uwsgiconfig.py --build

You can also use pip to install uWSGI (it will build a binary with python support).

# Install the latest stable release:
pip install uwsgi
# ... or if you want to install the latest LTS (long term support) release,
pip install https://projects.unbit.it/downloads/uwsgi-lts.tar.gz

Or you can use ruby gems (it will build a binary with ruby/rack support).

# Install the latest stable release:
gem install uwsgi

At the end of the build, you will get a report of the enabled features. If something you require is missing, just add the development headers and rerun the build. For example to build uWSGI with ssl and perl regexp support you need libssl-dev and pcre headers.

Alternative build profiles

For historical reasons when you run ‘make’, uWSGI is built with Python as the only supported language. You can build customized uWSGI servers using build profiles, located in the buildconf/ directory. You can use a specific profile with:

python uwsgiconfig.py --build <profile>

Or you can pass it via an environment variable:

UWSGI_PROFILE=lua make
# ... or even ...
UWSGI_PROFILE=gevent pip install uwsgi

Modular builds

This is the approach your distribution should follow, and this is the approach you MUST follow if you want to build a commercial service over uWSGI (see below). The vast majority of uWSGI features are available as plugins. Plugins can be loaded using the –plugin option. If you want to give users the maximum amount of flexibility allowing them to use only the minimal amount of resources, just create a modular build. A build profile named “core” is available.

python uwsgiconfig.py --build core

This will build a uWSGi binary without plugins. This is called the “server core”. Now you can start building all of the plugins you need. Check the plugins/ directory in the source distribution for a full list.

python uwsgiconfig.py --plugin plugins/psgi core
python uwsgiconfig.py --plugin plugins/rack core
python uwsgiconfig.py --plugin plugins/python core
python uwsgiconfig.py --plugin plugins/lua core
python uwsgiconfig.py --plugin plugins/corerouter core
python uwsgiconfig.py --plugin plugins/http core
...

Remember to always pass the build profile (‘core’ in this case) as the third argument.

The uWSGI build system

  • This is updated to 1.9.13

This page describes how the uWSGI build system works and how it can be customized

uwsgiconfig.py

This is the python script aimed at calling the various compile/link stage.

During 2009, when uWSGI guidelines (and mantra) started to be defined, people agreed that autotools, cmake and friends was not loved by a lot of sysadmins. Albeit they are pretty standardized, the amount of packages needed and the incompatibility between them (especially in the autotools world) was a problem for a project with fast development/evolution where “compile from sources” was, is and very probably will be the best way to get the best from the product. In addition to this the build procedure MUST BE fast (less than 1 minute on entry level x86 is the main rule)

For such a reason, to compile uWSGI you only need to have a c compiler suite (gcc, clang...) and a python interpreter. Someone could argue that perl could have been a better choice, and maybe it is the truth (it is generally installed by default in lot of operating systems), but we decided to stay with python mainly because when uWSGI started it was a python-only application. (Obviously if you want to develop an alternative build system you are free to do it)

The uwsgiconfig.py basically detects the available features in the system and builds a uwsgi binary (and eventually its plugins) using the so called ‘build profile’

build profiles

First example

CC and CPP

These 2 environment variables tell uwsgiconfig.py to use an alternative C compiler and C preprocessor.

If they are not defined the procedure is the following:

For CC -> try to get the CC config_var from the python binary running uwsgiconfig.py, fallback to ‘gcc’

For CPP -> fallback to ‘cpp’

As an example, on a system with both gcc and clang you will end with

CC=clang CPP=clang-cpp python uwsgiconfig.py --build

CPUCOUNT

In the spirit of “easy and fast build even on production systems”, uwsgiconfig.py tries to use all of your cpu cores spawning multiple instances of the c compiler (one per-core).

You can override this system using the CPUCOUNT environment variable, forcing the number of detected cpu cores (setting to 1 will disable parallel build).

CPUCOUNT=2 python uwsgiconfig.py --build

UWSGI_FORCE_REBUILD

Plugins and uwsgiplugin.py

A uWSGI plugin is a shared library exporting the <name>_plugin symbol. Where <name> is the name of the plugin.

As an example the psgi plugin will export the psgi_plugin symbol as well as pypy will export he pypy_plugin symbol and so on.

This symbol is a uwsgi_plugin C struct defining the hooks of the plugin.

When you ask uWSGI to load a plugin it simply calls dlopen() and get the uwsgi_plugin struct via dlsym().

The vast majority of the uWSGI project is developed as a plugin, this ensure a modular approach to configuration and an obviously saner development style.

The sysadmin is free to embed each plugin in the server binary or to build each plugin as an external shared library.

Embedded plugins are defined in the ‘embedded_plugins’ directive of the build profile. You can add more embedded plugins from command line using the UWSGI_EMBED_PLUGINS environment variable (see below).

Instead, if you want to build a plugin as a shared library just run uwsgiconfig.py with the –plugin option

python uwsgiconfig.py --plugin plugins/psgi

this will build the plugin in plugins/psgi to the psgi_plugin.so file

To specify a build profile when you build a plugin, you can pass the profile as an additional argument

python uwsgiconfig.py --plugin plugins/psgi mybuildprofile

UWSGI_INCLUDES

  • this has been added in 1.9.13

On startup, the CPP binary is run to detect default include paths. You can add more paths using the UWSGI_INCLUDES environment variable

UWSGI_INCLUDES=/usr/local/include,/opt/dev/include python uwsgiconfig.py --build

UWSGI_EMBED_PLUGINS

UWSGI_EMBED_CONFIG

Allows embedding the specified .ini file in the server binary (currently Linux only)

On startup the server parses the embedded file as soon as possible.

Custom options defined in the embedded config will be available as standard ones.

UWSGI_BIN_NAME

CFLAGS and LDFLAGS

UWSGICONFIG_* for plugins

libuwsgi.so

uwsgibuild.log

uwsgibuild.lastcflags

cflags and uwsgi.h magic

embedding files

The fake make

Managing the uWSGI server

See also

If you are managing multiple apps or a high volume site, take a look at

Starting the server

Starting an uWSGI server is the role of the system administrator, like starting the Web server. It should not be the role of the Web server to start the uWSGI server – though you can also do that if it fits your architecture.

How to best start uWSGI services at boot depends on the operating system you use.

On modern systems the following should hold true. On “classic” operating systems you can use init.d/rc.d scripts, or tools such as Supervisor, Daemontools or inetd/xinetd.

System Method
Ubuntu < 15.04 Running uWSGI via Upstart (the official uwsgi package, available since Ubuntu 12.04 provides an init.d based solution. Read the README.)
Ubuntu >= 15.04 Systemd
Debian Systemd
Arch Linux Systemd
Fedora Systemd
OSX launchd
Solaris SMF

Signals for controlling uWSGI

You can instruct uWSGI to write the master process PID to a file with the safe-pidfile option.

The uWSGI server responds to the following signals.

Signal Description Convenience command
SIGHUP gracefully reload all the workers and the master process --reload
SIGTERM brutally reload all the workers and the master process (use --die-on-term to respect the convention of shutting down the instance)
SIGINT immediately kill the entire uWSGI stack --stop
SIGQUIT immediately kill the entire uWSGI stack  
SIGUSR1 print statistics  
SIGUSR2 print worker status or wakeup the spooler  
SIGURG restore a snapshot  
SIGTSTP pause/suspend/resume an instance  
SIGWINCH wakeup a worker blocked in a syscall (internal use)  
SIGFPE generate C traceback  
SIGSEGV generate C traceback  

Note: there are better ways to manage your instances than signals, as an example the master-fifo is way more robust.

Reloading the server

When running with the master process mode, the uWSGI server can be gracefully restarted without closing the main sockets.

This functionality allows you patch/upgrade the uWSGI server without closing the connection with the web server and losing a single request.

When you send the SIGHUP to the master process it will try to gracefully stop all the workers, waiting for the completion of any currently running requests.

Then it closes all the eventually opened file descriptors not related to uWSGI.

Lastly, it binary patches (using execve()) the uWSGI process image with a new one, inheriting all of the previous file descriptors.

The server will know that it is a reloaded instance and will skip all the sockets initialization, reusing the previous ones.

Note

Sending the SIGTERM signal will obtain the same result reload-wise but will not wait for the completion of running requests.

There are several ways to make uWSGI gracefully restart.

# using kill to send the signal
kill -HUP `cat /tmp/project-master.pid`
# or the convenience option --reload
uwsgi --reload /tmp/project-master.pid
# or if uwsgi was started with touch-reload=/tmp/somefile
touch /tmp/somefile

Or from your application, in Python:

uwsgi.reload()

Or in Ruby,

UWSGI.reload

Stopping the server

If you have the uWSGI process running in the foreground for some reason, you can just hit CTRL+C to kill it off.

When dealing with background processes, you’ll need to use the master pidfile again. The SIGINT signal will kill uWSGI.

kill -INT `cat /tmp/project-master.pid`
# or for convenience...
uwsgi --stop /tmp/project-master.pid

The Master FIFO

Starting from uWSGI 1.9.17, a new management system has been added using unix named pipes (fifo): The Master FIFO

Supported languages and platforms

Technology Available since Notes Status
Python 0.9.1 The first available plugin, supports WSGI (PEP 333, PEP 3333), Web3 (from version 0.9.7-dev) and Pump (from 0.9.8.4). Works with Virtualenv, multiple Python interpreters, Python3 and has unique features like Aliasing Python modules, DynamicVirtualenv and uGreen – uWSGI Green Threads. A module exporting handy decorators for the uWSGI API is available in the source distribution. PyPy is supported since 1.3. The Python Tracebacker was added in 1.3. Stable, 100% uWSGI API support
Lua 0.9.5 Supports LuaWSAPI, coroutines and threads Stable, 60% uWSGI API support
Perl 0.9.5 uWSGI Perl support (PSGI) (PSGI) support. Multiple interpreters, threading and async modes supported Stable, 60% uWSGI API support
Ruby 0.9.7-dev Ruby support support. A loop engine for Ruby 1.9 fibers is available as well as a handy DSL module. Stable, 80% uWSGI API support
Integrating uWSGI with Erlang 0.9.5 Allows message exchanging between uWSGI and Erlang nodes. Stable, no uWSGI API support
Running CGI scripts on uWSGI 1.0-dev Run CGI scripts Stable, no uWSGI API support
Running PHP scripts in uWSGI 1.0-dev Run PHP scripts Stable from 1.1, 5% uWSGI API support
uWSGI Go support (1.4 only) 1.4-dev Allows integration with the Go language 15% uWSGI API support
JVM in the uWSGI server (updated to 1.9) 1.9-dev Allows integration between uWSGI and the Java Virtual Machine JWSGI and Clojure/Ring handlers are available. Stable
The Mono ASP.NET plugin 0.9.7-dev Allows integration between uWSGI and Mono, and execution of ASP.NET applications. Stable
uWSGI V8 support 1.9.4 Allows integration between uWSGI and the V8 JavaScript engine. Early stage of development

Supported Platforms/Systems

This is the list of officially supported operating systems and platforms.

  • Linux 2.6/3.x
  • FreeBSD
  • NetBSD
  • OpenBSD
  • DragonFlyBSD
  • Windows Cygwin
  • Mac OSX
  • Solaris >= 10
  • NexentaOS
  • SmartOS
  • OpenSolaris
  • OpenIndiana
  • OmniOS
  • Debian/kFreeBSD
  • GNU/Hurd

Web server integration

uWSGI supports several methods of integrating with web servers. It is also capable of serving HTTP requests by itself.

Nginx

See also

Nginx support

The uWSGI module is included in the official Nginx distribution since version 0.8.40. A version supporting Nginx 0.7.x is maintained in the uWSGI package.

This is a stable handler commercially supported by Unbit.

Apache

See also

Apache support

The Apache2 mod_uwsgi module was the first web server integration module developed for uWSGI. It is stable but could be better integrated with the Apache API.

It is commercially supported by Unbit.

Since uWSGI 0.9.6-dev a second Apache2 module called mod_Ruwsgi is included. It’s more Apache API friendly. mod_Ruwsgi is not commercially supported by Unbit.

During the 1.2 development cycle, another module called mod_proxy_uwsgi has been added. In the near future this should be the best choice for Apache based deployments.

Lighttpd (Experimental)

This module is the latest developed, but its inclusion in the official Lighttpd distribution has been rejected, as the main author considers the uwsgi protocol a “reinventing the wheel” technology while suggesting a FastCGI approach. We respect this position. The module will continue to reside in the uWSGI source tree, but it is currently unmaintained.

There is currently no commercial support for this handler. We consider this module “experimental”.

Twisted

This is a “commodity” handler, useful mainly for testing applications without installing a full web server. If you want to develop an uWSGI server, look at this module. Twisted.

Tomcat

The included servlet can be used to forward requests from Tomcat to the uWSGI server. It is stable, but currently lacks documentation.

There is currently no commercial support for this handler.

CGI

The CGI handlers are for “lazy” installations. Their use in production environments is discouraged.

Cherokee (Obsolete)

See also

Cherokee support

The Cherokee webserver officially supports uWSGI. Cherokee is fast and lightweight, has a beautiful admin interface and a great community. Their support for uWSGI has been awesome since the beginning and we recommend its use in most situations. The userbase of the Cherokee uWSGI handler is probably the biggest of all. The Cherokee uWSGI handler is commercially supported by Unbit.

Mongrel2 (Obsolete)

Support for the Mongrel2 Project has been available since 0.9.8-dev via the ZeroMQ protocol plugin.

In our tests Mongrel2 survived practically all of the loads we sent.

Very good and solid project. Try it :)

Frequently Asked Questions (FAQ)

Why should I choose uWSGI?

Because you can! :) uWSGI wants to be a complete web application deployment solution with batteries included:

  • ProcessManagement
  • Management of long-running tasks
  • uWSGI RPC Stack
  • Clustering
  • LoadBalancing
  • Monitoring
  • ResourceLimiting

... and many other annoying everyday tasks that you’d have to delegate to external scripts and manual sysadmin tasks.

If you are searching for a simple server for your WSGI, PSGI or Rack app, uWSGI may not be for you. Though, if you are building an app which needs to be rock solid, fast, and easy to distribute and optimize for various loads, you will most likely find yourself needing uWSGI.

The best definition for uWSGI is “Swiss Army Knife for your network applications”.

What about the protocol?

The uwsgi (all lowercase) protocol is derived from SCGI but with binary string length representations and a 4-byte header that includes the size of the var block (16 bit length) and a couple of general-purpose bytes. We are not reinventing the wheel. Binary management is much easier and cheaper than string parsing, and every single bit of power is required for our projects. If you need proof, look at the official protocol documentation and you will understand why a new protocol was needed. Obviously, you are free to use the other supported protocols. Remember, if you cannot use uWSGI in some scenario, it is a uWSGI bug.

Can I use it in cluster environments?

Yes, this is one of the main features of the uWSGI stack. You can have multiple instances bound on different servers, and using the load balancing facilities of your webserver/proxy/router you can distribute your load. Systems like uWSGI RPC Stack allows you to fast call functions on remote nodes, and The uWSGI Legion subsystem allows you to elect a master in a multi-node setup.

So, why all those timeout configuration flags?

Choosing sane timeouts is the key to high availability. Do not trust network applications that do not permit you to choose a timeout.

I need help! What do I do?

Post a message on the uWSGI mailing list including your

  • Operating system version
  • CPU architecture
  • Webserver used (if any)
  • uWSGI version
  • uWSGI command line or config files

You should add the –show-config option and post the output in the message. It will be very useful for finding out just what’s wrong with your uWSGI. You can also rebuild uWSGI with debug symbols and run it under a debugger like gdb.

uWSGI is an enormous project with hundreds of options. You should be prepared that not everything will go right at the first shot. Ask for help, ask for help and ask for help. If you are frustrated, do not waste time blaming and ranting - instead simply join the list and ask for help. This is open source, if you only rant you are doing nothing useful.

I am not a sysadmin, nor a UNIX guru. Can I use uWSGI?

That’s a good question :) But sadly there is no simple answer. uWSGI has not been developed with simplicity in mind, but with versatility. You can try it by starting with one of the quickstarts and if you have problems, simply ask for help in the list or on the IRC channel.

How can I buy commercial support for my company?

Send an email to info at unbit.it with the word “uWSGI” in the subject. The email you send should include your company information and your specific request. We will reply as soon as possible.

Will this allow me to run my awesome apps on my ancient close-minded ISP?

Probably not. The uWSGI server requires a modern platform/environment.

Where are the benchmarks?

Sorry, we only do “official” benchmarks for regression testing. If benchmarks are very important to you, you can search on the mailing list, make your own benchmarks or search on Google. uWSGI gives precedence to machine health, so do not expect your ab test with an unrealistic number of concurrent connections to be managed flawlessly without tuning. Some socket and networking knowledge is required if you want to make a valid benchmark (and avoid geek rage in your blog comments ;). Also remember that uWSGI can be run in various modes, so avoid comparing it configured in preforking mode with another server in non-blocking/async mode if you do not want to look ridiculous.

Note

If you see your tests failing at higher concurrency rates you are probably hitting your OS socket backlog queue limit (maximum of 128 slots on Linux, tunable via /proc/sys/net/somaxconn and /proc/sys/net/ipv4/tcp_max_syn_backlog for TCP sockets).

You can set this value in uWSGI with the listen configuration option.

Ha! Server XXX is faster than uWSGI! Take that!

As already stated uWSGI is not a silver bullet, it is not meant to be liked by the whole world and it is obviously not the fastest server out there. It is a piece of software following an “approach” to problems you may not like or that you may conversely love. The approach taken will work better for certain cases than others, and each application should be analyzed on it’s own merits using appropriate and accruate real-world benchmarks.

What is ‘Harakiri mode’?

At Unbit we host hundreds of unreliable web apps on our servers. All of them run on hardly constrained (at kernel level) environments where having processes block due to an implementation error will result in taking down an entire site. The harakiri mode has two operational modes:

  • one that we define as “raw and a bit unreliable” (used for simple setup without a process manager)
  • and another one that we define as “reliable” that depends on the presence of the uWSGI process manager (see ProcessManagement).

The first one sets a simple alarm at the start of every request. If the process gets a SIGALRM signal, it terminates itself. We call this unreliable, because your app or some module you use could overwrite or simply cancel the alarm with a simple call to alarm().

The second one uses a master process shared memory area (via mmap) that maintains statistics on every worker in the pool. At the start of every request, the worker sets a timestamp representing the time after which the process will be killed in its dedicated area. This timestamp is zeroed after every successful request. If the master process finds a worker with a timestamp in the past it will mercilessly kill it.

Will my app run faster with uWSGI?

It’s unlikely. The biggest bottleneck in web app deployment is the application itself. If you want a faster environment, optimize your code or use techniques such as clustering or caching. We say that uWSGI is fast because it introduces a very little overhead in the deployment structure.

What are the most important options for performance and robustness in the uWSGI environment?

By default, uWSGI is configured with sane “almost-good-for-all” values. But if and when things start going wild, tuning is a must.

  • Increasing (or decreasing) timeout is important, as is modifying the socket listen queue size.
  • Think about threading. If you do not need threads, do not enable them.
  • If you are running only a single application you can disable multiple interpreters.
  • Always remember to enable the master process in production environments. See ProcessManagement.
  • Adding workers does not mean “increasing performance”, so choose a good value for the workers option based on the nature of your app (IO bound, CPU bound, IO waiting...)

Why not simply use HTTP as the protocol?

A good question with a simple answer: HTTP parsing is slow, really slow. Why should we do a complex task twice? The web server has already parsed the request! The uwsgi protocol is very simple to parse for a machine, while HTTP is very easy to parse for a human. As soon as humans are being used as servers, we will abandon the uwsgi protocol in favor of the HTTP protocol. All this said, you can use uWSGI via Native HTTP support, FastCGI, ZeroMQ and other protocols as well.

Why do you support multiple methods of configuration?

System administration is all about skills and taste. uWSGI tries to give sysadmins as many choices as possible for integration with whatever infrastructure is already available. Having multiple methods of configuration is just one way we achieve this.

What is the best webserver handler?

See Web server integration.

Things to know (best practices and “issues”) READ IT !!!

  • The http and http-socket options are entirely different beasts. The first one spawns an additional process forwarding requests to a series of workers (think about it as a form of shield, at the same level of apache or nginx), while the second one sets workers to natively speak the http protocol. TL/DR: if you plan to expose uWSGI directly to the public, use --http, if you want to proxy it behind a webserver speaking http with backends, use --http-socket. .. seealso:: Native HTTP support

  • Til uWSGI 2.1, by default, sending the SIGTERM signal to uWSGI means “brutally reload the stack” while the convention is to shut an application down on SIGTERM. To shutdown uWSGI use SIGINT or SIGQUIT instead. If you absolutely can not live with uWSGI being so disrespectful towards SIGTERM, by all means enable the die-on-term option. Fortunately, this bad choice has been fixed in uWSGI 2.1

  • If you plan to host multiple applications do yourself a favor and check the The uWSGI Emperor – multi-app deployment docs.

  • Always use uwsgitop, through The uWSGI Stats Server or something similar to monitor your apps’ health.

  • uWSGI can include features in the core or as loadable plugins. uWSGI packages supplied with OS distributions tend to be modular. In such setups, be sure to load the plugins you require with the plugins option. A good symptom to recognize an unloaded plugin is messages like “Unavailable modifier requested” in your logs. If you are using distribution supplied packages, double check that you have installed the plugin for your language of choice.

  • Config files support a limited form of inheritance, variables, if constructs and simple cycles. Check the Configuration logic and How uWSGI parses config files pages.

  • To route requests to a specific plugin, the webserver needs to pass a magic number known as a modifier to the uWSGI instances. By default this number is set to 0, which is mapped to Python. As an example, routing a request to a PSGI app requires you to set the modifier to 5 - or optionally to load the PSGI plugin as modifier 0. (This will mean that all modifierless requests will be considered Perl.)

  • There is no magic rule for setting the number of processes or threads to use. It is very much application and system dependent. Simple math like processes = 2 * cpucores will not be enough. You need to experiment with various setups and be prepared to constantly monitor your apps. uwsgitop could be a great tool to find the best values.

  • If an HTTP request has a body (like a POST request generated by a form), you have to read (consume) it in your application. If you do not do this, the communication socket with your webserver may be clobbered. If you are lazy you can use the post-buffering option that will automatically read data for you. For Rack applications this is automatically enabled.

  • Always check the memory usage of your apps. The memory-report option could be your best friend.

  • If you plan to use UNIX sockets (as opposed to TCP), remember they are standard filesystem objects. This means they have permissions and as such your webserver must have write access to them.

  • Common sense: do not run uWSGI instances as root. You can start your uWSGIs as root, but be sure to drop privileges with the uid and gid options.

  • uWSGI tries to (ab)use the Copy On Write semantics of the fork() call whenever possible. By default it will fork after having loaded your applications to share as much of their memory as possible. If this behavior is undesirable for some reason, use the lazy-apps option. This will instruct uWSGI to load the applications after each worker’s fork(). Beware as there is an older options named lazy that is way more invasive and highly discouraged (it is still here only for backward compatibility)

  • By default the Python plugin does not initialize the GIL. This means your app-generated threads will not run. If you need threads, remember to enable them with enable-threads. Running uWSGI in multithreading mode (with the threads options) will automatically enable threading support. This “strange” default behaviour is for performance reasons, no shame in that.

  • If you spawn a new process during a request it will inherit the file descriptors of the worker spawning it - including the socket connected with the webserver/router. If you do not want this behaviour set the close-on-exec option.

  • The Ruby garbage collector is configured by default to run after every request. This is an aggressive policy that may slow down your apps a bit – but CPU resources are cheaper than memory, and especially cheaper than running out of memory. To tune this frequency use the ruby-gc <freq> option.

  • On OpenBSD, NetBSD and FreeBSD < 9, SysV IPC semaphores are used as the locking subsystem. These operating systems tend to limit the number of allocable semaphores to fairly small values. You should raise the default limits if you plan to run more than one uWSGI instance. FreeBSD 9 has POSIX semaphores, so you do not need to bother with that.

  • Do not build plugins using a different config file than used to build the uWSGI binary itself – unless you like pain or know exactly what you are doing.

  • By default uWSGI allocates a very small buffer (4096 bytes) for the headers of each request. If you start receiving “invalid request block size” in your logs, it could mean you need a bigger buffer. Increase it (up to 65535) with the buffer-size option.

    Note

    If you receive ‘21573’ as the request block size in your logs, it could mean you are using the HTTP protocol to speak with an instance speaking the uwsgi protocol. Don’t do this.

  • If your (Linux) server seems to have lots of idle workers, but performance is still sub-par, you may want to look at the value of the ip_conntrack_max system variable (/proc/sys/net/ipv4/ip_conntrack_max) and increase it to see if it helps.

  • Some Linux distributions (read: Debian 4 Etch, RHEL / CentOS 5) make a mix of newer kernels with very old userspace. This kind of combination can make the uWSGI build system spit out errors (most notably on unshare(), pthread locking, inotify...). You can force uWSGI to configure itself for an older system prefixing the ‘make’ (or whatever way you use to build it) with CFLAGS="-DOBSOLETE_LINUX_KERNEL"

  • By default, stdin is remapped to /dev/null on uWSGI startup. If you need a valid stdin (for debugging, piping and so on) add --honour-stdin.

  • You can easily add non-existent options to your config files (as placeholders, custom options, or app-related configuration items). This is a really handy feature, but can lead to headaches on typos. The strict mode (--strict) will disable this feature, and only valid uWSGI options are tolerated.

  • Some plugins (most notably Python and Perl) have code auto-reloading facilities. Although they might sound very appealing, you MUST use them only under development as they are really heavy-weight. For example the Python –py-autoreload option will scan your whole module tree at every check cycle.

  • wsgi.file_wrapper is an optimization of the WSGI standard. In some corner case it can raise an error. For example when returning an in-memory bytes buffer (io.Bytesio) in Python 3.5. See this issue. You can disable it by setting the option wsgi-disable-file-wrapper to true.

Configuring uWSGI

uWSGI can be configured using several different methods. All configuration methods may be mixed and matched in the same invocation of uWSGI.

Note

Some of the configuration methods may require a specific plugin (ie. sqlite and ldap).

The configuration system is unified, so each command line option maps 1:1 with entries in the config files.

Example:

uwsgi --http-socket :9090 --psgi myapp.pl

can be written as

[uwsgi]
http-socket = :9090
psgi = myapp.pl

Loading configuration files

uWSGI supports loading configuration files over several methods other than simple disk files:

uwsgi --ini http://uwsgi.it/configs/myapp.ini # HTTP
uwsgi --xml - # standard input
uwsgi --yaml fd://0 # file descriptor
uwsgi --json 'exec://nc 192.168.11.2:33000' # arbitrary executable

Note

More esoteric file sources, such as the Emperor, embedded configuration (in two flavors), dynamic library symbols and ELF sections could also be used.

Magic variables

uWSGI configuration files can include “magic” variables, prefixed with a percent sign. Currently the following magic variables (you can access them in Python via uwsgi.magic_table) are defined.

%v the vassals directory (pwd)
%V the uWSGI version
%h the hostname
%o the original config filename, as specified on the command line
%O same as %o but refer to the first non-template config file (version 1.9.18)
%p the absolute path of the configuration file
%P same as %p but refer to the first non-template config file (version 1.9.18)
%s the filename of the configuration file
%S same as %s but refer to the first non-template config file (version 1.9.18)
%d the absolute path of the directory containing the configuration file
%D same as %d but refer to the first non-template config file (version 1.9.18)
%e the extension of the configuration file
%E same as %e but refer to the first non-template config file (version 1.9.18)
%n the filename without extension
%N same as %n but refer to the first non-template config file (version 1.9.18)
%c the name of the directory containing the config file (version 1.3+)
%C same as %c but refer to the first non-template config file (version 1.9.18)
%t unix time (in seconds, gathered at instance startup) (version 1.9.20-dev+)
%T unix time (in microseconds, gathered at instance startup) (version 1.9.20-dev+)
%x the current section identifier, eg. config.ini:section (version 1.9-dev+)
%X same as %x but refer to the first non-template config file (version 1.9.18)
%i inode number of the file (version 2.0.1)
%I same as %i but refer to the first non-template config file
%0..%9 a specific component of the full path of the directory containing the config file (version 1.3+)
%[ ANSI escape “\033” (useful for printing colors)
%k detected cpu cores (version 1.9.20-dev+)
%u uid of the user running the process (version 2.0)
%U username (if available, otherwise fallback to uid) of the user running the process (version 2.0)
%g gid of the user running the process (version 2.0)
%G group name (if available, otherwise fallback to gid) of the user running the process (version 2.0)
%j HEX representation of the djb33x hash of the full config path
%J same as %j but refer to the first non-template config file

Note that most of these refer to the file they appear in, even if that file is included from another file.

An exception are most of the uppercase versions, which refer to the first non-template config file loaded. This means the first config file not loaded through --include or --inherit, but through for example --ini, --yaml or --config. These are intended to use with the emperor, to refer to the actual vassal config file instead of templates included with --vassals-include or --vassals-inherit.

For example, here’s funnyapp.ini.

[uwsgi]
socket = /tmp/%n.sock
module = werkzeug.testapp:test_app
processes = 4
master = 1

%n will be replaced with the name of the config file, sans extension, so the result in this case will be

[uwsgi]
socket = /tmp/funnyapp.sock
module = werkzeug.testapp:test_app
processes = 4
master = 1

Placeholders

Placeholders are custom magic variables defined during configuration time by setting a new configuration variable of your own devising.

[uwsgi]
; These are placeholders...
my_funny_domain = uwsgi.it
set-ph = max_customer_address_space=64
set-placeholder = customers_base_dir=/var/www
; And these aren't.
socket = /tmp/sockets/%(my_funny_domain).sock
chdir = %(customers_base_dir)/%(my_funny_domain)
limit-as = %(max_customer_address_space)

Placeholders can be assigned directly, or using the set-placeholder / set-ph option. These latter options can be useful to:

  • Make it more explicit that you’re setting placeholders instead of regular options.
  • Set options on the commandline, since unknown options like --foo=bar are rejected but --set-placeholder foo=bar is ok.
  • Set placeholders when strict mode is enabled.

Placeholders are accessible, like any uWSGI option, in your application code via uwsgi.opt.

import uwsgi
print uwsgi.opt['customers_base_dir']

This feature can be (ab)used to reduce the number of configuration files required by your application.

Similarly, contents of evironment variables and external text files can be included using the $(ENV_VAR) and @(file_name) syntax. See also How uWSGI parses config files.

Placeholders math (from uWSGI 1.9.20-dev)

You can apply math formulas to placeholders using this special syntax:

[uwsgi]
foo = 17
bar = 30
; total will be 50
total = %(foo + bar + 3)

Remember to not miss spaces between operations.

Operations are executed in a pipeline (not in common math style):

[uwsgi]
foo = 17
bar = 30
total = %(foo + bar + 3 * 2)

‘total’ will be evaluated as 100:

(((foo + bar) + 3) * 2)

Incremental and decremental shortcuts are available

[uwsgi]
foo = 29
; remember the space !!!
bar = %(foo ++)

bar will be 30

If you do not specify an operation between two items, ‘string concatenation’ is assumed:

[uwsgi]
foo = 2
bar = 9
; remember the space !!!
bar = %(foo bar ++)

the first two items will be evaluated as ‘29’ (not 11 as no math operation has been specified)

The ‘@’ magic

We have already seen we can use the form @(filename) to include the contents of a file

[uwsgi]
foo = @(/tmp/foobar)

the truth is that ‘@’ can read from all of the supported uwsgi schemes

[uwsgi]
; read from a symbol
foo = @(sym://uwsgi_funny_function)
; read from binary appended data
bar = @(data://0)
; read from http
test = @(http://example.com/hello)
; read from a file descriptor
content = @(fd://3)
; read from a process stdout
body = @(exec://foo.pl)
; call a function returning a char *
characters = @(call://uwsgi_func)

Command line arguments

Example:

uwsgi --socket /tmp/uwsgi.sock --socket 127.0.0.1:8000 --master --workers 3

Environment variables

When passed as environment variables, options are capitalized and prefixed with UWSGI_, and dashes are substituted with underscores.

Note

Several values for the same configuration variable are not supported with this method.

Example:

UWSGI_SOCKET=127.0.0.1 UWSGI_MASTER=1 UWSGI_WORKERS=3 uwsgi

INI files

.INI files are a standard de-facto configuration format used by many applications. It consists of [section]s and key=value pairs.

An example uWSGI INI configuration:

[uwsgi]
socket = /tmp/uwsgi.sock
socket = 127.0.0.1:8000
workers = 3
master = true

By default, uWSGI uses the [uwsgi] section, but you can specify another section name while loading the INI file with the syntax filename:section, that is:

uwsgi --ini myconf.ini:app1

Alternatively, you can load another section from the same file by omitting the filename and specifying just the section name. Note that technically, this loads the named section from the last .ini file loaded instead of the current one, so be careful when including other files.

[uwsgi]
# This will load the app1 section below
ini = :app1
# This will load the defaults.ini file
ini = defaults.ini
# This will load the app2 section from the defaults.ini file!
ini = :app2

[app1]
plugin = rack

[app2]
plugin = php
  • Whitespace is insignificant within lines.
  • Lines starting with a semicolon (;) or a hash/octothorpe (#) are ignored as comments.
  • Boolean values may be set without the value part. Simply master is thus equivalent to master=true. This may not be compatible with other INI parsers such as paste.deploy.
  • For convenience, uWSGI recognizes bare .ini arguments specially, so the invocation uwsgi myconf.ini is equal to uwsgi --ini myconf.ini.

XML files

The root node should be <uwsgi> and option values text nodes.

An example:

<uwsgi>
  <socket>/tmp/uwsgi.sock</socket>
  <socket>127.0.0.1:8000</socket>
  <master/>
  <workers>3</workers>
</uwsgi>

You can also have multiple <uwsgi> stanzas in your file, marked with different id attributes. To choose the stanza to use, specify its id after the filename in the xml option, using a colon as a separator. When using this id mode, the root node of the file may be anything you like. This will allow you to embed uwsgi configuration nodes in other XML files.

<i-love-xml>
  <uwsgi id="turbogears"><socket>/tmp/tg.sock</socket></uwsgi>
  <uwsgi id="django"><socket>/tmp/django.sock</socket></uwsgi>
</i-love-xml>
  • Boolean values may be set without a text value.
  • For convenience, uWSGI recognizes bare .xml arguments specially, so the invocation uwsgi myconf.xml is equal to uwsgi --xml myconf.xml.

JSON files

The JSON file should represent an object with one key-value pair, the key being “uwsgi” and the value an object of configuration variables. Native JSON lists, booleans and numbers are supported.

An example:

{"uwsgi": {
  "socket": ["/tmp/uwsgi.sock", "127.0.0.1:8000"],
  "master": true,
  "workers": 3
}}

Again, a named section can be loaded using a colon after the filename.

{"app1": {
  "plugin": "rack"
}, "app2": {
  "plugin": "php"
}}

And then load this using:

uwsgi --json myconf.json:app2

Note

The Jansson library is required during uWSGI build time to enable JSON support. By default the presence of the library will be auto-detected and JSON support will be automatically enabled, but you can force JSON support to be enabled or disabled by editing your build configuration.

See also

Installing uWSGI

YAML files

The root element should be uwsgi. Boolean options may be set as true or 1.

An example:

uwsgi:
  socket: /tmp/uwsgi.sock
  socket: 127.0.0.1:8000
  master: 1
  workers: 3

Again, a named section can be loaded using a colon after the filename.

app1:
  plugin: rack
app2:
  plugin: php

And then load this using:

uwsgi --yaml myconf.yaml:app2

SQLite configuration

Note

Under construction.

LDAP configuration

LDAP is a flexible way to centralize configuration of large clusters of uWSGI servers. Configuring it is a complex topic. See Configuring uWSGI with LDAP for more information.

Fallback configuration

(available from 1.9.15-dev)

If you need a “reset to factory defaults”, or “show a welcome page if the user has made mess with its config” scenario, fallback configuration is your silver bullet

Simple case

A very common problem is screwing-up the port on which the instance is listening.

To emulate this kind of error we try to bind on port 80 as an unprivileged user:

uwsgi --uid 1000 --http-socket :80

uWSGI will exit with:

bind(): Permission denied [core/socket.c line 755]

Internally (from the kernel point of view) the instance exited with status 1

Now we want to allow the instance to automatically bind on port 8080 when the user supplied config fails.

Let’s define a fallback config (you can save it as safe.ini):

[uwsgi]
print = Hello i am the fallback config !!!
http-socket = :8080
wsgi-file = welcomeapp.wsgi

Now we can re-run the (broken) instance:

uwsgi --fallback-config safe.ini --uid 1000 --http-socket :80

Your error will be now something like:

bind(): Permission denied [core/socket.c line 755]
Thu Jul 25 21:55:39 2013 - !!! /home/roberto/uwsgi/uwsgi (pid: 7409) exited with status 1 !!!
Thu Jul 25 21:55:39 2013 - !!! Fallback config to safe.ini !!!
[uWSGI] getting INI configuration from safe.ini
*** Starting uWSGI 1.9.15-dev-a0cb71c (64bit) on [Thu Jul 25 21:55:39 2013] ***
...

As you can see, the instance has detected the exit code 1 and has binary patched itself with a new config (without changing the pid, or calling fork())

Broken apps

Another common problem is the inability to load an application, but instead of bringing down the whole site we want to load an alternate application:

uwsgi --fallback-config safe.ini --need-app --http-socket :8080 --wsgi-file brokenapp.py

Here the key is –need-app. It will call exit(1) if the instance has not been able to load at least one application.

Multiple fallback levels

Your fallback config file can specify a fallback-config directive too, allowing multiple fallback levels. BEWARE OF LOOPS!!!

How it works

The objective is catching the exit code of a process before the process itself is destroyed (we do not want to call another fork(), or destroy already opened file descriptors)

uWSGI makes heavy usage of atexit() hooks, so we only need to register the fallback handler as the first one (hooks are executed in reverse order).

In addition to this we need to get the exit code in our atexit() hook, something is not supported by default (the on_exit() function is now deprecated).

The solution is “patching” exit(x) with uwsgi_exit(x) that is a simple wrapper setting uwsgi.last_exit_code memory pointer.

Now the hook only needs to check for uwsgi.last_exit_code == 1 and eventually execve() the binary again passing the fallback config to it

char *argv[3];
argv[0] = uwsgi.binary_path;
argv[1] = uwsgi.fallback_config;
argv[2] = NULL;
execvp(uwsgi.binary_path, argv);

Notes

Try to place –fallback-config as soon as possible in your config tree. The various config parsers may fail (calling exit(1)) before the fallback file is registered

Configuration logic

Starting from 1.1 certain logic constructs are available.

The following statements are currently supported:

  • for .. endfor
  • if-dir / if-not-dir
  • if-env / if-not-env
  • if-exists / if-not-exists
  • if-file / if-not-file
  • if-opt / if-not-opt
  • if-reload / if-not-reload – undocumented

Each of these statements exports a context value you can access with the special placeholder %(_). For example, the “for” statement sets %(_) to the current iterated value.

Warning

Recursive logic is not supported and will cause uWSGI to promptly exit.

for

For iterates over space-separated strings. The following three code blocks are equivalent.

[uwsgi]
master = true
; iterate over a list of ports
for = 3031 3032 3033 3034 3035
socket = 127.0.0.1:%(_)
endfor =
module = helloworld
<uwsgi>
  <master/>
  <for>3031 3032 3033 3034 3035</for>
    <socket>127.0.0.1:%(_)</socket>
  <endfor/>
  <module>helloworld</module>
</uwsgi>
uwsgi --for="3031 3032 3033 3034 3035" --socket="127.0.0.1:%(_)" --endfor --module helloworld

Note that the for-loop is applied to each line inside the block separately, not to the block as a whole. For example, this:

[uwsgi]
for = a b c
socket = /var/run/%(_).socket
http-socket = /var/run/%(_)-http.socket
endfor =

is expanded to:

[uwsgi]
socket = /var/run/a.socket
socket = /var/run/b.socket
socket = /var/run/c.socket
http-socket = /var/run/a-http.socket
http-socket = /var/run/b-http.socket
http-socket = /var/run/c-http.socket

if-env

Check if an environment variable is defined, putting its value in the context placeholder.

[uwsgi]
if-env = PATH
print = Your path is %(_)
check-static = /var/www
endif =
socket = :3031

if-exists

Check for the existence of a file or directory. The context placeholder is set to the filename found.

[uwsgi]
http = :9090
; redirect all requests if a file exists
if-exists = /tmp/maintenance.txt
route = .* redirect:/offline
endif =

Note

The above example uses uWSGI internal routing.

if-file

Check if the given path exists and is a regular file. The context placeholder is set to the filename found.

<uwsgi>
  <plugins>python</plugins>
  <http-socket>:8080</http-socket>
  <if-file>settings.py</if-file>
    <module>django.core.handlers.wsgi:WSGIHandler()</module>
  <endif/>
</uwsgi>

if-dir

Check if the given path exists and is a directory. The context placeholder is set to the filename found.

uwsgi:
  socket: 4040
  processes: 2
  if-dir: config.ru
  rack: %(_)
  endif:

if-opt

Check if the given option is set, or has a given value. The context placeholder is set to the value of the option reference.

To check if an option was set, pass just the option name to if-opt.

uwsgi:
  cheaper: 3
  if-opt: cheaper
  print: Running in cheaper mode, with initially %(_) processes
  endif:

To check if an option was set to a specific value, pass option-name=value to if-opt.

uwsgi:
  # Set busyness parameters if it was chosen
  if-opt: cheaper-algo=busyness
  cheaper-busyness-max: 25
  cheaper-busyness-min: 10
  endif:

Due to the way uWSGI parses its configs, you can only refer to options that uWSGI has previously seen. In particular, this means:

  • Only options that are set above the if-opt option are taken into account. This includes any options set by previous include (or type specific includes like ini) options, but does not include options set by previous inherit options).

  • if-opt is processed after expanding magic variables, but before expanding placeholders and other variables. So if you use if-opt to compare the value of an option, check against the value as stated in the config file, with only the magic variables filled in.

    If you use the context placeholder %(_) inside the if-opt block, you should be ok: any placeholders will later be expanded.

  • If an option is specified multiple times, only the value of the first one will be seen by if-opt.

  • Only explicitly set values will be seen, not implicit defaults.

uWSGI Options

This is an automatically generated reference list of the uWSGI options.

It is the same output you can get via the --help option.

This page is probably the worst way to understand uWSGI for newbies. If you are still learning how the project works, you should read the various quickstarts and tutorials.

Each option has the following attributes:

  • argument: it is the struct option (used by getopt()/getopt_long()) has_arg element. Can be ‘required_argument’, ‘no_argument’ or ‘optional_argument’
  • shortcut: some option can be specified with the short form (a dash followed by a single letter)
  • parser: this is how uWSGI parses the parameter. There are dozens of way, the most common are ‘uwsgi_opt_set_str’ when it takes a simple string, ‘uwsgi_opt_set_int’ when it takes a 32bit number, ‘uwsgi_opt_add_string_list’ when the parameter can be specified multiple times to build a list.
  • help: the help message, the same you get from uwsgi --help
  • reference: a link to a documentation page that gives better understanding and context of an option

You can add more detailed infos to this page, editing https://github.com/unbit/uwsgi-docs/blob/master/optdefs.pl (please, double check it before sending a pull request)

uWSGI core

socket

argument: required_argument

shortcut: -s

parser: uwsgi_opt_add_socket

help: bind to the specified UNIX/TCP socket using default protocol

uwsgi-socket

argument: required_argument

shortcut: -s

parser: uwsgi_opt_add_socket

help: bind to the specified UNIX/TCP socket using uwsgi protocol

suwsgi-socket

argument: required_argument

parser: uwsgi_opt_add_ssl_socket

help: bind to the specified UNIX/TCP socket using uwsgi protocol over SSL

ssl-socket

argument: required_argument

parser: uwsgi_opt_add_ssl_socket

help: bind to the specified UNIX/TCP socket using uwsgi protocol over SSL

http-socket

argument: required_argument

parser: uwsgi_opt_add_socket

help: bind to the specified UNIX/TCP socket using HTTP protocol

http-socket-modifier1

argument: required_argument

parser: uwsgi_opt_set_64bit

help: force the specified modifier1 when using HTTP protocol

http-socket-modifier2

argument: required_argument

parser: uwsgi_opt_set_64bit

help: force the specified modifier2 when using HTTP protocol

http11-socket

argument: required_argument

parser: uwsgi_opt_add_socket

help: bind to the specified UNIX/TCP socket using HTTP 1.1 (Keep-Alive) protocol

https-socket

argument: required_argument

parser: uwsgi_opt_add_ssl_socket

help: bind to the specified UNIX/TCP socket using HTTPS protocol

https-socket-modifier1

argument: required_argument

parser: uwsgi_opt_set_64bit

help: force the specified modifier1 when using HTTPS protocol

https-socket-modifier2

argument: required_argument

parser: uwsgi_opt_set_64bit

help: force the specified modifier2 when using HTTPS protocol

fastcgi-socket

argument: required_argument

parser: uwsgi_opt_add_socket

help: bind to the specified UNIX/TCP socket using FastCGI protocol

fastcgi-nph-socket

argument: required_argument

parser: uwsgi_opt_add_socket

help: bind to the specified UNIX/TCP socket using FastCGI protocol (nph mode)

fastcgi-modifier1

argument: required_argument

parser: uwsgi_opt_set_64bit

help: force the specified modifier1 when using FastCGI protocol

fastcgi-modifier2

argument: required_argument

parser: uwsgi_opt_set_64bit

help: force the specified modifier2 when using FastCGI protocol

scgi-socket

argument: required_argument

parser: uwsgi_opt_add_socket

help: bind to the specified UNIX/TCP socket using SCGI protocol

scgi-nph-socket

argument: required_argument

parser: uwsgi_opt_add_socket

help: bind to the specified UNIX/TCP socket using SCGI protocol (nph mode)

scgi-modifier1

argument: required_argument

parser: uwsgi_opt_set_64bit

help: force the specified modifier1 when using SCGI protocol

scgi-modifier2

argument: required_argument

parser: uwsgi_opt_set_64bit

help: force the specified modifier2 when using SCGI protocol

raw-socket

argument: required_argument

parser: uwsgi_opt_add_socket_no_defer

help: bind to the specified UNIX/TCP socket using RAW protocol

raw-modifier1

argument: required_argument

parser: uwsgi_opt_set_64bit

help: force the specified modifier1 when using RAW protocol

raw-modifier2

argument: required_argument

parser: uwsgi_opt_set_64bit

help: force the specified modifier2 when using RAW protocol

puwsgi-socket

argument: required_argument

parser: uwsgi_opt_add_socket

help: bind to the specified UNIX/TCP socket using persistent uwsgi protocol (puwsgi)

protocol

argument: required_argument

parser: uwsgi_opt_set_str

help: force the specified protocol for default sockets

socket-protocol

argument: required_argument

parser: uwsgi_opt_set_str

help: force the specified protocol for default sockets

shared-socket

argument: required_argument

parser: uwsgi_opt_add_shared_socket

help: create a shared socket for advanced jailing or ipc

undeferred-shared-socket

argument: required_argument

parser: uwsgi_opt_add_shared_socket

help: create a shared socket for advanced jailing or ipc (undeferred mode)

processes

argument: required_argument

shortcut: -p

parser: uwsgi_opt_set_int

help: spawn the specified number of workers/processes

workers

argument: required_argument

shortcut: -p

parser: uwsgi_opt_set_int

help: spawn the specified number of workers/processes

thunder-lock

argument: no_argument

parser: uwsgi_opt_true

help: serialize accept() usage (if possible)

reference: Serializing accept(), AKA Thundering Herd, AKA the Zeeg Problem

harakiri

argument: required_argument

shortcut: -t

parser: uwsgi_opt_set_int

help: set harakiri timeout

harakiri-verbose

argument: no_argument

parser: uwsgi_opt_true

help: enable verbose mode for harakiri

harakiri-no-arh

argument: no_argument

parser: uwsgi_opt_true

help: do not enable harakiri during after-request-hook

no-harakiri-arh

argument: no_argument

parser: uwsgi_opt_true

help: do not enable harakiri during after-request-hook

no-harakiri-after-req-hook

argument: no_argument

parser: uwsgi_opt_true

help: do not enable harakiri during after-request-hook

backtrace-depth

argument: required_argument

parser: uwsgi_opt_set_int

help: set backtrace depth

mule-harakiri

argument: required_argument

parser: uwsgi_opt_set_int

help: set harakiri timeout for mule tasks

xmlconfig

argument: required_argument

shortcut: -x

parser: uwsgi_opt_load_xml

flags: UWSGI_OPT_IMMEDIATE

help: load config from xml file

xml

argument: required_argument

shortcut: -x

parser: uwsgi_opt_load_xml

flags: UWSGI_OPT_IMMEDIATE

help: load config from xml file

config

argument: required_argument

parser: uwsgi_opt_load_config

flags: UWSGI_OPT_IMMEDIATE

help: load configuration using the pluggable system

fallback-config

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_IMMEDIATE

help: re-exec uwsgi with the specified config when exit code is 1

strict

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_IMMEDIATE

help: enable strict mode (placeholder cannot be used)

skip-zero

argument: no_argument

parser: uwsgi_opt_true

help: skip check of file descriptor 0

skip-atexit

argument: no_argument

parser: uwsgi_opt_true

help: skip atexit hooks (ignored by the master)

skip-atexit

argument: no_argument

parser: uwsgi_opt_true

help: skip atexit teardown (ignored by the master)

set

argument: required_argument

shortcut: -S

parser: uwsgi_opt_set_placeholder

flags: UWSGI_OPT_IMMEDIATE

help: set a placeholder or an option

set-placeholder

argument: required_argument

parser: uwsgi_opt_set_placeholder

flags: UWSGI_OPT_IMMEDIATE

help: set a placeholder

set-ph

argument: required_argument

parser: uwsgi_opt_set_placeholder

flags: UWSGI_OPT_IMMEDIATE

help: set a placeholder

get

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_NO_INITIAL

help: print the specified option value and exit

declare-option

argument: required_argument

parser: uwsgi_opt_add_custom_option

flags: UWSGI_OPT_IMMEDIATE

help: declare a new uWSGI custom option

reference: Defining new options for your instances

declare-option2

argument: required_argument

parser: uwsgi_opt_add_custom_option

help: declare a new uWSGI custom option (non-immediate)

resolve

argument: required_argument

parser: uwsgi_opt_resolve

flags: UWSGI_OPT_IMMEDIATE

help: place the result of a dns query in the specified placeholder, sytax: placeholder=name (immediate option)

for

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) for cycle

for-glob

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) for cycle (expand glob)

for-times

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) for cycle (expand the specified num to a list starting from 1)

for-readline

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) for cycle (expand the specified file to a list of lines)

endfor

argument: optional_argument

parser: uwsgi_opt_noop

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) end for cycle

end-for

argument: optional_argument

parser: uwsgi_opt_noop

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) end for cycle

if-opt

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for option

if-not-opt

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for option

if-env

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for environment variable

if-not-env

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for environment variable

ifenv

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for environment variable

if-reload

argument: no_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for reload

if-not-reload

argument: no_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for reload

if-hostname

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for hostname

if-not-hostname

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for hostname

if-hostname-match

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) try to match hostname against a regular expression

if-not-hostname-match

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) try to match hostname against a regular expression

if-exists

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for file/directory existance

if-not-exists

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for file/directory existance

ifexists

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for file/directory existance

if-plugin

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for plugin

if-not-plugin

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for plugin

ifplugin

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for plugin

if-file

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for file existance

if-not-file

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for file existance

if-dir

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for directory existance

if-not-dir

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for directory existance

ifdir

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for directory existance

if-directory

argument: required_argument

parser: uwsgi_opt_logic

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) check for directory existance

endif

argument: optional_argument

parser: uwsgi_opt_noop

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) end if

end-if

argument: optional_argument

parser: uwsgi_opt_noop

flags: UWSGI_OPT_IMMEDIATE

help: (opt logic) end if

blacklist

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_IMMEDIATE

help: set options blacklist context

end-blacklist

argument: no_argument

parser: uwsgi_opt_set_null

flags: UWSGI_OPT_IMMEDIATE

help: clear options blacklist context

whitelist

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_IMMEDIATE

help: set options whitelist context

end-whitelist

argument: no_argument

parser: uwsgi_opt_set_null

flags: UWSGI_OPT_IMMEDIATE

help: clear options whitelist context

ignore-sigpipe

argument: no_argument

parser: uwsgi_opt_true

help: do not report (annoying) SIGPIPE

ignore-write-errors

argument: no_argument

parser: uwsgi_opt_true

help: do not report (annoying) write()/writev() errors

write-errors-tolerance

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set the maximum number of allowed write errors (default: no tolerance)

write-errors-exception-only

argument: no_argument

parser: uwsgi_opt_true

help: only raise an exception on write errors giving control to the app itself

disable-write-exception

argument: no_argument

parser: uwsgi_opt_true

help: disable exception generation on write()/writev()

inherit

argument: required_argument

parser: uwsgi_opt_load

help: use the specified file as config template

include

argument: required_argument

parser: uwsgi_opt_load

flags: UWSGI_OPT_IMMEDIATE

help: include the specified file as immediate configuration

inject-before

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_IMMEDIATE

help: inject a text file before the config file (advanced templating)

inject-after

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_IMMEDIATE

help: inject a text file after the config file (advanced templating)

daemonize

argument: required_argument

shortcut: -d

parser: uwsgi_opt_set_str

help: daemonize uWSGI

daemonize2

argument: required_argument

parser: uwsgi_opt_set_str

help: daemonize uWSGI after app loading

stop

argument: required_argument

parser: uwsgi_opt_pidfile_signal

flags: UWSGI_OPT_IMMEDIATE

help: stop an instance

reload

argument: required_argument

parser: uwsgi_opt_pidfile_signal

flags: UWSGI_OPT_IMMEDIATE

help: reload an instance

pause

argument: required_argument

parser: uwsgi_opt_pidfile_signal

flags: UWSGI_OPT_IMMEDIATE

help: pause an instance

suspend

argument: required_argument

parser: uwsgi_opt_pidfile_signal

flags: UWSGI_OPT_IMMEDIATE

help: suspend an instance

resume

argument: required_argument

parser: uwsgi_opt_pidfile_signal

flags: UWSGI_OPT_IMMEDIATE

help: resume an instance

connect-and-read

argument: required_argument

parser: uwsgi_opt_connect_and_read

flags: UWSGI_OPT_IMMEDIATE

help: connect to a socket and wait for data from it

extract

argument: required_argument

parser: uwsgi_opt_extract

flags: UWSGI_OPT_IMMEDIATE

help: fetch/dump any supported address to stdout

listen

argument: required_argument

shortcut: -l

parser: uwsgi_opt_set_int

help: set the socket listen queue size

max-vars

argument: required_argument

shortcut: -v

parser: uwsgi_opt_max_vars

help: set the amount of internal iovec/vars structures

max-apps

argument: required_argument

parser: uwsgi_opt_set_int

help: set the maximum number of per-worker applications

buffer-size

argument: required_argument

shortcut: -b

parser: uwsgi_opt_set_64bit

help: set internal buffer size

Set the max size of a request (request-body excluded), this generally maps to the size of request headers. By default it is 4k. If you receive a bigger request (for example with big cookies or query string) you may need to increase it. It is a security measure too, so adapt to your app needs instead of maxing it out.

memory-report

argument: no_argument

shortcut: -m

parser: uwsgi_opt_true

help: enable memory report

profiler

argument: required_argument

parser: uwsgi_opt_set_str

help: enable the specified profiler

cgi-mode

argument: no_argument

shortcut: -c

parser: uwsgi_opt_true

help: force CGI-mode for plugins supporting it

abstract-socket

argument: no_argument

shortcut: -a

parser: uwsgi_opt_true

help: force UNIX socket in abstract mode (Linux only)

chmod-socket

argument: optional_argument

shortcut: -C

parser: uwsgi_opt_chmod_socket

help: chmod-socket

chmod

argument: optional_argument

shortcut: -C

parser: uwsgi_opt_chmod_socket

help: chmod-socket

chown-socket

argument: required_argument

parser: uwsgi_opt_set_str

help: chown unix sockets

umask

argument: required_argument

parser: uwsgi_opt_set_umask

flags: UWSGI_OPT_IMMEDIATE

help: set umask

freebind

argument: no_argument

parser: uwsgi_opt_true

help: put socket in freebind mode

set the IP_FREEBIND flag to every socket created by uWSGI. This kind of socket can bind to non-existent ip addresses. Its main purpose is for high availability (this is Linux only)

map-socket

argument: required_argument

parser: uwsgi_opt_add_string_list

help: map sockets to specific workers

enable-threads

argument: no_argument

shortcut: -T

parser: uwsgi_opt_true

help: enable threads

no-threads-wait

argument: no_argument

parser: uwsgi_opt_true

help: do not wait for threads cancellation on quit/reload

auto-procname

argument: no_argument

parser: uwsgi_opt_true

help: automatically set processes name to something meaningful

procname-prefix

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_PROCNAME

help: add a prefix to the process names

procname-prefix-spaced

argument: required_argument

parser: uwsgi_opt_set_str_spaced

flags: UWSGI_OPT_PROCNAME

help: add a spaced prefix to the process names

procname-append

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_PROCNAME

help: append a string to process names

procname

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_PROCNAME

help: set process names

procname-master

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_PROCNAME

help: set master process name

single-interpreter

argument: no_argument

shortcut: -i

parser: uwsgi_opt_true

help: do not use multiple interpreters (where available)

need-app

argument: no_argument

parser: uwsgi_opt_true

help: exit if no app can be loaded

master

argument: no_argument

shortcut: -M

parser: uwsgi_opt_true

help: enable master process

honour-stdin

argument: no_argument

parser: uwsgi_opt_true

help: do not remap stdin to /dev/null

emperor

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the Emperor

reference: The uWSGI Emperor – multi-app deployment

The Emperor is a special uWSGI instance aimed at governing other uWSGI instances (named: vassals). By default it is configured to monitor a directory containing valid uWSGI config files, whenever a file is created a new instance is spawned, when the file is touched the instance is reloaded, when the file is removed the instance is destroyed. It can be extended to support more paradigms

emperor-proxy-socket

argument: required_argument

parser: uwsgi_opt_set_str

help: force the vassal to became an Emperor proxy

emperor-wrapper

argument: required_argument

parser: uwsgi_opt_set_str

help: set a binary wrapper for vassals

emperor-nofollow

argument: no_argument

parser: uwsgi_opt_true

help: do not follow symlinks when checking for mtime

emperor-procname

argument: required_argument

parser: uwsgi_opt_set_str

help: set the Emperor process name

emperor-freq

argument: required_argument

parser: uwsgi_opt_set_int

help: set the Emperor scan frequency (default 3 seconds)

emperor-required-heartbeat

argument: required_argument

parser: uwsgi_opt_set_int

help: set the Emperor tolerance about heartbeats

emperor-curse-tolerance

argument: required_argument

parser: uwsgi_opt_set_int

help: set the Emperor tolerance about cursed vassals

emperor-pidfile

argument: required_argument

parser: uwsgi_opt_set_str

help: write the Emperor pid in the specified file

emperor-tyrant

argument: no_argument

parser: uwsgi_opt_true

help: put the Emperor in Tyrant mode

emperor-tyrant-nofollow

argument: no_argument

parser: uwsgi_opt_true

help: do not follow symlinks when checking for uid/gid in Tyrant mode

emperor-tyrant-initgroups

argument: no_argument

parser: uwsgi_opt_true

help: add additional groups set via initgroups() in Tyrant mode

emperor-stats

argument: required_argument

parser: uwsgi_opt_set_str

help: run the Emperor stats server

emperor-stats-server

argument: required_argument

parser: uwsgi_opt_set_str

help: run the Emperor stats server

early-emperor

argument: no_argument

parser: uwsgi_opt_true

help: spawn the emperor as soon as possibile

emperor-broodlord

argument: required_argument

parser: uwsgi_opt_set_int

help: run the emperor in BroodLord mode

emperor-throttle

argument: required_argument

parser: uwsgi_opt_set_int

help: set throttling level (in milliseconds) for bad behaving vassals (default 1000)

emperor-max-throttle

argument: required_argument

parser: uwsgi_opt_set_int

help: set max throttling level (in milliseconds) for bad behaving vassals (default 3 minutes)

emperor-magic-exec

argument: no_argument

parser: uwsgi_opt_true

help: prefix vassals config files with exec:// if they have the executable bit

emperor-on-demand-extension

argument: required_argument

parser: uwsgi_opt_set_str

help: search for text file (vassal name + extension) containing the on demand socket name

emperor-on-demand-ext

argument: required_argument

parser: uwsgi_opt_set_str

help: search for text file (vassal name + extension) containing the on demand socket name

emperor-on-demand-directory

argument: required_argument

parser: uwsgi_opt_set_str

help: enable on demand mode binding to the unix socket in the specified directory named like the vassal + .socket

emperor-on-demand-dir

argument: required_argument

parser: uwsgi_opt_set_str

help: enable on demand mode binding to the unix socket in the specified directory named like the vassal + .socket

emperor-on-demand-exec

argument: required_argument

parser: uwsgi_opt_set_str

help: use the output of the specified command as on demand socket name (the vassal name is passed as the only argument)

emperor-extra-extension

argument: required_argument

parser: uwsgi_opt_add_string_list

help: allows the specified extension in the Emperor (vassal will be called with –config)

emperor-extra-ext

argument: required_argument

parser: uwsgi_opt_add_string_list

help: allows the specified extension in the Emperor (vassal will be called with –config)

emperor-no-blacklist

argument: no_argument

parser: uwsgi_opt_true

help: disable Emperor blacklisting subsystem

emperor-use-clone

argument: required_argument

parser: uwsgi_opt_set_unshare

help: use clone() instead of fork() passing the specified unshare() flags

emperor-use-fork-server

argument: required_argument

parser: uwsgi_opt_set_str

help: connect to the specified fork server instead of using plain fork() for new vassals

vassal-fork-base

argument: required_argument

parser: uwsgi_opt_add_string_list

help: use plain fork() for the specified vassal (instead of a fork-server)

emperor-subreaper

argument: no_argument

parser: uwsgi_opt_true

help: force the Emperor to be a sub-reaper (if supported)

emperor-cap

argument: required_argument

parser: uwsgi_opt_set_emperor_cap

help: set vassals capability

vassals-cap

argument: required_argument

parser: uwsgi_opt_set_emperor_cap

help: set vassals capability

vassal-cap

argument: required_argument

parser: uwsgi_opt_set_emperor_cap

help: set vassals capability

emperor-collect-attribute

argument: required_argument

parser: uwsgi_opt_add_string_list

help: collect the specified vassal attribute from imperial monitors

emperor-collect-attr

argument: required_argument

parser: uwsgi_opt_add_string_list

help: collect the specified vassal attribute from imperial monitors

emperor-fork-server-attr

argument: required_argument

parser: uwsgi_opt_set_str

help: set the vassal’s attribute to get when checking for fork-server

emperor-wrapper-attr

argument: required_argument

parser: uwsgi_opt_set_str

help: set the vassal’s attribute to get when checking for fork-wrapper

emperor-chdir-attr

argument: required_argument

parser: uwsgi_opt_set_str

help: set the vassal’s attribute to get when checking for chdir

imperial-monitor-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled imperial monitors

imperial-monitors-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled imperial monitors

vassals-inherit

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add config templates to vassals config (uses –inherit)

vassals-include

argument: required_argument

parser: uwsgi_opt_add_string_list

help: include config templates to vassals config (uses –include instead of –inherit)

vassals-inherit-before

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add config templates to vassals config (uses –inherit, parses before the vassal file)

vassals-include-before

argument: required_argument

parser: uwsgi_opt_add_string_list

help: include config templates to vassals config (uses –include instead of –inherit, parses before the vassal file)

vassals-start-hook

argument: required_argument

parser: uwsgi_opt_set_str

help: run the specified command before each vassal starts

vassals-stop-hook

argument: required_argument

parser: uwsgi_opt_set_str

help: run the specified command after vassal’s death

vassal-sos

argument: required_argument

parser: uwsgi_opt_set_int

help: ask emperor for reinforcement when overloaded

vassal-sos-backlog

argument: required_argument

parser: uwsgi_opt_set_int

help: ask emperor for sos if backlog queue has more items than the value specified

vassals-set

argument: required_argument

parser: uwsgi_opt_add_string_list

help: automatically set the specified option (via –set) for every vassal

vassal-set

argument: required_argument

parser: uwsgi_opt_add_string_list

help: automatically set the specified option (via –set) for every vassal

heartbeat

argument: required_argument

parser: uwsgi_opt_set_int

help: announce healthiness to the emperor

zeus

argument: required_argument

parser: uwsgi_opt_set_str

help: enable Zeus mode

reload-mercy

argument: required_argument

parser: uwsgi_opt_set_int

help: set the maximum time (in seconds) we wait for workers and other processes to die during reload/shutdown

worker-reload-mercy

argument: required_argument

parser: uwsgi_opt_set_int

help: set the maximum time (in seconds) a worker can take to reload/shutdown (default is 60)

mule-reload-mercy

argument: required_argument

parser: uwsgi_opt_set_int

help: set the maximum time (in seconds) a mule can take to reload/shutdown (default is 60)

exit-on-reload

argument: no_argument

parser: uwsgi_opt_true

help: force exit even if a reload is requested

die-on-term

argument: no_argument

parser: uwsgi_opt_deprecated

help: exit instead of brutal reload on SIGTERM (no more needed)

force-gateway

argument: no_argument

parser: uwsgi_opt_true

help: force the spawn of the first registered gateway without a master

help

argument: no_argument

shortcut: -h

parser: uwsgi_help

flags: UWSGI_OPT_IMMEDIATE

help: show this help

usage

argument: no_argument

shortcut: -h

parser: uwsgi_help

flags: UWSGI_OPT_IMMEDIATE

help: show this help

reaper

argument: no_argument

shortcut: -r

parser: uwsgi_opt_true

help: call waitpid(-1,...) after each request to get rid of zombies

max-requests

argument: required_argument

shortcut: -R

parser: uwsgi_opt_set_64bit

help: reload workers after the specified amount of managed requests

max-requests-delta

argument: required_argument

parser: uwsgi_opt_set_64bit

help: add (worker_id * delta) to the max_requests value of each worker

min-worker-lifetime

argument: required_argument

parser: uwsgi_opt_set_64bit

help: number of seconds worker must run before being reloaded (default is 60)

max-worker-lifetime

argument: required_argument

parser: uwsgi_opt_set_64bit

help: reload workers after the specified amount of seconds (default is disabled)

socket-timeout

argument: required_argument

shortcut: -z

parser: uwsgi_opt_set_int

help: set internal sockets timeout

no-fd-passing

argument: no_argument

parser: uwsgi_opt_true

help: disable file descriptor passing

locks

argument: required_argument

parser: uwsgi_opt_set_int

help: create the specified number of shared locks

lock-engine

argument: required_argument

parser: uwsgi_opt_set_str

help: set the lock engine

ftok

argument: required_argument

parser: uwsgi_opt_set_str

help: set the ipcsem key via ftok() for avoiding duplicates

persistent-ipcsem

argument: no_argument

parser: uwsgi_opt_true

help: do not remove ipcsem’s on shutdown

sharedarea

argument: required_argument

shortcut: -A

parser: uwsgi_opt_add_string_list

help: create a raw shared memory area of specified pages (note: it supports keyval too)

reference: SharedArea – share memory pages between uWSGI components

safe-fd

argument: required_argument

parser: uwsgi_opt_safe_fd

help: do not close the specified file descriptor

fd-safe

argument: required_argument

parser: uwsgi_opt_safe_fd

help: do not close the specified file descriptor

cache

argument: required_argument

parser: uwsgi_opt_set_64bit

help: create a shared cache containing given elements

cache-blocksize

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set cache blocksize

cache-store

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: enable persistent cache to disk

cache-store-sync

argument: required_argument

parser: uwsgi_opt_set_int

help: set frequency of sync for persistent cache

cache-no-expire

argument: no_argument

parser: uwsgi_opt_true

help: disable auto sweep of expired items

cache-expire-freq

argument: required_argument

parser: uwsgi_opt_set_int

help: set the frequency of cache sweeper scans (default 3 seconds)

cache-report-freed-items

argument: no_argument

parser: uwsgi_opt_true

help: constantly report the cache item freed by the sweeper (use only for debug)

cache-udp-server

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: bind the cache udp server (used only for set/update/delete) to the specified socket

cache-udp-node

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: send cache update/deletion to the specified cache udp server

cache-sync

argument: required_argument

parser: uwsgi_opt_set_str

help: copy the whole content of another uWSGI cache server on server startup

cache-use-last-modified

argument: no_argument

parser: uwsgi_opt_true

help: update last_modified_at timestamp on every cache item modification (default is disabled)

add-cache-item

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an item in the cache

load-file-in-cache

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load a static file in the cache

load-file-in-cache-gzip

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load a static file in the cache with gzip compression

cache2

argument: required_argument

parser: uwsgi_opt_add_string_list

help: create a new generation shared cache (keyval syntax)

queue

argument: required_argument

parser: uwsgi_opt_set_int

help: enable shared queue

queue-blocksize

argument: required_argument

parser: uwsgi_opt_set_int

help: set queue blocksize

queue-store

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: enable persistent queue to disk

queue-store-sync

argument: required_argument

parser: uwsgi_opt_set_int

help: set frequency of sync for persistent queue

spooler

argument: required_argument

shortcut: -Q

parser: uwsgi_opt_add_spooler

flags: UWSGI_OPT_MASTER

help: run a spooler on the specified directory

spooler-external

argument: required_argument

parser: uwsgi_opt_add_spooler

flags: UWSGI_OPT_MASTER

help: map spoolers requests to a spooler directory managed by an external instance

spooler-ordered

argument: no_argument

parser: uwsgi_opt_true

help: try to order the execution of spooler tasks

spooler-chdir

argument: required_argument

parser: uwsgi_opt_set_str

help: chdir() to specified directory before each spooler task

spooler-processes

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_IMMEDIATE

help: set the number of processes for spoolers

spooler-quiet

argument: no_argument

parser: uwsgi_opt_true

help: do not be verbose with spooler tasks

spooler-max-tasks

argument: required_argument

parser: uwsgi_opt_set_int

help: set the maximum number of tasks to run before recycling a spooler

spooler-harakiri

argument: required_argument

parser: uwsgi_opt_set_int

help: set harakiri timeout for spooler tasks

spooler-frequency

argument: required_argument

parser: uwsgi_opt_set_int

help: set spooler frequency, default 30 seconds

spooler-freq

argument: required_argument

parser: uwsgi_opt_set_int

help: set spooler frequency, default 30 seconds

mule

argument: optional_argument

parser: uwsgi_opt_add_mule

flags: UWSGI_OPT_MASTER

help: add a mule

mules

argument: required_argument

parser: uwsgi_opt_add_mules

flags: UWSGI_OPT_MASTER

help: add the specified number of mules

farm

argument: required_argument

parser: uwsgi_opt_add_farm

flags: UWSGI_OPT_MASTER

help: add a mule farm

mule-msg-size

argument: optional_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER

help: set mule message buffer size

signal

argument: required_argument

parser: uwsgi_opt_signal

flags: UWSGI_OPT_IMMEDIATE

help: send a uwsgi signal to a server

signal-bufsize

argument: required_argument

parser: uwsgi_opt_set_int

help: set buffer size for signal queue

signals-bufsize

argument: required_argument

parser: uwsgi_opt_set_int

help: set buffer size for signal queue

signal-timer

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: add a timer (syntax: <signal> <seconds>)

timer

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: add a timer (syntax: <signal> <seconds>)

signal-rbtimer

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: add a redblack timer (syntax: <signal> <seconds>)

rbtimer

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: add a redblack timer (syntax: <signal> <seconds>)

rpc-max

argument: required_argument

parser: uwsgi_opt_set_64bit

help: maximum number of rpc slots (default: 64)

disable-logging

argument: no_argument

shortcut: -L

parser: uwsgi_opt_false

help: disable request logging

flock

argument: required_argument

parser: uwsgi_opt_flock

flags: UWSGI_OPT_IMMEDIATE

help: lock the specified file before starting, exit if locked

flock-wait

argument: required_argument

parser: uwsgi_opt_flock_wait

flags: UWSGI_OPT_IMMEDIATE

help: lock the specified file before starting, wait if locked

flock2

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_IMMEDIATE

help: lock the specified file after logging/daemon setup, exit if locked

flock-wait2

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_IMMEDIATE

help: lock the specified file after logging/daemon setup, wait if locked

pidfile

argument: required_argument

parser: uwsgi_opt_set_str

help: create pidfile (before privileges drop)

pidfile2

argument: required_argument

parser: uwsgi_opt_set_str

help: create pidfile (after privileges drop)

safe-pidfile

argument: required_argument

parser: uwsgi_opt_set_str

help: create safe pidfile (before privileges drop)

safe-pidfile2

argument: required_argument

parser: uwsgi_opt_set_str

help: create safe pidfile (after privileges drop)

chroot

argument: required_argument

parser: uwsgi_opt_set_str

help: chroot() to the specified directory

pivot-root

argument: required_argument

parser: uwsgi_opt_set_str

help: pivot_root() to the specified directories (new_root and put_old must be separated with a space)

pivot_root

argument: required_argument

parser: uwsgi_opt_set_str

help: pivot_root() to the specified directories (new_root and put_old must be separated with a space)

uid

argument: required_argument

parser: uwsgi_opt_set_uid

help: setuid to the specified user/uid

gid

argument: required_argument

parser: uwsgi_opt_set_gid

help: setgid to the specified group/gid

add-gid

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add the specified group id to the process credentials

immediate-uid

argument: required_argument

parser: uwsgi_opt_set_immediate_uid

flags: UWSGI_OPT_IMMEDIATE

help: setuid to the specified user/uid IMMEDIATELY

immediate-gid

argument: required_argument

parser: uwsgi_opt_set_immediate_gid

flags: UWSGI_OPT_IMMEDIATE

help: setgid to the specified group/gid IMMEDIATELY

no-initgroups

argument: no_argument

parser: uwsgi_opt_true

help: disable additional groups set via initgroups()

cap

argument: required_argument

parser: uwsgi_opt_set_cap

help: set process capability

unshare

argument: required_argument

parser: uwsgi_opt_set_unshare

help: unshare() part of the processes and put it in a new namespace

unshare2

argument: required_argument

parser: uwsgi_opt_set_unshare

help: unshare() part of the processes and put it in a new namespace after rootfs change

setns-socket

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: expose a unix socket returning namespace fds from /proc/self/ns

setns-socket-skip

argument: required_argument

parser: uwsgi_opt_add_string_list

help: skip the specified entry when sending setns file descriptors

setns-skip

argument: required_argument

parser: uwsgi_opt_add_string_list

help: skip the specified entry when sending setns file descriptors

setns

argument: required_argument

parser: uwsgi_opt_set_str

help: join a namespace created by an external uWSGI instance

setns-preopen

argument: no_argument

parser: uwsgi_opt_true

help: open /proc/self/ns as soon as possible and cache fds

fork-socket

argument: required_argument

parser: uwsgi_opt_set_str

help: suspend the execution after early initialization and fork() at every unix socket connection

fork-server

argument: required_argument

parser: uwsgi_opt_set_str

help: suspend the execution after early initialization and fork() at every unix socket connection

jailed

argument: no_argument

parser: uwsgi_opt_true

help: mark the instance as jailed (force the execution of post_jail hooks)

jail

argument: required_argument

parser: uwsgi_opt_set_str

help: put the instance in a FreeBSD jail

jail-ip4

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an ipv4 address to the FreeBSD jail

jail-ip6

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an ipv6 address to the FreeBSD jail

jidfile

argument: required_argument

parser: uwsgi_opt_set_str

help: save the jid of a FreeBSD jail in the specified file

jid-file

argument: required_argument

parser: uwsgi_opt_set_str

help: save the jid of a FreeBSD jail in the specified file

jail2

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an option to the FreeBSD jail

libjail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an option to the FreeBSD jail

jail-attach

argument: required_argument

parser: uwsgi_opt_set_str

help: attach to the FreeBSD jail

refork

argument: no_argument

parser: uwsgi_opt_true

help: fork() again after privileges drop. Useful for jailing systems

re-fork

argument: no_argument

parser: uwsgi_opt_true

help: fork() again after privileges drop. Useful for jailing systems

refork-as-root

argument: no_argument

parser: uwsgi_opt_true

help: fork() again before privileges drop. Useful for jailing systems

re-fork-as-root

argument: no_argument

parser: uwsgi_opt_true

help: fork() again before privileges drop. Useful for jailing systems

refork-post-jail

argument: no_argument

parser: uwsgi_opt_true

help: fork() again after jailing. Useful for jailing systems

re-fork-post-jail

argument: no_argument

parser: uwsgi_opt_true

help: fork() again after jailing. Useful for jailing systems

hook-asap

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook as soon as possible

hook-pre-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook before jailing

hook-post-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook after jailing

hook-in-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook in jail after initialization

hook-as-root

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook before privileges drop

hook-as-user

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook after privileges drop

hook-as-user-atexit

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook before app exit and reload

hook-pre-app

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook before app loading

hook-post-app

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook after app loading

hook-post-fork

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook after each fork

hook-accepting

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook after each worker enter the accepting phase

hook-accepting1

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook after the first worker enters the accepting phase

hook-accepting-once

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook after each worker enter the accepting phase (once per-instance)

hook-accepting1-once

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook after the first worker enters the accepting phase (once per instance)

hook-master-start

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook when the Master starts

hook-touch

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook when the specified file is touched (syntax: <file> <action>)

hook-emperor-start

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook when the Emperor starts

hook-emperor-stop

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook when the Emperor send a stop message

hook-emperor-reload

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook when the Emperor send a reload message

hook-emperor-lost

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook when the Emperor connection is lost

hook-as-vassal

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook before exec()ing the vassal

hook-as-emperor

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook in the emperor after the vassal has been started

hook-as-on-demand-vassal

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook whenever a vassal enters on-demand mode

hook-as-on-config-vassal

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook whenever the emperor detects a config change for an on-demand vassal

hook-as-emperor-before-vassal

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook before the new vassal is spawned

hook-as-vassal-before-drop

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook into vassal, before dropping its privileges

hook-as-emperor-setns

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook in the emperor entering vassal namespace

hook-as-mule

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook in each mule

hook-as-gateway

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified hook in each gateway

after-request-hook

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified function/symbol after each request

after-request-call

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified function/symbol after each request

exec-asap

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified command as soon as possible

exec-pre-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified command before jailing

exec-post-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified command after jailing

exec-in-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified command in jail after initialization

exec-as-root

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified command before privileges drop

exec-as-user

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified command after privileges drop

exec-as-user-atexit

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified command before app exit and reload

exec-pre-app

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified command before app loading

exec-post-app

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified command after app loading

exec-as-vassal

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified command before exec()ing the vassal

exec-as-emperor

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the specified command in the emperor after the vassal has been started

mount-asap

argument: required_argument

parser: uwsgi_opt_add_string_list

help: mount filesystem as soon as possible

mount-pre-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: mount filesystem before jailing

mount-post-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: mount filesystem after jailing

mount-in-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: mount filesystem in jail after initialization

mount-as-root

argument: required_argument

parser: uwsgi_opt_add_string_list

help: mount filesystem before privileges drop

mount-as-vassal

argument: required_argument

parser: uwsgi_opt_add_string_list

help: mount filesystem before exec()ing the vassal

mount-as-emperor

argument: required_argument

parser: uwsgi_opt_add_string_list

help: mount filesystem in the emperor after the vassal has been started

umount-asap

argument: required_argument

parser: uwsgi_opt_add_string_list

help: unmount filesystem as soon as possible

umount-pre-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: unmount filesystem before jailing

umount-post-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: unmount filesystem after jailing

umount-in-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: unmount filesystem in jail after initialization

umount-as-root

argument: required_argument

parser: uwsgi_opt_add_string_list

help: unmount filesystem before privileges drop

umount-as-vassal

argument: required_argument

parser: uwsgi_opt_add_string_list

help: unmount filesystem before exec()ing the vassal

umount-as-emperor

argument: required_argument

parser: uwsgi_opt_add_string_list

help: unmount filesystem in the emperor after the vassal has been started

wait-for-interface

argument: required_argument

parser: uwsgi_opt_add_string_list

help: wait for the specified network interface to come up before running root hooks

wait-for-interface-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set the timeout for wait-for-interface

wait-interface

argument: required_argument

parser: uwsgi_opt_add_string_list

help: wait for the specified network interface to come up before running root hooks

wait-interface-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set the timeout for wait-for-interface

wait-for-iface

argument: required_argument

parser: uwsgi_opt_add_string_list

help: wait for the specified network interface to come up before running root hooks

wait-for-iface-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set the timeout for wait-for-interface

wait-iface

argument: required_argument

parser: uwsgi_opt_add_string_list

help: wait for the specified network interface to come up before running root hooks

wait-iface-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set the timeout for wait-for-interface

wait-for-fs

argument: required_argument

parser: uwsgi_opt_add_string_list

help: wait for the specified filesystem item to appear before running root hooks

wait-for-file

argument: required_argument

parser: uwsgi_opt_add_string_list

help: wait for the specified file to appear before running root hooks

wait-for-dir

argument: required_argument

parser: uwsgi_opt_add_string_list

help: wait for the specified directory to appear before running root hooks

wait-for-mountpoint

argument: required_argument

parser: uwsgi_opt_add_string_list

help: wait for the specified mountpoint to appear before running root hooks

wait-for-fs-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set the timeout for wait-for-fs/file/dir

call-asap

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function as soon as possible

call-pre-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function before jailing

call-post-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function after jailing

call-in-jail

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function in jail after initialization

call-as-root

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function before privileges drop

call-as-user

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function after privileges drop

call-as-user-atexit

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function before app exit and reload

call-pre-app

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function before app loading

call-post-app

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function after app loading

call-as-vassal

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function() before exec()ing the vassal

call-as-vassal1

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function before exec()ing the vassal

call-as-vassal3

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function(char *, uid_t, gid_t) before exec()ing the vassal

call-as-emperor

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function() in the emperor after the vassal has been started

call-as-emperor1

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function in the emperor after the vassal has been started

call-as-emperor2

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function(char *, pid_t) in the emperor after the vassal has been started

call-as-emperor4

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified function(char *, pid_t, uid_t, gid_t) in the emperor after the vassal has been started

ini

argument: required_argument

parser: uwsgi_opt_load_ini

flags: UWSGI_OPT_IMMEDIATE

help: load config from ini file

yaml

argument: required_argument

shortcut: -y

parser: uwsgi_opt_load_yml

flags: UWSGI_OPT_IMMEDIATE

help: load config from yaml file

yml

argument: required_argument

shortcut: -y

parser: uwsgi_opt_load_yml

flags: UWSGI_OPT_IMMEDIATE

help: load config from yaml file

json

argument: required_argument

shortcut: -j

parser: uwsgi_opt_load_json

flags: UWSGI_OPT_IMMEDIATE

help: load config from json file

js

argument: required_argument

shortcut: -j

parser: uwsgi_opt_load_json

flags: UWSGI_OPT_IMMEDIATE

help: load config from json file

weight

argument: required_argument

parser: uwsgi_opt_set_64bit

help: weight of the instance (used by clustering/lb/subscriptions)

auto-weight

argument: required_argument

parser: uwsgi_opt_true

help: set weight of the instance (used by clustering/lb/subscriptions) automatically

no-server

argument: no_argument

parser: uwsgi_opt_true

help: force no-server mode

command-mode

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_IMMEDIATE

help: force command mode

no-defer-accept

argument: no_argument

parser: uwsgi_opt_true

help: disable deferred-accept on sockets

tcp-nodelay

argument: no_argument

parser: uwsgi_opt_true

help: enable TCP NODELAY on each request

so-keepalive

argument: no_argument

parser: uwsgi_opt_true

help: enable TCP KEEPALIVEs

so-send-timeout

argument: no_argument

parser: uwsgi_opt_set_int

help: set SO_SNDTIMEO

socket-send-timeout

argument: no_argument

parser: uwsgi_opt_set_int

help: set SO_SNDTIMEO

so-write-timeout

argument: no_argument

parser: uwsgi_opt_set_int

help: set SO_SNDTIMEO

socket-write-timeout

argument: no_argument

parser: uwsgi_opt_set_int

help: set SO_SNDTIMEO

socket-sndbuf

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set SO_SNDBUF

socket-rcvbuf

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set SO_RCVBUF

limit-as

argument: required_argument

parser: uwsgi_opt_set_megabytes

help: limit processes address space/vsz

limit-nproc

argument: required_argument

parser: uwsgi_opt_set_int

help: limit the number of spawnable processes

reload-on-as

argument: required_argument

parser: uwsgi_opt_set_megabytes

flags: UWSGI_OPT_MEMORY

help: reload if address space is higher than specified megabytes

reload-on-rss

argument: required_argument

parser: uwsgi_opt_set_megabytes

flags: UWSGI_OPT_MEMORY

help: reload if rss memory is higher than specified megabytes

evil-reload-on-as

argument: required_argument

parser: uwsgi_opt_set_megabytes

flags: UWSGI_OPT_MASTER | UWSGI_OPT_MEMORY

help: force the master to reload a worker if its address space is higher than specified megabytes

evil-reload-on-rss

argument: required_argument

parser: uwsgi_opt_set_megabytes

flags: UWSGI_OPT_MASTER | UWSGI_OPT_MEMORY

help: force the master to reload a worker if its rss memory is higher than specified megabytes

reload-on-fd

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: reload if the specified file descriptor is ready

brutal-reload-on-fd

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: brutal reload if the specified file descriptor is ready

ksm

argument: optional_argument

parser: uwsgi_opt_set_int

help: enable Linux KSM

pcre-jit

argument: no_argument

parser: uwsgi_opt_pcre_jit

flags: UWSGI_OPT_IMMEDIATE

help: enable pcre jit (if available)

never-swap

argument: no_argument

parser: uwsgi_opt_true

help: lock all memory pages avoiding swapping

touch-reload

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: reload uWSGI if the specified file is modified/touched

touch-workers-reload

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: trigger reload of (only) workers if the specified file is modified/touched

touch-chain-reload

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: trigger chain reload if the specified file is modified/touched

touch-logrotate

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: trigger logrotation if the specified file is modified/touched

touch-logreopen

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: trigger log reopen if the specified file is modified/touched

touch-exec

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: run command when the specified file is modified/touched (syntax: file command)

touch-signal

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: signal when the specified file is modified/touched (syntax: file signal)

fs-reload

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: graceful reload when the specified filesystem object is modified

fs-brutal-reload

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: brutal reload when the specified filesystem object is modified

fs-signal

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: raise a uwsgi signal when the specified filesystem object is modified (syntax: file signal)

check-mountpoint

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: destroy the instance if a filesystem is no more reachable (useful for reliable Fuse management)

mountpoint-check

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: destroy the instance if a filesystem is no more reachable (useful for reliable Fuse management)

check-mount

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: destroy the instance if a filesystem is no more reachable (useful for reliable Fuse management)

mount-check

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: destroy the instance if a filesystem is no more reachable (useful for reliable Fuse management)

propagate-touch

argument: no_argument

parser: uwsgi_opt_true

help: over-engineering option for system with flaky signal management

limit-post

argument: required_argument

parser: uwsgi_opt_set_64bit

help: limit request body

no-orphans

argument: no_argument

parser: uwsgi_opt_true

help: automatically kill workers if master dies (can be dangerous for availability)

prio

argument: required_argument

parser: uwsgi_opt_set_rawint

help: set processes/threads priority

cpu-affinity

argument: required_argument

parser: uwsgi_opt_set_int

help: set cpu affinity

post-buffering

argument: required_argument

parser: uwsgi_opt_set_64bit

help: enable post buffering

post-buffering-bufsize

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set buffer size for read() in post buffering mode

body-read-warning

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set the amount of allowed memory allocation (in megabytes) for request body before starting printing a warning

upload-progress

argument: required_argument

parser: uwsgi_opt_set_str

help: enable creation of .json files in the specified directory during a file upload

no-default-app

argument: no_argument

parser: uwsgi_opt_true

help: do not fallback to default app

manage-script-name

argument: no_argument

parser: uwsgi_opt_true

help: automatically rewrite SCRIPT_NAME and PATH_INFO

ignore-script-name

argument: no_argument

parser: uwsgi_opt_true

help: ignore SCRIPT_NAME

catch-exceptions

argument: no_argument

parser: uwsgi_opt_true

help: report exception as http output (discouraged, use only for testing)

reload-on-exception

argument: no_argument

parser: uwsgi_opt_true

help: reload a worker when an exception is raised

reload-on-exception-type

argument: required_argument

parser: uwsgi_opt_add_string_list

help: reload a worker when a specific exception type is raised

reload-on-exception-value

argument: required_argument

parser: uwsgi_opt_add_string_list

help: reload a worker when a specific exception value is raised

reload-on-exception-repr

argument: required_argument

parser: uwsgi_opt_add_string_list

help: reload a worker when a specific exception type+value (language-specific) is raised

exception-handler

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: add an exception handler

enable-metrics

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MASTER

help: enable metrics subsystem

metric

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_METRICS|UWSGI_OPT_MASTER

help: add a custom metric

metric-threshold

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_METRICS|UWSGI_OPT_MASTER

help: add a metric threshold/alarm

metric-alarm

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_METRICS|UWSGI_OPT_MASTER

help: add a metric threshold/alarm

alarm-metric

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_METRICS|UWSGI_OPT_MASTER

help: add a metric threshold/alarm

metrics-dir

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_METRICS|UWSGI_OPT_MASTER

help: export metrics as text files to the specified directory

metrics-dir-restore

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_METRICS|UWSGI_OPT_MASTER

help: restore last value taken from the metrics dir

metric-dir

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_METRICS|UWSGI_OPT_MASTER

help: export metrics as text files to the specified directory

metric-dir-restore

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_METRICS|UWSGI_OPT_MASTER

help: restore last value taken from the metrics dir

metrics-no-cores

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_METRICS|UWSGI_OPT_MASTER

help: disable generation of cores-related metrics

reference: The Metrics subsystem

Do not expose metrics of async cores.

udp

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: run the udp server on the specified address

stats

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: enable the stats server on the specified address

stats-server

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: enable the stats server on the specified address

stats-http

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MASTER

help: prefix stats server json output with http headers

stats-minified

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MASTER

help: minify statistics json output

stats-min

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MASTER

help: minify statistics json output

stats-push

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER|UWSGI_OPT_METRICS

help: push the stats json to the specified destination

stats-pusher-default-freq

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER

help: set the default frequency of stats pushers

stats-pushers-default-freq

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER

help: set the default frequency of stats pushers

stats-no-cores

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MASTER

help: disable generation of cores-related stats

reference: The Metrics subsystem

Do not expose the information about cores in the stats server.

stats-no-metrics

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MASTER

help: do not include metrics in stats output

reference: The Metrics subsystem

Do not expose the metrics at all in the stats server.

multicast

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: subscribe to specified multicast group

multicast-ttl

argument: required_argument

parser: uwsgi_opt_set_int

help: set multicast ttl

multicast-loop

argument: required_argument

parser: uwsgi_opt_set_int

help: set multicast loop (default 1)

master-fifo

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: enable the master fifo

notify-socket

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: enable the notification socket

subscription-notify-socket

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: set the notification socket for subscriptions

subscription-mountpoints

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MASTER

help: enable mountpoints support for subscription system

subscription-mountpoint

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MASTER

help: enable mountpoints support for subscription system

legion

argument: required_argument

parser: uwsgi_opt_legion

flags: UWSGI_OPT_MASTER

help: became a member of a legion

legion-mcast

argument: required_argument

parser: uwsgi_opt_legion_mcast

flags: UWSGI_OPT_MASTER

help: became a member of a legion (shortcut for multicast)

legion-node

argument: required_argument

parser: uwsgi_opt_legion_node

flags: UWSGI_OPT_MASTER

help: add a node to a legion

legion-freq

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER

help: set the frequency of legion packets

legion-tolerance

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER

help: set the tolerance of legion subsystem

legion-death-on-lord-error

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER

help: declare itself as a dead node for the specified amount of seconds if one of the lord hooks fails

legion-skew-tolerance

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER

help: set the clock skew tolerance of legion subsystem (default 30 seconds)

legion-lord

argument: required_argument

parser: uwsgi_opt_legion_hook

flags: UWSGI_OPT_MASTER

help: action to call on Lord election

legion-unlord

argument: required_argument

parser: uwsgi_opt_legion_hook

flags: UWSGI_OPT_MASTER

help: action to call on Lord dismiss

legion-setup

argument: required_argument

parser: uwsgi_opt_legion_hook

flags: UWSGI_OPT_MASTER

help: action to call on legion setup

legion-death

argument: required_argument

parser: uwsgi_opt_legion_hook

flags: UWSGI_OPT_MASTER

help: action to call on legion death (shutdown of the instance)

legion-join

argument: required_argument

parser: uwsgi_opt_legion_hook

flags: UWSGI_OPT_MASTER

help: action to call on legion join (first time quorum is reached)

legion-node-joined

argument: required_argument

parser: uwsgi_opt_legion_hook

flags: UWSGI_OPT_MASTER

help: action to call on new node joining legion

legion-node-left

argument: required_argument

parser: uwsgi_opt_legion_hook

flags: UWSGI_OPT_MASTER

help: action to call node leaving legion

legion-quorum

argument: required_argument

parser: uwsgi_opt_legion_quorum

flags: UWSGI_OPT_MASTER

help: set the quorum of a legion

legion-scroll

argument: required_argument

parser: uwsgi_opt_legion_scroll

flags: UWSGI_OPT_MASTER

help: set the scroll of a legion

legion-scroll-max-size

argument: required_argument

parser: uwsgi_opt_set_16bit

help: set max size of legion scroll buffer

legion-scroll-list-max-size

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set max size of legion scroll list buffer

subscriptions-sign-check

argument: required_argument

parser: uwsgi_opt_scd

flags: UWSGI_OPT_MASTER

help: set digest algorithm and certificate directory for secured subscription system

subscriptions-sign-check-tolerance

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER

help: set the maximum tolerance (in seconds) of clock skew for secured subscription system

subscriptions-sign-skip-uid

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: skip signature check for the specified uid when using unix sockets credentials

subscriptions-credentials-check

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: add a directory to search for subscriptions key credentials

subscriptions-use-credentials

argument: no_argument

parser: uwsgi_opt_true

help: enable management of SCM_CREDENTIALS in subscriptions UNIX sockets

subscription-algo

argument: required_argument

parser: uwsgi_opt_ssa

help: set load balancing algorithm for the subscription system

subscription-dotsplit

argument: no_argument

parser: uwsgi_opt_true

help: try to fallback to the next part (dot based) in subscription key

subscribe-to

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: subscribe to the specified subscription server

st

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: subscribe to the specified subscription server

subscribe

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: subscribe to the specified subscription server

subscribe2

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: subscribe to the specified subscription server using advanced keyval syntax

subscribe-freq

argument: required_argument

parser: uwsgi_opt_set_int

help: send subscription announce at the specified interval

subscription-tolerance

argument: required_argument

parser: uwsgi_opt_set_int

help: set tolerance for subscription servers

unsubscribe-on-graceful-reload

argument: no_argument

parser: uwsgi_opt_true

help: force unsubscribe request even during graceful reload

start-unsubscribed

argument: no_argument

parser: uwsgi_opt_true

help: configure subscriptions but do not send them (useful with master fifo)

subscribe-with-modifier1

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: force the specififed modifier1 when subscribing

snmp

argument: optional_argument

parser: uwsgi_opt_snmp

help: enable the embedded snmp server

snmp-community

argument: required_argument

parser: uwsgi_opt_snmp_community

help: set the snmp community string

ssl-verbose

argument: no_argument

parser: uwsgi_opt_true

help: be verbose about SSL errors

ssl-sessions-use-cache

argument: optional_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: use uWSGI cache for ssl sessions storage

ssl-session-use-cache

argument: optional_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: use uWSGI cache for ssl sessions storage

ssl-sessions-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set SSL sessions timeout (default: 300 seconds)

ssl-session-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set SSL sessions timeout (default: 300 seconds)

sni

argument: required_argument

parser: uwsgi_opt_sni

help: add an SNI-governed SSL context

sni-dir

argument: required_argument

parser: uwsgi_opt_set_str

help: check for cert/key/client_ca file in the specified directory and create a sni/ssl context on demand

sni-dir-ciphers

argument: required_argument

parser: uwsgi_opt_set_str

help: set ssl ciphers for sni-dir option

ssl-enable3

argument: no_argument

parser: uwsgi_opt_true

help: enable SSLv3 (insecure)

ssl-option

argument: no_argument

parser: uwsgi_opt_add_string_list

help: set a raw ssl option (numeric value)

sni-regexp

argument: required_argument

parser: uwsgi_opt_sni

help: add an SNI-governed SSL context (the key is a regexp)

ssl-tmp-dir

argument: required_argument

parser: uwsgi_opt_set_str

help: store ssl-related temp files in the specified directory

check-interval

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER

help: set the interval (in seconds) of master checks

forkbomb-delay

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER

help: sleep for the specified number of seconds when a forkbomb is detected

binary-path

argument: required_argument

parser: uwsgi_opt_set_str

help: force binary path

privileged-binary-patch

argument: required_argument

parser: uwsgi_opt_set_str

help: patch the uwsgi binary with a new command (before privileges drop)

unprivileged-binary-patch

argument: required_argument

parser: uwsgi_opt_set_str

help: patch the uwsgi binary with a new command (after privileges drop)

privileged-binary-patch-arg

argument: required_argument

parser: uwsgi_opt_set_str

help: patch the uwsgi binary with a new command and arguments (before privileges drop)

unprivileged-binary-patch-arg

argument: required_argument

parser: uwsgi_opt_set_str

help: patch the uwsgi binary with a new command and arguments (after privileges drop)

async

argument: required_argument

parser: uwsgi_opt_set_int

help: enable async mode with specified cores

disable-async-warn-on-queue-full

argument: no_argument

parser: uwsgi_opt_false

help: Disable printing ‘async queue is full’ warning messages.

max-fd

argument: required_argument

parser: uwsgi_opt_set_int

help: set maximum number of file descriptors (requires root privileges)

logto

argument: required_argument

parser: uwsgi_opt_set_str

help: set logfile/udp address

logto2

argument: required_argument

parser: uwsgi_opt_set_str

help: log to specified file or udp address after privileges drop

log-format

argument: required_argument

parser: uwsgi_opt_set_str

help: set advanced format for request logging

logformat

argument: required_argument

parser: uwsgi_opt_set_str

help: set advanced format for request logging

logformat-strftime

argument: no_argument

parser: uwsgi_opt_true

help: apply strftime to logformat output

log-format-strftime

argument: no_argument

parser: uwsgi_opt_true

help: apply strftime to logformat output

logfile-chown

argument: no_argument

parser: uwsgi_opt_true

help: chown logfiles

logfile-chmod

argument: required_argument

parser: uwsgi_opt_logfile_chmod

help: chmod logfiles

log-syslog

argument: optional_argument

parser: uwsgi_opt_set_logger

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: log to syslog

log-socket

argument: required_argument

parser: uwsgi_opt_set_logger

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: send logs to the specified socket

req-logger

argument: required_argument

parser: uwsgi_opt_set_req_logger

flags: UWSGI_OPT_REQ_LOG_MASTER

help: set/append a request logger

logger-req

argument: required_argument

parser: uwsgi_opt_set_req_logger

flags: UWSGI_OPT_REQ_LOG_MASTER

help: set/append a request logger

logger

argument: required_argument

parser: uwsgi_opt_set_logger

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: set/append a logger

logger-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled loggers

loggers-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled loggers

threaded-logger

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: offload log writing to a thread

log-encoder

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: add an item in the log encoder chain

log-req-encoder

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: add an item in the log req encoder chain

log-drain

argument: required_argument

parser: uwsgi_opt_add_regexp_list

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: drain (do not show) log lines matching the specified regexp

log-filter

argument: required_argument

parser: uwsgi_opt_add_regexp_list

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: show only log lines matching the specified regexp

log-route

argument: required_argument

parser: uwsgi_opt_add_regexp_custom_list

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: log to the specified named logger if regexp applied on logline matches

log-req-route

argument: required_argument

parser: uwsgi_opt_add_regexp_custom_list

flags: UWSGI_OPT_REQ_LOG_MASTER

help: log requests to the specified named logger if regexp applied on logline matches

use-abort

argument: no_argument

parser: uwsgi_opt_true

help: call abort() on segfault/fpe, could be useful for generating a core dump

alarm

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: create a new alarm, syntax: <alarm> <plugin:args>

alarm-cheap

argument: required_argument

parser: uwsgi_opt_true

help: use main alarm thread rather than create dedicated threads for curl-based alarms

alarm-freq

argument: required_argument

parser: uwsgi_opt_set_int

help: tune the anti-loop alam system (default 3 seconds)

alarm-fd

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: raise the specified alarm when an fd is read for read (by default it reads 1 byte, set 8 for eventfd)

alarm-segfault

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: raise the specified alarm when the segmentation fault handler is executed

segfault-alarm

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: raise the specified alarm when the segmentation fault handler is executed

alarm-backlog

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: raise the specified alarm when the socket backlog queue is full

backlog-alarm

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: raise the specified alarm when the socket backlog queue is full

lq-alarm

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: raise the specified alarm when the socket backlog queue is full

alarm-lq

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: raise the specified alarm when the socket backlog queue is full

alarm-listen-queue

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: raise the specified alarm when the socket backlog queue is full

listen-queue-alarm

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: raise the specified alarm when the socket backlog queue is full

log-alarm

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: raise the specified alarm when a log line matches the specified regexp, syntax: <alarm>[,alarm...] <regexp>

alarm-log

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: raise the specified alarm when a log line matches the specified regexp, syntax: <alarm>[,alarm...] <regexp>

not-log-alarm

argument: required_argument

parser: uwsgi_opt_add_string_list_custom

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: skip the specified alarm when a log line matches the specified regexp, syntax: <alarm>[,alarm...] <regexp>

not-alarm-log

argument: required_argument

parser: uwsgi_opt_add_string_list_custom

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: skip the specified alarm when a log line matches the specified regexp, syntax: <alarm>[,alarm...] <regexp>

alarm-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled alarms

alarms-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled alarms

alarm-msg-size

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set the max size of an alarm message (default 8192)

log-master

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MASTER|UWSGI_OPT_LOG_MASTER

help: delegate logging to master process

log-master-bufsize

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set the buffer size for the master logger. bigger log messages will be truncated

log-master-stream

argument: no_argument

parser: uwsgi_opt_true

help: create the master logpipe as SOCK_STREAM

log-master-req-stream

argument: no_argument

parser: uwsgi_opt_true

help: create the master requests logpipe as SOCK_STREAM

log-reopen

argument: no_argument

parser: uwsgi_opt_true

help: reopen log after reload

log-truncate

argument: no_argument

parser: uwsgi_opt_true

help: truncate log on startup

log-maxsize

argument: required_argument

parser: uwsgi_opt_set_64bit

flags: UWSGI_OPT_MASTER|UWSGI_OPT_LOG_MASTER

help: set maximum logfile size

log-backupname

argument: required_argument

parser: uwsgi_opt_set_str

help: set logfile name after rotation

logdate

argument: optional_argument

parser: uwsgi_opt_log_date

help: prefix logs with date or a strftime string

log-date

argument: optional_argument

parser: uwsgi_opt_log_date

help: prefix logs with date or a strftime string

log-prefix

argument: optional_argument

parser: uwsgi_opt_log_date

help: prefix logs with a string

log-zero

argument: no_argument

parser: uwsgi_opt_true

help: log responses without body

log-slow

argument: required_argument

parser: uwsgi_opt_set_int

help: log requests slower than the specified number of milliseconds

log-4xx

argument: no_argument

parser: uwsgi_opt_true

help: log requests with a 4xx response

log-5xx

argument: no_argument

parser: uwsgi_opt_true

help: log requests with a 5xx response

log-big

argument: required_argument

parser: uwsgi_opt_set_64bit

help: log requestes bigger than the specified size

log-sendfile

argument: required_argument

parser: uwsgi_opt_true

help: log sendfile requests

log-ioerror

argument: required_argument

parser: uwsgi_opt_true

help: log requests with io errors

log-micros

argument: no_argument

parser: uwsgi_opt_true

help: report response time in microseconds instead of milliseconds

log-x-forwarded-for

argument: no_argument

parser: uwsgi_opt_true

help: use the ip from X-Forwarded-For header instead of REMOTE_ADDR

master-as-root

argument: no_argument

parser: uwsgi_opt_true

help: leave master process running as root

drop-after-init

argument: no_argument

parser: uwsgi_opt_true

help: run privileges drop after plugin initialization

drop-after-apps

argument: no_argument

parser: uwsgi_opt_true

help: run privileges drop after apps loading

force-cwd

argument: required_argument

parser: uwsgi_opt_set_str

help: force the initial working directory to the specified value

binsh

argument: required_argument

parser: uwsgi_opt_add_string_list

help: override /bin/sh (used by exec hooks, it always fallback to /bin/sh)

chdir

argument: required_argument

parser: uwsgi_opt_set_str

help: chdir to specified directory before apps loading

chdir2

argument: required_argument

parser: uwsgi_opt_set_str

help: chdir to specified directory after apps loading

lazy

argument: no_argument

parser: uwsgi_opt_true

help: set lazy mode (load apps in workers instead of master)

lazy-apps

argument: no_argument

parser: uwsgi_opt_true

help: load apps in each worker instead of the master

cheap

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MASTER

help: set cheap mode (spawn workers only after the first request)

cheaper

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER | UWSGI_OPT_CHEAPER

help: set cheaper mode (adaptive process spawning)

cheaper-initial

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER | UWSGI_OPT_CHEAPER

help: set the initial number of processes to spawn in cheaper mode

cheaper-algo

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: choose to algorithm used for adaptive process spawning

cheaper-step

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER | UWSGI_OPT_CHEAPER

help: number of additional processes to spawn at each overload

cheaper-overload

argument: required_argument

parser: uwsgi_opt_set_64bit

flags: UWSGI_OPT_MASTER | UWSGI_OPT_CHEAPER

help: increase workers after specified overload

cheaper-idle

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER | UWSGI_OPT_CHEAPER

help: decrease workers after specified idle (algo: spare2) (default: 10)

cheaper-algo-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled cheapers algorithms

cheaper-algos-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled cheapers algorithms

cheaper-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled cheapers algorithms

cheaper-rss-limit-soft

argument: required_argument

parser: uwsgi_opt_set_64bit

flags: UWSGI_OPT_MASTER | UWSGI_OPT_CHEAPER

help: don’t spawn new workers if total resident memory usage of all workers is higher than this limit

cheaper-rss-limit-hard

argument: required_argument

parser: uwsgi_opt_set_64bit

flags: UWSGI_OPT_MASTER | UWSGI_OPT_CHEAPER

help: if total workers resident memory usage is higher try to stop workers

idle

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER

help: set idle mode (put uWSGI in cheap mode after inactivity)

die-on-idle

argument: no_argument

parser: uwsgi_opt_true

help: shutdown uWSGI when idle

mount

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load application under mountpoint

worker-mount

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load application under mountpoint in the specified worker or after workers spawn

threads

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_THREADS

help: run each worker in prethreaded mode with the specified number of threads

thread-stacksize

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_THREADS

help: set threads stacksize

threads-stacksize

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_THREADS

help: set threads stacksize

thread-stack-size

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_THREADS

help: set threads stacksize

threads-stack-size

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_THREADS

help: set threads stacksize

vhost

argument: no_argument

parser: uwsgi_opt_true

help: enable virtualhosting mode (based on SERVER_NAME variable)

vhost-host

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_VHOST

help: enable virtualhosting mode (based on HTTP_HOST variable)

route

argument: required_argument

parser: uwsgi_opt_add_route

help: add a route

route-host

argument: required_argument

parser: uwsgi_opt_add_route

help: add a route based on Host header

route-uri

argument: required_argument

parser: uwsgi_opt_add_route

help: add a route based on REQUEST_URI

route-qs

argument: required_argument

parser: uwsgi_opt_add_route

help: add a route based on QUERY_STRING

route-remote-addr

argument: required_argument

parser: uwsgi_opt_add_route

help: add a route based on REMOTE_ADDR

route-user-agent

argument: required_argument

parser: uwsgi_opt_add_route

help: add a route based on HTTP_USER_AGENT

route-remote-user

argument: required_argument

parser: uwsgi_opt_add_route

help: add a route based on REMOTE_USER

route-referer

argument: required_argument

parser: uwsgi_opt_add_route

help: add a route based on HTTP_REFERER

route-label

argument: required_argument

parser: uwsgi_opt_add_route

help: add a routing label (for use with goto)

route-if

argument: required_argument

parser: uwsgi_opt_add_route

help: add a route based on condition

route-if-not

argument: required_argument

parser: uwsgi_opt_add_route

help: add a route based on condition (negate version)

route-run

argument: required_argument

parser: uwsgi_opt_add_route

help: always run the specified route action

final-route

argument: required_argument

parser: uwsgi_opt_add_route

help: add a final route

final-route-status

argument: required_argument

parser: uwsgi_opt_add_route

help: add a final route for the specified status

final-route-host

argument: required_argument

parser: uwsgi_opt_add_route

help: add a final route based on Host header

final-route-uri

argument: required_argument

parser: uwsgi_opt_add_route

help: add a final route based on REQUEST_URI

final-route-qs

argument: required_argument

parser: uwsgi_opt_add_route

help: add a final route based on QUERY_STRING

final-route-remote-addr

argument: required_argument

parser: uwsgi_opt_add_route

help: add a final route based on REMOTE_ADDR

final-route-user-agent

argument: required_argument

parser: uwsgi_opt_add_route

help: add a final route based on HTTP_USER_AGENT

final-route-remote-user

argument: required_argument

parser: uwsgi_opt_add_route

help: add a final route based on REMOTE_USER

final-route-referer

argument: required_argument

parser: uwsgi_opt_add_route

help: add a final route based on HTTP_REFERER

final-route-label

argument: required_argument

parser: uwsgi_opt_add_route

help: add a final routing label (for use with goto)

final-route-if

argument: required_argument

parser: uwsgi_opt_add_route

help: add a final route based on condition

final-route-if-not

argument: required_argument

parser: uwsgi_opt_add_route

help: add a final route based on condition (negate version)

final-route-run

argument: required_argument

parser: uwsgi_opt_add_route

help: always run the specified final route action

error-route

argument: required_argument

parser: uwsgi_opt_add_route

help: add an error route

error-route-status

argument: required_argument

parser: uwsgi_opt_add_route

help: add an error route for the specified status

error-route-host

argument: required_argument

parser: uwsgi_opt_add_route

help: add an error route based on Host header

error-route-uri

argument: required_argument

parser: uwsgi_opt_add_route

help: add an error route based on REQUEST_URI

error-route-qs

argument: required_argument

parser: uwsgi_opt_add_route

help: add an error route based on QUERY_STRING

error-route-remote-addr

argument: required_argument

parser: uwsgi_opt_add_route

help: add an error route based on REMOTE_ADDR

error-route-user-agent

argument: required_argument

parser: uwsgi_opt_add_route

help: add an error route based on HTTP_USER_AGENT

error-route-remote-user

argument: required_argument

parser: uwsgi_opt_add_route

help: add an error route based on REMOTE_USER

error-route-referer

argument: required_argument

parser: uwsgi_opt_add_route

help: add an error route based on HTTP_REFERER

error-route-label

argument: required_argument

parser: uwsgi_opt_add_route

help: add an error routing label (for use with goto)

error-route-if

argument: required_argument

parser: uwsgi_opt_add_route

help: add an error route based on condition

error-route-if-not

argument: required_argument

parser: uwsgi_opt_add_route

help: add an error route based on condition (negate version)

error-route-run

argument: required_argument

parser: uwsgi_opt_add_route

help: always run the specified error route action

response-route

argument: required_argument

parser: uwsgi_opt_add_route

help: add a response route

response-route-status

argument: required_argument

parser: uwsgi_opt_add_route

help: add a response route for the specified status

response-route-host

argument: required_argument

parser: uwsgi_opt_add_route

help: add a response route based on Host header

response-route-uri

argument: required_argument

parser: uwsgi_opt_add_route

help: add a response route based on REQUEST_URI

response-route-qs

argument: required_argument

parser: uwsgi_opt_add_route

help: add a response route based on QUERY_STRING

response-route-remote-addr

argument: required_argument

parser: uwsgi_opt_add_route

help: add a response route based on REMOTE_ADDR

response-route-user-agent

argument: required_argument

parser: uwsgi_opt_add_route

help: add a response route based on HTTP_USER_AGENT

response-route-remote-user

argument: required_argument

parser: uwsgi_opt_add_route

help: add a response route based on REMOTE_USER

response-route-referer

argument: required_argument

parser: uwsgi_opt_add_route

help: add a response route based on HTTP_REFERER

response-route-label

argument: required_argument

parser: uwsgi_opt_add_route

help: add a response routing label (for use with goto)

response-route-if

argument: required_argument

parser: uwsgi_opt_add_route

help: add a response route based on condition

response-route-if-not

argument: required_argument

parser: uwsgi_opt_add_route

help: add a response route based on condition (negate version)

response-route-run

argument: required_argument

parser: uwsgi_opt_add_route

help: always run the specified response route action

router-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled routers

routers-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled routers

error-page-403

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an error page (html) for managed 403 response

error-page-404

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an error page (html) for managed 404 response

error-page-500

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an error page (html) for managed 500 response

websockets-ping-freq

argument: required_argument

parser: uwsgi_opt_set_int

help: set the frequency (in seconds) of websockets automatic ping packets

websocket-ping-freq

argument: required_argument

parser: uwsgi_opt_set_int

help: set the frequency (in seconds) of websockets automatic ping packets

websockets-pong-tolerance

argument: required_argument

parser: uwsgi_opt_set_int

help: set the tolerance (in seconds) of websockets ping/pong subsystem

websocket-pong-tolerance

argument: required_argument

parser: uwsgi_opt_set_int

help: set the tolerance (in seconds) of websockets ping/pong subsystem

websockets-max-size

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set the max allowed size of websocket messages (in Kbytes, default 1024)

websocket-max-size

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set the max allowed size of websocket messages (in Kbytes, default 1024)

chunked-input-limit

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set the max size of a chunked input part (default 1MB, in bytes)

chunked-input-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set default timeout for chunked input

clock

argument: required_argument

parser: uwsgi_opt_set_str

help: set a clock source

clock-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled clocks

clocks-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled clocks

add-header

argument: required_argument

parser: uwsgi_opt_add_string_list

help: automatically add HTTP headers to response

rem-header

argument: required_argument

parser: uwsgi_opt_add_string_list

help: automatically remove specified HTTP header from the response

del-header

argument: required_argument

parser: uwsgi_opt_add_string_list

help: automatically remove specified HTTP header from the response

collect-header

argument: required_argument

parser: uwsgi_opt_add_string_list

help: store the specified response header in a request var (syntax: header var)

response-header-collect

argument: required_argument

parser: uwsgi_opt_add_string_list

help: store the specified response header in a request var (syntax: header var)

pull-header

argument: required_argument

parser: uwsgi_opt_add_string_list

help: store the specified response header in a request var and remove it from the response (syntax: header var)

check-static

argument: required_argument

parser: uwsgi_opt_check_static

flags: UWSGI_OPT_MIME

help: check for static files in the specified directory

check-static-docroot

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MIME

help: check for static files in the requested DOCUMENT_ROOT

static-check

argument: required_argument

parser: uwsgi_opt_check_static

flags: UWSGI_OPT_MIME

help: check for static files in the specified directory

static-map

argument: required_argument

parser: uwsgi_opt_static_map

flags: UWSGI_OPT_MIME

help: map mountpoint to static directory (or file)

static-map2

argument: required_argument

parser: uwsgi_opt_static_map

flags: UWSGI_OPT_MIME

help: like static-map but completely appending the requested resource to the docroot

static-skip-ext

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: skip specified extension from staticfile checks

static-index

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: search for specified file if a directory is requested

static-safe

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: skip security checks if the file is under the specified path

static-cache-paths

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MIME|UWSGI_OPT_MASTER

help: put resolved paths in the uWSGI cache for the specified amount of seconds

static-cache-paths-name

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MIME|UWSGI_OPT_MASTER

help: use the specified cache for static paths

mimefile

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: set mime types file path (default /etc/apache2/mime.types)

mime-file

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: set mime types file path (default /etc/apache2/mime.types)

mimefile

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: set mime types file path (default /etc/mime.types)

mime-file

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: set mime types file path (default /etc/mime.types)

static-expires-type

argument: required_argument

parser: uwsgi_opt_add_dyn_dict

flags: UWSGI_OPT_MIME

help: set the Expires header based on content type

static-expires-type-mtime

argument: required_argument

parser: uwsgi_opt_add_dyn_dict

flags: UWSGI_OPT_MIME

help: set the Expires header based on content type and file mtime

static-expires

argument: required_argument

parser: uwsgi_opt_add_regexp_dyn_dict

flags: UWSGI_OPT_MIME

help: set the Expires header based on filename regexp

static-expires-mtime

argument: required_argument

parser: uwsgi_opt_add_regexp_dyn_dict

flags: UWSGI_OPT_MIME

help: set the Expires header based on filename regexp and file mtime

static-expires-uri

argument: required_argument

parser: uwsgi_opt_add_regexp_dyn_dict

flags: UWSGI_OPT_MIME

help: set the Expires header based on REQUEST_URI regexp

static-expires-uri-mtime

argument: required_argument

parser: uwsgi_opt_add_regexp_dyn_dict

flags: UWSGI_OPT_MIME

help: set the Expires header based on REQUEST_URI regexp and file mtime

static-expires-path-info

argument: required_argument

parser: uwsgi_opt_add_regexp_dyn_dict

flags: UWSGI_OPT_MIME

help: set the Expires header based on PATH_INFO regexp

static-expires-path-info-mtime

argument: required_argument

parser: uwsgi_opt_add_regexp_dyn_dict

flags: UWSGI_OPT_MIME

help: set the Expires header based on PATH_INFO regexp and file mtime

static-gzip

argument: required_argument

parser: uwsgi_opt_add_regexp_list

flags: UWSGI_OPT_MIME

help: if the supplied regexp matches the static file translation it will search for a gzip version

static-gzip-all

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MIME

help: check for a gzip version of all requested static files

static-gzip-dir

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: check for a gzip version of all requested static files in the specified dir/prefix

static-gzip-prefix

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: check for a gzip version of all requested static files in the specified dir/prefix

static-gzip-ext

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: check for a gzip version of all requested static files with the specified ext/suffix

static-gzip-suffix

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: check for a gzip version of all requested static files with the specified ext/suffix

honour-range

argument: no_argument

parser: uwsgi_opt_true

help: enable support for the HTTP Range header

offload-threads

argument: required_argument

parser: uwsgi_opt_set_int

help: set the number of offload threads to spawn (per-worker, default 0)

offload-thread

argument: required_argument

parser: uwsgi_opt_set_int

help: set the number of offload threads to spawn (per-worker, default 0)

file-serve-mode

argument: required_argument

parser: uwsgi_opt_fileserve_mode

flags: UWSGI_OPT_MIME

help: set static file serving mode

fileserve-mode

argument: required_argument

parser: uwsgi_opt_fileserve_mode

flags: UWSGI_OPT_MIME

help: set static file serving mode

disable-sendfile

argument: no_argument

parser: uwsgi_opt_true

help: disable sendfile() and rely on boring read()/write()

check-cache

argument: optional_argument

parser: uwsgi_opt_set_str

help: check for response data in the specified cache (empty for default cache)

close-on-exec

argument: no_argument

parser: uwsgi_opt_true

help: set close-on-exec on connection sockets (could be required for spawning processes in requests)

close-on-exec2

argument: no_argument

parser: uwsgi_opt_true

help: set close-on-exec on server sockets (could be required for spawning processes in requests)

mode

argument: required_argument

parser: uwsgi_opt_set_str

help: set uWSGI custom mode

env

argument: required_argument

parser: uwsgi_opt_set_env

help: set environment variable

ienv

argument: required_argument

parser: uwsgi_opt_set_env

flags: UWSGI_OPT_IMMEDIATE

help: set environment variable (IMMEDIATE version)

envdir

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load a daemontools compatible envdir

early-envdir

argument: required_argument

parser: uwsgi_opt_envdir

flags: UWSGI_OPT_IMMEDIATE

help: load a daemontools compatible envdir ASAP

unenv

argument: required_argument

parser: uwsgi_opt_unset_env

help: unset environment variable

vacuum

argument: no_argument

parser: uwsgi_opt_true

help: try to remove all of the generated file/sockets

file-write

argument: required_argument

parser: uwsgi_opt_add_string_list

help: write the specified content to the specified file (syntax: file=value) before privileges drop

cgroup

argument: required_argument

parser: uwsgi_opt_add_string_list

help: put the processes in the specified cgroup

cgroup-opt

argument: required_argument

parser: uwsgi_opt_add_string_list

help: set value in specified cgroup option

cgroup-dir-mode

argument: required_argument

parser: uwsgi_opt_set_str

help: set permission for cgroup directory (default is 700)

namespace

argument: required_argument

parser: uwsgi_opt_set_str

help: run in a new namespace under the specified rootfs

namespace-keep-mount

argument: required_argument

parser: uwsgi_opt_add_string_list

help: keep the specified mountpoint in your namespace

ns

argument: required_argument

parser: uwsgi_opt_set_str

help: run in a new namespace under the specified rootfs

namespace-net

argument: required_argument

parser: uwsgi_opt_set_str

help: add network namespace

ns-net

argument: required_argument

parser: uwsgi_opt_set_str

help: add network namespace

enable-proxy-protocol

argument: no_argument

parser: uwsgi_opt_true

help: enable PROXY1 protocol support (only for http parsers)

reuse-port

argument: no_argument

parser: uwsgi_opt_true

help: enable REUSE_PORT flag on socket (BSD only)

tcp-fast-open

argument: required_argument

parser: uwsgi_opt_set_int

help: enable TCP_FASTOPEN flag on TCP sockets with the specified qlen value

tcp-fastopen

argument: required_argument

parser: uwsgi_opt_set_int

help: enable TCP_FASTOPEN flag on TCP sockets with the specified qlen value

tcp-fast-open-client

argument: no_argument

parser: uwsgi_opt_true

help: use sendto(..., MSG_FASTOPEN, ...) instead of connect() if supported

tcp-fastopen-client

argument: no_argument

parser: uwsgi_opt_true

help: use sendto(..., MSG_FASTOPEN, ...) instead of connect() if supported

zerg

argument: required_argument

parser: uwsgi_opt_add_string_list

help: attach to a zerg server

zerg-fallback

argument: no_argument

parser: uwsgi_opt_true

help: fallback to normal sockets if the zerg server is not available

zerg-server

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MASTER

help: enable the zerg server on the specified UNIX socket

cron

argument: required_argument

parser: uwsgi_opt_add_cron

flags: UWSGI_OPT_MASTER

help: add a cron task

cron2

argument: required_argument

parser: uwsgi_opt_add_cron2

flags: UWSGI_OPT_MASTER

help: add a cron task (key=val syntax)

unique-cron

argument: required_argument

parser: uwsgi_opt_add_unique_cron

flags: UWSGI_OPT_MASTER

help: add a unique cron task

cron-harakiri

argument: required_argument

parser: uwsgi_opt_set_int

help: set the maximum time (in seconds) we wait for cron command to complete

legion-cron

argument: required_argument

parser: uwsgi_opt_add_legion_cron

flags: UWSGI_OPT_MASTER

help: add a cron task runnable only when the instance is a lord of the specified legion

cron-legion

argument: required_argument

parser: uwsgi_opt_add_legion_cron

flags: UWSGI_OPT_MASTER

help: add a cron task runnable only when the instance is a lord of the specified legion

unique-legion-cron

argument: required_argument

parser: uwsgi_opt_add_unique_legion_cron

flags: UWSGI_OPT_MASTER

help: add a unique cron task runnable only when the instance is a lord of the specified legion

unique-cron-legion

argument: required_argument

parser: uwsgi_opt_add_unique_legion_cron

flags: UWSGI_OPT_MASTER

help: add a unique cron task runnable only when the instance is a lord of the specified legion

loop

argument: required_argument

parser: uwsgi_opt_set_str

help: select the uWSGI loop engine

loop-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled loop engines

loops-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled loop engines

worker-exec

argument: required_argument

parser: uwsgi_opt_set_str

help: run the specified command as worker

worker-exec2

argument: required_argument

parser: uwsgi_opt_set_str

help: run the specified command as worker (after post_fork hook)

attach-daemon

argument: required_argument

parser: uwsgi_opt_add_daemon

flags: UWSGI_OPT_MASTER

help: attach a command/daemon to the master process (the command has to not go in background)

attach-control-daemon

argument: required_argument

parser: uwsgi_opt_add_daemon

flags: UWSGI_OPT_MASTER

help: attach a command/daemon to the master process (the command has to not go in background), when the daemon dies, the master dies too

smart-attach-daemon

argument: required_argument

parser: uwsgi_opt_add_daemon

flags: UWSGI_OPT_MASTER

help: attach a command/daemon to the master process managed by a pidfile (the command has to daemonize)

smart-attach-daemon2

argument: required_argument

parser: uwsgi_opt_add_daemon

flags: UWSGI_OPT_MASTER

help: attach a command/daemon to the master process managed by a pidfile (the command has to NOT daemonize)

legion-attach-daemon

argument: required_argument

parser: uwsgi_opt_add_daemon

flags: UWSGI_OPT_MASTER

help: same as –attach-daemon but daemon runs only on legion lord node

legion-smart-attach-daemon

argument: required_argument

parser: uwsgi_opt_add_daemon

flags: UWSGI_OPT_MASTER

help: same as –smart-attach-daemon but daemon runs only on legion lord node

legion-smart-attach-daemon2

argument: required_argument

parser: uwsgi_opt_add_daemon

flags: UWSGI_OPT_MASTER

help: same as –smart-attach-daemon2 but daemon runs only on legion lord node

daemons-honour-stdin

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MASTER

help: do not change the stdin of external daemons to /dev/null

attach-daemon2

argument: required_argument

parser: uwsgi_opt_add_daemon2

flags: UWSGI_OPT_MASTER

help: attach-daemon keyval variant (supports smart modes too)

plugins

argument: required_argument

parser: uwsgi_opt_load_plugin

flags: UWSGI_OPT_IMMEDIATE

help: load uWSGI plugins

plugin

argument: required_argument

parser: uwsgi_opt_load_plugin

flags: UWSGI_OPT_IMMEDIATE

help: load uWSGI plugins

need-plugins

argument: required_argument

parser: uwsgi_opt_load_plugin

flags: UWSGI_OPT_IMMEDIATE

help: load uWSGI plugins (exit on error)

need-plugin

argument: required_argument

parser: uwsgi_opt_load_plugin

flags: UWSGI_OPT_IMMEDIATE

help: load uWSGI plugins (exit on error)

plugins-dir

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_IMMEDIATE

help: add a directory to uWSGI plugin search path

plugin-dir

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_IMMEDIATE

help: add a directory to uWSGI plugin search path

plugins-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled plugins

plugin-list

argument: no_argument

parser: uwsgi_opt_true

help: list enabled plugins

autoload

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_IMMEDIATE

help: try to automatically load plugins when unknown options are found

dlopen

argument: required_argument

parser: uwsgi_opt_load_dl

flags: UWSGI_OPT_IMMEDIATE

help: blindly load a shared library

allowed-modifiers

argument: required_argument

parser: uwsgi_opt_set_str

help: comma separated list of allowed modifiers

remap-modifier

argument: required_argument

parser: uwsgi_opt_set_str

help: remap request modifier from one id to another

dump-options

argument: no_argument

parser: uwsgi_opt_true

help: dump the full list of available options

show-config

argument: no_argument

parser: uwsgi_opt_true

help: show the current config reformatted as ini

binary-append-data

argument: required_argument

parser: uwsgi_opt_binary_append_data

flags: UWSGI_OPT_IMMEDIATE

help: return the content of a resource to stdout for appending to a uwsgi binary (for data:// usage)

print

argument: required_argument

parser: uwsgi_opt_print

help: simple print

iprint

argument: required_argument

parser: uwsgi_opt_print

flags: UWSGI_OPT_IMMEDIATE

help: simple print (immediate version)

exit

argument: optional_argument

parser: uwsgi_opt_exit

flags: UWSGI_OPT_IMMEDIATE

help: force exit() of the instance

cflags

argument: no_argument

parser: uwsgi_opt_cflags

flags: UWSGI_OPT_IMMEDIATE

help: report uWSGI CFLAGS (useful for building external plugins)

dot-h

argument: no_argument

parser: uwsgi_opt_dot_h

flags: UWSGI_OPT_IMMEDIATE

help: dump the uwsgi.h used for building the core (useful for building external plugins)

config-py

argument: no_argument

parser: uwsgi_opt_config_py

flags: UWSGI_OPT_IMMEDIATE

help: dump the uwsgiconfig.py used for building the core (useful for building external plugins)

build-plugin

argument: required_argument

parser: uwsgi_opt_build_plugin

flags: UWSGI_OPT_IMMEDIATE

help: build a uWSGI plugin for the current binary

version

argument: no_argument

parser: uwsgi_opt_print

help: print uWSGI version

plugin: airbrake

plugin: alarm_curl

plugin: alarm_speech

plugin: alarm_xmpp

plugin: asyncio

asyncio

argument: required_argument

parser: uwsgi_opt_setup_asyncio

flags: UWSGI_OPT_THREADS

help: a shortcut enabling asyncio loop engine with the specified number of async cores and optimal parameters

plugin: cache

plugin: carbon

carbon

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: push statistics to the specified carbon server

carbon-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set carbon connection timeout in seconds (default 3)

carbon-freq

argument: required_argument

parser: uwsgi_opt_set_int

help: set carbon push frequency in seconds (default 60)

carbon-id

argument: required_argument

parser: uwsgi_opt_set_str

help: set carbon id

carbon-no-workers

argument: no_argument

parser: uwsgi_opt_true

help: disable generation of single worker metrics

carbon-max-retry

argument: required_argument

parser: uwsgi_opt_set_int

help: set maximum number of retries in case of connection errors (default 1)

carbon-retry-delay

argument: required_argument

parser: uwsgi_opt_set_int

help: set connection retry delay in seconds (default 7)

carbon-root

argument: required_argument

parser: uwsgi_opt_set_str

help: set carbon metrics root node (default ‘uwsgi’)

carbon-hostname-dots

argument: required_argument

parser: uwsgi_opt_set_str

help: set char to use as a replacement for dots in hostname (dots are not replaced by default)

carbon-name-resolve

argument: no_argument

parser: uwsgi_opt_true

help: allow using hostname as carbon server address (default disabled)

carbon-resolve-names

argument: no_argument

parser: uwsgi_opt_true

help: allow using hostname as carbon server address (default disabled)

carbon-idle-avg

argument: required_argument

parser: uwsgi_opt_set_str

help: average values source during idle period (no requests), can be “last”, “zero”, “none” (default is last)

carbon-use-metrics

argument: no_argument

parser: uwsgi_opt_true

help: don’t compute all statistics, use metrics subsystem data instead (warning! key names will be different)

plugin: cgi

cgi

argument: required_argument

parser: uwsgi_opt_add_cgi

help: add a cgi mountpoint/directory/script

cgi-map-helper

argument: required_argument

parser: uwsgi_opt_add_cgi_maphelper

help: add a cgi map-helper

cgi-helper

argument: required_argument

parser: uwsgi_opt_add_cgi_maphelper

help: add a cgi map-helper

cgi-from-docroot

argument: no_argument

parser: uwsgi_opt_true

help: blindly enable cgi in DOCUMENT_ROOT

cgi-buffer-size

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set cgi buffer size

cgi-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set cgi script timeout

cgi-index

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add a cgi index file

cgi-allowed-ext

argument: required_argument

parser: uwsgi_opt_add_string_list

help: cgi allowed extension

cgi-unset

argument: required_argument

parser: uwsgi_opt_add_string_list

help: unset specified environment variables

cgi-loadlib

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load a cgi shared library/optimizer

cgi-optimize

argument: no_argument

parser: uwsgi_opt_true

help: enable cgi realpath() optimizer

cgi-optimized

argument: no_argument

parser: uwsgi_opt_true

help: enable cgi realpath() optimizer

cgi-path-info

argument: no_argument

parser: uwsgi_opt_true

help: disable PATH_INFO management in cgi scripts

cgi-do-not-kill-on-error

argument: no_argument

parser: uwsgi_opt_true

help: do not send SIGKILL to cgi script on errors

cgi-async-max-attempts

argument: no_argument

parser: uwsgi_opt_set_int

help: max waitpid() attempts in cgi async mode (default 10)

plugin: cheaper_backlog2

plugin: cheaper_busyness

plugin: clock_monotonic

plugin: clock_realtime

plugin: corerouter

plugin: coroae

coroae

argument: required_argument

parser: uwsgi_opt_setup_coroae

help: a shortcut enabling Coro::AnyEvent loop engine with the specified number of async cores and optimal parameters

plugin: cplusplus

plugin: curl_cron

curl-cron

argument: required_argument

parser: uwsgi_opt_add_cron_curl

flags: UWSGI_OPT_MASTER

help: add a cron task invoking the specified url via CURL

cron-curl

argument: required_argument

parser: uwsgi_opt_add_cron_curl

flags: UWSGI_OPT_MASTER

help: add a cron task invoking the specified url via CURL

legion-curl-cron

argument: required_argument

parser: uwsgi_opt_add_legion_cron_curl

flags: UWSGI_OPT_MASTER

help: add a cron task invoking the specified url via CURL runnable only when the instance is a lord of the specified legion

legion-cron-curl

argument: required_argument

parser: uwsgi_opt_add_legion_cron_curl

flags: UWSGI_OPT_MASTER

help: add a cron task invoking the specified url via CURL runnable only when the instance is a lord of the specified legion

curl-cron-legion

argument: required_argument

parser: uwsgi_opt_add_legion_cron_curl

flags: UWSGI_OPT_MASTER

help: add a cron task invoking the specified url via CURL runnable only when the instance is a lord of the specified legion

cron-curl-legion

argument: required_argument

parser: uwsgi_opt_add_legion_cron_curl

flags: UWSGI_OPT_MASTER

help: add a cron task invoking the specified url via CURL runnable only when the instance is a lord of the specified legion

plugin: dumbloop

dumbloop-modifier1

argument: required_argument

parser: uwsgi_opt_set_int

help: set the modifier1 for the code_string

dumbloop-code

argument: required_argument

parser: uwsgi_opt_set_str

help: set the script to load for the code_string

dumbloop-function

argument: required_argument

parser: uwsgi_opt_set_str

help: set the function to run for the code_string

plugin: dummy

plugin: echo

plugin: emperor_amqp

plugin: emperor_mongodb

plugin: emperor_pg

plugin: emperor_zeromq

plugin: example

plugin: exception_log

plugin: fastrouter

fastrouter

argument: required_argument

parser: uwsgi_opt_corerouter

help: run the fastrouter on the specified port

reference: The uWSGI FastRouter

fastrouter-processes

argument: required_argument

parser: uwsgi_opt_set_int

help: prefork the specified number of fastrouter processes

fastrouter-workers

argument: required_argument

parser: uwsgi_opt_set_int

help: prefork the specified number of fastrouter processes

fastrouter-zerg

argument: required_argument

parser: uwsgi_opt_corerouter_zerg

help: attach the fastrouter to a zerg server

fastrouter-use-cache

argument: optional_argument

parser: uwsgi_opt_set_str

help: use uWSGI cache as hostname->server mapper for the fastrouter

fastrouter-use-pattern

argument: required_argument

parser: uwsgi_opt_corerouter_use_pattern

help: use a pattern for fastrouter hostname->server mapping

fastrouter-use-base

argument: required_argument

parser: uwsgi_opt_corerouter_use_base

help: use a base dir for fastrouter hostname->server mapping

fastrouter-fallback

argument: required_argument

parser: uwsgi_opt_add_string_list

help: fallback to the specified node in case of error

fastrouter-use-code-string

argument: required_argument

parser: uwsgi_opt_corerouter_cs

help: use code string as hostname->server mapper for the fastrouter

fastrouter-use-socket

argument: optional_argument

parser: uwsgi_opt_corerouter_use_socket

help: forward request to the specified uwsgi socket

fastrouter-to

argument: required_argument

parser: uwsgi_opt_add_string_list

help: forward requests to the specified uwsgi server (you can specify it multiple times for load balancing)

fastrouter-gracetime

argument: required_argument

parser: uwsgi_opt_set_int

help: retry connections to dead static nodes after the specified amount of seconds

fastrouter-events

argument: required_argument

parser: uwsgi_opt_set_int

help: set the maximum number of concurrent events

fastrouter-quiet

argument: required_argument

parser: uwsgi_opt_true

help: do not report failed connections to instances

fastrouter-cheap

argument: no_argument

parser: uwsgi_opt_true

help: run the fastrouter in cheap mode

fastrouter-subscription-server

argument: required_argument

parser: uwsgi_opt_corerouter_ss

help: run the fastrouter subscription server on the specified address

fastrouter-subscription-slot

argument: required_argument

parser: uwsgi_opt_deprecated

help: * deprecated *

fastrouter-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set fastrouter timeout

fastrouter-post-buffering

argument: required_argument

parser: uwsgi_opt_set_64bit

help: enable fastrouter post buffering

fastrouter-post-buffering-dir

argument: required_argument

parser: uwsgi_opt_set_str

help: put fastrouter buffered files to the specified directory (noop, use TMPDIR env)

fastrouter-stats

argument: required_argument

parser: uwsgi_opt_set_str

help: run the fastrouter stats server

fastrouter-stats-server

argument: required_argument

parser: uwsgi_opt_set_str

help: run the fastrouter stats server

fastrouter-ss

argument: required_argument

parser: uwsgi_opt_set_str

help: run the fastrouter stats server

fastrouter-harakiri

argument: required_argument

parser: uwsgi_opt_set_int

help: enable fastrouter harakiri

fastrouter-uid

argument: required_argument

parser: uwsgi_opt_uid

help: drop fastrouter privileges to the specified uid

fastrouter-gid

argument: required_argument

parser: uwsgi_opt_gid

help: drop fastrouter privileges to the specified gid

fastrouter-resubscribe

argument: required_argument

parser: uwsgi_opt_add_string_list

help: forward subscriptions to the specified subscription server

fastrouter-resubscribe-bind

argument: required_argument

parser: uwsgi_opt_set_str

help: bind to the specified address when re-subscribing

fastrouter-buffer-size

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set internal buffer size (default: page size)

fastrouter-fallback-on-no-key

argument: no_argument

parser: uwsgi_opt_true

help: move to fallback node even if a subscription key is not found

fastrouter-force-key

argument: required_argument

parser: uwsgi_opt_set_str

help: skip uwsgi parsing and directly set a key

plugin: fiber

fiber

argument: no_argument

parser: uwsgi_opt_true

help: enable ruby fiber as suspend engine

plugin: forkptyrouter

forkptyrouter

argument: required_argument

parser: uwsgi_opt_undeferred_corerouter

help: run the forkptyrouter on the specified address

forkpty-router

argument: required_argument

parser: uwsgi_opt_undeferred_corerouter

help: run the forkptyrouter on the specified address

forkptyurouter

argument: required_argument

parser: uwsgi_opt_forkpty_urouter

help: run the forkptyrouter on the specified address

forkpty-urouter

argument: required_argument

parser: uwsgi_opt_forkpty_urouter

help: run the forkptyrouter on the specified address

forkptyrouter-command

argument: required_argument

parser: uwsgi_opt_set_str

help: run the specified command on every connection (default: /bin/sh)

forkpty-router-command

argument: required_argument

parser: uwsgi_opt_set_str

help: run the specified command on every connection (default: /bin/sh)

forkptyrouter-cmd

argument: required_argument

parser: uwsgi_opt_set_str

help: run the specified command on every connection (default: /bin/sh)

forkpty-router-cmd

argument: required_argument

parser: uwsgi_opt_set_str

help: run the specified command on every connection (default: /bin/sh)

forkptyrouter-rows

argument: required_argument

parser: uwsgi_opt_set_16bit

help: set forkptyrouter default pty window rows

forkptyrouter-cols

argument: required_argument

parser: uwsgi_opt_set_16bit

help: set forkptyrouter default pty window cols

forkptyrouter-processes

argument: required_argument

parser: uwsgi_opt_set_int

help: prefork the specified number of forkptyrouter processes

forkptyrouter-workers

argument: required_argument

parser: uwsgi_opt_set_int

help: prefork the specified number of forkptyrouter processes

forkptyrouter-zerg

argument: required_argument

parser: uwsgi_opt_corerouter_zerg

help: attach the forkptyrouter to a zerg server

forkptyrouter-fallback

argument: required_argument

parser: uwsgi_opt_add_string_list

help: fallback to the specified node in case of error

forkptyrouter-events

argument: required_argument

parser: uwsgi_opt_set_int

help: set the maximum number of concufptyent events

forkptyrouter-cheap

argument: no_argument

parser: uwsgi_opt_true

help: run the forkptyrouter in cheap mode

forkptyrouter-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set forkptyrouter timeout

forkptyrouter-stats

argument: required_argument

parser: uwsgi_opt_set_str

help: run the forkptyrouter stats server

forkptyrouter-stats-server

argument: required_argument

parser: uwsgi_opt_set_str

help: run the forkptyrouter stats server

forkptyrouter-ss

argument: required_argument

parser: uwsgi_opt_set_str

help: run the forkptyrouter stats server

forkptyrouter-harakiri

argument: required_argument

parser: uwsgi_opt_set_int

help: enable forkptyrouter harakiri

plugin: gccgo

go-load

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load a go shared library in the process address space, eventually patching main.main and __go_init_main

gccgo-load

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load a go shared library in the process address space, eventually patching main.main and __go_init_main

go-args

argument: required_argument

parser: uwsgi_opt_set_str

help: set go commandline arguments

gccgo-args

argument: required_argument

parser: uwsgi_opt_set_str

help: set go commandline arguments

goroutines

argument: required_argument

parser: uwsgi_opt_setup_goroutines

flags: UWSGI_OPT_THREADS

help: a shortcut setting optimal options for goroutine-based apps, takes the number of max goroutines to spawn as argument

plugin: geoip

geoip-country

argument: required_argument

parser: uwsgi_opt_set_str

help: load the specified geoip country database

geoip-city

argument: required_argument

parser: uwsgi_opt_set_str

help: load the specified geoip city database

geoip-use-disk

argument: no_argument

parser: uwsgi_opt_true

help: do not cache geoip databases in memory

plugin: gevent

gevent

argument: required_argument

parser: uwsgi_opt_setup_gevent

flags: UWSGI_OPT_THREADS

help: a shortcut enabling gevent loop engine with the specified number of async cores and optimal parameters

gevent-monkey-patch

argument: no_argument

parser: uwsgi_opt_true

help: call gevent.monkey.patch_all() automatically on startup

gevent-early-monkey-patch

argument: no_argument

parser: uwsgi_opt_true

help: call gevent.monkey.patch_all() automatically before app loading

gevent-wait-for-hub

argument: no_argument

parser: uwsgi_opt_true

help: wait for gevent hub’s death instead of the control greenlet

plugin: glusterfs

glusterfs-mount

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: virtual mount the specified glusterfs volume in a uri

glusterfs-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: timeout for glusterfs async mode

plugin: graylog2

plugin: greenlet

greenlet

argument: no_argument

parser: uwsgi_opt_true

help: enable greenlet as suspend engine

plugin: gridfs

gridfs-mount

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: mount a gridfs db on the specified mountpoint

gridfs-debug

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_MIME

help: report gridfs mountpoint and itemname for each request (debug)

plugin: http

http

argument: required_argument

parser: uwsgi_opt_corerouter

help: add an http router/server on the specified address

httprouter

argument: required_argument

parser: uwsgi_opt_corerouter

help: add an http router/server on the specified address

https

argument: required_argument

parser: uwsgi_opt_https

help: add an https router/server on the specified address with specified certificate and key

https2

argument: required_argument

parser: uwsgi_opt_https2

help: add an https/spdy router/server using keyval options

https-export-cert

argument: no_argument

parser: uwsgi_opt_true

help: export uwsgi variable HTTPS_CC containing the raw client certificate

https-session-context

argument: required_argument

parser: uwsgi_opt_set_str

help: set the session id context to the specified value

http-to-https

argument: required_argument

parser: uwsgi_opt_http_to_https

help: add an http router/server on the specified address and redirect all of the requests to https

http-processes

argument: required_argument

parser: uwsgi_opt_set_int

help: set the number of http processes to spawn

http-workers

argument: required_argument

parser: uwsgi_opt_set_int

help: set the number of http processes to spawn

http-var

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add a key=value item to the generated uwsgi packet

http-to

argument: required_argument

parser: uwsgi_opt_add_string_list

help: forward requests to the specified node (you can specify it multiple time for lb)

http-zerg

argument: required_argument

parser: uwsgi_opt_corerouter_zerg

help: attach the http router to a zerg server

http-fallback

argument: required_argument

parser: uwsgi_opt_add_string_list

help: fallback to the specified node in case of error

http-modifier1

argument: required_argument

parser: uwsgi_opt_set_int

help: set uwsgi protocol modifier1

http-modifier2

argument: required_argument

parser: uwsgi_opt_set_int

help: set uwsgi protocol modifier2

http-use-cache

argument: optional_argument

parser: uwsgi_opt_set_str

help: use uWSGI cache as key->value virtualhost mapper

http-use-pattern

argument: required_argument

parser: uwsgi_opt_corerouter_use_pattern

help: use the specified pattern for mapping requests to unix sockets

http-use-base

argument: required_argument

parser: uwsgi_opt_corerouter_use_base

help: use the specified base for mapping requests to unix sockets

http-events

argument: required_argument

parser: uwsgi_opt_set_int

help: set the number of concurrent http async events

http-subscription-server

argument: required_argument

parser: uwsgi_opt_corerouter_ss

help: enable the subscription server

http-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set internal http socket timeout

http-manage-expect

argument: optional_argument

parser: uwsgi_opt_set_64bit

help: manage the Expect HTTP request header (optionally checking for Content-Length)

http-keepalive

argument: optional_argument

parser: uwsgi_opt_set_int

help: HTTP 1.1 keepalive support (non-pipelined) requests

http-auto-chunked

argument: no_argument

parser: uwsgi_opt_true

help: automatically transform output to chunked encoding during HTTP 1.1 keepalive (if needed)

http-auto-gzip

argument: no_argument

parser: uwsgi_opt_true

help: automatically gzip content if uWSGI-Encoding header is set to gzip, but content size (Content-Length/Transfer-Encoding) and Content-Encoding are not specified

http-raw-body

argument: no_argument

parser: uwsgi_opt_true

help: blindly send HTTP body to backends (required for WebSockets and Icecast support in backends)

http-websockets

argument: no_argument

parser: uwsgi_opt_true

help: automatically detect websockets connections and put the session in raw mode

http-chunked-input

argument: no_argument

parser: uwsgi_opt_true

help: automatically detect chunked input requests and put the session in raw mode

http-use-code-string

argument: required_argument

parser: uwsgi_opt_corerouter_cs

help: use code string as hostname->server mapper for the http router

http-use-socket

argument: optional_argument

parser: uwsgi_opt_corerouter_use_socket

help: forward request to the specified uwsgi socket

http-gracetime

argument: required_argument

parser: uwsgi_opt_set_int

help: retry connections to dead static nodes after the specified amount of seconds

http-quiet

argument: required_argument

parser: uwsgi_opt_true

help: do not report failed connections to instances

http-cheap

argument: no_argument

parser: uwsgi_opt_true

help: run the http router in cheap mode

http-stats

argument: required_argument

parser: uwsgi_opt_set_str

help: run the http router stats server

http-stats-server

argument: required_argument

parser: uwsgi_opt_set_str

help: run the http router stats server

http-ss

argument: required_argument

parser: uwsgi_opt_set_str

help: run the http router stats server

http-harakiri

argument: required_argument

parser: uwsgi_opt_set_int

help: enable http router harakiri

http-stud-prefix

argument: required_argument

parser: uwsgi_opt_add_addr_list

help: expect a stud prefix (1byte family + 4/16 bytes address) on connections from the specified address

http-uid

argument: required_argument

parser: uwsgi_opt_uid

help: drop http router privileges to the specified uid

http-gid

argument: required_argument

parser: uwsgi_opt_gid

help: drop http router privileges to the specified gid

http-resubscribe

argument: required_argument

parser: uwsgi_opt_add_string_list

help: forward subscriptions to the specified subscription server

http-buffer-size

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set internal buffer size (default: page size)

http-server-name-as-http-host

argument: required_argument

parser: uwsgi_opt_true

help: force SERVER_NAME to HTTP_HOST

http-headers-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set internal http socket timeout for headers

http-connect-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set internal http socket timeout for backend connections

http-manage-source

argument: no_argument

parser: uwsgi_opt_true

help: manage the SOURCE HTTP method placing the session in raw mode

http-enable-proxy-protocol

argument: optional_argument

parser: uwsgi_opt_true

help: manage PROXY protocol requests

http-backend-http

argument: no_argument

parser: uwsgi_opt_true

help: use plain http protocol instead of uwsgi for backend nodes

http-manage-rtsp

argument: no_argument

parser: uwsgi_opt_true

help: manage RTSP sessions

0x1f

argument: 0x8b

shortcut: -Z_DEFLATED

help: 0

plugin: jvm

jvm-main-class

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load the specified class and call its main() function

jvm-opt

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add the specified jvm option

jvm-class

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load the specified class

jvm-classpath

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add the specified directory to the classpath

plugin: jwsgi

jwsgi

argument: required_argument

parser: uwsgi_opt_set_str

help: load the specified JWSGI application (syntax class:method)

plugin: ldap

ldap

argument: required_argument

parser: uwsgi_opt_load_ldap

flags: UWSGI_OPT_IMMEDIATE

help: load configuration from ldap server

ldap-schema

argument: no_argument

parser: uwsgi_opt_ldap_dump

flags: UWSGI_OPT_IMMEDIATE

help: dump uWSGI ldap schema

ldap-schema-ldif

argument: no_argument

parser: uwsgi_opt_ldap_dump_ldif

flags: UWSGI_OPT_IMMEDIATE

help: dump uWSGI ldap schema in ldif format

plugin: legion_cache_fetch

plugin: libffi

plugin: libtcc

plugin: logcrypto

plugin: logfile

plugin: logpipe

plugin: logsocket

plugin: logzmq

log-zeromq

argument: required_argument

parser: uwsgi_opt_set_logger

flags: UWSGI_OPT_MASTER | UWSGI_OPT_LOG_MASTER

help: send logs to a zeromq server

plugin: lua

lua

argument: required_argument

parser: uwsgi_opt_set_str

help: load lua wsapi app

lua-load

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load a lua file

lua-shell

argument: no_argument

parser: uwsgi_opt_luashell

help: run the lua interactive shell (debug.debug())

luashell

argument: no_argument

parser: uwsgi_opt_luashell

help: run the lua interactive shell (debug.debug())

lua-gc-freq

argument: no_argument

parser: uwsgi_opt_set_int

help: set the lua gc frequency (default: 0, runs after every request)

plugin: matheval

plugin: mongodb

plugin: mongodblog

plugin: mongrel2

zeromq

argument: required_argument

parser: uwsgi_opt_add_lazy_socket

help: create a mongrel2/zeromq pub/sub pair

zmq

argument: required_argument

parser: uwsgi_opt_add_lazy_socket

help: create a mongrel2/zeromq pub/sub pair

zeromq-socket

argument: required_argument

parser: uwsgi_opt_add_lazy_socket

help: create a mongrel2/zeromq pub/sub pair

zmq-socket

argument: required_argument

parser: uwsgi_opt_add_lazy_socket

help: create a mongrel2/zeromq pub/sub pair

mongrel2

argument: required_argument

parser: uwsgi_opt_add_lazy_socket

help: create a mongrel2/zeromq pub/sub pair

plugin: mono

mono-app

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load a Mono asp.net app from the specified directory

mono-gc-freq

argument: required_argument

parser: uwsgi_opt_set_64bit

help: run the Mono GC every <n> requests (default: run after every request)

mono-key

argument: required_argument

parser: uwsgi_opt_add_string_list

help: select the ApplicationHost based on the specified CGI var

mono-version

argument: required_argument

parser: uwsgi_opt_set_str

help: set the Mono jit version

mono-config

argument: required_argument

parser: uwsgi_opt_set_str

help: set the Mono config file

mono-assembly

argument: required_argument

parser: uwsgi_opt_set_str

help: load the specified main assembly (default: uwsgi.dll)

mono-exec

argument: required_argument

parser: uwsgi_opt_add_string_list

help: exec the specified assembly just before app loading

mono-index

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an asp.net index file

plugin: msgpack

plugin: nagios

nagios

argument: no_argument

parser: uwsgi_opt_true

flags: UWSGI_OPT_NO_INITIAL

help: nagios check

plugin: notfound

notfound-log

argument: no_argument

parser: uwsgi_opt_true

help: log requests to the notfound plugin

plugin: objc_gc

plugin: pam

pam

argument: required_argument

parser: uwsgi_opt_set_str

help: set the pam service name to use

pam-user

argument: required_argument

parser: uwsgi_opt_set_str

help: set a fake user for pam

plugin: php

php-ini

argument: required_argument

parser: uwsgi_opt_php_ini

help: set php.ini path

php-config

argument: required_argument

parser: uwsgi_opt_php_ini

help: set php.ini path

php-ini-append

argument: required_argument

parser: uwsgi_opt_add_string_list

help: set php.ini path (append mode)

php-config-append

argument: required_argument

parser: uwsgi_opt_add_string_list

help: set php.ini path (append mode)

php-set

argument: required_argument

parser: uwsgi_opt_add_string_list

help: set a php config directive

php-index

argument: required_argument

parser: uwsgi_opt_add_string_list

help: list the php index files

php-docroot

argument: required_argument

parser: uwsgi_opt_set_str

help: force php DOCUMENT_ROOT

php-allowed-docroot

argument: required_argument

parser: uwsgi_opt_add_string_list

help: list the allowed document roots

php-allowed-ext

argument: required_argument

parser: uwsgi_opt_add_string_list

help: list the allowed php file extensions

php-allowed-script

argument: required_argument

parser: uwsgi_opt_add_string_list

help: list the allowed php scripts (require absolute path)

php-server-software

argument: required_argument

parser: uwsgi_opt_set_str

help: force php SERVER_SOFTWARE

php-app

argument: required_argument

parser: uwsgi_opt_set_str

help: force the php file to run at each request

php-app-qs

argument: required_argument

parser: uwsgi_opt_set_str

help: when in app mode force QUERY_STRING to the specified value + REQUEST_URI

php-fallback

argument: required_argument

parser: uwsgi_opt_set_str

help: run the specified php script when the request one does not exist

php-app-bypass

argument: required_argument

parser: uwsgi_opt_add_regexp_list

help: if the regexp matches the uri the –php-app is bypassed

php-var

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add/overwrite a CGI variable at each request

php-dump-config

argument: no_argument

parser: uwsgi_opt_true

help: dump php config (if modified via –php-set or append options)

php-exec-before

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run specified php code before the requested script

php-exec-begin

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run specified php code before the requested script

php-exec-after

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run specified php code after the requested script

php-exec-end

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run specified php code after the requested script

php-sapi-name

argument: required_argument

parser: uwsgi_opt_set_str

help: hack the sapi name (required for enabling zend opcode cache)

early-php

argument: no_argument

parser: uwsgi_opt_early_php

flags: UWSGI_OPT_IMMEDIATE

help: initialize an early perl interpreter shared by all loaders

early-php-sapi-name

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_IMMEDIATE

help: hack the sapi name (required for enabling zend opcode cache)

plugin: ping

ping

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_NO_INITIAL | UWSGI_OPT_NO_SERVER

help: ping specified uwsgi host

ping-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set ping timeout

plugin: psgi

psgi

argument: required_argument

parser: uwsgi_opt_set_str

help: load a psgi app

psgi-enable-psgix-io

argument: no_argument

parser: uwsgi_opt_true

help: enable psgix.io support

perl-no-die-catch

argument: no_argument

parser: uwsgi_opt_true

help: do not catch $SIG{__DIE__}

perl-local-lib

argument: required_argument

parser: uwsgi_opt_set_str

help: set perl locallib path

perl-version

argument: no_argument

parser: uwsgi_opt_print

flags: UWSGI_OPT_IMMEDIATE

help: print perl version

perl-args

argument: required_argument

parser: uwsgi_opt_set_str

help: add items (space separated) to @ARGV

perl-arg

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an item to @ARGV

perl-exec

argument: required_argument

parser: uwsgi_opt_add_string_list

help: exec the specified perl file before fork()

perl-exec-post-fork

argument: required_argument

parser: uwsgi_opt_add_string_list

help: exec the specified perl file after fork()

perl-auto-reload

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_MASTER

help: enable perl auto-reloader with the specified frequency

perl-auto-reload-ignore

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER

help: ignore the specified files when auto-reload is enabled

plshell

argument: optional_argument

parser: uwsgi_opt_plshell

help: run a perl interactive shell

plshell-oneshot

argument: no_argument

parser: uwsgi_opt_plshell

help: run a perl interactive shell (one shot)

perl-no-plack

argument: no_argument

parser: uwsgi_opt_true

help: force the use of do instead of Plack::Util::load_psgi

early-perl

argument: required_argument

parser: uwsgi_opt_early_perl

flags: UWSGI_OPT_IMMEDIATE

help: initialize an early perl interpreter shared by all loaders

early-psgi

argument: required_argument

parser: uwsgi_opt_early_psgi

flags: UWSGI_OPT_IMMEDIATE

help: load a psgi app soon after uWSGI initialization

early-perl-exec

argument: required_argument

parser: uwsgi_opt_early_exec

flags: UWSGI_OPT_IMMEDIATE

help: load a perl script soon after uWSGI initialization

plugin: pty

pty-socket

argument: required_argument

parser: uwsgi_opt_set_str

help: bind the pty server on the specified address

pty-log

argument: no_argument

parser: uwsgi_opt_true

help: send stdout/stderr to the log engine too

pty-input

argument: no_argument

parser: uwsgi_opt_true

help: read from original stdin in addition to pty

pty-connect

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_NO_INITIAL

help: connect the current terminal to a pty server

pty-uconnect

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_NO_INITIAL

help: connect the current terminal to a pty server (using uwsgi protocol)

pty-no-isig

argument: no_argument

parser: uwsgi_opt_true

help: disable ISIG terminal attribute in client mode

pty-exec

argument: required_argument

parser: uwsgi_opt_set_str

help: run the specified command soon after the pty thread is spawned

plugin: pypy

pypy-lib

argument: required_argument

parser: uwsgi_opt_set_str

help: set the path/name of the pypy library

pypy-setup

argument: required_argument

parser: uwsgi_opt_set_str

help: set the path of the python setup script

pypy-home

argument: required_argument

parser: uwsgi_opt_set_str

help: set the home of pypy library

pypy-wsgi

argument: required_argument

parser: uwsgi_opt_set_str

help: load a WSGI module

pypy-wsgi-file

argument: required_argument

parser: uwsgi_opt_set_str

help: load a WSGI/mod_wsgi file

pypy-ini-paste

argument: required_argument

parser: uwsgi_opt_pypy_ini_paste

flags: UWSGI_OPT_IMMEDIATE

help: load a paste.deploy config file containing uwsgi section

pypy-paste

argument: required_argument

parser: uwsgi_opt_set_str

help: load a paste.deploy config file

pypy-eval

argument: required_argument

parser: uwsgi_opt_add_string_list

help: evaluate pypy code before fork()

pypy-eval-post-fork

argument: required_argument

parser: uwsgi_opt_add_string_list

help: evaluate pypy code soon after fork()

pypy-exec

argument: required_argument

parser: uwsgi_opt_add_string_list

help: execute pypy code from file before fork()

pypy-exec-post-fork

argument: required_argument

parser: uwsgi_opt_add_string_list

help: execute pypy code from file soon after fork()

pypy-pp

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an item to the pythonpath

pypy-python-path

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an item to the pythonpath

pypy-pythonpath

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add an item to the pythonpath

plugin: python

wsgi-file

argument: required_argument

parser: uwsgi_opt_set_str

help: load .wsgi file

file

argument: required_argument

parser: uwsgi_opt_set_str

help: load .wsgi file

eval

argument: required_argument

parser: uwsgi_opt_set_str

help: eval python code

module

argument: required_argument

shortcut: -w

parser: uwsgi_opt_set_str

help: load a WSGI module

wsgi

argument: required_argument

shortcut: -w

parser: uwsgi_opt_set_str

help: load a WSGI module

callable

argument: required_argument

parser: uwsgi_opt_set_str

help: set default WSGI callable name

test

argument: required_argument

shortcut: -J

parser: uwsgi_opt_set_str

help: test a module import

home

argument: required_argument

shortcut: -H

parser: uwsgi_opt_set_str

help: set PYTHONHOME/virtualenv

virtualenv

argument: required_argument

shortcut: -H

parser: uwsgi_opt_set_str

help: set PYTHONHOME/virtualenv

venv

argument: required_argument

shortcut: -H

parser: uwsgi_opt_set_str

help: set PYTHONHOME/virtualenv

pyhome

argument: required_argument

shortcut: -H

parser: uwsgi_opt_set_str

help: set PYTHONHOME/virtualenv

py-programname

argument: required_argument

parser: uwsgi_opt_set_str

help: set python program name

py-program-name

argument: required_argument

parser: uwsgi_opt_set_str

help: set python program name

pythonpath

argument: required_argument

parser: uwsgi_opt_pythonpath

help: add directory (or glob) to pythonpath

python-path

argument: required_argument

parser: uwsgi_opt_pythonpath

help: add directory (or glob) to pythonpath

pp

argument: required_argument

parser: uwsgi_opt_pythonpath

help: add directory (or glob) to pythonpath

pymodule-alias

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add a python alias module

post-pymodule-alias

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add a python module alias after uwsgi module initialization

import

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import a python module

pyimport

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import a python module

py-import

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import a python module

python-import

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import a python module

shared-import

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import a python module in all of the processes

shared-pyimport

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import a python module in all of the processes

shared-py-import

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import a python module in all of the processes

shared-python-import

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import a python module in all of the processes

pyargv

argument: required_argument

parser: uwsgi_opt_set_str

help: manually set sys.argv

optimize

argument: required_argument

shortcut: -O

parser: uwsgi_opt_set_int

help: set python optimization level

pecan

argument: required_argument

parser: uwsgi_opt_set_str

help: load a pecan config file

paste

argument: required_argument

parser: uwsgi_opt_set_str

help: load a paste.deploy config file

paste-logger

argument: no_argument

parser: uwsgi_opt_true

help: enable paste fileConfig logger

web3

argument: required_argument

parser: uwsgi_opt_set_str

help: load a web3 app

pump

argument: required_argument

parser: uwsgi_opt_set_str

help: load a pump app

wsgi-lite

argument: required_argument

parser: uwsgi_opt_set_str

help: load a wsgi-lite app

ini-paste

argument: required_argument

parser: uwsgi_opt_ini_paste

flags: UWSGI_OPT_IMMEDIATE

help: load a paste.deploy config file containing uwsgi section

ini-paste-logged

argument: required_argument

parser: uwsgi_opt_ini_paste

flags: UWSGI_OPT_IMMEDIATE

help: load a paste.deploy config file containing uwsgi section (load loggers too)

reload-os-env

argument: no_argument

parser: uwsgi_opt_true

help: force reload of os.environ at each request

no-site

argument: no_argument

parser: uwsgi_opt_true

help: do not import site module

pyshell

argument: optional_argument

parser: uwsgi_opt_pyshell

help: run an interactive python shell in the uWSGI environment

pyshell-oneshot

argument: optional_argument

parser: uwsgi_opt_pyshell

help: run an interactive python shell in the uWSGI environment (one-shot variant)

python

argument: required_argument

parser: uwsgi_opt_pyrun

help: run a python script in the uWSGI environment

py

argument: required_argument

parser: uwsgi_opt_pyrun

help: run a python script in the uWSGI environment

pyrun

argument: required_argument

parser: uwsgi_opt_pyrun

help: run a python script in the uWSGI environment

py-tracebacker

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_THREADS|UWSGI_OPT_MASTER

help: enable the uWSGI python tracebacker

py-auto-reload

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_THREADS|UWSGI_OPT_MASTER

help: monitor python modules mtime to trigger reload (use only in development)

py-autoreload

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_THREADS|UWSGI_OPT_MASTER

help: monitor python modules mtime to trigger reload (use only in development)

python-auto-reload

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_THREADS|UWSGI_OPT_MASTER

help: monitor python modules mtime to trigger reload (use only in development)

python-autoreload

argument: required_argument

parser: uwsgi_opt_set_int

flags: UWSGI_OPT_THREADS|UWSGI_OPT_MASTER

help: monitor python modules mtime to trigger reload (use only in development)

py-auto-reload-ignore

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_THREADS|UWSGI_OPT_MASTER

help: ignore the specified module during auto-reload scan (can be specified multiple times)

wsgi-env-behaviour

argument: required_argument

parser: uwsgi_opt_set_str

help: set the strategy for allocating/deallocating the WSGI env, can be: “cheat” or “holy”

reference: WSGI env behaviour policies

wsgi-env-behavior

argument: required_argument

parser: uwsgi_opt_set_str

help: set the strategy for allocating/deallocating the WSGI env, can be: “cheat” or “holy”

reference: WSGI env behaviour policies

start_response-nodelay

argument: no_argument

parser: uwsgi_opt_true

help: send WSGI http headers as soon as possible (PEP violation)

wsgi-strict

argument: no_argument

parser: uwsgi_opt_true

help: try to be fully PEP compliant disabling optimizations

wsgi-accept-buffer

argument: no_argument

parser: uwsgi_opt_true

help: accept CPython buffer-compliant objects as WSGI response in addition to string/bytes

wsgi-accept-buffers

argument: no_argument

parser: uwsgi_opt_true

help: accept CPython buffer-compliant objects as WSGI response in addition to string/bytes

python-version

argument: no_argument

parser: uwsgi_opt_pyver

flags: UWSGI_OPT_IMMEDIATE

help: report python version

python-raw

argument: required_argument

parser: uwsgi_opt_set_str

help: load a python file for managing raw requests

py-sharedarea

argument: required_argument

parser: uwsgi_opt_add_string_list

help: create a sharedarea from a python bytearray object of the specified size

py-call-osafterfork

argument: no_argument

parser: uwsgi_opt_true

help: enable child processes running cpython to trap OS signals

early-python

argument: no_argument

parser: uwsgi_early_python

flags: UWSGI_OPT_IMMEDIATE

help: load the python VM as soon as possible (useful for the fork server)

early-pyimport

argument: required_argument

parser: uwsgi_early_python_import

flags: UWSGI_OPT_IMMEDIATE

help: import a python module in the early phase

early-python-import

argument: required_argument

parser: uwsgi_early_python_import

flags: UWSGI_OPT_IMMEDIATE

help: import a python module in the early phase

early-pythonpath

argument: required_argument

parser: uwsgi_opt_pythonpath

flags: UWSGI_OPT_IMMEDIATE

help: add directory (or glob) to pythonpath (immediate version)

early-python-path

argument: required_argument

parser: uwsgi_opt_pythonpath

flags: UWSGI_OPT_IMMEDIATE

help: add directory (or glob) to pythonpath (immediate version)

plugin: pyuwsgi

plugin: rack

rails

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_POST_BUFFERING

help: load a rails <= 2.x app

rack

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_POST_BUFFERING

help: load a rack app

ruby-gc-freq

argument: required_argument

parser: uwsgi_opt_set_int

help: set ruby GC frequency

rb-gc-freq

argument: required_argument

parser: uwsgi_opt_set_int

help: set ruby GC frequency

rb-lib

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add a directory to the ruby libdir search path

ruby-lib

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add a directory to the ruby libdir search path

rb-require

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import/require a ruby module/script

ruby-require

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import/require a ruby module/script

rbrequire

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import/require a ruby module/script

rubyrequire

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import/require a ruby module/script

require

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import/require a ruby module/script

shared-rb-require

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import/require a ruby module/script (shared)

shared-ruby-require

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import/require a ruby module/script (shared)

shared-rbrequire

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import/require a ruby module/script (shared)

shared-rubyrequire

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import/require a ruby module/script (shared)

shared-require

argument: required_argument

parser: uwsgi_opt_add_string_list

help: import/require a ruby module/script (shared)

gemset

argument: required_argument

parser: uwsgi_opt_set_str

help: load the specified gemset (rvm)

rvm

argument: required_argument

parser: uwsgi_opt_set_str

help: load the specified gemset (rvm)

rvm-path

argument: required_argument

parser: uwsgi_opt_add_string_list

help: search for rvm in the specified directory

rbshell

argument: optional_argument

parser: uwsgi_opt_rbshell

help: run a ruby/irb shell

rbshell-oneshot

argument: no_argument

parser: uwsgi_opt_rbshell

help: set ruby/irb shell (one shot)

plugin: rados

rados-mount

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: virtual mount the specified rados volume in a uri

rados-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: timeout for async operations

plugin: rawrouter

rawrouter

argument: required_argument

parser: uwsgi_opt_undeferred_corerouter

help: run the rawrouter on the specified port

rawrouter-processes

argument: required_argument

parser: uwsgi_opt_set_int

help: prefork the specified number of rawrouter processes

rawrouter-workers

argument: required_argument

parser: uwsgi_opt_set_int

help: prefork the specified number of rawrouter processes

rawrouter-zerg

argument: required_argument

parser: uwsgi_opt_corerouter_zerg

help: attach the rawrouter to a zerg server

rawrouter-use-cache

argument: optional_argument

parser: uwsgi_opt_set_str

help: use uWSGI cache as hostname->server mapper for the rawrouter

rawrouter-use-pattern

argument: required_argument

parser: uwsgi_opt_corerouter_use_pattern

help: use a pattern for rawrouter hostname->server mapping

rawrouter-use-base

argument: required_argument

parser: uwsgi_opt_corerouter_use_base

help: use a base dir for rawrouter hostname->server mapping

rawrouter-fallback

argument: required_argument

parser: uwsgi_opt_add_string_list

help: fallback to the specified node in case of error

rawrouter-use-code-string

argument: required_argument

parser: uwsgi_opt_corerouter_cs

help: use code string as hostname->server mapper for the rawrouter

rawrouter-use-socket

argument: optional_argument

parser: uwsgi_opt_corerouter_use_socket

help: forward request to the specified uwsgi socket

rawrouter-to

argument: required_argument

parser: uwsgi_opt_add_string_list

help: forward requests to the specified uwsgi server (you can specify it multiple times for load balancing)

rawrouter-gracetime

argument: required_argument

parser: uwsgi_opt_set_int

help: retry connections to dead static nodes after the specified amount of seconds

rawrouter-events

argument: required_argument

parser: uwsgi_opt_set_int

help: set the maximum number of concurrent events

rawrouter-max-retries

argument: required_argument

parser: uwsgi_opt_set_int

help: set the maximum number of retries/fallbacks to other nodes

rawrouter-quiet

argument: required_argument

parser: uwsgi_opt_true

help: do not report failed connections to instances

rawrouter-cheap

argument: no_argument

parser: uwsgi_opt_true

help: run the rawrouter in cheap mode

rawrouter-subscription-server

argument: required_argument

parser: uwsgi_opt_corerouter_ss

help: run the rawrouter subscription server on the spcified address

rawrouter-subscription-slot

argument: required_argument

parser: uwsgi_opt_deprecated

help: * deprecated *

rawrouter-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set rawrouter timeout

rawrouter-stats

argument: required_argument

parser: uwsgi_opt_set_str

help: run the rawrouter stats server

rawrouter-stats-server

argument: required_argument

parser: uwsgi_opt_set_str

help: run the rawrouter stats server

rawrouter-ss

argument: required_argument

parser: uwsgi_opt_set_str

help: run the rawrouter stats server

rawrouter-harakiri

argument: required_argument

parser: uwsgi_opt_set_int

help: enable rawrouter harakiri

rawrouter-xclient

argument: no_argument

parser: uwsgi_opt_true

help: use the xclient protocol to pass the client address

rawrouter-buffer-size

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set internal buffer size (default: page size)

plugin: rbthreads

rbthreads

argument: no_argument

parser: uwsgi_opt_true

help: enable ruby native threads

rb-threads

argument: no_argument

parser: uwsgi_opt_true

help: enable ruby native threads

rbthread

argument: no_argument

parser: uwsgi_opt_true

help: enable ruby native threads

rb-thread

argument: no_argument

parser: uwsgi_opt_true

help: enable ruby native threads

plugin: redislog

plugin: ring

ring-load

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load the specified clojure script

clojure-load

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load the specified clojure script

ring-app

argument: required_argument

parser: uwsgi_opt_set_str

help: map the specified ring application (syntax namespace:function)

plugin: router_access

plugin: router_basicauth

plugin: router_cache

plugin: router_expires

plugin: router_hash

plugin: router_http

plugin: router_memcached

plugin: router_metrics

plugin: router_radius

plugin: router_redirect

plugin: router_redis

plugin: router_rewrite

plugin: router_spnego

plugin: router_static

plugin: router_uwsgi

plugin: router_xmldir

plugin: rpc

plugin: rrdtool

rrdtool

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MASTER|UWSGI_OPT_METRICS

help: store rrd files in the specified directory

rrdtool-freq

argument: required_argument

parser: uwsgi_opt_set_int

help: set collect frequency

rrdtool-lib

argument: required_argument

parser: uwsgi_opt_set_str

help: set the name of rrd library (default: librrd.so)

plugin: rsyslog

rsyslog-packet-size

argument: required_argument

parser: uwsgi_opt_set_int

help: set maximum packet size for syslog messages (default 1024) WARNING! using packets > 1024 breaks RFC 3164 (#4.1)

rsyslog-split-messages

argument: no_argument

parser: uwsgi_opt_true

help: split big messages into multiple chunks if they are bigger than allowed packet size (default is false)

plugin: ruby19

plugin: servlet

plugin: signal

plugin: spooler

plugin: sqlite3

sqlite3

argument: required_argument

parser: uwsgi_opt_load_sqlite3

flags: UWSGI_OPT_IMMEDIATE

help: load config from sqlite3 db

sqlite

argument: required_argument

parser: uwsgi_opt_load_sqlite3

flags: UWSGI_OPT_IMMEDIATE

help: load config from sqlite3 db

plugin: ssi

plugin: sslrouter

sslrouter

argument: required_argument

parser: uwsgi_opt_sslrouter

help: run the sslrouter on the specified port

sslrouter2

argument: required_argument

parser: uwsgi_opt_sslrouter2

help: run the sslrouter on the specified port (key-value based)

sslrouter-session-context

argument: required_argument

parser: uwsgi_opt_set_str

help: set the session id context to the specified value

sslrouter-processes

argument: required_argument

parser: uwsgi_opt_set_int

help: prefork the specified number of sslrouter processes

sslrouter-workers

argument: required_argument

parser: uwsgi_opt_set_int

help: prefork the specified number of sslrouter processes

sslrouter-zerg

argument: required_argument

parser: uwsgi_opt_corerouter_zerg

help: attach the sslrouter to a zerg server

sslrouter-use-cache

argument: optional_argument

parser: uwsgi_opt_set_str

help: use uWSGI cache as hostname->server mapper for the sslrouter

sslrouter-use-pattern

argument: required_argument

parser: uwsgi_opt_corerouter_use_pattern

help: use a pattern for sslrouter hostname->server mapping

sslrouter-use-base

argument: required_argument

parser: uwsgi_opt_corerouter_use_base

help: use a base dir for sslrouter hostname->server mapping

sslrouter-fallback

argument: required_argument

parser: uwsgi_opt_add_string_list

help: fallback to the specified node in case of error

sslrouter-use-code-string

argument: required_argument

parser: uwsgi_opt_corerouter_cs

help: use code string as hostname->server mapper for the sslrouter

sslrouter-use-socket

argument: optional_argument

parser: uwsgi_opt_corerouter_use_socket

help: forward request to the specified uwsgi socket

sslrouter-to

argument: required_argument

parser: uwsgi_opt_add_string_list

help: forward requests to the specified uwsgi server (you can specify it multiple times for load balancing)

sslrouter-gracetime

argument: required_argument

parser: uwsgi_opt_set_int

help: retry connections to dead static nodes after the specified amount of seconds

sslrouter-events

argument: required_argument

parser: uwsgi_opt_set_int

help: set the maximum number of concurrent events

sslrouter-max-retries

argument: required_argument

parser: uwsgi_opt_set_int

help: set the maximum number of retries/fallbacks to other nodes

sslrouter-quiet

argument: required_argument

parser: uwsgi_opt_true

help: do not report failed connections to instances

sslrouter-cheap

argument: no_argument

parser: uwsgi_opt_true

help: run the sslrouter in cheap mode

sslrouter-subscription-server

argument: required_argument

parser: uwsgi_opt_corerouter_ss

help: run the sslrouter subscription server on the spcified address

sslrouter-timeout

argument: required_argument

parser: uwsgi_opt_set_int

help: set sslrouter timeout

sslrouter-stats

argument: required_argument

parser: uwsgi_opt_set_str

help: run the sslrouter stats server

sslrouter-stats-server

argument: required_argument

parser: uwsgi_opt_set_str

help: run the sslrouter stats server

sslrouter-ss

argument: required_argument

parser: uwsgi_opt_set_str

help: run the sslrouter stats server

sslrouter-harakiri

argument: required_argument

parser: uwsgi_opt_set_int

help: enable sslrouter harakiri

sslrouter-sni

argument: no_argument

parser: uwsgi_opt_true

help: use SNI to route requests

sslrouter-buffer-size

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set internal buffer size (default: page size)

plugin: stackless

stackless

argument: no_argument

parser: uwsgi_opt_true

help: use stackless as suspend engine

plugin: stats_pusher_file

plugin: stats_pusher_mongodb

plugin: stats_pusher_socket

plugin: stats_pusher_statsd

plugin: symcall

symcall

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load the specified C symbol as the symcall request handler (supports <mountpoint=func> too)

symcall-use-next

argument: no_argument

parser: uwsgi_opt_true

help: use RTLD_NEXT when searching for symbols

symcall-register-rpc

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load the specified C symbol as an RPC function (syntax: name function)

symcall-post-fork

argument: required_argument

parser: uwsgi_opt_add_string_list

help: call the specified C symbol after each fork()

plugin: syslog

plugin: systemd_logger

plugin: tornado

tornado

argument: required_argument

parser: uwsgi_opt_setup_tornado

flags: UWSGI_OPT_THREADS

help: a shortcut enabling tornado loop engine with the specified number of async cores and optimal parameters

plugin: transformation_chunked

plugin: transformation_gzip

plugin: transformation_offload

plugin: transformation_template

plugin: transformation_tofile

plugin: transformation_toupper

plugin: tuntap

tuntap-router

argument: required_argument

parser: uwsgi_opt_add_string_list

help: run the tuntap router (syntax: <device> <socket> [stats] [gateway])

tuntap-device

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add a tuntap device to the instance (syntax: <device>[ <socket>])

tuntap-use-credentials

argument: optional_argument

parser: uwsgi_opt_set_str

help: enable check of SCM_CREDENTIALS for tuntap client/server

tuntap-router-firewall-in

argument: required_argument

parser: uwsgi_tuntap_opt_firewall

help: add a firewall rule to the tuntap router (syntax: <action> <src/mask> <dst/mask>)

tuntap-router-firewall-out

argument: required_argument

parser: uwsgi_tuntap_opt_firewall

help: add a firewall rule to the tuntap router (syntax: <action> <src/mask> <dst/mask>)

tuntap-router-route

argument: required_argument

parser: uwsgi_tuntap_opt_route

help: add a routing rule to the tuntap router (syntax: <src/mask> <dst/mask> <gateway>)

tuntap-router-stats

argument: required_argument

parser: uwsgi_opt_set_str

help: run the tuntap router stats server

tuntap-device-rule

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add a tuntap device rule (syntax: <direction> <src/mask> <dst/mask> <action> [target])

plugin: ugreen

ugreen

argument: no_argument

parser: uwsgi_opt_true

help: enable ugreen coroutine subsystem

ugreen-stacksize

argument: required_argument

parser: uwsgi_opt_set_int

help: set ugreen stack size in pages

plugin: v8

v8-load

argument: required_argument

parser: uwsgi_opt_add_string_list

help: load a javascript file

v8-preemptive

argument: required_argument

parser: uwsgi_opt_set_int

help: put v8 in preemptive move (single isolate) with the specified frequency

v8-gc-freq

argument: required_argument

parser: uwsgi_opt_set_64bit

help: set the v8 garbage collection frequency

v8-module-path

argument: required_argument

parser: uwsgi_opt_add_string_list

help: set the v8 modules search path

v8-jsgi

argument: required_argument

parser: uwsgi_opt_set_str

help: load the specified JSGI 3.0 application

plugin: webdav

webdav-mount

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: map a filesystem directory as a webdav store

webdav-css

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a css url for automatic webdav directory listing

webdav-javascript

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a javascript url for automatic webdav directory listing

webdav-js

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a javascript url for automatic webdav directory listing

webdav-class-directory

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MIME

help: set the css directory class for automatic webdav directory listing

webdav-div

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MIME

help: set the div id for automatic webdav directory listing

webdav-lock-cache

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MIME

help: set the cache to use for webdav locking

webdav-principal-base

argument: required_argument

parser: uwsgi_opt_set_str

flags: UWSGI_OPT_MIME

help: enable WebDAV Current Principal Extension using the specified base

webdav-add-option

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV standard to the OPTIONS response

webdav-add-prop

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV property to all resources

webdav-add-collection-prop

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV property to all collections

webdav-add-object-prop

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV property to all objects

webdav-add-prop-href

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV property to all resources (href value)

webdav-add-collection-prop-href

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV property to all collections (href value)

webdav-add-object-prop-href

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV property to all objects (href value)

webdav-add-prop-comp

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV property to all resources (xml value)

webdav-add-collection-prop-comp

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV property to all collections (xml value)

webdav-add-object-prop-comp

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV property to all objects (xml value)

webdav-add-rtype-prop

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV resourcetype property to all resources

webdav-add-rtype-collection-prop

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV resourcetype property to all collections

webdav-add-rtype-object-prop

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: add a WebDAV resourcetype property to all objects

webdav-skip-prop

argument: required_argument

parser: uwsgi_opt_add_string_list

flags: UWSGI_OPT_MIME

help: do not add the specified prop if available in resource xattr

plugin: xattr

plugin: xslt

xslt-docroot

argument: required_argument

parser: uwsgi_opt_add_string_list

help: add a document_root for xslt processing

xslt-ext

argument: required_argument

parser: uwsgi_opt_add_string_list

help: search for xslt stylesheets with the specified extension

xslt-var

argument: required_argument

parser: uwsgi_opt_add_string_list

help: get the xslt stylesheet path from the specified request var

xslt-stylesheet

argument: required_argument

parser: uwsgi_opt_add_string_list

help: if no xslt stylesheet file can be found, use the specified one

xslt-content-type

argument: required_argument

parser: uwsgi_opt_set_str

help: set the content-type for the xslt rsult (default: text/html)

plugin: zabbix

zabbix-template

argument: optional_argument

parser: uwsgi_opt_zabbix_template

flags: UWSGI_OPT_METRICS

help: print (or store to a file) the zabbix template for the current metrics setup

plugin: zergpool

zergpool

argument: required_argument

parser: uwsgi_opt_add_string_list

help: start a zergpool on specified address for specified address

zerg-pool

argument: required_argument

parser: uwsgi_opt_add_string_list

help: start a zergpool on specified address for specified address

Defining new options for your instances

Sometimes the built-in options are not enough. For example, you may need to give your customers custom options for configuring their apps on your platform. Or you need to configure so many instances you want to simplify things such as per-datacenter or per-server-type options. Declaring new options for your config files/command-line is a good way of achieving these goals.

To define new options use --declare-option:

--declare-option <option_name>=<option1=value1>[;<option2=value2>;<option3=value3>...]

An useful example could be defining a “redirect” option, using the redirect plugin of the InternalRouting subsystem:

--declare-option "redirect=route=\$1 redirect:\$2"

This will declare a new option called redirect that takes 2 arguments. Those arguments will be expanded using the $-prefixed variables. Like shell scripts, the backslash is required to make your shell not expand these values.

Now you will be able to define a redirect in your config files:

uwsgi --declare-option "redirect=route=\$1 redirect:\$2" --ini config.ini

Config.ini:

[uwsgi]
socket = :3031
; define my redirects
redirect = ^/foo http://unbit.it
redirect = \.jpg$ http://uwsgi.it/test
redirect = ^/foo/bar/ /test

or directly on the command line:

uwsgi --declare-option "redirect=route=\$1 redirect:\$2" --socket :3031 --redirect "^/foo http://unbit.it" --redirect "\.jpg$ http://uwsgi.it/test" --redirect "^/foo/bar/ /test"

More fun: a bunch of shortcuts

Now we will define new options for frequently-used apps.

Shortcuts.ini:

[uwsgi]
; let's define a shortcut for trac (new syntax: trac=<path_to_trac_instance>)
declare-option = trac=plugin=python;env=TRAC_ENV=$1;module=trac.web.main:dispach_request
; one for web2py (new syntax: web2py=<path_to_web2_py_dir>)
declare-option = web2py=plugin=python;chdir=$1;module=wsgihandler
; another for flask (new syntax: flask=<path_to_your_app_entry_point>)
declare-option = flask=plugin=python;wsgi-file=$1;callable=app

To hook up a Trac instance on /var/www/trac/fooenv:

[uwsgi]
; include new shortcuts
ini = shortcuts.ini

; classic options
http = :8080
master = true
threads = 4

; our new option
trac = /var/www/trac/fooenv

A config for Web2py, in XML:

<uwsgi>
  <!-- import shortcuts -->
  <ini>shortcuts.ini</ini>
  <!-- run the https router with HIGH ciphers -->
  <https>:443,test.crt,test.key,HIGH</https>

  <master/>
  <processes>4</processes>

  <!-- load web2py from /var/www/we2py -->
  <web2py>/var/www/we2py</web2py>
</uwsgi>

A trick for the Emperor: automatically import shortcuts for your vassals

If you manage your customers/users with the Emperor, you can configure it to automatically import your shortcuts in each vassal.

uwsgi --emperor /etc/uwsgi/vassals --vassals-include /etc/uwsgi/shortcuts.ini

For multiple shortcuts use:

uwsgi --emperor /etc/uwsgi/vassals --vassals-include /etc/uwsgi/shortcuts.ini --vassals-include /etc/uwsgi/shortcuts2.ini --vassals-include /etc/uwsgi/shortcuts3.ini

Or (with a bit of configuration logic magic):

[uwsgi]
emperor = /etc/uwsgi/vassals

for = shortcuts shortcuts2 shortcuts3
  vassals-include = /etc/uwsgi/%(_).ini
endfor =

An advanced trick: embedding shortcuts in your uWSGI binary

uWSGI’s build system allows you to embed files, be they generic files or configuration, in the server binary. Abusing this feature will enable you to embed your new option shortcuts into the server binary, automagically allowing users to use them. To embed your shortcuts file, edit your build profile (like buildconf/base.ini) and set embed_config to the path of the shortcuts file. Rebuild your server and your new options will be available.

See also

BuildConf

How uWSGI parses config files

Until uWSGI 1.1 the parsing order has not been ‘stable’ or ‘reliable’.

Starting from uWSGI 1.1 (thanks to its new options subsystem) we have a general rule: top-bottom and expand asap.

Top-bottom means options are internally ordered as they are parsed, while “expand asap” means to inject the options of a requested config file, interrupting the currently parsed one:

Note that the inherit option behaves differently from the other include options: It is expanded after variable expansion, so any environment variables, external files and placeholders are not expanded. Magic variables (e.g. %n) are expanded normally.

file1.ini (the one requested from the command line)

[uwsgi]
socket = :3031
ini = file2.ini
socket = :3032
chdir = /var/www

file2.ini

[uwsgi]
master = true
memory-report = true
processes = 4

internally will be assembled in:

[uwsgi]
socket = :3031
ini = file2.ini
master = true
memory-report = true
processes = 4
socket = :3032
chdir = /var/www

A more complex example:

file1.ini (the one requested from the command line)

[uwsgi]
socket = :3031
ini = file2.ini
socket = :3032
chdir = /var/www

file2.ini

[uwsgi]
master = true
xml = file3.xml
memory-report = true
processes = 4

file3.xml

<uwsgi>
  <plugins>router_uwsgi</plugins>
  <route>^/foo uwsgi:127.0.0.1:4040,0,0</route>
</uwsgi>

will result in:

[uwsgi]
socket = :3031
ini = file2.ini
master = true
xml = file3.xml
plugins = router_uwsgi
route = ^/foo uwsgi:127.0.0.1:4040,0,0
memory-report = true
processes = 4
socket = :3032
chdir = /var/www

Expanding variables/placeholders

After the internal config tree is assembled, variables and placeholder substitution will be applied.

The first step is substituting all of the $(VALUE) occurrences with the value of the environment variable VALUE.

[uwsgi]
foobar = $(PATH)

foobar value will be the content of shell’s PATH variable

The second step will expand text files embraced in @(FILENAME)

[uwsgi]
nodename = @(/etc/hostname)

nodename value will be the content of /etc/hostname

The last step is placeholder substitution. A placeholder is a reference to another option:

[uwsgi]
socket = :3031
foobar = %(socket)

the content of foobar will be mapped to the content of socket.

A note on magic variables

Config files, support another form of variables, called ‘magic’ variables. As they refer to the config file itself, they will be parsed asap:

[uwsgi]
my_config_file = %p

The content of my_config_file will be set to %p value (the current file’s absolute path) as soon as it is parsed. That means %p (or whatever magic vars you need) will be always be consistent in the currently parsing config file.

uwsgi protocol magic variables

You can dynamically tune or configure various aspects of the uWSGI server using special variables passed by the web server (or in general by a uwsgi compliant client).

  • For Nginx, the uwsgi_param <name> <value>; directive is used.
  • For Apache, the SetEnv <name> <value> directive is used.

UWSGI_SCHEME

Set the URL scheme when it cannot be reliably determined. This may be used to force HTTPS (with the value https), for instance.

UWSGI_SCRIPT

Load the specified script as a new application mapped to SCRIPT_NAME. The app will obviously only be loaded once, not on each request.

uwsgi_param UWSGI_SCRIPT werkzeug.testapp:test_app;
uwsgi_param SCRIPT_NAME  /testapp;

UWSGI_MODULE and UWSGI_CALLABLE

Load a new app (defined as module:callable) mapped into SCRIPT_NAME.

uwsgi_param UWSGI_MODULE werkzeug.testapp;
uwsgi_param UWSGI_CALLABLE test_app;
uwsgi_param SCRIPT_NAME  /testapp;

UWSGI_PYHOME

Dynamically set the Python Virtualenv support for a dynamic application.

See also

DynamicVirtualenv

UWSGI_CHDIR

chdir() to the specified directory before managing the request.

UWSGI_FILE

Load the specified file as a new dynamic app.

UWSGI_TOUCH_RELOAD

Reload the uWSGI stack when the specified file’s modification time has changed since the last request.

location / {
  include uwsgi_params;
  uwsgi_param UWSGI_TOUCH_RELOAD /tmp/touchme.foo;
  uwsgi_pass /tmp/uwsgi.sock;
}

UWSGI_CACHE_GET

Check the uWSGI cache for a specified key. If the value is found, it will be returned as raw HTTP output instead of the usual processing of the request.

location / {
  include uwsgi_params;
  uwsgi_param UWSGI_CACHE_GET $request_uri;
  uwsgi_pass 127.0.0.1:3031;
}

UWSGI_SETENV

Set the specified environment variable for a new dynamic app.

Note

To allow this in Python applications you need to enable the reload-os-env uWSGI option.

Dynamically load a Django app without using a WSGI file/module:

location / {
  include uwsgi_params;
  uwsgi_param UWSGI_SCRIPT django.core.handlers.wsgi:WSGIHandler();
  uwsgi_param UWSGI_CHDIR /mydjangoapp_path;
  uwsgi_param UWSGI_SETENV DJANGO_SETTINGS_MODULE=myapp.settings;
}

UWSGI_APPID

Note

Available since 0.9.9.

Bypass SCRIPT_NAME and VirtualHosting to let the user choose the mountpoint without limitations (or headaches).

The concept is very generic: UWSGI_APPID is the identifier of an application. If it is not found in the internal list of apps, it will be loaded.

server {
    server_name server001;
    location / {
        include uwsgi_params;
        uwsgi_param UWSGI_APPID myfunnyapp;
        uwsgi_param UWSGI_FILE /var/www/app1.py
    }
}

server {
    server_name server002;
    location / {
        include uwsgi_params;
        uwsgi_param UWSGI_APPID myamazingapp;
        uwsgi_param UWSGI_FILE /var/www/app2.py
    }
}

The uwsgi Protocol

The uwsgi (lowercase!) protocol is the native protocol used by the uWSGI server.

It is a binary protocol that can carry any type of data. The first 4 bytes of a uwsgi packet describe the type of the data contained by the packet.

Every uwsgi request generates a response in the uwsgi format.

Even the web server handlers obey this rule, as an HTTP response is a valid uwsgi packet (look at the modifier1 = 72).

The protocol works mainly via TCP but the master process can bind to a UDP Unicast/Multicast for The embedded SNMP server or cluster management/messaging requests.

SCTP support is being worked on.

uwsgi packet header

struct uwsgi_packet_header {
    uint8_t modifier1;
    uint16_t datasize;
    uint8_t modifier2;
};

Unless otherwise specified the datasize value contains the size (16-bit little endian) of the packet body.

Packet descriptions

modifier1 datasize modifier2 packet type
0 size of WSGI block vars (HTTP request body excluded) 0 Standard WSGI request followed by the HTTP request body
1 reserved for UNBIT    
2 reserved for UNBIT    
3 reserved for UNBIT    
5 size of PSGI block vars (HTTP request body excluded) 0 Standard PSGI request followed by the HTTP request body
6 size of LUA WSAPI block vars (HTTP request body excluded) 0 Standard LUA/WSAPI request followed by the HTTP request body
7 size of RACK block vars (HTTP request body excluded) 0 Standard RACK request followed by the HTTP request body
8 size of JWSGI/Ring block vars (HTTP request body excluded) 0 Standard JVM request for The JWSGI interface and The Clojure/Ring JVM request handler followed by the HTTP request body
9 size of CGI block vars (HTTP request body excluded) 0 Standard Running CGI scripts on uWSGI request followed by the HTTP request body
10 size of block vars 0- 255 Management interface request: setup flag specified by modifier2. For a list of management flag look at ManagementFlag
14 size of CGI block vars (HTTP request body excluded) 0 Standard Running PHP scripts in uWSGI request followed by the HTTP request body
15 size of Mono ASP.NET block vars (HTTP request body excluded) 0 Standard The Mono ASP.NET plugin request followed by the HTTP request body
17 size of Spooler block vars 0- 255 The uWSGI Spooler request, the block vars is converted to a dictionary/hash/table and passed to the spooler callable. The second modifier is currently ignored.
18 size of CGI block vars 0-255 direct call to c-like symbols
22 size of code string 0- 255 Raw Code evaluation. The interpreter is chosen by the modifier2. 0 is Python, 5 is Perl. It does not return a valid uwsgi response, but a raw string (that may be an HTTP response)
23 size of CGI vars 0- 255 invoke the The XSLT plugin
24 size of CGI vars 0- 255 invoke the uWSGI V8 support
25 size of CGI vars 0- 255 invoke the The GridFS plugin
26 size of CGI vars 0- 255 invoke the The GlusterFS plugin
27 0 0- 255 call the FastFuncs specified by the modifier2 field
28 0 0- 255 invoke the The RADOS plugin
30 size of WSGI block vars (HTTP request body excluded) 0 (if defined the size of the block vars is 24bit le, for now none of the webserver handlers support this feature) Standard WSGI request followed by the HTTP request body. The PATH_INFO is automatically modified, removing the SCRIPT_NAME from it
31 size of block vars 0- 255 Generic message passing (reserved)
32 size of char array 0- 255 array of char passing (reserved)
33 size of marshal object 0- 255 marshalled/serialzed object passing (reserved)
48 snmp specific snmp specific identify a SNMP request/response (mainly via UDP)
72 chr(TT) chr(P) Corresponds to the ‘HTTP’ string and signals that this is a raw HTTP response.
73 announce message size (for sanity check) announce type (0 = hostname) announce message
74 multicast message size (for sanity check) 0 array of chars; a custom multicast message managed by uwsgi.multicast_manager
95 cluster membership dict size action add/remove/enable/disable node from a cluster. Action may be 0 = add, 1 = remove, 2 = enable, 3 = disable. Add action requires a dict of at least 3 keys: hostname, address and workers
96 log message size 0 Remote logging (clustering/multicast/unicast)
97 0 0, 1 brutal reload request (0 request - 1 confirmation)
98 0 0, 1 graceful reload request (0 request - 1 confirmation)
99 size of options dictionary (if response) 0, 1 request configuration data from a uwsgi node (even via multicast)
100 0 0, 1 PING- PONG if modifier2 is 0 it is a PING request otherwise it is a PONG (a response). Useful for cluster health- check
101 size of packet 0 ECHO service
109 size of clean payload 0 to 255 legion msg (UDP, the body is encrypted)
110 size of payload 0 to 255 uwsgi_signal framework (payload is optional), modifier2 is the signal num
111 size of packet 0, 1, 2, 3 Cache operations. 0: read, 1: write, 2: delete, 3: dict_based
123 size of packet
special modifier for signaling corerouters about special conditions
173 size of packet 0, 1 RPC. The packet is an uwsgi array where the first item is the name of the function and the following are the args (if modifier2 is 1 the RPC will be ‘raw’ and all of the response will be returned to the app, uwsgi header included, if available.
200 0 0 Close mark for persistent connections
224 size of packet 0 Subscription packet. see SubscriptionServer
255 0 0- 255 Generic response. Request dependent. For example a spooler response set 0 for a failed spool or 1 for a successful one

The uwsgi vars

The uwsgi block vars represent a dictionary/hash. Every key-value is encoded in this way:

struct uwsgi_var {
    uint16_t key_size;
    uint8_t key[key_size];
    uint16_t val_size;
    uint8_t val[val_size];
}

Managing external daemons/services

uWSGI can easily monitor external processes, allowing you to increase reliability and usability of your multi-tier apps. For example you can manage services like Memcached, Redis, Celery, Ruby delayed_job or even dedicated PostgreSQL instances.

Kinds of services

Currently uWSGI supports 3 categories of processes:

  • --attach-daemon – directly attached non daemonized processes
  • --smart-attach-daemon – pidfile governed (both foreground and daemonized)
  • --smart-attach-daemon2 – pidfile governed with daemonization management

The first category allows you to directly attach processes to the uWSGI master. When the master dies or is reloaded these processes are destroyed. This is the best choice for services that must be flushed whenever the app is restarted.

Pidfile governed processes can survive death or reload of the master so long as their pidfiles are available and the pid contained therein matches a running pid. This is the best choice for processes requiring longer persistence, and for which a brutal kill could mean loss of data such as a database.

The last category is a superset of the second one. If your process does not support daemonization or writing to pidfile, you can let the master do the management. Very few daemons/applications require this feature, but it could be useful for tiny prototype applications or simply poorly designed ones.

Since uWSGI 2.0 a fourth option, --attach-daemon2 has been added for advanced configurations (see below).

Examples

Managing a memcached instance in ‘dumb’ mode. Whenever uWSGI is stopped or reloaded, memcached is destroyed.

[uwsgi]
master = true
socket = :3031
attach-daemon = memcached -p 11311 -u roberto

Managing a memcached instance in ‘smart’ mode. Memcached survives uWSGI stop and reload.

[uwsgi]
master = true
socket = :3031
smart-attach-daemon = /tmp/memcached.pid memcached -p 11311 -d -P /tmp/memcached.pid -u roberto

Managing 2 mongodb instances in smart mode:

[uwsgi]
master = true
socket = :3031
smart-attach-daemon = /tmp/mongo1.pid mongod --pidfilepath /tmp/mongo1.pid --dbpath foo1 --port 50001
smart-attach-daemon = /tmp/mongo2.pid mongod --pidfilepath /tmp/mongo2.pid --dbpath foo2 --port 50002

Managing PostgreSQL dedicated-instance (cluster in /db/foobar1):

[uwsgi]
master = true
socket = :3031
smart-attach-daemon = /db/foobar1/postmaster.pid /usr/lib/postgresql/9.1/bin/postgres -D /db/foobar1

Managing celery:

[uwsgi]
master = true
socket = :3031
smart-attach-daemon = /tmp/celery.pid celery -A tasks worker --pidfile=/tmp/celery.pid

Managing delayed_job:

[uwsgi]
master = true
socket = :3031
env = RAILS_ENV=production
rbrequire = bundler/setup
rack = config.ru
chdir = /var/apps/foobar
smart-attach-daemon = %(chdir)/tmp/pids/delayed_job.pid %(chdir)/script/delayed_job start

Managing dropbear:

[uwsgi]
namespace = /ns/001/:testns
namespace-keep-mount = /dev/pts
socket = :3031
exec-as-root = chown -R www-data /etc/dropbear
attach-daemon = /usr/sbin/dropbear -j -k -p 1022 -E -F -I 300

When using the namespace option you can attach a dropbear daemon to allow direct access to the system inside the specified namespace. This requires the /dev/pts filesystem to be mounted inside the namespace, and the user your workers will be running as have access to the /etc/dropbear directory inside the namespace.

Legion support

Starting with uWSGI 1.9.9 it’s possible to use the The uWSGI Legion subsystem subsystem for daemon management. Legion daemons will be executed only on the legion lord node, so there will always be a single daemon instance running in each legion. Once the lord dies a daemon will be spawned on another node. To add a legion daemon use –legion-attach-daemon, –legion-smart-attach-daemon and –legion-smart-attach-daemon2 options, they have the same syntax as normal daemon options. The difference is the need to add legion name as first argument.

Example:

Managing celery beat:

[uwsgi]
master = true
socket = :3031
legion-mcast = mylegion 225.1.1.1:9191 90 bf-cbc:mysecret
legion-smart-attach-daemon = mylegion /tmp/celery-beat.pid celery beat --pidfile=/tmp/celery-beat.pid

–attach-daemon2

This option has been added in uWSGI 2.0 and allows advanced configurations. It is a keyval option, and it accepts the following keys:

  • command/cmd/exec: the command line to execute
  • freq: maximum attempts before considering a daemon “broken”
  • pidfile: the pidfile to check (enable smart mode)
  • control: if set, the daemon becomes a ‘control’ one: if it dies the whole uWSGI instance dies
  • daemonize/daemon: daemonize the process (enable smart2 mode)
  • touch semicolon separated list of files to check: whenever they are ‘touched’, the daemon is restarted
  • stopsignal/stop_signal: the signal number to send to the daemon when uWSGI is stopped
  • reloadsignal/reload_signal: the signal to send to the daemon when uWSGI is reloaded
  • stdin: if set the file descriptor zero is not remapped to /dev/null
  • uid: drop privileges to the specified uid (requires master running as root)
  • gid: drop privileges to the specified gid (requires master running as root)
  • ns_pid: spawn the process in a new pid namespace (requires master running as root, Linux only)
  • chdir: chdir() to the specified directory before running the command (added in uWSGI 2.0.6)

Example:

[uwsgi]
attach-daemon2 = cmd=my_daemon.sh,pidfile=/tmp/my.pid,uid=33,gid=33,stopsignal=3

The Master FIFO

Available from uWSGI 1.9.17.

Generally you use UNIX signals to manage the master, but we are running out of signal numbers and (more importantly) not needing to mess with PIDs greatly simplifies the implementation of external management scripts.

So, instead of signals, you can tell the master to create a UNIX named pipe (FIFO) that you may use to issue commands to the master.

To create a FIFO just add --master-fifo <filename> then start issuing commands to it.

echo r > /tmp/yourfifo

You can send multiple commands in one shot.

# add 3 workers and print stats
echo +++s > /tmp/yourfifo

Available commands

  • ‘0’ to ‘9’ - set the fifo slot (see below)
  • ‘+’ - increase the number of workers when in cheaper mode (add --cheaper-algo manual for full control)
  • ‘-‘ - decrease the number of workers when in cheaper mode (add --cheaper-algo manual for full control)
  • ‘B’ - ask Emperor for reinforcement (broodlord mode, requires uWSGI >= 2.0.7)
  • ‘C’ - set cheap mode
  • ‘c’ - trigger chain reload
  • ‘E’ - trigger an Emperor rescan
  • ‘f’ - re-fork the master (dangerous, but very powerful)
  • ‘l’ - reopen log file (need –log-master and –logto/–logto2)
  • ‘L’ - trigger log rotation (need –log-master and –logto/–logto2)
  • ‘p’ - pause/resume the instance
  • ‘P’ - update pidfiles (can be useful after master re-fork)
  • ‘Q’ - brutally shutdown the instance
  • ‘q’ - gracefully shutdown the instance
  • ‘R’ - send brutal reload
  • ‘r’ - send graceful reload
  • ‘S’ - block/unblock subscriptions
  • ‘s’ - print stats in the logs
  • ‘W’ - brutally reload workers
  • ‘w’ - gracefully reload workers

FIFO slots

uWSGI supports up to 10 different FIFO files. By default the first specified is bound (mapped as ‘0’).

During the instance’s lifetime you can change from one FIFO to another by simply sending the number of the FIFO slot to use.

[uwsgi]
master-fifo = /tmp/fifo0
master-fifo = /tmp/fifo1
master-fifo = /var/run/foofifo
processes = 2
...

By default /tmp/fifo0 will be allocated, but after sending:

echo 1 > /tmp/fifo0

the /tmp/fifo1 file will be bound.

This is very useful to map FIFO files to specific instance when you (ab)use the ‘fork the master’ command (the ‘f’ one).

echo 1fp > /tmp/fifo0

After sending this command, a new uWSGI instance (inheriting all of the bound sockets) will be spawned, the old one will be put in “paused” mode (the ‘p’ command).

As we have sent the ‘1’ command before ‘f’ and ‘p’ the old instance will now accept commands on /tmp/fifo1 (the slot 1), and the new one will use the default one (‘0’).

There are lot of tricks you can accomplish, and lots of ways to abuse the forking of the master.

Just take into account that corner-case problems can occur all over the place, especially if you use the most complex features of uWSGI.

Notes

  • The FIFO is created in non-blocking modes and recreated by the master every time a client disconnects.
  • You can override (or add) commands using the global array uwsgi_fifo_table via plugins or C hooks.
  • Only the uid running the master has write access to the fifo.

Socket activation with inetd/xinetd

Inetd and Xinetd are two daemons used to start network processes on demand. You can use this in uWSGI too.

Inetd

127.0.0.1:3031 stream tcp wait root /usr/bin/uwsgi uwsgi -M -p 4 --wsgi-file /root/uwsgi/welcome.py --log-syslog=uwsgi

With this config you will run uWSGI on port 3031 as soon as the first connection is made. Note: the first argument (the one soon after /usr/bin/uwsgi) is mapped to argv[0]. Do not forget this – always set it to uwsgi if you want to be sure.

Xinetd

service uwsgi
    {
            disable         = no
            id              = uwsgi-000
            type            = UNLISTED
            socket_type     = stream
            server          = /root/uwsgi/uwsgi
            server_args     = --chdir /root/uwsgi/ --module welcome --logto /tmp/uwsgi.log
            port            = 3031
            bind            = 127.0.0.1
            user            = root
            wait            = yes
    }

Again, you do not need to specify the socket in uWSGI, as it will be passed to the server by xinetd.

Running uWSGI via Upstart

Upstart is the init system of Ubuntu-like distributions.

It is based on declarative configuration files – not shell scripts of yore – that are put in the /etc/init directory.

A simple script (/etc/init/uwsgi.conf)

# simple uWSGI script

description "uwsgi tiny instance"
start on runlevel [2345]
stop on runlevel [06]

respawn

exec uwsgi --master --processes 4 --die-on-term --socket :3031 --wsgi-file /var/www/myapp.wsgi

Using the Emperor

A better approach than init files for each app would be to only start an Emperor via Upstart and let it deal with the rest.

# Emperor uWSGI script

description "uWSGI Emperor"
start on runlevel [2345]
stop on runlevel [06]

respawn

exec uwsgi --emperor /etc/uwsgi

If you want to run the Emperor under the master process (for accessing advanced features) remember to add –die-on-term

# Emperor uWSGI script

description "uWSGI Emperor"
start on runlevel [2345]
stop on runlevel [06]

respawn

exec uwsgi --master --die-on-term --emperor /etc/uwsgi

What is –die-on-term?

By default uWSGI maps the SIGTERM signal to “a brutal reload procedure”.

However, Upstart uses SIGTERM to completely shutdown processes. die-on-term inverts the meanings of SIGTERM and SIGQUIT to uWSGI.

The first will shutdown the whole stack, the second one will brutally reload it.

Socket activation (from Ubuntu 12.04)

Newer Upstart releases have an Inetd-like feature that lets processes start when connections are made to specific sockets.

You can use this feature to start uWSGI only when a client (or the webserver) first connects to it.

The ‘start on socket’ directive will trigger the behaviour.

You do not need to specify the socket in uWSGI as it will be passed to it by Upstart itself.

# simple uWSGI script

description "uwsgi tiny instance"
start on socket PROTO=inet PORT=3031
stop on runlevel [06]

respawn

exec uwsgi --master --processes 4 --die-on-term --wsgi-file /var/www/myapp.wsgi

Systemd

uWSGI is a new-style daemon for systemd.

It can notify status change and readyness.

When uWSGI detects it is running under systemd, the notification system is enabled.

Adding the Emperor to systemd

One approach to integrate uWSGI apps with your init system is using the Emperor.

Your init system will talk only with the Emperor that will rule all of the apps itself.

Create a systemd service file (you can save it as /etc/systemd/system/emperor.uwsgi.service)

Note

Be careful with some systemd versions (e.g. 215 in Debian Jessie), since SIGQUIT signal will trash the systemd services. Use KillSignal=SIGTERM + “die-on-term” UWSGI option there.

[Unit]
Description=uWSGI Emperor
After=syslog.target

[Service]
ExecStart=/root/uwsgi/uwsgi --ini /etc/uwsgi/emperor.ini
# Requires systemd version 211 or newer
RuntimeDirectory=uwsgi
Restart=always
KillSignal=SIGQUIT
Type=notify
StandardError=syslog
NotifyAccess=all

[Install]
WantedBy=multi-user.target

Then run it

systemctl start emperor.uwsgi.service

And check its status.

systemctl status emperor.uwsgi.service

You will see the Emperor reporting the number of governed vassals to systemd (and to you).

emperor.uwsgi.service - uWSGI Emperor
 Loaded: loaded (/etc/systemd/system/emperor.uwsgi.service)
       Active: active (running) since Tue, 17 May 2011 08:51:31 +0200; 5s ago
Main PID: 30567 (uwsgi)
       Status: "The Emperor is governing 1 vassals"
       CGroup: name=systemd:/system/emperor.uwsgi.service
               ├ 30567 /root/uwsgi/uwsgi --ini /etc/uwsgi/emperor.ini
               ├ 30568 /root/uwsgi/uwsgi --ini werkzeug.ini
               └ 30569 /root/uwsgi/uwsgi --ini werkzeug.ini

You can stop the Emperor (and all the apps it governs) with

systemctl stop emperor.uwsgi.service

A simple emperor.ini could look like this (www-data is just an anonymous user)

NOTE: DO NOT daemonize the Emperor (or the master) unless you know what you are doing!!!

[uwsgi]
emperor = /etc/uwsgi/vassals
uid = www-data
gid = www-data

If you want to allow each vassal to run under different privileges, remove the uid and gid options from the emperor configuration (and please read the Emperor docs!)

Logging

Using the previous service file all of the Emperor messages go to the syslog. You can avoid it by removing the StandardError=syslog directive.

If you do that, be sure to set a --logto option in your Emperor configuration, otherwise all of your logs will be lost!

Putting sockets in /run/

On a modern system, /run/ is mounted as a tmpfs and is the right place to put sockets and pidfiles into. To have systemd automatically create a /run/uwsgi/ subdirectory with the correct user/group ownership, as well as cleaning up the directory when the daemon is stopped, add

RuntimeDirectory=uwsgi

to the [Service] section of your systemd uwsgi unit file. This RuntimeDirectory parameter requires systemd version 211 or newer. For older versions of systemd, create a systemd-tmpfiles configuration file (you can save it as /etc/tmpfiles.d/emperor.uwsgi.conf):

d /run/uwsgi 0755 www-data www-data -

Socket activation

Starting from uWSGI 0.9.8.3 socket activation is available. You can setup systemd to spawn uWSGI instances only after the first socket connection.

Create the required emperor.uwsgi.socket (in /etc/systemd/system/emperor.uwsgi.socket). Note that the *.socket file name must match the *.service file name.

[Unit]
Description=Socket for uWSGI Emperor

[Socket]
# Change this to your uwsgi application port or unix socket location
ListenStream=/tmp/uwsgid.sock

[Install]
WantedBy=sockets.target

Then disable the service and enable the socket unit.

# systemctl disable emperor.uwsgi.service
# systemctl enable emperor.uwsgi.socket

When using Systemd socket activation, you do not need to specify any socket in your uWSGI configuration; the instance will inherit the socket from Systemd.

To have uWSGI serve HTTP (instead of the binary uwsgi protocol) under Systemd socket activation, set protocol to http; for instance, in an INI, do this:

[uwsgi]
protocol = http
wsgi = ...
...

One service per app in systemd

Another approach is to let systemd handle starting individual apps while taking advantage of systemd template unit files, and of course socket activation. Each app will run under its own user.

/etc/systemd/system/uwsgi-app@.socket:

[Unit]
Description=Socket for uWSGI app %i

[Socket]
ListenStream=/var/run/uwsgi/%i.socket
SocketUser=www-%i
SocketGroup=www-data
SocketMode=0660

[Install]
WantedBy=sockets.target

/etc/systemd/system/uwsgi-app@.service:

[Unit]
Description=%i uWSGI app
After=syslog.target

[Service]
ExecStart=/usr/bin/uwsgi \
        --ini /etc/uwsgi/apps-available/%i.ini \
        --socket /var/run/uwsgi/%i.socket
User=www-%i
Group=www-data
Restart=on-failure
KillSignal=SIGQUIT
Type=notify
StandardError=syslog
NotifyAccess=all

Now, adding a new app to your system is a matter of creating the appropriate user and enabling the socket and the service. For instance, if one were to configure cgit:

adduser www-cgit --disabled-login --disabled-password \
  --ingroup www-data --home /var/lib/www/cgit --shell /bin/false
systemctl enable uwsgi-app@cgit.socket
systemctl enable uwsgi-app@cgit.service
systemctl start uwsgi-app@cgit.socket

Then configure the ini file /etc/uwsgi/apps-available/cgit.ini:

[uwsgi]
master = True
cheap = True
idle = 600
die-on-idle = True # If app is not used often, it will exit and be launched
                   # again by systemd requested by users.

manage-script-name = True

plugins = 0:cgi
cgi = /usr/lib/cgit/cgit.cgi

And last, if applicable, configure your HTTP server the usual way.

Running uWSGI instances with Circus

Circus (https://circus.readthedocs.io/en/0.7/) is a process manager written in Python. It is very similar to projects like Supervisor, but with several additional features. Although most, if not all, of it’s functionalities have a counterpart in uWSGI, Circus can be used as a library allowing you to build dynamic configurations (and extend uWSGI patterns). This aspect is very important and may be the real selling point of Circus.

Socket activation

Based on the venerable inetd pattern, Circus can bind to sockets and pass them to children.

Start with a simple Circus config (call it circus.ini):

[circus]
endpoint = tcp://127.0.0.1:5555
pubsub_endpoint = tcp://127.0.0.1:5556
stats_endpoint = tcp://127.0.0.1:5557

[watcher:dummy]
cmd = uwsgi --http-socket fd://$(circus.sockets.foo) --wsgi-file yourapp.wsgi
use_sockets = True
send_hup = True
stop_signal = QUIT

[socket:foo]
host = 0.0.0.0
port = 8888

run it with

circusd circus.ini

(Better) Socket activation

If you want to spawn instances on demand, you will likely want to shut them down when they are no longer used. To accomplish that use the –idle uWSGI option.

[circus]
check_delay = 5
endpoint = tcp://127.0.0.1:5555
pubsub_endpoint = tcp://127.0.0.1:5556
stats_endpoint = tcp://127.0.0.1:5557

[watcher:dummy]
cmd = uwsgi --master --idle 60 --http-socket fd://$(circus.sockets.foo) --wsgi-file yourapp.wsgi
use_sockets = True
warmup_delay = 0
send_hup = True
stop_signal = QUIT

[socket:foo]
host = 0.0.0.0
port = 8888

This time we have enabled the master process. It will manage the –idle option, shutting down the instance if it is inactive for more than 60 seconds.

Embedding an application in uWSGI

Starting from uWSGI 0.9.8.2, you can embed files in the server binary. These can be any file type, including configuration files. You can embed directories too, so by hooking the Python module loader you can transparently import packages, too. In this example we’ll be embedding a full Flask project.

Step 1: creating the build profile

We’re assuming you have your uWSGI source at the ready.

In the buildconf directory, define your profile – let’s call it flask.ini:

[uwsgi]
inherit = base
main_plugin = python
bin_name = myapp
embed_files = bootstrap.py,myapp.py

myapp.py is a simple flask app.

from flask import Flask
app = Flask(__name__)
app.debug = True

@app.route('/')
def index():
    return "Hello World"

bootstrap.py is included in the source distribution. It will extend the python import subsystem to use files embedded in uWSGI.

Now compile your app-inclusive server. Files will be embedded as symbols in the executable. Dots and dashes, etc. in filenames are thus transformed to underscores.

python uwsgiconfig.py --build flask

As bin_name was myapp, you can now run

./myapp --socket :3031 --import sym://bootstrap_py --module myapp:app

The sym:// pseudoprotocol enables uWSGI to access the binary’s embedded symbols and data, in this case importing bootstrap.py directly from the binary image.

Step 2: embedding the config file

We want our binary to automatically load our Flask app without having to pass a long command line.

Let’s create the configuration – flaskconfig.ini:

[uwsgi]
socket = 127.0.0.1:3031
import = sym://bootstrap_py
module = myapp:app

And add it to the build profile as a config file.

[uwsgi]
inherit = default
bin_name = myapp
embed_files = bootstrap.py,myapp.py
embed_config = flaskconfig.ini

Then, after you rebuild the server

python uwsgiconfig.py --build flask

you can now simply launch

./myapp
# Remember that this new binary continues to be able to take parameters and config files:
./myapp --master --processes 4

Step 3: embedding flask itself

Now, we are ready to kick asses with uWSGI ninja awesomeness. We want a single binary embedding all of the Flask modules, including Werkzeug and Jinja2, Flask’s dependencies. We need to have these packages’ directories and then specify them in the build profile.

[uwsgi]
inherit = default
bin_name = myapp
embed_files = bootstrap.py,myapp.py,werkzeug=site-packages/werkzeug,jinja2=site-packages/jinja2,flask=site-packages/flask
embed_config = flaskconfig.ini

Note

This time we have used the form “name=directory” to force symbols to a specific names to avoid ending up with a clusterfuck like site_packages_flask___init___py.

Rebuild and re-run. We’re adding –no-site when running to show you that the embedded modules are being loaded.

python uwsgiconfig.py --build flask
./myapp --no-site --master --processes 4

Step 4: adding templates

Still not satisfied? WELL YOU SHOULDN’T BE.

[uwsgi]
inherit = default
bin_name = myapp
embed_files = bootstrap.py,myapp.py,werkzeug=site-packages/werkzeug,jinja2=site-packages/jinja2,flask=site-packages/flask,templates
embed_config = flaskconfig.ini

Templates will be added to the binary... but we’ll need to instruct Flask on how to load templates from the binary image by creating a custom Jinja2 template loader.

from flask import Flask, render_template
from flask.templating import DispatchingJinjaLoader

class SymTemplateLoader(DispatchingJinjaLoader):

    def symbolize(self, name):
        return name.replace('.','_').replace('/', '_').replace('-','_')

    def get_source(self, environment, template):
        try:
            import uwsgi
            source = uwsgi.embedded_data("templates_%s" % self.symbolize(template))
            return source, None, lambda: True
        except:
            pass
        return super(SymTemplateLoader, self).get_source(environment, template)

app = Flask(__name__)
app.debug = True

app.jinja_env.loader = SymTemplateLoader(app)

@app.route('/')
def index():
    return render_template('hello.html')

@app.route('/foo')
def foo():
    return render_template('bar/foo.html')

POW! BIFF! NINJA AWESOMENESS.

Logging

Basic logging

The most basic form of logging in uWSGI is writing requests, errors, and informational messages to stdout/stderr. This happens in the default configuration. The most basic form of log redirection is the --logto / --logto2 / --daemonize options which allow you to redirect logs to files.

Basic logging to files

To log to files instead of stdout/stderr, use --logto, or to simultaneously daemonize uWSGI, --daemonize.

./uwsgi -s :3031 -w simple_app --daemonize /tmp/mylog.log
./uwsgi -s :3031 -w simple_app --logto /tmp/mylog.log
# logto2 only opens the log file after privileges have been dropped to the specified uid/gid.
./uwsgi -s :3031 -w simple_app --uid 1001 --gid 1002 --logto2 /tmp/mylog.log

Basic logging (connected UDP mode)

With UDP logging you can centralize cluster logging or redirect the persistence of logs to another machine to offload disk I/O. UDP logging works in both daemonized and interactive modes. UDP logging operaties in connected-socket mode, so the UDP server must be available before uWSGI starts. For a more raw approach (working in unconnected mode) see the section on socket logging.

To enable connected UDP mode pass the address of a UDP server to the --daemonize/--logto option:

./uwsgi -s :3031 -w simple_app --daemonize 192.168.0.100:1717
./uwsgi -s :3031 -w simple_app --logto 192.168.0.100:1717

This will redirect all the stdout/stderr data to the UDP socket on 192.168.0.100, port 1717. Now you need an UDP server that will manage your UDP messages. You could use netcat, or even uWSGI:

nc -u -p 1717 -s 192.168.0.100 -l
./uwsgi --udp 192.168.0.100:1717

The second way is a bit more useful as it will print the source (ip:port) of every message. In case of multiple uWSGI server logging on the same UDP server it will allow you to recognize one server from another. Naturally you can write your own apps to manage/filter/save the logs received via udp.

Pluggable loggers

uWSGI also supports pluggable loggers, which allow you more flexibility on where and what to log. Depending on the configuration of your uWSGI build, some loggers may or may not be available. Some may require to be loaded as plugins. To find out what plugins are available in your build, invoke uWSGI with --logger-list. To set up a pluggable logger, use the --logger or --req-logger options. --logger will set up a logger for every message while --req-logger will set up a logger for request information messages.

This is the syntax:

--logger <plugin>[:options]
--logger "<name> <plugin>[:options]" # The quotes are only required on the command line -- config files don't use them

You may set up as many loggers as you like. Named plugins are used for log routing. A very simple example of split request/error logging using plain text files follows.

[uwsgi]
req-logger = file:/tmp/reqlog
logger = file:/tmp/errlog

Log routing

By default all log lines are sent to all declared loggers. If this is not what you want, you can use --log-route (and --log-req-route for request loggers) to specify a regular expression to route certain log messages to different destinations.

For instance:

[uwsgi]
logger = mylogger1 syslog
logger = theredisone redislog:127.0.0.1:6269
logger = theredistwo redislog:127.0.0.1:6270
logger = file:/tmp/foobar # This logger will log everything else, as it's not named
logger = internalservererror file:/tmp/errors
# ...
log-route = internalservererror (HTTP/1.\d 500)
log-route = mylogger1 uWSGI listen queue of socket .* full

This will log each 500 level error to /tmp/errors, while listen queue full errors will end up in /tmp/foobar. This is somewhat similar to the The uWSGI alarm subsystem (from 1.3), though alarms are usually heavier and should only be used for critical situations.

Logging to files

logfile plugin – embedded by default.

Logging to sockets

logsocket plugin – embedded by default.

You can log to an unconnected UNIX or UDP socket using --logger socket:... (or --log-socket ...).

uwsgi --socket :3031 --logger socket:/tmp/uwsgi.logsock

will send log entries to the Unix socket /tmp/uwsgi.logsock.

uwsgi --socket :3031 --logger socket:192.168.173.19:5050

will send log datagrams to the UDP address 192.168.173.19 on port 5050. You may also multicast logs to multiple log servers by passing the multicast address:

uwsgi --socket :3031 --logger socket:225.1.1.1:1717

Logging to syslog

syslog plugin – embedded by default

The syslog plugin routes logs to Unix standard syslog. You may pass an optional ID to send and the “facility” for the log entry.

uwsgi --socket :3031 --logger syslog:uwsgi1234

or

uwsgi --socket :3031 --logger syslog:uwsgi1234,local6

to send to the local6 facility

Logging to remote syslog

rsyslog plugin – embedded by default

The rsyslog plugin routes logs to Unix standard syslog residing on a remote server. In addtition to the address+port of the remote syslog server, you may pass an optional ID to send as the “facility” parameter for the log entry.

uwsgi --socket :3031 --logger rsyslog:12.34.56.78:12345,uwsgi1234

Redis logger

redislog plugin – embedded by default.

By default the redislog plugin will ‘publish’ each logline to a redis pub/sub queue. The logger plugin syntax is:

--logger redislog[:<host>,<command>,<prefix>]

By default host is mapped to 127.0.0.1:6379, command is mapped to “publish uwsgi” and prefix is empty. To publish to a queue called foobar, use redislog:127.0.0.1:6379,publish foobar. Redis logging is not limited to pub/sub. You could for instance push items into a list, as in the next example.

--logger redislog:/tmp/redis.sock,rpush foo,example.com

As error situations could cause the master to block while writing a log line to a remote server, it’s a good idea to use --threaded-logger to offload log writes to a secondary thread.

MongoDB logger

mongodblog plugin – embedded by default.

The logger syntax for MongoDB logging (mongodblog) is

--logger mongodblog[:<host>,<collection>,<node>]

Where host is the address of the MongoDB instance (default 127.0.0.1:27017), collection names the collection to write log lines into (default uwsgi.logs) and node is an identification string for the instance sending logs (default: server hostname).

--logger mongodblog

Will run the logger with default values, while

--logger mongodblog:127.0.0.1:9090,foo.bar

Will write logs to the mongodb server 127.0.0.1:9090 in the collection foo.bar using the default node name. As with the Redis logger, offloading log writes to a dedicated thread is a good choice.

[uwsgi]
threaded-logger = true
logger = mongodblog:127.0.0.1:27017,uwsgi.logs_of_foobar
# As usual, you could have multiple loggers:
# logger = mongodblog:192.168.173.22:27017,uwsgi.logs_of_foobar
socket = :3031

ZeroMQ logging

As with UDP logging you can centralize/distribute logging via ZeroMQ. Build your logger daemon using a ZMQ_PULL socket:

import zmq

ctx = zmq.Context()

puller = ctx.socket(zmq.PULL)
puller.bind("tcp://192.168.173.18:9191")

while True:
    message = puller.recv()
    print message,

Now run your uWSGI server:

uwsgi --logger zeromq:tcp://192.168.173.18:9191 --socket :3031 --module werkzeug.testapp:test_app

(--log-zeromq is an alias for this logger.)

Crypto logger (plugin)

If you host your applications on cloud services without persistent storage you may want to send your logs to external systems. However logs often contain sensitive information that should not be transferred in clear. The logcrypto plugin logger attempts to solve this issue by encrypting each log packet before sending it over UDP to a server able to decrypt it. The next example will send each log packet to a UDP server available at 192.168.173.22:1717 encrypting the text with the secret key ciaociao with Blowfish in CBC mode.

uwsgi --plugin logcrypto --logger crypto:addr=192.168.173.22:1717,algo=bf-cbc,secret=ciaociao -M -p 4 -s :3031

An example server is available at https://github.com/unbit/uwsgi/blob/master/contrib/cryptologger.rb

Graylog2 logger (plugin)

graylog2 plugin – not compiled by default.

This plugin will send logs to a Graylog2 server in Graylog2’s native GELF format.

uwsgi --plugin graylog2 --logger graylog2:127.0.0.1:1234,dsfargeg

Systemd logger (plugin)

systemd_logger plugin – not compiled by default.

This plugin will write log entries into the Systemd journal.

uwsgi --plugin systemd_logger --logger systemd

Writing your own logger plugins

This plugin, foolog.c will write your messages in the file specified with –logto/–daemonize with a simple prefix using vector IO.

#include <uwsgi.h>

ssize_t uwsgi_foolog_logger(struct uwsgi_logger *ul, char *message, size_t len) {

        struct iovec iov[2];

        iov[0].iov_base = "[foo] ";
        iov[0].iov_len = 6;

        iov[1].iov_base = message;
        iov[1].iov_len = len;

        return writev(uwsgi.original_log_fd, iov, 2);
}

void uwsgi_foolog_register() {
        uwsgi_register_logger("syslog", uwsgi_syslog_logger);
}

struct uwsgi_plugin foolog_plugin = {
    .name = "foolog",
    .on_load = uwsgi_foolog_register,
};

Formatting uWSGI requests logs

uWSGI has a --logformat option for building custom request loglines. The syntax is simple:

[uwsgi]
logformat = i am a logline reporting "%(method) %(uri) %(proto)" returning with status %(status)

All of the variables marked with %() are substituted u