uWSGI can be configured using several different methods. All configuration methods may be mixed and matched in the same invocation of uWSGI.
Note
Some of the configuration methods may require a specific plugin (ie. sqlite and ldap).
.. seealso:: :doc:`ConfigLogic`
The configuration system is unified, so each command line option maps 1:1 with entries in the config files.
Example:
uwsgi --http-socket :9090 --psgi myapp.pl
can be written as
[uwsgi]
http-socket = :9090
psgi = myapp.pl
uWSGI supports loading configuration files over several methods other than simple disk files:
uwsgi --ini http://uwsgi.it/configs/myapp.ini # HTTP uwsgi --xml - # standard input uwsgi --yaml fd://0 # file descriptor uwsgi --json 'exec://nc 192.168.11.2:33000' # arbitrary executable
Note
If the configuration file type is not specified in the parameter list (e.g. --ini, --xml, etc.), uwsgi tries to deduce the file type from the filename extension. If the extension is not a supported file type, uwsgi displays the message "unable to load configuration from..." and exits.
Note
More esoteric file sources, such as the :doc:`Emperor<Emperor>`, embedded configuration (in two flavors), dynamic library symbols and ELF sections could also be used.
uWSGI configuration files can include "magic" variables, prefixed with a percent sign. Currently the following magic variables (you can access them in Python via :py:data:`uwsgi.magic_table`) are defined.
%v | the vassals directory (pwd) |
%V | the uWSGI version |
%h | the hostname |
%o | the original config filename, as specified on the command line |
%O | same as %o but refer to the first non-template config file (version 1.9.18) |
%p | the absolute path of the configuration file |
%P | same as %p but refer to the first non-template config file (version 1.9.18) |
%s | the filename of the configuration file |
%S | same as %s but refer to the first non-template config file (version 1.9.18) |
%d | the absolute path of the directory containing the configuration file |
%D | same as %d but refer to the first non-template config file (version 1.9.18) |
%e | the extension of the configuration file |
%E | same as %e but refer to the first non-template config file (version 1.9.18) |
%n | the filename without extension |
%N | same as %n but refer to the first non-template config file (version 1.9.18) |
%c | the name of the directory containing the config file (version 1.3+) |
%C | same as %c but refer to the first non-template config file (version 1.9.18) |
%t | unix time (in seconds, gathered at instance startup) (version 1.9.20-dev+) |
%T | unix time (in microseconds, gathered at instance startup) (version 1.9.20-dev+) |
%x | the current section identifier, eg. config.ini:section (version 1.9-dev+) |
%X | same as %x but refer to the first non-template config file (version 1.9.18) |
%i | inode number of the file (version 2.0.1) |
%I | same as %i but refer to the first non-template config file |
%0..%9 | a specific component of the full path of the directory containing the config file (version 1.3+) |
%[ | ANSI escape "\033" (useful for printing colors) |
%k | detected cpu cores (version 1.9.20-dev+) |
%u | uid of the user running the process (version 2.0) |
%U | username (if available, otherwise fallback to uid) of the user running the process (version 2.0) |
%g | gid of the user running the process (version 2.0) |
%G | group name (if available, otherwise fallback to gid) of the user running the process (version 2.0) |
%j | HEX representation of the djb33x hash of the full config path |
%J | same as %j but refer to the first non-template config file |
Note that most of these refer to the file they appear in, even if that file is included from another file.
An exception are most of the uppercase versions, which refer to the
first non-template config file loaded. This means the first config file
not loaded through --include
or --inherit
, but through for
example --ini
, --yaml
or --config
. These are intended to use
with the emperor, to refer to the actual vassal config file instead of
templates included with --vassals-include
or --vassals-inherit
.
For example, here's :file:`funnyapp.ini`.
[uwsgi]
socket = /tmp/%n.sock
module = werkzeug.testapp:test_app
processes = 4
master = 1
%n
will be replaced with the name of the config file, without extension, so the result in this case will be
[uwsgi]
socket = /tmp/funnyapp.sock
module = werkzeug.testapp:test_app
processes = 4
master = 1
Placeholders are custom magic variables defined during configuration time by setting a new configuration variable of your own devising.
[uwsgi]
; These are placeholders...
my_funny_domain = uwsgi.it
set-ph = max_customer_address_space=64
set-placeholder = customers_base_dir=/var/www
; And these aren't.
socket = /tmp/sockets/%(my_funny_domain).sock
chdir = %(customers_base_dir)/%(my_funny_domain)
limit-as = %(max_customer_address_space)
Placeholders can be assigned directly, or using the set-placeholder
/ set-ph
option. These latter options can be useful to:
- Make it more explicit that you're setting placeholders instead of regular options.
- Set options on the commandline, since unknown options like
--foo=bar
are rejected but--set-placeholder foo=bar
is ok. - Set placeholders when strict mode is enabled.
Placeholders are accessible, like any uWSGI option, in your application code via :py:data:`uwsgi.opt`.
import uwsgi
print uwsgi.opt['customers_base_dir']
This feature can be (ab)used to reduce the number of configuration files required by your application.
Similarly, contents of environment variables and external text files can be included using the $(ENV_VAR) and @(file_name) syntax. See also :doc:`ParsingOrder`.
You can apply math formulas to placeholders using this special syntax:
[uwsgi]
foo = 17
bar = 30
; total will be 50
total = %(foo + bar + 3)
Remember to not miss spaces between operations.
Operations are executed in a pipeline (not in common math style):
[uwsgi]
foo = 17
bar = 30
total = %(foo + bar + 3 * 2)
'total' will be evaluated as 100:
(((foo + bar) + 3) * 2)
Incremental and decremental shortcuts are available
[uwsgi]
foo = 29
; remember the space !!!
bar = %(foo ++)
bar will be 30
If you do not specify an operation between two items, 'string concatenation' is assumed:
[uwsgi]
foo = 2
bar = 9
; remember the space !!!
bar = %(foo bar ++)
the first two items will be evaluated as '29' (not 11 as no math operation has been specified)
We have already seen we can use the form @(filename) to include the contents of a file
[uwsgi]
foo = @(/tmp/foobar)
the truth is that '@' can read from all of the supported uwsgi schemes
[uwsgi]
; read from a symbol
foo = @(sym://uwsgi_funny_function)
; read from binary appended data
bar = @(data://0)
; read from http
test = @(http://example.com/hello)
; read from a file descriptor
content = @(fd://3)
; read from a process stdout
body = @(exec://foo.pl)
; call a function returning a char *
characters = @(call://uwsgi_func)
Example:
uwsgi --socket /tmp/uwsgi.sock --socket 127.0.0.1:8000 --master --workers 3
When passed as environment variables, options are capitalized and prefixed with UWSGI_, and dashes are substituted with underscores.
Note
Several values for the same configuration variable are not supported with this method.
Example:
UWSGI_SOCKET=127.0.0.1 UWSGI_MASTER=1 UWSGI_WORKERS=3 uwsgi
.INI files are a de facto standard configuration format used by many
applications. It consists of [section]
s and key=value
pairs.
An example uWSGI INI configuration:
[uwsgi]
socket = /tmp/uwsgi.sock
socket = 127.0.0.1:8000
workers = 3
master = true
By default, uWSGI uses the [uwsgi]
section, but you can specify another
section name while loading the INI file with the syntax filename:section
,
that is:
uwsgi --ini myconf.ini:app1
Alternatively, you can load another section from the same file by omitting the filename and specifying just the section name. Note that technically, this loads the named section from the last .ini file loaded instead of the current one, so be careful when including other files.
[uwsgi]
# This will load the app1 section below
ini = :app1
# This will load the defaults.ini file
ini = defaults.ini
# This will load the app2 section from the defaults.ini file!
ini = :app2
[app1]
plugin = rack
[app2]
plugin = php
- Whitespace is insignificant within lines.
- Lines starting with a semicolon (
;
) or a hash/octothorpe (#
) are ignored as comments. - Boolean values may be set without the value part. Simply
master
is thus equivalent tomaster=true
. This may not be compatible with other INI parsers such aspaste.deploy
. - For convenience, uWSGI recognizes bare
.ini
arguments specially, so the invocationuwsgi myconf.ini
is equal touwsgi --ini myconf.ini
.
The root node should be <uwsgi>
and option values text nodes.
An example:
<uwsgi>
<socket>/tmp/uwsgi.sock</socket>
<socket>127.0.0.1:8000</socket>
<master/>
<workers>3</workers>
</uwsgi>
You can also have multiple <uwsgi>
stanzas in your file, marked with
different id
attributes. To choose the stanza to use, specify its id after
the filename in the xml
option, using a colon as a separator. When using
this id mode, the root node of the file may be anything you like. This will
allow you to embed uwsgi
configuration nodes in other XML files.
<i-love-xml>
<uwsgi id="turbogears"><socket>/tmp/tg.sock</socket></uwsgi>
<uwsgi id="django"><socket>/tmp/django.sock</socket></uwsgi>
</i-love-xml>
- Boolean values may be set without a text value.
- For convenience, uWSGI recognizes bare
.xml
arguments specially, so the invocationuwsgi myconf.xml
is equal touwsgi --xml myconf.xml
.
The JSON file should represent an object with one key-value pair, the key being "uwsgi" and the value an object of configuration variables. Native JSON lists, booleans and numbers are supported.
An example:
{"uwsgi": {
"socket": ["/tmp/uwsgi.sock", "127.0.0.1:8000"],
"master": true,
"workers": 3
}}
Again, a named section can be loaded using a colon after the filename.
{"app1": {
"plugin": "rack"
}, "app2": {
"plugin": "php"
}}
And then load this using:
uwsgi --json myconf.json:app2
Note
The Jansson library is required during uWSGI build time to enable JSON support. By default the presence of the library will be auto-detected and JSON support will be automatically enabled, but you can force JSON support to be enabled or disabled by editing your build configuration.
.. seealso:: :doc:`Install`
The root element should be uwsgi. Boolean options may be set as true or 1.
An example:
uwsgi:
socket: /tmp/uwsgi.sock
socket: 127.0.0.1:8000
master: 1
workers: 3
Again, a named section can be loaded using a colon after the filename.
app1:
plugin: rack
app2:
plugin: php
And then load this using:
uwsgi --yaml myconf.yaml:app2
Note
Under construction.
LDAP is a flexible way to centralize configuration of large clusters of uWSGI servers. Configuring it is a complex topic. See :doc:`LDAP` for more information.