Skip to content

Latest commit

 

History

History
1252 lines (1159 loc) · 35.8 KB

Options.rst

File metadata and controls

1252 lines (1159 loc) · 35.8 KB
Raw

Configuration Options

This is a (partial!) list of the various configuration options uWSGI supports. See the documentation for each feature for further details.

Networking/sockets

Option Argument Description
socket, uwsgi-socket string Bind to the specified socket using default protocol (see protocol). This option may be set with -s from the command line.
http-socket string Bind to the specified socket using HTTP.
fastcgi-socket string Bind to the specified socket using FastCGI.
protocol, socket-protocol string Force the specified protocol (uwsgi, http, fastcgi) for default sockets.
shared-socket string Create a shared socket for advanced jailing or IPC purposes.
listen number Set the socket listen queue size. This option may be set with -l from the command line.
abstract-socket Force UNIX socket into abstract mode (Linux only).
chmod-socket [string] Chmod socket. This option may be set with -C from the command line.
chown-socket string Chown UNIX sockets.
umask string Set UNIX socket umask.
freebind Put socket in freebind mode (Linux only).
map-socket string Map sockets to specific workers. This option may be declared multiple times.
zeromq, zmq, zeromq-socket, zmq-socket string Create a zeromq pub/sub pair.
udp string Run the udp server on the specified address.
reuse-port Enable REUSE_PORT flag on socket (BSD only).

Process Management

Option Argument Description
workers, processes number Spawn the specified number of workers/processes. This option may be set with -p from the command line.
harakiri number Harakiri timeout in seconds.
harakiri-verbose Enable verbose Harakiri mode.
harakiri-no-arh, no-harakiri-arh, no-harakiri-after-req-hook Disallow Harakiri killings during after-request-hook.
mule-harakiri number Set harakiri timeout for mule tasks.
master Enable uWSGI master process. This option may be set with -M from the command line.
reaper Call waitpid(-1,...) after each request to get rid of zombies. This option may be set with -r from the command line.
max-requests number Reload workers after the specified amount of managed requests (avoid memory leaks). This option may be set with -R from the command line.
limit-as number Limit process address space (vsz) (in megabytes).
limit-nproc number Limit the number of spawnable processes.
reload-on-as number Reload if address space is higher than specified megabytes (in megabytes).
reload-on-rss number Reload if rss memory is higher than specified megabytes (in megabytes).
evil-reload-on-as number Force the master to reload a worker if its address space is higher than specified megabytes (in megabytes).
evil-reload-on-rss number Force the master to reload a worker if its rss memory is higher than specified megabytes (in megabytes).
threads number Run each worker in prethreaded mode with the specified number of threads.
thread-stacksize, threads-stacksize, thread-stack-size, threads-stack-size number Set threads stacksize.
check-interval number Set the interval (in seconds) of master checks.

Process Management - Emperor

.. seealso::

   :doc:`Emperor`
Option Argument Description
emperor string Run as the Emperor. This option may be declared multiple times.
emperor-freq number Set the Emperor scan frequency (default 3 seconds).
emperor-required-heartbeat number Set the Emperor tolerance about heartbeats.
emperor-pidfile string Write the Emperor pid in the specified file.
emperor-tyrant Put the Emperor in Tyrant mode.
emperor-stats, emperor-stats-server string Run the Emperor stats server.
early-emperor Spawn the emperor as soon as possibile.
emperor-broodlord number Run the emperor in BroodLord mode.
emperor-throttle number Set throttling level (in milliseconds) for bad behaving vassals (default 1000).
emperor-max-throttle number Set max throttling level (in milliseconds) for bad behaving vassals (default 3 minutes).
emperor-magic-exec Prefix vassals config files with exec as s:// if they have the executable bit.
imperial-monitor-list, imperial-monitors-list List enabled imperial monitors.
vassals-inherit string Add given config templates to vassals' config. This option may be declared multiple times.
vassals-start-hook string Run the specified command before each vassal starts.
vassals-stop-hook string Run the specified command after vassal's death.
vassal-sos-backlog number Ask emperor for sos if backlog queue has more items than the value specified.
heartbeat number Announce healtness to the emperor.
auto-snapshot [number] Automatically make workers snapshot after reload.
reload-mercy number Set the maximum time (in seconds) a worker can take to reload/shutdown.

Process Management - Zerg

.. seealso::

   :doc:`Zerg`
Option Argument Description
zerg string Attach to a zerg server. This option may be declared multiple times.
zerg-fallback Fallback to normal sockets if the zerg server is not available.
zerg-server string Enable the zerg server on the specified UNIX socket.

Debugging

Option Argument Description
backtrace-depth number Set backtrace depth.
memory-report Enable memory report. This option may be set with -m from the command line.
profiler string Enable the specified profiler.
dump-options Dump the full list of available options.
show-config Show the current config reformatted as ini.
print string Simple print (for your convenience).
cflags Report uWSGI CFLAGS (useful for building external plugins).
version Print uWSGI version.
allowed-modifiers string Comma separated list of allowed modifiers.
connect-and-read str Connect to a socket and wait for data from it.

Configuration

.. seealso::

   :doc:`Configuration`
Option Argument Description
set string Set a custom placeholder for configuration.
declare-option string Declare a new custom uWSGI option.
inherit string Use the specified file as configuration template.
plugins, plugin number Load uWSGI plugins.
plugins-dir, plugin-dir string Add a directory to uWSGI plugin search path. This option may be declared multiple times.
plugins-list, plugin-list List enabled plugins.
autoload Try to automatically load plugins when unknown options are found.
dlopen string Blindly load a shared library.
ini number Load config from ini file.
xml, xmlconfig string Load XML file as configuration. This option may be set with -x from the command line.
yaml, yal string Load config from yaml file. This option may be set with -y from the command line.
json, js string Load config from json file. This option may be set with -j from the command line.
sqlite3, sqlite number Load config from sqlite3 db.
ldap number Load configuration from ldap server. See :doc:`LDAP` for more information.
ldap-schema Dump uWSGI ldap schema. See :doc:`LDAP` for more information.
ldap-schema-ldif Dump uWSGI ldap schema in ldif format. See :doc:`LDAP` for more information.

Config logic

.. seealso::

   :doc:`ConfigLogic`
Option Argument Description
for string For cycle.
endfor [string] End for cycle.
if-opt string Check for option.
if-not-opt string Check for lack of option.
if-env, ifenv string Check for environment variable.
if-not-env string Check for lack of environment variable.
if-reload string Check for reload.
if-not-reload string Check for lack of reload.
if-exists, ifexists string Check for file/directory existence.
if-not-exists string Check for file/directory inexistence.
if-file string Check for file existence.
if-not-file string Check for file inexistence.
if-dir, ifdir, if-directory string Check for directory existence.
if-not-dir string Check for directory inexistence.
endif [string] End if block.

Logging

.. seealso::

   :doc:`Logging`
Option Argument Description
disable-logging Disable request logging. This option may be set with -L from the command line.
ignore-sigpipe Do not report (annoying) SIGPIPE.
ignore-write-errors Do not report (annoying) write()/writev() errors.
write-errors-tolerance number Set the maximum number of allowed write errors (default: no tolerance).
write-errors-exception-only Only raise an exception on write errors giving control to the app itself.
disable-write-exception Disable exception generation on write()/writev().
logto string Set logfile/udp address.
logto2 string Log to specified file or udp address after privileges drop.
log-format, logformat string Set advanced format for request logging.
logformat-strftime, log-format-strftime Apply strftime to logformat output.
logfile-chown Chown logfiles.
logfile-chmod string Chmod logfiles.
log-syslog [string] Log to syslog.
log-socket string Send logs to the specified socket.
logger string Set/append a logger. This option may be declared multiple times.
logger-list, loggers-list List enabled loggers.
threaded-logger Offload log writing to a thread.
log-drain regexp Drain (do not show) log lines matching the specified regexp. This option may be declared multiple times.
alarm string Create a new alarm. Syntax: <alarm> <plugin:args>. This option may be declared multiple times.
alarm-freq number Tune the alarm anti-loop system (default 3 seconds).
log-alarm 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 List enabled alarms.
log-zeromq string Send logs to a ZeroMQ server.
log-master Delegate logging to master process.
log-master-bufsize number Set the buffer size for the master logger. Log messages larger than this will be truncated.
log-reopen Reopen log after reload.
log-truncate Truncate log on startup.
log-maxsize number Set maximum logfile size.
log-backupname string Set logfile name after rotation.
log-prefix, logdate, log-date [string] Prefix logs with date (without argument) or a strftime string.
log-zero Log responses without body.
log-slow number Log requests slower than the specified number of milliseconds.
log-4xx Log requests with a 4xx response.
log-5xx Log requests with a 5xx response.
log-big number Log requestes bigger than the specified size in bytes.
log-sendfile Log sendfile requests.
log-micros Report response time in microseconds instead of milliseconds.
log-x-forwarded-for Use the ip from X-Forwarded-For header instead of REMOTE_ADDR.
stats, stats-server string Enable the stats server on the specified address.
ssl-verbose Be verbose about SSL errors.
snmp string Enable the embedded SNMP server. This option may be declared multiple times.
snmp-community string Set the SNMP community string.

uWSGI Process

Option Argument Description
daemonize logfile Daemonize uWSGI, write messages into given log file or UDP socket address.
daemonize2 logfile Daemonize uWSGI after loading application, write messages into given log file or UDP socket address.
stop pidfile Send the stop (SIGINT) signal to the instance described by the pidfile.
reload pidfile Send the reload (SIGHUP) signal to the instance described by the pidfile.
pause pidfile Send the pause (SIGTSTP) signal to the instance described by the pidfile.
suspend pidfile Send the suspend (SIGTSTP) signal to the instance described by the pidfile.
resume pidfile Send the resume (SIGTSTP) signal to the instance described by the pidfile.
auto-procname Automatically set process name to something meaningful.
procname-prefix string Add prefix to process names.
procname-prefix-spaced string Add spaced prefix to process names.
procname-append string Append string to process names.
procname string Set process name.
procname-master string Set master process name.
pidfile string Create pidfile (before privileges drop).
pidfile2 string Create pidfile (after privileges drop).
chroot string Chroot() to the specified directory.
uid username|uid Setuid to the specified user/uid.
gid groupname|gid Setgid to the specified grooup/gid.
no-initgroups Disable additional groups set via initgroups().
cap string Set process capability.
unshare string Unshare() part of the processes and put it in a new namespace.
exec-pre-jail string Run the specified command before jailing. This option may be declared multiple times.
exec-post-jail string Run the specified command after jailing. This option may be declared multiple times.
exec-in-jail string Run the specified command in jail after initialization. This option may be declared multiple times.
exec-as-root string Run the specified command before privileges drop. This option may be declared multiple times.
exec-as-user string Run the specified command after privileges drop. This option may be declared multiple times.
exec-as-user-atexit string Run the specified command before app exit and reload. This option may be declared multiple times.
exec-pre-app string Run the specified command before app loading. This option may be declared multiple times.
cgroup string Put the processes in the specified cgroup. This option may be declared multiple times.
cgroup-opt string Set value in specified cgroup option. This option may be declared multiple times.
namespace, ns string Run in a new namespace under the specified rootfs.
namespace-keep-mount string Keep the specified mountpoint in your namespace. This option may be declared multiple times.
namespace-net, ns-net string Add network namespace.
forkbomb-delay number Sleep for the specified number of seconds when a forkbomb is detected.
binary-path string Force binary path.
privileged-binary-patch string Patch the uwsgi binary with a new command (before privileges drop).
unprivileged-binary-patch string Patch the uwsgi binary with a new command (after privileges drop).
privileged-binary-patch-arg string Patch the uwsgi binary with a new command and arguments (before privileges drop).
unprivileged-binary-patch-arg string Patch the uwsgi binary with a new command and arguments (after privileges drop).
async number Enable async mode with specified cores.
max-fd number Set maximum number of file descriptors (requires root privileges).
master-as-root Leave master process running as root.

Miscellaneous

Option Argument Description
skip-zero Skip check of file descriptor 0.
need-app Exit if no app can be loaded.
exit-on-reload Force exit even if a reload is requested.
die-on-term Exit instead of brutal reload on SIGTERM.
no-fd-passing Disable file descriptor passing.
single-interpreter Do not use multiple interpreters (where available). This option may be set with -i from the command line.
max-apps number Set the maximum number of per-worker applications.
sharedarea number Create a raw shared memory area of specified pages. This option may be set with -A from the command line.
cgi-mode Force CGI-mode for plugins supporting it. This option may be set with -c from the command line.
buffer-size number Set internal buffer size. This option may be set with -b from the command line.
enable-threads Enable threads. This option may be set with -T from the command line.
signal-bufsize, signals-bufsize number Set buffer size for signal queue.
socket-timeout number Set internal sockets timeout. This option may be set with -z from the command line.
max-vars number Set the amount of internal iovec/vars structures. This option may be set with -v from the command line.
weight number Weight of the instance (used by clustering/lb/subscriptions).
auto-weight number Set weight of the instance (used by clustering/lb/subscriptions) automatically.
no-server Force no-server mode.
command-mode Force command mode.
no-defer-accept Disable deferred-accept on sockets.
so-keepalive Enable TCP KEEPALIVEs.
never-swap Lock all memory pages avoiding swapping.
ksm number Enable Linux KSM. This option may be declared multiple times.
touch-reload string Reload uWSGI if the specified file is modified/touched. This option may be declared multiple times.
touch-logrotate string Trigger logrotation if the specified file is modified/touched. This option may be declared multiple times.
touch-logreopen string Trigger log reopen if the specified file is modified/touched. This option may be declared multiple times.
propagate-touch Over-engineering option for system with flaky signal mamagement.
no-orphans Automatically kill workers if master dies (can be dangerous for availability).
prio number Set processes/threads priority.
cpu-affinity number Set cpu affinity.
remap-modifier string Remap request modifier from one id to another.
env string Set environment variable (key=value).
unenv string Set environment variable (key).
close-on-exec Set close-on-exec on sockets (could be required for spawning processes in requests).
mode string Set uWSGI custom mode.
vacuum Try to remove all of the generated files/sockets upon exit.
cron string Add a cron task.
worker-exec string Run the specified command as worker.
attach-daemon string Attach a command/daemon to the master process (the command has to remain in foreground).
smart-attach-daemon pidfile Attach a command/daemon to the master process managed by a pidfile (the command must daemonize).
smart-attach-daemon2 pidfile Attach a command/daemon to the master process managed by a pidfile (the command must NOT daemonize).

Locks

Option Argument Description
locks number Create the specified number of shared locks.
lock-engine string Set the lock engine.
ftok string Set the ipcsem key via ftok() for avoiding duplicates.
flock string Lock the specified file before starting, exit if locked.
flock-wait string Lock the specified file before starting, wait if locked.
flock2 string Lock the specified file after logging/daemon setup, exit if locked.
flock-wait2 string Lock the specified file after logging/daemon setup, wait if locked.

Cache

.. seealso::

   :doc:`Caching`
Option Argument Description
cache number Create a shared cache containing given elements.
cache-blocksize number Set cache blocksize.
cache-store string Enable persistent cache to disk.
cache-store-sync number Set frequency of sync for persistent cache.
cache-server string Enable the threaded cache server.
cache-server-threads number Set the number of threads for the cache server.
cache-no-expire Disable auto sweep of expired items.
cache-expire-freq number Set the frequency of cache sweeper scans (default 3 seconds).
cache-report-freed-items Constantly report the cache item freed by the sweeper (use only for debug).

Queue

.. seealso::

   :doc:`Queue`
Option Argument Description
queue number Enable the shared queue with the given size.
queue-blocksize number Set the block size for the queue.
queue-store filename Enable periodical persisting of the queue to disk.
queue-store-sync number Set periodical persisting frequency in seconds.

Spooler

.. seealso::

   :doc:`Spooler`
Option Argument Description
spooler string Run a spooler on the specified directory. This option may be set with -Q from the command line.
spooler-external string Map spooler requests to a spooler directory managed by an external instance.
spooler-ordered Try to order the execution of spooler tasks.
spooler-chdir string Chdir() to specified directory before each spooler task.
spooler-processes number Set the number of processes for spoolers.
spooler-quiet Do not be verbose with spooler tasks.
spooler-max-tasks number Set the maximum number of tasks to run before recycling a spooler.
spooler-harakiri number Set harakiri timeout for spooler tasks.

Mules

.. seealso::

   :doc:`Mules`
Option Argument Description
mule string Add a mule (signal-only mode without argument). This option may be declared multiple times.
mules number Add the specified number of mules.
farm string Add a mule farm.
signal string Send a uwsgi signal to a server.

Application loading

Option Argument Description
chdir string Chdir to specified directory before apps loading.
chdir2 string Chdir to specified directory after apps loading.
lazy Set lazy mode (load apps in workers instead of master).
lazy-apps Load apps in each worker instead of the master.
cheap Set cheap mode (spawn workers only after the first request).
cheaper number Set cheaper mode (adaptive process spawning).
cheaper-initial number Set the initial number of processes to spawn in cheaper mode.
cheaper-algo string Choose to algorithm used for adaptive process spawning).
cheaper-step number Number of additional processes to spawn at each overload.
cheaper-overload number Increase workers after specified overload.
cheaper-algo-list, cheaper-algos-list, cheaper-list List enabled cheapers algorithms.
idle number Set idle mode (put uWSGI in cheap mode after inactivity).
die-on-idle Shutdown uWSGI when idle.
mount string Load application under mountpoint. This option may be declared multiple times.
worker-mount string Load application under mountpoint in the specified worker or after workers spawn. This option may be declared multiple times.
grunt Enable grunt mode (in-request fork).

Request handling

Option Argument Description
limit-post number Limit request body (bytes).
post-buffering number Enable post buffering past N bytes.
post-buffering-bufsize number Set buffer size for read() in post buffering mode.
upload-progress string Enable creation of .json files in the specified directory during a file upload.
no-default-app Do not fallback to default app.
manage-script-name Automatically rewrite SCRIPT_NAME and PATH_INFO.
ignore-script-name Ignore SCRIPT_NAME.
catch-exceptions Report exception as HTTP output (discouraged -- this is a security risk).
reload-on-exception Reload a worker when an exception is raised.
reload-on-exception-type string Reload a worker when a specific exception type is raised. This option may be declared multiple times.
reload-on-exception-value string Reload a worker when a specific exception value is raised. This option may be declared multiple times.
reload-on-exception-repr string Reload a worker when a specific exception type+value (language-specific) is raised. This option may be declared multiple times.
add-header string Automatically add HTTP headers to response. This option may be declared multiple times.
vhost Enable virtualhosting mode (based on SERVER_NAME variable).
vhost-host Enable virtualhosting mode (based on HTTP_HOST variable).

Clustering

Option Argument Description
multicast string Subscribe to specified multicast group.
multicast-ttl number Set multicast ttl.
cluster string Join specified uWSGI cluster.
cluster-nodes string Get nodes list from the specified cluster.
cluster-reload string Send a reload message to the cluster.
cluster-log string Send a log line to the cluster.

Subscriptions

.. seealso::

   :doc:`SubscriptionServer`
Option Argument Description
subscriptions-sign-check string Set digest algorithm and certificate directory for secured subscription system.
subscriptions-sign-check-tolerance number Set the maximum tolerance (in seconds) of clock skew for secured subscription system.
subscription-algo string Set load balancing algorithm for the subscription system.
subscription-dotsplit Try to fallback to the next part (dot based) in subscription key.
subscribe-to, st, subscribe string Subscribe to the specified subscription server. This option may be declared multiple times.
subscribe-freq number Send subscription announce at the specified interval.
subscription-tolerance number Set tolerance for subscription servers.
unsubscribe-on-graceful-reload Force unsubscribe request even during graceful reload.

Router

.. seealso::

   :doc:`InternalRouting`
Option Argument Description
route string Add a route. This option may be declared multiple times.
route-host string Add a route based on Host header. This option may be declared multiple times.
route-uri string Add a route based on REQUEST_URI. This option may be declared multiple times.
route-qs string Add a route based on QUERY_STRING. This option may be declared multiple times.
router-list, routers-list List enabled routers.

Static files

Option Argument Description
check-static, static-check string Check for static files in the specified directory. This option may be declared multiple times.
check-static-docroot Check for static files in the requested DOCUMENT_ROOT.
static-map string Map mountpoint to static directory (or file). This option may be declared multiple times.
static-map2 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 string Skip specified extension from staticfile checks. This option may be declared multiple times.
static-index string Search for specified file if a directory is requested. This option may be declared multiple times.
mimefile, mime-file string Set mime types file path (default /etc/mime.types). This option may be declared multiple times.
static-expires-type string Set the Expires header based on content type (syntax: Content-type=Expires). This option may be declared multiple times.
static-expires-type-mtime 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 string Set the Expires header based on filename regexp (syntax x=y). This option may be declared multiple times.
static-expires-mtime 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 string Set the Expires header based on REQUEST_URI regexp (syntax x=y). This option may be declared multiple times.
static-expires-uri-mtime 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 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 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 number Offload static file serving to a thread (upto the specified number of threads).
file-serve-mode string Set static file serving mode (x-sendfile, nginx, ...).
check-cache Check for response data in the cache.

Clocks

Option Argument Description
clock string Set a clock source.
clock-list, clocks-list List enabled clocks.

Loop engines

Option Argument Description
loop string Select the uWSGI loop engine.
loop-list, loops-list List enabled loop engines.