Configuration Options

uWSGI and the various plugins it consists of is almost infinitely configurable.

There’s an exhaustive and exhausting list of all options below. Take a deep breath and don’t panic – the list below is long, but you don’t need to know everything to start using uWSGI.

Networking/sockets

socket, uwsgi-socket

Argument: string

Bind to the specified socket using default protocol (see protocol).

This option may be set with -s from the command line.

http-socket

Argument: string

Bind to the specified socket using HTTP.

fastcgi-socket

Argument: string

Bind to the specified socket using FastCGI.

protocol, socket-protocol

Argument: string

Force the specified protocol (uwsgi, http, fastcgi) for default sockets.

shared-socket

Argument: string

Create a shared socket for advanced jailing or IPC purposes.

Advanced option for plugin writers or special needs. Allows you to create a socket early in the server’s startup and use it after privileges drop or jailing. This can be used to bind to privileged (<1024) ports.

listen

Argument: number Default: 100

Set the socket listen queue size.

This option may be set with -l from the command line.

Every socket has an associated queue where request will be put waiting for a process to became ready to accept them. When this queue is full, requests will be rejected.

The maximum value is system/kernel dependent.

abstract-socket

Argument: no argument

Force UNIX socket into abstract mode (Linux only).

chmod-socket

Argument: optional string

Chmod socket.

This option may be set with -C from the command line.

UNIX sockets are filesystem objects that obey UNIX permissions like any other filesystem object. You can set the UNIX sockets’ permissions with this option if your webserver would otherwise have no access to the uWSGI socket. When used without a parameter, the permissions will be set to 666. Otherwise the specified chmod value will be used.

chown-socket

Argument: string

Chown UNIX sockets.

umask

Argument: string

Set UNIX socket umask.

freebind

Argument: no argument

Put socket in freebind mode (Linux only).

Allows binding to non-existent network addresses.

map-socket

Argument: string

Map sockets to specific workers.

This option may be declared multiple times.

As you can bind a uWSGI instance to multiple sockets, you can use this option to map specific workers to specific sockets to implement a sort of in-process Quality of Service scheme.

This will map workers 1, 2 and 3 to the first socket and 4 and 5 to the second one.

If you host multiple apps in the same uWSGI instance, you can easily dedicate resources to each of them.

zeromq, zmq, zeromq-socket, zmq-socket

Argument: string

Create a zeromq pub/sub pair.

udp

Argument: string

Run the udp server on the specified address.

Mainly useful for SNMP or shared UDP logging.

reuse-port

Argument: no argument

Enable REUSE_PORT flag on socket to allow multiple instances binding on the same address (BSD only).

http-socket-modifier1

Argument: number

Force the specified modifier1 when using HTTP protocol.

http-socket-modifier2

Argument: number

Force the specified modifier2 when using HTTP protocol.

fastcgi-nph-socket

Argument: add socket

Bind to the specified UNIX/TCP socket using FastCGI protocol (nph mode).

fastcgi-modifier1

Argument: number

Force the specified modifier1 when using FastCGI protocol.

fastcgi-modifier2

Argument: number

Force the specified modifier2 when using FastCGI protocol.

scgi-socket

Argument: add socket

Bind to the specified UNIX/TCP socket using SCGI protocol.

scgi-nph-socket

Argument: add socket

Bind to the specified UNIX/TCP socket using SCGI protocol (nph mode).

scgi-modifier1

Argument: number

Force the specified modifier1 when using SCGI protocol.

scgi-modifier2

Argument: number

Force the specified modifier2 when using SCGI protocol.

undeferred-shared-socket

Argument: add shared socket

Create a shared socket for advanced jailing or ipc (undeferred mode).

raw-socket

Argument: add socket no defer

Bind to the specified UNIX/TCP socket using RAW protocol.

raw-modifier1

Argument: number

Force the specified modifier1 when using RAW protocol.

raw-modifier2

Argument: number

Force the specified modifier2 when using RAW protocol.

puwsgi-socket

Argument: add socket

Bind to the specified UNIX/TCP socket using persistent uwsgi protocol (puwsgi).

Process Management

workers, processes

Argument: number

Spawn the specified number of workers/processes.

This option may be set with -p from the command line.

Set the number of workers for preforking mode. This is the base for easy and safe concurrency in your app. More workers you add, more concurrent requests you can manage. Each worker corresponds to a system process, so it consumes memory, choose carefully the right number. You can easily drop your system to its knees by setting a too high value. Setting workers to a ridiculously high number will not magically make your application web scale – quite the contrary.

harakiri

Argument: number

Harakiri timeout in seconds.

Every request that will take longer than the seconds specified in the harakiri timeout will be dropped and the corresponding worker is thereafter recycled.

harakiri-verbose

Argument: no argument

Enable verbose Harakiri mode.

When a request is killed by Harakiri you will get a message in the uWSGI log. Enabling this option will print additional info (for example, the current syscall will be reported on Linux platforms).

harakiri-no-arh, no-harakiri-arh, no-harakiri-after-req-hook

Argument: no argument

Disallow Harakiri killings during after-request hook methods.

mule-harakiri

Argument: number

Set harakiri timeout for mule tasks.

master

Argument: no argument

Enable uWSGI master process.

This option may be set with -M from the command line.

reaper

Argument: no argument

Call waitpid(-1,...) after each request to get rid of zombies.

This option may be set with -r from the command line.

Enables reaper mode. After each request the server will call waitpid(-1) to get rid of zombie processes. If you spawn subprocesses in your app and you happen to end up with zombie processes all over the place you can enable this option. (It really would be better if you could fix your application’s process spawning usage though.)

max-requests

Argument: number

Reload workers after the specified amount of managed requests (avoid memory leaks).

This option may be set with -R from the command line.

When a worker reaches this number of requests it will get recycled (killed and restarted). You can use this option to “dumb fight” memory leaks. Also take a look at the reload-on-as and reload-on-rss options as they are more useful for memory leaks.

Beware: The default min-worker-lifetime 60 seconds takes priority over max-requests. Do not use with benchmarking as you’ll get stalls such as worker respawning too fast !!! i have to sleep a bit (2 seconds)...

min-worker-lifetime

Argument: number

A worker cannot be destroyed/reloaded unless it has been alive for N seconds (default 60). This is an anti-fork-bomb measure.

This option is available since version 1.9.

max-worker-lifetime

Argument: number

Reload workers after this many seconds. Disabled by default.

This option is available since version 1.9.

limit-as

Argument: number

Limit process address space (vsz) (in megabytes).

Limits the address space usage of each uWSGI (worker) process using POSIX/UNIX setrlimit(). For example, limit-as 256 will disallow uWSGI processes to grow over 256MB of address space. Address space is the virtual memory a process has access to. It does not correspond to physical memory. Read and understand this page before enabling this option: http://en.wikipedia.org/wiki/Virtual_memory

limit-nproc

Argument: number

Limit the number of spawnable processes.

reload-on-as

Argument: number

Reload a worker if its address space usage is higher than the specified value (in megabytes).

reload-on-rss

Argument: number

Reload a worker if its physical unshared memory is higher than the specified value (in megabytes).

evil-reload-on-as

Argument: number

Force the master to reload a worker if its address space is higher than specified megabytes (in megabytes).

evil-reload-on-rss

Argument: number

Force the master to reload a worker if its rss memory is higher than specified megabytes (in megabytes).

threads

Argument: number

Run each worker in prethreaded mode with the specified number of threads per worker.

thread-stacksize, threads-stacksize, thread-stack-size, threads-stack-size

Argument: number

Set threads stacksize.

check-interval

Argument: number Default: 1

Set the interval (in seconds) of master checks.

The master process makes a scan of subprocesses, etc. every N seconds. You can increase this time if you need to, but it’s DISCOURAGED.

Process Management - Emperor

emperor

Argument: string

Run as the Emperor, using the given configuration method.

This option may be declared multiple times.

emperor-freq

Argument: number Default: 3

Set the Emperor scanning frequency in seconds.

emperor-pidfile

Argument: string

Write the Emperor pid in the specified file.

emperor-tyrant

Argument: no argument

Put the Emperor in Tyrant (multi-user hosting) mode.

emperor-stats, emperor-stats-server

Argument: string

Run the imperial bureau of statistics on the given address:port.

early-emperor

Argument: no argument

Spawn the emperor before jailing and privilege dropping.

emperor-broodlord

Argument: number

Run the emperor in Broodlord mode.

emperor-throttle

Argument: number Default: 1000

Set throttling level (in milliseconds) for bad behaving vassals.

emperor-max-throttle

Argument: number Default: 180000

Set max throttling level (in milliseconds) for badly behaving vassals (default 3 minutes).

emperor-magic-exec

Argument: no argument

Prefix vassals config files with exec as s:// if they have the executable bit.

imperial-monitor-list, imperial-monitors-list

Argument: no argument

List enabled imperial monitors.

vassals-inherit

Argument: string

Add given config templates to vassals’ config.

This works by passing the inherit option when starting each vassal (which differs from the include option in that inherit will not replace placeholders etc.).

This option may be declared multiple times.

vassals-include

Argument: string

Add given config templates to vassals’ config.

This works by passing the include option when starting each vassal (which differs from the inherit option in that include will replace placeholders etc.).

This option may be declared multiple times.

vassals-start-hook

Argument: string

Run the specified command before each vassal starts.

vassals-stop-hook

Argument: string

Run the specified command after vassal’s death.

vassal-sos-backlog

Argument: number

Ask emperor for sos if backlog queue has more items than the value specified.

heartbeat

Argument: number

(Vassal option) Announce vassal health to the emperor every N seconds.

emperor-required-heartbeat

Argument: number Default: 30

Set the Emperor tolerance about heartbeats.

When a vassal asks for ‘heartbeat mode’ the emperor will also expect a ‘heartbeat’ at least every <secs> seconds.

auto-snapshot

Argument: optional number

Automatically make workers snapshot after reload.

See also

Snapshot

reload-mercy

Argument: number

Set the maximum time (in seconds) a worker can take to reload/shutdown.

For example reload-mercy 8 would brutally kill every worker that will not terminate itself within 8 seconds during graceful reload

Process Management - Zerg

See also

Zerg mode

zerg

Argument: string

Attach to a zerg server.

This option may be declared multiple times.

zerg-fallback

Argument: no argument

Fallback to normal sockets if the zerg server is not available.

zerg-server

Argument: string

Enable the zerg server on the specified UNIX socket.

zergpool, zerg-pool

Argument: string

Start a zergpool on specified address for specified address (zergpool plugin).

This option may be declared multiple times.

Debugging

backtrace-depth

Argument: number

Set backtrace depth.

memory-report

Argument: no argument

Enable memory usage report.

This option may be set with -m from the command line.

When enabled, diagnostic information about RSS and address space usage will be printed in the request log.

profiler

Argument: string

Enable the specified profiler.

dump-options

Argument: no argument

Dump the full list of available options.

show-config

Argument: no argument

Show the current config reformatted as ini.

print

Argument: string

Simple print (for your convenience).

cflags

Argument: no argument

Report uWSGI CFLAGS (useful for building external plugins).

version

Argument: no argument

Print uWSGI version.

allowed-modifiers

Argument: string

Comma separated list of allowed modifiers for clients.

allowed-modifiers 0,111 would allow access to only the WSGI handler and the cache handler.

connect-and-read

Argument: str

Connect to a socket and wait for data from it.

Configuration

strict

Argument: no argument

Enable strict configuration parsing. If any unknown option is encountered in a configuration file, an error is shown and uWSGI quits.

To use placeholder variables when using strict mode, use the set-placeholder option.

set

Argument: string

Set a configuration option. This option was created to work around a specific problem with commandline options on Solaris and should not normally need to be used.

set-placeholder

Argument: string

Set a placeholder variable. The value of this option should be in the form placeholder=value. This option can be to set placeholders when the strict option is enabled.

This option is available since version 1.9.18.

declare-option

Argument: string

Declare a new custom uWSGI option.

inherit

Argument: string

Use the specified file as configuration template. The file type of the included file is automatically detected based on filename extension.

Note that environment variables, external file includes and placeholders are not expanded inside the inherited configuration. Magic variables (e.g. %n) are expanded normally.

include

Argument: string

Include the specified file as if its configuration entries had been declared here. The file type of the included file is automatically detected based on filename extension.

This option is available since version 1.3.

plugins, plugin

Argument: string

Load uWSGI plugins (comma-separated).

This option may be declared multiple times.

plugins-dir, plugin-dir

Argument: string

Add a directory to uWSGI plugin search path.

This option may be declared multiple times.

plugins-list, plugin-list

Argument: no argument

List enabled plugins.

autoload

Argument: no argument

Try to automatically load plugins when unknown options are found.

dlopen

Argument: string

Blindly load a shared library.

ini

Argument: number

Load config from ini file.

xml, xmlconfig

Argument: string

Load XML file as configuration.

This option may be set with -x from the command line.

yaml, yal

Argument: string

Load config from yaml file.

This option may be set with -y from the command line.

json, js

Argument: string

Load config from json file.

This option may be set with -j from the command line.

sqlite3, sqlite

Argument: number

Load config from sqlite3 db.

ldap

Argument: number

Load configuration from ldap server.

ldap-schema

Argument: no argument

Dump uWSGI ldap schema.

ldap-schema-ldif

Argument: no argument

Dump uWSGI ldap schema in ldif format.

Config logic

for

Argument: string

For cycle.

endfor

Argument: optional string

End for cycle.

if-opt

Argument: string

Check for option.

if-not-opt

Argument: string

Check for lack of option.

if-env, ifenv

Argument: string

Check for environment variable.

if-not-env

Argument: string

Check for lack of environment variable.

if-reload

Argument: string

Check for reload.

if-not-reload

Argument: string

Check for lack of reload.

if-exists, ifexists

Argument: string

Check for file/directory existence.

if-not-exists

Argument: string

Check for file/directory inexistence.

if-file

Argument: string

Check for file existence.

if-not-file

Argument: string

Check for file inexistence.

if-dir, ifdir, if-directory

Argument: string

Check for directory existence.

if-not-dir

Argument: string

Check for directory inexistence.

endif

Argument: optional string

End if block.

Logging

See also

Logging

disable-logging

Argument: no argument

Disable request logging.

This option may be set with -L from the command line.

When enabled, only uWSGI internal messages and errors are logged.

ignore-sigpipe

Argument: no argument

Do not report (annoying) SIGPIPE.

ignore-write-errors

Argument: no argument

Do not report (annoying) write()/writev() errors.

write-errors-tolerance

Argument: number

Set the maximum number of allowed write errors (default: no tolerance).

write-errors-exception-only

Argument: no argument

Only raise an exception on write errors giving control to the app itself.

disable-write-exception

Argument: no argument

Disable exception generation on write()/writev().

logto

Argument: string

Set logfile/udp address.

logto2

Argument: string

Log to specified file or udp address after privileges drop.

log-format, logformat

Argument: string

Set advanced format for request logging.

logformat-strftime, log-format-strftime

Argument: no argument

Apply strftime to logformat output.

logfile-chown

Argument: no argument

Chown logfiles.

logfile-chmod

Argument: string

Chmod logfiles.

log-syslog

Argument: optional string

Log to syslog.

Passing a parameter makes uwsgi use the parameter as program-name in the syslog entry header.

log-socket

Argument: string

Send logs to the specified socket.

logger

Argument: string

Set/append a logger.

This option may be declared multiple times.

logger-list, loggers-list

Argument: no argument

List enabled loggers.

threaded-logger

Argument: no argument

Offload log writing to a thread.

log-drain

Argument: regexp

Drain (do not show) log lines matching the specified regexp.

This option may be declared multiple times.

log-zeromq

Argument: string

Send logs to a ZeroMQ server.

log-master

Argument: no argument

Delegate logging to master process.

Delegate the write of the logs to the master process (this will put all of the logging I/O to a single process). Useful for system with advanced I/O schedulers/elevators.

log-master-bufsize

Argument: number

Set the buffer size for the master logger. Log messages larger than this will be truncated.

log-reopen

Argument: no argument

Reopen log after reload.

log-truncate

Argument: no argument

Truncate log on startup.

log-maxsize

Argument: number

Set maximum logfile size.

log-backupname

Argument: string

Set logfile name after rotation.

log-prefix, logdate, log-date

Argument: optional string

Prefix log lines with date (without argument) or a strftime string.

log-zero

Argument: no argument

Log responses without body (zero response size).

log-slow

Argument: number

Log requests slower than the specified number of milliseconds.

log-4xx

Argument: no argument

Log requests with a 4xx response.

log-5xx

Argument: no argument

Log requests with a 5xx response.

log-big

Argument: number

Log requestes bigger than the specified size in bytes.

log-sendfile

Argument: no argument

Log sendfile requests.

log-micros

Argument: no argument

Report response time in microseconds instead of milliseconds.

log-x-forwarded-for

Argument: no argument

Use the ip from X-Forwarded-For header instead of REMOTE_ADDR. Used when uWSGI is run behind multiple proxies.

stats, stats-server

Argument: string

Enable the stats server on the specified address.

ssl-verbose

Argument: no argument

Be verbose about SSL errors.

snmp

Argument: string

Enable the embedded SNMP server.

This option may be declared multiple times.

snmp-community

Argument: string

Set the SNMP community string.

Alarms

alarm

Argument: string

Create a new alarm. Syntax: <alarm> <plugin:args>.

This option may be declared multiple times.

alarm-freq

Argument: number

Tune the alarm anti-loop system (default 3 seconds).

log-alarm

Argument: string

Raise the specified alarm when a log line matches the specified regexp, syntax: <alarm>[,alarm...] <regexp>.

This option may be declared multiple times.

alarm-list, alarms-list

Argument: no argument

List enabled alarms.

uWSGI Process

daemonize

Argument: logfile

Daemonize uWSGI and write messages into given log file or UDP socket address.

See also

Logging

daemonize2

Argument: logfile

Daemonize uWSGI after loading application, write messages into given log file or UDP socket address.

See also

Logging

stop

Argument: pidfile

Send the stop (SIGINT) signal to the instance described by the pidfile.

reload

Argument: pidfile

Send the reload (SIGHUP) signal to the instance described by the pidfile.

pause

Argument: pidfile

Send the pause (SIGTSTP) signal to the instance described by the pidfile.

suspend

Argument: pidfile

Send the suspend (SIGTSTP) signal to the instance described by the pidfile.

resume

Argument: pidfile

Send the resume (SIGTSTP) signal to the instance described by the pidfile.

auto-procname

Argument: no argument

Automatically set process name to something meaningful.

Generated process names may be ‘uWSGI Master’, ‘uWSGI Worker #’, etc.

procname-prefix

Argument: string

Add prefix to process names.

procname-prefix-spaced

Argument: string

Add spaced prefix to process names.

procname-append

Argument: string

Append string to process names.

procname

Argument: string

Set process name to given value.

procname-master

Argument: string

Set master process name to given value.

pidfile

Argument: string

Create pidfile (before privileges drop).

pidfile2

Argument: string

Create pidfile (after privileges drop).

chroot

Argument: string

Chroot() to the specified directory.

uid

Argument: username|uid

Setuid to the specified user/uid.

gid

Argument: groupname|gid

Setgid to the specified grooup/gid.

no-initgroups

Argument: no argument

Disable additional groups set via initgroups().

cap

Argument: string

Set process capability.

unshare

Argument: string

Unshare() part of the processes and put it in a new namespace.

exec-pre-jail

Argument: string

Run the specified command before jailing.

This option may be declared multiple times.

exec-post-jail

Argument: string

Run the specified command after jailing.

This option may be declared multiple times.

exec-in-jail

Argument: string

Run the specified command in jail after initialization.

This option may be declared multiple times.

exec-as-root

Argument: string

Run the specified command before privileges drop.

This option may be declared multiple times.

exec-as-user

Argument: string

Run the specified command after privileges drop.

This option may be declared multiple times.

exec-as-user-atexit

Argument: string

Run the specified command before app exit and reload.

This option may be declared multiple times.

exec-pre-app

Argument: string

Run the specified command before app loading.

This option may be declared multiple times.

cgroup

Argument: string

Put the processes in the specified cgroup (Linux only).

This option may be declared multiple times.

cgroup-opt

Argument: string

Set value in specified cgroup option.

This option may be declared multiple times.

namespace, ns

Argument: string

Run in a new namespace under the specified rootfs.

namespace-keep-mount

Argument: <mount>[:<jailed-mountpoint>]

Keep the specified mountpoint in your namespace, optionally renaming it.

namespace-net, ns-net

Argument: string

Add network namespace.

forkbomb-delay

Argument: number

Sleep for the specified number of seconds when a forkbomb is detected.

binary-path

Argument: string

Force binary path.

If you do not have uWSGI in the system path you can force its path with this option to permit the reloading system and the Emperor to easily find the binary to execute.

privileged-binary-patch

Argument: string

Patch the uwsgi binary with a new command (before privileges drop).

unprivileged-binary-patch

Argument: string

Patch the uwsgi binary with a new command (after privileges drop).

privileged-binary-patch-arg

Argument: string

Patch the uwsgi binary with a new command and arguments (before privileges drop).

unprivileged-binary-patch-arg

Argument: string

Patch the uwsgi binary with a new command and arguments (after privileges drop).

async

Argument: number

Enable async mode with specified cores.

max-fd

Argument: number

Set maximum number of file descriptors (requires root privileges).

master-as-root

Argument: no argument

Leave master process running as root.

Miscellaneous

thunder-lock

Argument: no argument

Serialize accept() usage (if possibie).

skip-zero

Argument: no argument

Skip check of file descriptor 0.

need-app

Argument: no argument

Exit if no app can be loaded.

exit-on-reload

Argument: no argument

Force exit even if a reload is requested.

die-on-term

Argument: no argument

Exit instead of brutal reload on SIGTERM.

no-fd-passing

Argument: no argument

Disable file descriptor passing.

single-interpreter

Argument: no argument

Do not use multiple interpreters (where available).

This option may be set with -i from the command line.

Some of the supported languages (such as Python) have the concept of “multiple interpreters”. This feature allows you to isolate apps living in the same process. If you do not want this kind of feature use this option.

max-apps

Argument: number

Set the maximum number of per-worker applications.

sharedarea

Argument: number

Create a raw shared memory area of specified number of pages.

This option may be set with -A from the command line.

This enables the SharedArea. This is a low level shared memory. If you want a more usable/user-friendly system look at the caching framework.

cgi-mode

Argument: no argument

Force CGI-mode for plugins supporting it.

This option may be set with -c from the command line.

When enabled, responses generated by uWSGI will not be HTTP responses, but CGI ones; namely, the Status: header will be added.

buffer-size

Argument: number Default: 4096

Set the internal buffer size for uwsgi packet parsing.

This option may be set with -b from the command line.

If you plan to receive big requests with lots of headers you can increase this value up to 64k (65535).

enable-threads

Argument: no argument

Enable threads.

This option may be set with -T from the command line.

Enable threads in the embedded languages. This will allow to spawn threads in your app.

Warning

Threads will simply not work if this option is not enabled. There will likely be no error, just no execution of your thread code.

signal-bufsize, signals-bufsize

Argument: number

Set buffer size for signal queue.

socket-timeout

Argument: number Default: 4

Set internal sockets timeout in seconds.

This option may be set with -z from the command line.

max-vars

Argument: number

Set the amount of internal iovec/vars structures for uwsgi clients (web servers, etc.).

This option may be set with -v from the command line.

This is only a security measure you will probably never need to touch.

weight

Argument: number

Weight of the instance (used by clustering/lb/subscriptions).

auto-weight

Argument: number

Set weight of the instance (used by clustering/lb/subscriptions) automatically.

no-server

Argument: no argument

Initialize the uWSGI server but exit as soon as the initialization is complete (useful for testing).

command-mode

Argument: no argument

Force command mode.

no-defer-accept

Argument: no argument

Disable deferred accept() on sockets.

by default (where available) uWSGI will defer the accept() of requests until some data is sent by the client (this is a security/performance measure). If you want to disable this feature for some reason, specify this option.

so-keepalive

Argument: no argument

Enable TCP KEEPALIVEs.

never-swap

Argument: no argument

Lock all memory pages avoiding swapping.

ksm

Argument: number

Enable Linux KSM.

This option may be declared multiple times.

touch-reload

Argument: string

Reload uWSGI if the specified file or directory is modified/touched.

This option may be declared multiple times.

touch-logrotate

Argument: string

Trigger logrotation if the specified file is modified/touched.

This option may be declared multiple times.

touch-logreopen

Argument: string

Trigger log reopen if the specified file is modified/touched.

This option may be declared multiple times.

propagate-touch

Argument: no argument

Over-engineering option for system with flaky signal mamagement.

no-orphans

Argument: no argument

Automatically kill workers if master dies (can be dangerous for availability).

prio

Argument: number

Set processes/threads priority (nice) value.

cpu-affinity

Argument: number of cores for each worker (Linux only)

Set CPU affinity.

Set the number of cores (CPUs) to allocate to each worker process.

For example

  • With 4 workers, 4 CPUs and cpu-affinity is 1, each worker is allocated one CPU.
  • With 4 workers, 2 CPUs and cpu-affinity is 1, workers get one CPU each (0; 1; 0; 1).
  • With 4 workers, 4 CPUs and cpu-affinity is 2, workers get two CPUs each in a round-robin fashion (0, 1; 2, 3; 0, 1; 2; 3).
  • With 8 workers, 4 CPUs and cpu-affinity is 3, workers get three CPUs each in a round-robin fashion (0, 1, 2; 3, 0, 1; 2, 3, 0; 1, 2, 3; 0, 1, 2; 3, 0, 1; 2, 3, 0; 1, 2, 3).

remap-modifier

Argument: string

Remap request modifier from one id to another (old-id:new-id).

env

Argument: string

Set environment variable (key=value).

unenv

Argument: string

Set environment variable (key).

close-on-exec

Argument: no argument

Set close-on-exec on sockets (could be required for spawning processes in requests).

mode

Argument: string

Set uWSGI custom mode.

Generic mode option that is passed down to applications as uwsgi.mode (or similar for other languages)

vacuum

Argument: no argument

Try to remove all of the generated files/sockets (UNIX sockets and pidfiles) upon exit.

cron

Argument: string

Add a cron task.

worker-exec

Argument: string

Run the specified command as worker instead of uWSGI itself.

This could be used to run a PHP FastCGI server pool:

/usr/bin/uwsgi --workers 4 --worker-exec /usr/bin/php53-cgi

attach-daemon

Argument: string

Attach a command/daemon to the master process (the command has to remain in foreground).

This will allow the uWSGI master to control/monitor/respawn this process.

A typical usage is attaching a memcached instance:

[uwsgi]
master = true
attach-daemon = memcached

smart-attach-daemon

Argument: pidfile

Attach a command/daemon to the master process managed by a pidfile (the command must daemonize).

smart-attach-daemon2

Argument: pidfile

Attach a command/daemon to the master process managed by a pidfile (the command must NOT daemonize).

Locks

See also

Locks

locks

Argument: number

Create the specified number of shared locks.

lock-engine

Argument: string

Set the lock engine.

ftok

Argument: string

Set the ipcsem key via ftok() for avoiding duplicates.

flock

Argument: string

Lock the specified file before starting, exit if locked.

flock-wait

Argument: string

Lock the specified file before starting, wait if locked.

flock2

Argument: string

Lock the specified file after logging/daemon setup, exit if locked.

flock-wait2

Argument: string

Lock the specified file after logging/daemon setup, wait if locked.

Cache

cache

Argument: number

Create a shared cache containing given elements.

cache-blocksize

Argument: number Default: 65536

Set the cache block size in bytes. It’s a good idea to use a multiple of 4096 (common memory page size).

cache-store

Argument: string

Enable persistent cache to disk.

cache-store-sync

Argument: number

Set frequency of sync for persistent cache.

cache-server

Argument: string

Enable the threaded cache server.

cache-server-threads

Argument: number

Set the number of threads for the cache server.

cache-no-expire

Argument: no argument

Disable auto sweep of expired items.

cache-expire-freq

Argument: number

Set the frequency of cache sweeper scans (default 3 seconds).

cache-report-freed-items

Argument: no argument

Constantly report the cache item freed by the sweeper (use only for debug).

Queue

queue

Argument: number

Enable the shared queue with the given size.

queue-blocksize

Argument: number

Set the block size for the queue.

queue-store

Argument: filename

Enable periodical persisting of the queue to disk.

queue-store-sync

Argument: number

Set periodical persisting frequency in seconds.

Spooler

spooler

Argument: string

Run a spooler on the specified directory.

This option may be set with -Q from the command line.

spooler-external

Argument: string

Map spooler requests to a spooler directory, but do not start a spooler (spooling managed by external instance).

spooler-ordered

Argument: no argument

Try to order the execution of spooler tasks.

spooler-chdir

Argument: string

Chdir() to specified directory before each spooler task.

spooler-processes

Argument: number

Set the number of processes for spoolers.

spooler-quiet

Argument: no argument

Do not be verbose with spooler tasks.

spooler-max-tasks

Argument: number

Set the maximum number of tasks to run before recycling a spooler.

spooler-harakiri

Argument: number

Set harakiri timeout for spooler tasks.

Mules

See also

uWSGI Mules

mule

Argument: string

Add a mule (signal-only mode without argument).

This option may be declared multiple times.

mules

Argument: number

Add the specified number of mules.

farm

Argument: string

Add a mule farm.

signal

Argument: string

Send a uwsgi signal to a server.

Application loading

chdir

Argument: string

Chdir to specified directory before apps loading.

chdir2

Argument: string

Chdir to specified directory after apps loading.

lazy

Argument: no argument

Set lazy mode (load apps in workers instead of master).

This option may have memory usage implications as Copy-on-Write semantics can not be used. When lazy is enabled, only workers will be reloaded by uWSGI’s reload signals; the master will remain alive. As such, uWSGI configuration changes are not picked up on reload by the master.

lazy-apps

Argument: no argument

Load apps in each worker instead of the master.

This option may have memory usage implications as Copy-on-Write semantics can not be used. Unlike lazy, this only affects the way applications are loaded, not master’s behavior on reload.

cheap

Argument: no argument

Set cheap mode (spawn workers only after the first request).

cheaper

Argument: number

Set cheaper mode (adaptive process spawning).

This an advanced cheap mode. This will only spawn <n> workers on startup and will use various (pluggable) algorithms to implement adaptive process spawning.

cheaper-initial

Argument: number

Set the initial number of processes to spawn in cheaper mode.

cheaper-algo

Argument: string

Choose to algorithm used for adaptive process spawning).

cheaper-step

Argument: number

Number of additional processes to spawn at each overload.

cheaper-overload

Argument: number

Increase workers after specified overload.

cheaper-algo-list, cheaper-algos-list, cheaper-list

Argument: no argument

List enabled ‘cheaper’ algorithms.

idle

Argument: number

Set idle mode (put uWSGI in cheap mode after inactivity).

die-on-idle

Argument: no argument

Shutdown uWSGI when idle.

mount

Argument: /mountpoint=/app/path

Load application under mountpoint.

Example: mount /pinax=/var/www/pinax/deploy/pinax.wsgi

worker-mount

Argument: string

Load application under mountpoint in the specified worker or after workers spawn.

This option may be declared multiple times.

grunt

Argument: no argument

Enable grunt mode (in-request fork).

Request handling

limit-post

Argument: number

Limit request body (bytes) based on the CONTENT_LENGTH uwsgi var.

post-buffering

Argument: number

Enable post buffering past N bytes.

Enables HTTP body buffering. uWSGI will save to disk all HTTP bodies larger than the limit specified. This option is required and auto-enabled for Ruby Rack applications as they require a rewindable input stream.

post-buffering-bufsize

Argument: number

Set buffer size for read() in post buffering mode.

This is an advanced option you probably won’t need to touch.

upload-progress

Argument: string

Enable creation of .json files in the specified directory during a file upload.

Enable the embedded upload progress system.

Pass the name of a directory where uWSGI has write permissions into.

For every upload with a X-Progress-ID query string (“GET”) parameter, a JSON file will be written to this directory containing the status of the upload. AJAX calls can then be used to read these files.

For instance, when upload-progress is set to /var/www/progress the user uploads a file to the URL:

/upload?X-Progress-ID=550e8400-e29b-41d4-a716-446655440000

uWSGI find X-Progress-ID in the query string and create a file called /var/www/progress/550e8400-e29b-41d4-a716-446655440000.js containing something like:

{"state": "uploading", "received": 170000, "size": 300000}

If /var/www/progress has been mapped to the /progress path in your web server, you can then request this file at /progress/550e8400-e29b-41d4-a716-446655440000.js.

It’s likely that your web server supports similar functionality (Nginx does, at least), but the uWSGI implementation is ostensibly more controllable and hackable.

no-default-app

Argument: no argument

Do not fallback to default app.

By default, when uWSGI does not find a corresponding app for the specified SCRIPT_NAME variable, it will use the default app (most of the time the app mounted under /). Enabling this option will return an error in case of unavailable app.

manage-script-name

Argument: no argument

Automatically rewrite SCRIPT_NAME and PATH_INFO.

If for some reason your webserver cannot manage SCRIPT_NAME on its own you can force uWSGI to rebuild the PATH_INFO variable automatically from it.

ignore-script-name

Argument: no argument

Ignore SCRIPT_NAME.

catch-exceptions

Argument: no argument

Report exception as HTTP output.

Warning

This option is heavily discouraged as it is a definite security risk.

reload-on-exception

Argument: no argument

Reload a worker when an exception is raised.

reload-on-exception-type

Argument: string

Reload a worker when a specific exception type is raised.

This option may be declared multiple times.

reload-on-exception-value

Argument: string

Reload a worker when a specific exception value is raised.

This option may be declared multiple times.

reload-on-exception-repr

Argument: string

Reload a worker when a specific exception type+value (language-specific) is raised.

This option may be declared multiple times.

add-header

Argument: string

Automatically add HTTP headers to response.

This option may be declared multiple times.

vhost

Argument: no argument

Enable virtualhosting mode (based on SERVER_NAME variable).

See also

VirtualHosting

vhost-host

Argument: no argument

Enable virtualhosting mode (based on HTTP_HOST variable).

By default the virtualhosting mode use the SERVER_NAME variable as the hostname key. If you want to use the HTTP_HOST one (corresponding to the Host: header) add this option

See also

VirtualHosting

Clustering

multicast

Argument: string

Subscribe to specified multicast group. internal option, usable by third party plugins.

multicast-ttl

Argument: number

Set multicast ttl.

cluster

Argument: string

Join specified uWSGI cluster.

cluster-nodes

Argument: address:port

Get nodes list from the specified cluster without joining it.

This list is used internally by the uwsgi load balancing api.

cluster-reload

Argument: address:port

Send a graceful reload message to the cluster.

cluster-log

Argument: address:port

Send a log line to the cluster.

For instance, --cluster-log "Hello, world!" will print that to each cluster node’s log file.

Subscriptions

subscriptions-sign-check

Argument: string

Set digest algorithm and certificate directory for secured subscription system.

subscriptions-sign-check-tolerance

Argument: number

Set the maximum tolerance (in seconds) of clock skew for secured subscription system.

subscription-algo

Argument: string

Set load balancing algorithm for the subscription system.

subscription-dotsplit

Argument: no argument

Try to fallback to the next part (dot based) in subscription key.

subscribe-to, st, subscribe

Argument: string

Subscribe to the specified subscription server.

This option may be declared multiple times.

subscribe-freq

Argument: number

Send subscription announce at the specified interval.

subscription-tolerance

Argument: number

Set tolerance for subscription servers.

unsubscribe-on-graceful-reload

Argument: no argument

Force unsubscribe request even during graceful reload.

Router

route

Argument: string

Add a route.

This option may be declared multiple times.

route-host

Argument: string

Add a route based on Host header.

This option may be declared multiple times.

route-uri

Argument: string

Add a route based on REQUEST_URI.

This option may be declared multiple times.

route-qs

Argument: string

Add a route based on QUERY_STRING.

This option may be declared multiple times.

router-list, routers-list

Argument: no argument

List enabled routers.

Static files

static-check, check-static

Argument: string

Check for static files in the specified directory.

This option may be declared multiple times.

Specify a directory that uWSGI will check before passing control to a specific handler.

uWSGI will check if the requested PATH_INFO has a file correspondence in this directory and serve it.

For example, with check-static /var/www/example.com, uWSGI will check if /var/www/example.com/foo.png exists and directly serve it using sendfile() (or another configured method).

check-static-docroot

Argument: no argument

Check for static files in the requested DOCUMENT_ROOT.

static-map

Argument: string

Map mountpoint to static directory (or file).

This option may be declared multiple times.

Whenever a PATH_INFO starts with one of the configured resources, uWSGI will serve the file as a static file.

static-map2

Argument: string

Map mountpoint to static directory (or file), completely appending the requested resource to the docroot.

This option may be declared multiple times.

static-skip-ext

Argument: string

Skip specified extension from staticfile checks.

This option may be declared multiple times.

static-index

Argument: string

Search for specified file if a directory is requested.

This option may be declared multiple times.

With static-index=index.html, if the client asks for /doc/ then uWSGI will check for /doc/index.html and if it exists it will be served to the client.

mimefile, mime-file

Argument: string

Set mime types file path (default /etc/mime.types).

This option may be declared multiple times.

static-expires-type

Argument: string

Set the Expires header based on content type (syntax: Content-type=Expires).

This option may be declared multiple times.

static-expires-type-mtime

Argument: string

Set the Expires header based on content type and file mtime (syntax: Content-type=Expires).

This option may be declared multiple times.

static-expires

Argument: string

Set the Expires header based on filename regexp (syntax x=y).

This option may be declared multiple times.

static-expires-mtime

Argument: string

Set the Expires header based on filename regexp and file mtime (syntax x=y).

This option may be declared multiple times.

static-expires-uri

Argument: string

Set the Expires header based on REQUEST_URI regexp (syntax x=y).

This option may be declared multiple times.

static-expires-uri-mtime

Argument: string

Set the Expires header based on REQUEST_URI regexp and file mtime (syntax x=y).

This option may be declared multiple times.

static-expires-path-info

Argument: string

Set the Expires header based on PATH_INFO regexp (syntax x=y).

This option may be declared multiple times.

static-expires-path-info-mtime

Argument: string

Set the Expires header based on PATH_INFO regexp and file mtime (syntax x=y).

This option may be declared multiple times.

static-offload-to-thread

Argument: number

Offload static file serving to a thread (upto the specified number of threads).

file-serve-mode

Argument: string

Set static file serving mode (x-sendfile, nginx, ...).

Set the static serving mode:

  • x-sendfile will use the X-Sendfile header supported by Apache, Cherokee, lighttpd
  • x-accel-redirect will use the X-Accel-Redirect header supported by Nginx

By default the sendfile() syscall is used.

check-cache

Argument: no argument

Check for response data in the cache based on PATH_INFO.

Clocks

clock

Argument: string

Set a clock source.

clock-list, clocks-list

Argument: no argument

List enabled clocks.

Loop engines

loop

Argument: string

Select the uWSGI loop engine (advanced).

See also

LoopEngine

loop-list, loops-list

Argument: no argument

List enabled loop engines.

Greenlet

See also

Greenlet

greenlet

Argument: no argument

Enable greenlet as suspend engine.

Gevent

gevent

Argument: number

A shortcut enabling gevent loop engine with the specified number of async cores and optimal parameters.

gevent-monkey-patch

Argument: no argument

Call gevent.monkey.patch_all() automatically on startup.

gevent-wait-for-hub

Argument: no argument

Wait for gevent hub’s death instead of the control greenlet.

Stackless

See also

Stackless

stackless

Argument: no argument

Use stackless as suspend engine.

uGreen

ugreen

Argument: no argument

Enable uGreen as suspend/resume engine.

ugreen-stacksize

Argument: number

Set ugreen stack size in pages.

Fiber

fiber

Argument: no argument

Enable Ruby fiber as suspend engine.

CoroAE

coroae

Argument: setup coroae

A shortcut enabling Coro::AnyEvent loop engine with the specified number of async cores and optimal parameters.

tornado

tornado

Argument: setup tornado

A shortcut enabling tornado loop engine with the specified number of async cores and optimal parameters.

Carbon

carbon

Argument: host:port

Push statistics to the specified carbon server/port.

This option may be declared multiple times.

carbon-timeout

Argument: number Default: 3

Set Carbon connection timeout in seconds.

carbon-freq

Argument: number Default: 60

Set Carbon push frequency in seconds.

carbon-id

Argument: string

Set the identifier for Carbon metrics (by default the first uWSGI socket name).

carbon-no-workers

Argument: no argument

Disable generation of single worker metrics.

carbon-max-retry

Argument: number

Set maximum number of retries in case of connection errors (default 1).

carbon-retry-delay

Argument: number

Set connection retry delay in seconds (default 7).

carbon-root

Argument: string

Set carbon metrics root node (default ‘uwsgi’).

carbon-hostname-dots

Argument: string

Set char to use as a replacement for dots in hostname (dots are not replaced by default).

carbon-name-resolve, carbon-resolve-names

Argument: no argument

Allow using hostname as carbon server address (default disabled).

carbon-idle-avg

Argument: string

Average values source during idle period (no requests), can be ‘last’, ‘zero’, ‘none’ (default is last).

carbon-use-metrics

Argument: no argument

Don’t compute all statistics, use metrics subsystem data instead (warning! key names will be different).

CGI

cgi

Argument: [mountpoint=]script

Add a CGI directory/script with optional mountpoint (URI prefix).

cgi-map-helper, cgi-helper

Argument: extension=helper-executable

Add a cgi helper to map an extension into an executable.

cgi-from-docroot

Argument: no argument

Blindly enable cgi in DOCUMENT_ROOT.

cgi-buffer-size

Argument: number

Set the CGI buffer size.

cgi-timeout

Argument: number

Set CGI script timeout.

cgi-index

Argument: string

Add a CGI index file.

This option may be declared multiple times.

cgi-allowed-ext

Argument: string

Allowed extensions for CGI.

This option may be declared multiple times.

cgi-unset

Argument: string

Unset specified environment variables before running CGI executable.

This option may be declared multiple times.

cgi-loadlib

Argument: string

Load a CGI shared library/optimizer.

This option may be declared multiple times.

cgi-optimize, cgi-optimized

Argument: no argument

Enable CGI realpath() optimizer.

cgi-path-info

Argument: no argument

Disable PATH_INFO management in CGI scripts.

Busyness Cheaper algorithm

cheaper-busyness-max

Argument: number

Set the cheaper busyness high percent limit, above that value worker is considered loaded (default 50).

cheaper-busyness-min

Argument: number

Set the cheaper busyness low percent limit, belowe that value worker is considered idle (default 25).

cheaper-busyness-multiplier

Argument: number

Set initial cheaper multiplier, worker needs to be idle for cheaper-overload*multiplier seconds to be cheaped (default 10).

cheaper-busyness-penalty

Argument: number

Penalty for respawning workers to fast, it will be added to the current multiplier value if worker is cheaped and than respawned back too fast (default 2).

cheaper-busyness-verbose

Argument: no argument

Enable verbose log messages from busyness algorithm.

cheaper-busyness-backlog-alert

Argument: number

Spawn emergency worker if anytime listen queue is higher than this value (default 33) (Linux only).

cheaper-busyness-backlog-multiplier

Argument: number

Set cheaper multiplier used for emergency workers (default 3) (Linux only).

cheaper-busyness-backlog-step

Argument: number

Number of emergency workers to spawn at a time (default 1) (Linux only).

cheaper-busyness-backlog-nonzero

Argument: number

Spawn emergency worker(s) if backlog is > 0 for more then N seconds (default 60).

Erlang

erlang

Argument: string

Spawn an Erlang c-node.

Fastrouter

fastrouter

Argument: address:port

Run the fastrouter (uwsgi protocol proxy/load balancer) on the specified address:port.

fastrouter-processes, fastrouter-workers

Argument: number

Prefork the specified number of fastrouter processes.

fastrouter-zerg

Argument: corerouter zerg

Attach the fastrouter to a zerg server.

fastrouter-use-cache

Argument: no argument

Use uWSGI cache as hostname->server mapper for the fastrouter.

fastrouter-use-pattern

Argument: corerouter use pattern

Use a pattern for fastrouter hostname->server mapping.

fastrouter-use-base

Argument: corerouter use base

Use a base dir for fastrouter hostname->server mapping.

fastrouter-fallback

Argument: string

Fallback to the specified node in case of error.

This option may be declared multiple times.

fastrouter-use-cluster

Argument: no argument

Load balance to nodes subscribed to the cluster.

fastrouter-use-code-string

Argument: corerouter cs

Use code string as hostname->server mapper for the fastrouter.

fastrouter-use-socket

Argument: optional corerouter use socket

Forward request to the specified uwsgi socket.

fastrouter-to

Argument: string

Forward requests to the specified uwsgi server (you can specify it multiple times for load balancing).

This option may be declared multiple times.

fastrouter-gracetime

Argument: number

Retry connections to dead static nodes after the specified amount of seconds.

fastrouter-events

Argument: number

Set the maximum number of concurrent events the fastrouter can return in one cycle.

fastrouter-quiet

Argument: no argument

Do not report failed connections to instances.

fastrouter-cheap

Argument: no argument

Run the fastrouter in cheap mode (do not respond to requests unless a node is available).

fastrouter-subscription-slot

Argument: deprecated

* deprecated *.

fastrouter-subscription-server

Argument: corerouter ss

Add a Subscription Server to the fastrouter to build the hostname:address map.

fastrouter-timeout

Argument: number

Set the internal fastrouter timeout.

fastrouter-post-buffering

Argument: number

Enable fastrouter post buffering.

fastrouter-post-buffering-dir

Argument: string

Put fastrouter buffered files to the specified directory.

fastrouter-stats, fastrouter-stats-server, fastrouter-ss

Argument: string

Run the fastrouter stats server.

fastrouter-harakiri

Argument: number

Enable fastrouter harakiri.

GeoIP

geoip-country

Argument: string

Load the specified geoip country database.

geoip-city

Argument: string

Load the specified geoip city database.

GlusterFS

glusterfs-mount

Argument: string

Virtual mount the specified glusterfs volume in a uri.

This option may be declared multiple times.

glusterfs-timeout

Argument: number

Timeout for glusterfs async mode.

Gccgo

go-load, gccgo-load

Argument: string

Load a go shared library in the process address space, eventually patching main.main and __go_init_main.

This option may be declared multiple times.

go-args, gccgo-args

Argument: string

Set go commandline arguments.

Go_plugin

goroutines

Argument: setup goroutines

A shortcut setting optimal options for goroutine-based apps, takes the number of goroutines to spawn as argument.

HTTP

http

Argument: address

Enable the embedded HTTP router/server/gateway/loadbalancer/proxy on the specified address.

http-processes, http-workers

Argument: number

Set the number of http processes to spawn.

http-var

Argument: string

Add a key=value item to the generated uwsgi packet.

This option may be declared multiple times.

http-to

Argument: string

Forward requests to the specified node (you can specify it multiple time for lb).

This option may be declared multiple times.

http-zerg

Argument: corerouter zerg

Attach the http router to a zerg server.

http-fallback

Argument: string

Fallback to the specified node in case of error.

This option may be declared multiple times.

http-modifier1

Argument: number

Set uwsgi protocol modifier1.

http-use-cache

Argument: no argument

Use uWSGI cache as key->value virtualhost mapper.

http-use-pattern

Argument: corerouter use pattern

Use the specified pattern for mapping requests to unix sockets.

http-use-base

Argument: corerouter use base

Use the specified base for mapping requests to unix sockets.

http-use-cluster

Argument: no argument

Load balance to nodes subscribed to the cluster.

http-events

Argument: number

Set the number of concurrent http async events.

http-subscription-server

Argument: corerouter ss

Enable the SubscriptionServer for clustering and massive hosting/load-balancing.

http-timeout

Argument: number

Set internal http socket timeout.

http-manage-expect

Argument: no argument

Manage the Expect HTTP request header.

http-keepalive

Argument: no argument

Support HTTP keepalive (non-pipelined) requests (requires backend support).

http-raw-body

Argument: no argument

Blindly send HTTP body to backends (required for WebSockets and Icecast support).

http-use-code-string

Argument: corerouter cs

Use code string as hostname->server mapper for the http router.

http-use-socket

Argument: optional corerouter use socket

Forward request to the specified uwsgi socket.

http-gracetime

Argument: number

Retry connections to dead static nodes after the specified amount of seconds.

http-quiet

Argument: no argument

Do not report failed connections to instances.

http-cheap

Argument: no argument

Run the http router in cheap mode.

http-stats, http-stats-server, http-ss

Argument: string

Run the http router stats server.

http-harakiri

Argument: number

Enable http router harakiri.

http-modifier2

Argument: number

Set uwsgi protocol modifier2.

http-auto-chunked

Argument: no argument

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

http-auto-gzip

Argument: no argument

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-websockets

Argument: no argument

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

http-stud-prefix

Argument: add addr list

Expect a stud prefix (1byte family + 4/16 bytes address) on connections from the specified address.

HTTPS

https

Argument: https config

Add an https router/server on the specified address with specified certificate and key.

https-export-cert

Argument: no argument

Export uwsgi variable HTTPS_CC containing the raw client certificate.

http-to-https

Argument: address

Add an HTTP router/server on the specified address and redirect all of the requests to HTTPS.

https2

Argument: https2

Add an https/spdy router/server using keyval options.

https-session-context

Argument: string

Set the session id context to the specified value.

JVM

jvm-main-class

Argument: string

Load the specified class and call its main() function.

jvm-classpath

Argument: string

Add the specified directory to the classpath.

This option may be declared multiple times.

jvm-opt

Argument: string

Add the specified jvm option.

This option may be declared multiple times.

jvm-class

Argument: string

Load the specified class.

This option may be declared multiple times.

jwsgi

Argument: string

Load the specified JWSGI application (syntax class:method).

Lua

lua

Argument: string

Load lua wsapi app.

lua-load

Argument: string

Load a lua file.

This option may be declared multiple times.

lua-shell, luashell

Argument: no argument

Run the lua interactive shell (debug.debug()).

Mono

mono-app

Argument: string

Load a Mono asp.net app from the specified directory.

This option may be declared multiple times.

mono-gc-freq

Argument: number

Run the Mono GC every <n> requests (default: run after every request).

mono-key

Argument: string

Select the ApplicationHost based on the specified CGI var.

This option may be declared multiple times.

mono-version

Argument: string

Set the Mono jit version.

mono-config

Argument: string

Set the Mono config file.

mono-assembly

Argument: string

Load the specified main assembly (default: uwsgi.dll).

mono-exec

Argument: string

Exec the specified assembly just before app loading.

This option may be declared multiple times.

mono-index

Argument: string

Add an asp.net index file.

This option may be declared multiple times.

Nagios output

nagios

Argument: no argument

Output Nagios-friendly status check information.

PAM

See also

PAM

pam

Argument: string

Set the pam service name to use.

pam-user

Argument: string

Set a fake user for pam.

Perl

psgi

Argument: string

Load a psgi app.

perl-no-die-catch

Argument: no argument

Do not catch $SIG{__DIE__}.

perl-local-lib

Argument: string

Set perl locallib path.

perl-version

Argument: no argument

Print perl version.

perl-args

Argument: string

Add items (space separated) to @ARGV.

perl-arg

Argument: string

Add an item to @ARGV.

This option may be declared multiple times.

perl-exec

Argument: string

Exec the specified perl file before fork().

This option may be declared multiple times.

perl-exec-post-fork

Argument: string

Exec the specified perl file after fork().

This option may be declared multiple times.

perl-auto-reload

Argument: number

Enable perl auto-reloader with the specified frequency.

perl-auto-reload-ignore

Argument: string

Ignore the specified files when auto-reload is enabled.

This option may be declared multiple times.

PHP

php-ini, php-config

Argument: php ini

Use this PHP.ini.

php-ini-append, php-config-append

Argument: string

Append this (these) php.inis to the first one.

This option may be declared multiple times.

php-set

Argument: key=value

Set a php config directive.

This option may be declared multiple times.

php-index

Argument: string

Set the file to open (like index.php) when a directory is requested.

This option may be declared multiple times.

php-docroot

Argument: string

Force php DOCUMENT_ROOT.

php-allowed-docroot

Argument: string

Add an allowed document root. Only scripts under these directories will be executed.

This option may be declared multiple times.

php-allowed-ext

Argument: string

Add an allowed php file extension. Only scripts ending with these extensions will run.

This option may be declared multiple times.

php-server-software

Argument: string

Force the SERVER_SOFTWARE value reported to PHP.

php-app

Argument: string

Run _only_ this file whenever a request to the PHP plugin is made.

php-dump-config

Argument: no argument

Dump php config (even if modified via –php-set or append options).

php-allowed-script

Argument: string

List the allowed php scripts (require absolute path).

This option may be declared multiple times.

php-app-qs

Argument: string

When in app mode force QUERY_STRING to the specified value + REQUEST_URI.

php-fallback

Argument: string

Run the specified php script when the request one does not exist.

php-app-bypass

Argument: add regexp list

If the regexp matches the uri the –php-app is bypassed.

php-var

Argument: string

Add/overwrite a CGI variable at each request.

This option may be declared multiple times.

Ping

See also

Ping

ping

Argument: string

Ping specified uwsgi host.

If the ping is successful the process exits with a 0 code, otherwise with a value > 0.

ping-timeout

Argument: number Default: 3

Set ping timeout.

The maximum number of seconds to wait before considering a uWSGI instance dead

PyPy

pypy-lib

Argument: string

Set the path/name of the pypy library.

pypy-setup

Argument: string

Set the path of the python setup script.

pypy-home

Argument: string

Set the home of pypy library.

pypy-wsgi

Argument: string

Load a WSGI module.

pypy-wsgi-file

Argument: string

Load a WSGI/mod_wsgi file.

pypy-eval

Argument: string

Evaluate pypy code before fork().

This option may be declared multiple times.

pypy-eval-post-fork

Argument: string

Evaluate pypy code soon after fork().

This option may be declared multiple times.

pypy-exec

Argument: string

Execute pypy code from file before fork().

This option may be declared multiple times.

pypy-exec-post-fork

Argument: string

Execute pypy code from file soon after fork().

This option may be declared multiple times.

pypy-pp, pypy-python-path, pypy-pythonpath

Argument: string

Add an item to the pythonpath.

This option may be declared multiple times.

Python

See also

Python support

wsgi-file, file

Argument: string

Load .wsgi file as the Python application.

eval

Argument: string

Evaluate Python code as WSGI entry point.

module, wsgi

Argument: string

Load a WSGI module as the application. The module (sans .py) must be importable, ie. be in PYTHONPATH.

This option may be set with -w from the command line.

callable

Argument: string Default: application

Set default WSGI callable name.

test

Argument: string

Test a module import.

This option may be set with -J from the command line.

home, virtualenv, venv, pyhome

Argument: string

Set PYTHONHOME/virtualenv.

This option may be set with -H from the command line.

See also

Virtualenv

py-programname, py-program-name

Argument: string

Set python program name.

pythonpath, python-path, pp

Argument: directory/glob

Add directory (or an .egg or a glob) to the Python search path. This can be specified up to 64 times.

This option may be declared multiple times.

pymodule-alias

Argument: string

Add a python alias module.

This option may be declared multiple times.

See also

PyModuleAlias

post-pymodule-alias

Argument: string

Add a python module alias after uwsgi module initialization.

This option may be declared multiple times.

import, pyimport, py-import, python-import

Argument: string

Import a python module.

This option may be declared multiple times.

shared-import, shared-pyimport, shared-py-import, shared-python-import

Argument: string

Import a python module in all of the processes.

This option may be declared multiple times.

spooler-import, spooler-pyimport, spooler-py-import, spooler-python-import

Argument: string

Import a python module in the spooler.

This option may be declared multiple times.

pyargv

Argument: string

Manually set sys.argv for python apps.

pyargv="one two three" will set sys.argv to ('one', 'two', 'three').

optimize

Argument: number

Set python optimization level (this may be dangerous for some apps).

This option may be set with -O from the command line.

paste

Argument: string

Load a paste.deploy config file.

See also

PythonPaste

paste-logger

Argument: no argument

Enable paste fileConfig logger.

web3

Argument: string

Load a web3 app.

pump

Argument: string

Load a pump app.

wsgi-lite

Argument: string

Load a wsgi-lite app.

pecan

Argument: string

Load a pecan config file.

See also

PythonPecan

ini-paste

Argument: paste .INI

Load a paste.deploy config file containing uwsgi section.

ini-paste-logged

Argument: paste .INI

Load a paste.deploy config file containing uwsgi section (load loggers too).

reload-os-env

Argument: no argument

Force reloading os.environ at each request.

no-site

Argument: no argument

Do not import the site module while initializing Python. This is usually only required for dynamic virtualenvs. If in doubt, do not enable.

pyshell

Argument: no argument

Run an interactive Python shell in the uWSGI environment.

pyshell-oneshot

Argument: no argument

Run an interactive Python shell in the uWSGI environment (one-shot variant).

python, py, pyrun

Argument: .py file

Run a Python script in the uWSGI environment.

py-tracebacker

Argument: string

Enable the uWSGI Python tracebacker.

py-auto-reload, py-autoreload, python-auto-reload, python-autoreload

Argument: number

Monitor Python modules’ modification times to trigger reload (use only in development).

py-auto-reload-ignore

Argument: string

Ignore the specified module during auto-reload scan.

This option may be declared multiple times.

wsgi-env-behaviour, wsgi-env-behavior

Argument: string

Set the strategy for allocating/deallocating the WSGI env.

start_response-nodelay

Argument: no argument

Send WSGI http headers as soon as possible (PEP violation).

python-version

Argument: no argument

Report python version.

Rawrouter

See also

Rawrouter

rawrouter

Argument: corerouter

Run the rawrouter on the specified port.

rawrouter-processes, rawrouter-workers

Argument: number

Prefork the specified number of rawrouter processes.

rawrouter-zerg

Argument: corerouter zerg

Attach the rawrouter to a zerg server.

rawrouter-use-cache

Argument: no argument

Use uWSGI cache as address->server mapper for the rawrouter.

rawrouter-use-pattern

Argument: corerouter use pattern

Use a pattern for rawrouter address->server mapping.

rawrouter-use-base

Argument: corerouter use base

Use a base dir for rawrouter address->server mapping.

rawrouter-fallback

Argument: string

Fallback to the specified node in case of error.

This option may be declared multiple times.

rawrouter-use-cluster

Argument: no argument

Load balance to nodes subscribed to the cluster.

rawrouter-use-code-string

Argument: corerouter cs

Use code string as address->server mapper for the rawrouter.

rawrouter-use-socket

Argument: optional corerouter use socket

Forward request to the specified uwsgi socket.

rawrouter-to

Argument: string

Forward requests to the specified uwsgi server (you can specify it multiple times for load balancing).

This option may be declared multiple times.

rawrouter-gracetime

Argument: number

Retry connections to dead static nodes after the specified amount of seconds.

rawrouter-events

Argument: number

Set the maximum number of concurrent events.

rawrouter-quiet

Argument: no argument

Do not report failed connections to instances.

rawrouter-cheap

Argument: no argument

Run the rawrouter in cheap mode.

rawrouter-subscription-server

Argument: corerouter ss

Run the rawrouter subscription server on the spcified address.

rawrouter-subscription-slot

Argument: deprecated

* deprecated *.

rawrouter-timeout

Argument: number

Set rawrouter timeout.

rawrouter-stats, rawrouter-stats-server, rawrouter-ss

Argument: string

Run the rawrouter stats server.

rawrouter-harakiri

Argument: number

Enable rawrouter harakiri.

rawrouter-max-retries

Argument: number

Set the maximum number of retries/fallbacks to other nodes.

Ring

ring-load, clojure-load

Argument: string

Load the specified clojure script.

This option may be declared multiple times.

ring-app

Argument: string

Map the specified ring application (syntax namespace:function).

RRDtool

See also

RRDtool

rrdtool

Argument: string

Collect request data in the specified rrd file.

This option may be declared multiple times.

rrdtool-freq

Argument: number

Set collect frequency.

rrdtool-max-ds

Argument: number

Set maximum number of data sources.

rrdtool-lib

Argument: string

Set the name of rrd library (default: librrd.so).

Rsyslog

rsyslog-packet-size

Argument: number

Set maximum packet size for syslog messages (default 1024) WARNING! using packets > 1024 breaks RFC 3164 (#4.1).

rsyslog-split-messages

Argument: no argument

Split big messages into multiple chunks if they are bigger than allowed packet size (default is false).

Ruby

See also

Ruby support

rails

Argument: string

Load a Ruby on Rails <= 2.x app.

rack

Argument: string

Load a Rack app.

ruby-gc-freq, rb-gc-freq

Argument: number

Set Ruby GC frequency.

rb-require, ruby-require, rbrequire, rubyrequire, require

Argument: string

Import/require a Ruby module/script.

This option may be declared multiple times.

shared-rb-require, shared-ruby-require, shared-rbrequire, shared-rubyrequire, shared-require

Argument: string

Import/require a Ruby module/script (shared).

This option may be declared multiple times.

gemset, rvm

Argument: string

Load the specified gemset (rvm).

rvm-path

Argument: string

Search for rvm in the specified directory.

This option may be declared multiple times.

rbshell

Argument: optional no argument

Run a Ruby/irb shell.

rb-threads, rbthreads, ruby-threads

Argument: number

Set the number of Ruby threads to run (Ruby 1.9+).

rb-lib, ruby-lib

Argument: string

Add a directory to the ruby libdir search path.

This option may be declared multiple times.

rbshell-oneshot

Argument: no argument

Set ruby/irb shell (one shot).

SSL Router

sslrouter

Argument: sslrouter

Run the sslrouter on the specified port.

sslrouter2

Argument: sslrouter2

Run the sslrouter on the specified port (key-value based).

sslrouter-session-context

Argument: string

Set the session id context to the specified value.

sslrouter-processes, sslrouter-workers

Argument: number

Prefork the specified number of sslrouter processes.

sslrouter-zerg

Argument: corerouter zerg

Attach the sslrouter to a zerg server.

sslrouter-use-cache

Argument: optional string

Use uWSGI cache as hostname->server mapper for the sslrouter.

sslrouter-use-pattern

Argument: corerouter use pattern

Use a pattern for sslrouter hostname->server mapping.

sslrouter-use-base

Argument: corerouter use base

Use a base dir for sslrouter hostname->server mapping.

sslrouter-fallback

Argument: string

Fallback to the specified node in case of error.

This option may be declared multiple times.

sslrouter-use-code-string

Argument: corerouter cs

Use code string as hostname->server mapper for the sslrouter.

sslrouter-use-socket

Argument: optional corerouter use socket

Forward request to the specified uwsgi socket.

sslrouter-to

Argument: string

Forward requests to the specified uwsgi server (you can specify it multiple times for load balancing).

This option may be declared multiple times.

sslrouter-gracetime

Argument: number

Retry connections to dead static nodes after the specified amount of seconds.

sslrouter-events

Argument: number

Set the maximum number of concusrent events.

sslrouter-max-retries

Argument: number

Set the maximum number of retries/fallbacks to other nodes.

sslrouter-quiet

Argument: no argument

Do not report failed connections to instances.

sslrouter-cheap

Argument: no argument

Run the sslrouter in cheap mode.

sslrouter-subscription-server

Argument: corerouter ss

Run the sslrouter subscription server on the spcified address.

sslrouter-timeout

Argument: number

Set sslrouter timeout.

sslrouter-stats, sslrouter-stats-server, sslrouter-ss

Argument: string

Run the sslrouter stats server.

sslrouter-harakiri

Argument: number

Enable sslrouter harakiri.

sslrouter-sni

Argument: no argument

Use SNI to route requests.

Symcall

symcall

Argument: string

Load the specified C symbol as the symcall request handler.

symcall-register-rpc

Argument: string

Load the specified C symbol as an RPC function (syntax: name function).

This option may be declared multiple times.

symcall-post-fork

Argument: string

Call the specified C symbol after each fork().

This option may be declared multiple times.

WebDAV

webdav-mount

Argument: string

Map a filesystem directory as a webdav store.

This option may be declared multiple times.

webdav-css

Argument: string

Add a css url for automatic webdav directory listing.

This option may be declared multiple times.

webdav-javascript, webdav-js

Argument: string

Add a javascript url for automatic webdav directory listing.

This option may be declared multiple times.

webdav-class-directory

Argument: string

Set the css directory class for automatic webdav directory listing.

webdav-div

Argument: string

Set the div id for automatic webdav directory listing.

webdav-lock-cache

Argument: string

Set the cache to use for webdav locking.

webdav-principal-base

Argument: string

Enable WebDAV Current Principal Extension using the specified base.

webdav-add-option

Argument: string

Add a WebDAV standard to the OPTIONS response.

This option may be declared multiple times.

webdav-add-prop

Argument: string

Add a WebDAV property to all resources.

This option may be declared multiple times.

webdav-add-collection-prop

Argument: string

Add a WebDAV property to all collections.

This option may be declared multiple times.

webdav-add-object-prop

Argument: string

Add a WebDAV property to all objects.

This option may be declared multiple times.

webdav-add-prop-href

Argument: string

Add a WebDAV property to all resources (href value).

This option may be declared multiple times.

webdav-add-collection-prop-href

Argument: string

Add a WebDAV property to all collections (href value).

This option may be declared multiple times.

webdav-add-object-prop-href

Argument: string

Add a WebDAV property to all objects (href value).

This option may be declared multiple times.

webdav-add-prop-comp

Argument: string

Add a WebDAV property to all resources (xml value).

This option may be declared multiple times.

webdav-add-collection-prop-comp

Argument: string

Add a WebDAV property to all collections (xml value).

This option may be declared multiple times.

webdav-add-object-prop-comp

Argument: string

Add a WebDAV property to all objects (xml value).

This option may be declared multiple times.

webdav-add-rtype-prop

Argument: string

Add a WebDAV resourcetype property to all resources.

This option may be declared multiple times.

webdav-add-rtype-collection-prop

Argument: string

Add a WebDAV resourcetype property to all collections.

This option may be declared multiple times.

webdav-add-rtype-object-prop

Argument: string

Add a WebDAV resourcetype property to all objects.

This option may be declared multiple times.

webdav-skip-prop

Argument: string

Do not add the specified prop if available in resource xattr.

This option may be declared multiple times.

XSLT

xslt-docroot

Argument: string

Add a document_root for xslt processing.

This option may be declared multiple times.

xslt-ext

Argument: string

Search for xslt stylesheets with the specified extension.

This option may be declared multiple times.

xslt-var

Argument: string

Get the xslt stylesheet path from the specified request var.

This option may be declared multiple times.

xslt-stylesheet

Argument: string

If no xslt stylesheet file can be found, use the specified one.

This option may be declared multiple times.

xslt-content-type

Argument: string

Set the content-type for the xslt rsult (default: text/html).