Configuring uWSGI

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

Note

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

See also

Configuration logic

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

Example:

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

can be written as

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

Loading configuration files

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

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

Note

More esoteric file sources, such as the Emperor, embeddedconfiguration (in two flavors), dynamic library symbols and ELF sectionscould also be used.

Magic variables

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

%vthe vassals directory (pwd)
%Vthe uWSGI version
%hthe hostname
%othe original config filename, as specified on the command line
%Osame as %o but refer to the first non-template config file(version 1.9.18)
%pthe absolute path of the configuration file
%Psame as %p but refer to the first non-template config file(version 1.9.18)
%sthe filename of the configuration file
%Ssame as %s but refer to the first non-template config file(version 1.9.18)
%dthe absolute path of the directory containing the configuration file
%Dsame as %d but refer to the first non-template config file(version 1.9.18)
%ethe extension of the configuration file
%Esame as %e but refer to the first non-template config file(version 1.9.18)
%nthe filename without extension
%Nsame as %n but refer to the first non-template config file(version 1.9.18)
%cthe name of the directory containing the config file (version 1.3+)
%Csame as %c but refer to the first non-template config file(version 1.9.18)
%tunix time (in seconds, gathered at instance startup) (version 1.9.20-dev+)
%Tunix time (in microseconds, gathered at instance startup) (version 1.9.20-dev+)
%xthe current section identifier, eg. config.ini:section (version 1.9-dev+)
%Xsame as %x but refer to the first non-template config file(version 1.9.18)
%iinode number of the file (version 2.0.1)
%Isame as %i but refer to the first non-template config file
%0..%9a specific component of the full path of the directory containing the config file (version 1.3+)
%[ANSI escape “\033” (useful for printing colors)
%kdetected cpu cores (version 1.9.20-dev+)
%uuid of the user running the process (version 2.0)
%Uusername (if available, otherwise fallback to uid) of the user running the process (version 2.0)
%ggid of the user running the process (version 2.0)
%Ggroup name (if available, otherwise fallback to gid) of the user running the process (version 2.0)
%jHEX representation of the djb33x hash of the full config path
%Jsame 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 thatfile is included from another file.

An exception are most of the uppercase versions, which refer to thefirst non-template config file loaded. This means the first config filenot loaded through —include or —inherit, but through forexample —ini, —yaml or —config. These are intended to usewith the emperor, to refer to the actual vassal config file instead oftemplates included with —vassals-include or —vassals-inherit.

For example, here’s funnyapp.ini.

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

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

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

Placeholders

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

  1. [uwsgi]
  2. ; These are placeholders...
  3. my_funny_domain = uwsgi.it
  4. set-ph = max_customer_address_space=64
  5. set-placeholder = customers_base_dir=/var/www
  6. ; And these aren't.
  7. socket = /tmp/sockets/%(my_funny_domain).sock
  8. chdir = %(customers_base_dir)/%(my_funny_domain)
  9. 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 ofregular 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 codevia uwsgi.opt.

  1. import uwsgi
  2. print uwsgi.opt['customers_base_dir']

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

Similarly, contents of environment variables and external text files canbe included using the $(ENV_VAR) and @(file_name) syntax. See alsoHow uWSGI parses config files.

Placeholders math (from uWSGI 1.9.20-dev)

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

  1. [uwsgi]
  2. foo = 17
  3. bar = 30
  4. ; total will be 50
  5. total = %(foo + bar + 3)

Remember to not miss spaces between operations.

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

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

‘total’ will be evaluated as 100:

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

Incremental and decremental shortcuts are available

  1. [uwsgi]
  2. foo = 29
  3. ; remember the space !!!
  4. bar = %(foo ++)

bar will be 30

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

  1. [uwsgi]
  2. foo = 2
  3. bar = 9
  4. ; remember the space !!!
  5. bar = %(foo bar ++)

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

The ‘@’ magic

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

  1. [uwsgi]
  2. foo = @(/tmp/foobar)

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

  1. [uwsgi]
  2. ; read from a symbol
  3. foo = @(sym://uwsgi_funny_function)
  4. ; read from binary appended data
  5. bar = @(data://0)
  6. ; read from http
  7. test = @(http://example.com/hello)
  8. ; read from a file descriptor
  9. content = @(fd://3)
  10. ; read from a process stdout
  11. body = @(exec://foo.pl)
  12. ; call a function returning a char *
  13. characters = @(call://uwsgi_func)

Command line arguments

Example:

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

Environment variables

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

Note

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

Example:

  1. UWSGI_SOCKET=127.0.0.1 UWSGI_MASTER=1 UWSGI_WORKERS=3 uwsgi

INI files

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

An example uWSGI INI configuration:

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

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

  1. uwsgi --ini myconf.ini:app1

Alternatively, you can load another section from the same file byomitting the filename and specifying just the section name. Note thattechnically, this loads the named section from the last .ini file loadedinstead of the current one, so be careful when including other files.

  1. [uwsgi]
  2. # This will load the app1 section below
  3. ini = :app1
  4. # This will load the defaults.ini file
  5. ini = defaults.ini
  6. # This will load the app2 section from the defaults.ini file!
  7. ini = :app2
  8.  
  9. [app1]
  10. plugin = rack
  11.  
  12. [app2]
  13. plugin = php
  • Whitespace is insignificant within lines.
  • Lines starting with a semicolon (;) or a hash/octothorpe (#) are ignored as comments.
  • Boolean values may be set without the value part. Simply master is thus equivalent to master=true. This may not be compatible with other INI parsers such as paste.deploy.
  • For convenience, uWSGI recognizes bare .ini arguments specially, so the invocation uwsgi myconf.ini is equal to uwsgi —ini myconf.ini.

XML files

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

An example:

  1. <uwsgi>
  2.   <socket>/tmp/uwsgi.sock</socket>
  3.   <socket>127.0.0.1:8000</socket>
  4.   <master/>
  5.   <workers>3</workers>
  6. </uwsgi>

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

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

JSON files

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

An example:

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

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

  1. {"app1": {
  2.   "plugin": "rack"
  3. }, "app2": {
  4.   "plugin": "php"
  5. }}

And then load this using:

  1. uwsgi --json myconf.json:app2

Note

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

See also

Installing uWSGI

YAML files

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

An example:

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

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

  1. app1:
  2.   plugin: rack
  3. app2:
  4.   plugin: php

And then load this using:

  1. uwsgi --yaml myconf.yaml:app2

SQLite configuration

Note

Under construction.

LDAP configuration

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