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.
protocol, socket-protocol¶
Argument: string
Force the specified protocol (uwsgi, http, fastcgi) for default sockets.
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.
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.
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.
udp¶
Argument: string
Run the udp server on the specified address.
Mainly useful for SNMP or shared UDP logging.
See also
reuse-port¶
Argument: no argument
Enable REUSE_PORT flag on socket to allow multiple instances binding on the same address (BSD only).
fastcgi-nph-socket¶
Argument: add socket
Bind to the specified UNIX/TCP socket using FastCGI protocol (nph mode).
scgi-nph-socket¶
Argument: add socket
Bind to the specified UNIX/TCP socket using SCGI protocol (nph mode).
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.
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
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-stats, emperor-stats-server¶
Argument: string
Run the imperial bureau of statistics on the given address:port.
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.
vassal-sos-backlog¶
Argument: number
Ask emperor for sos if backlog queue has more items than the value specified.
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-fallback¶
Argument: no argument
Fallback to normal sockets if the zerg server is not available.
zergpool, zerg-pool¶
Argument: string
Start a zergpool on specified address for specified address (zergpool plugin).
This option may be declared multiple times.
Debugging¶
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.
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.
Configuration¶
See also
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.
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.
See also
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.
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.
Config logic¶
See also
Logging¶
See also
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.
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.
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-drain¶
Argument: regexp
Drain (do not show) log lines matching the specified regexp.
This option may be declared multiple times.
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-prefix, logdate, log-date¶
Argument: optional string
Prefix log lines with date (without argument) or a strftime string.
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.
snmp¶
Argument: string
Enable the embedded SNMP server.
This option may be declared multiple times.
See also
Alarms¶
See also
alarm¶
Argument: string
Create a new alarm. Syntax: <alarm> <plugin:args>.
This option may be declared multiple times.
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.
uWSGI Process¶
daemonize¶
Argument: logfile
Daemonize uWSGI and write messages into given log file or UDP socket address.
See also
daemonize2¶
Argument: logfile
Daemonize uWSGI after loading application, write messages into given log file or UDP socket address.
See also
stop¶
Argument: pidfile
Send the stop (SIGINT) signal to the instance described by the pidfile.
See also
reload¶
Argument: pidfile
Send the reload (SIGHUP) signal to the instance described by the pidfile.
See also
pause¶
Argument: pidfile
Send the pause (SIGTSTP) signal to the instance described by the pidfile.
See also
suspend¶
Argument: pidfile
Send the suspend (SIGTSTP) signal to the instance described by the pidfile.
See also
resume¶
Argument: pidfile
Send the resume (SIGTSTP) signal to the instance described by the pidfile.
See also
auto-procname¶
Argument: no argument
Automatically set process name to something meaningful.
Generated process names may be ‘uWSGI Master’, ‘uWSGI Worker #’, etc.
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.
See also
cgroup-opt¶
Argument: string
Set value in specified cgroup option.
This option may be declared multiple times.
See also
namespace-keep-mount¶
Argument: <mount>[:<jailed-mountpoint>]
Keep the specified mountpoint in your namespace, optionally renaming it.
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).
Miscellaneous¶
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.
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.
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.
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).
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.
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).
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).
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.
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
Cache¶
See also
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-report-freed-items¶
Argument: no argument
Constantly report the cache item freed by the sweeper (use only for debug).
Queue¶
See also
Spooler¶
See also
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-max-tasks¶
Argument: number
Set the maximum number of tasks to run before recycling a spooler.
Mules¶
See also
mule¶
Argument: string
Add a mule (signal-only mode without argument).
This option may be declared multiple times.
Application 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.
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-algo-list, cheaper-algos-list, cheaper-list¶
Argument: no argument
List enabled ‘cheaper’ algorithms.
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.
Request handling¶
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.
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-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.
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-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¶
See also
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-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.
unsubscribe-on-graceful-reload¶
Argument: no argument
Force unsubscribe request even during graceful reload.
Router¶
See also
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.
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).
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.
Clocks¶
Loop engines¶
Gevent¶
See also
gevent¶
Argument: number
A shortcut enabling gevent loop engine with the specified number of async cores and optimal parameters.
gevent-wait-for-hub¶
Argument: no argument
Wait for gevent hub’s death instead of the control greenlet.
uGreen¶
See also
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¶
See also
carbon¶
Argument: host:port
Push statistics to the specified carbon server/port.
This option may be declared multiple times.
carbon-id¶
Argument: string
Set the identifier for Carbon metrics (by default the first uWSGI socket name).
carbon-max-retry¶
Argument: number
Set maximum number of retries in case of connection errors (default 1).
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¶
See also
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-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.
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¶
See also
Fastrouter¶
See also
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-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-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-cheap¶
Argument: no argument
Run the fastrouter in cheap mode (do not respond to requests unless a node is available).
fastrouter-subscription-server¶
Argument: corerouter ss
Add a Subscription Server to the fastrouter to build the hostname:address map.
See also
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.
GeoIP¶
GlusterFS¶
glusterfs-mount¶
Argument: string
Virtual mount the specified glusterfs volume in a uri.
This option may be declared multiple times.
Gccgo¶
See also
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_plugin¶
See also
goroutines¶
Argument: setup goroutines
A shortcut setting optimal options for goroutine-based apps, takes the number of goroutines to spawn as argument.
HTTP¶
See also
http¶
Argument: address
Enable the embedded HTTP router/server/gateway/loadbalancer/proxy on the specified address.
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-fallback¶
Argument: string
Fallback to the specified node in case of error.
This option may be declared multiple times.
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-subscription-server¶
Argument: corerouter ss
Enable the SubscriptionServer for clustering and massive hosting/load-balancing.
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-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¶
See also
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.
JVM¶
jvm-classpath¶
Argument: string
Add the specified directory to the classpath.
This option may be declared multiple times.
Lua¶
See also
Mono¶
See also
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-exec¶
Argument: string
Exec the specified assembly just before app loading.
This option may be declared multiple times.
Nagios output¶
See also
PAM¶
See also
PAM
Perl¶
See also
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-ignore¶
Argument: string
Ignore the specified files when auto-reload is enabled.
This option may be declared multiple times.
PHP¶
See also
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-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-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-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-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
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.
home, virtualenv, venv, pyhome¶
Argument: string
Set PYTHONHOME/virtualenv.
This option may be set with -H from the command line.
See also
Virtualenv
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.
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.
ini-paste-logged¶
Argument: paste .INI
Load a paste.deploy config file containing uwsgi section (load loggers too).
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-oneshot¶
Argument: no argument
Run an interactive Python shell in the uWSGI environment (one-shot variant).
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).
Rawrouter¶
See also
Rawrouter
rawrouter-processes, rawrouter-workers¶
Argument: number
Prefork the specified number of rawrouter processes.
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-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-subscription-server¶
Argument: corerouter ss
Run the rawrouter subscription server on the spcified address.
rawrouter-stats, rawrouter-stats-server, rawrouter-ss¶
Argument: string
Run the rawrouter stats server.
Ring¶
ring-load, clojure-load¶
Argument: string
Load the specified clojure script.
This option may be declared multiple times.
RRDtool¶
See also
RRDtool
rrdtool¶
Argument: string
Collect request data in the specified rrd file.
This option may be declared multiple times.
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
rb-require, ruby-require, rbrequire, rubyrequire, require¶
Argument: string
Import/require a Ruby module/script.
This option may be declared multiple times.
rvm-path¶
Argument: string
Search for rvm in the specified directory.
This option may be declared multiple times.
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.
SSL Router¶
sslrouter-processes, sslrouter-workers¶
Argument: number
Prefork the specified number of sslrouter processes.
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-subscription-server¶
Argument: corerouter ss
Run the sslrouter subscription server on the spcified address.
sslrouter-stats, sslrouter-stats-server, sslrouter-ss¶
Argument: string
Run the sslrouter stats server.
Symcall¶
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-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.