Skip to content

Latest commit

 

History

History
440 lines (309 loc) · 12.2 KB

Configuration.rst

File metadata and controls

440 lines (309 loc) · 12.2 KB
Raw

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).

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

Loading configuration files

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

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.

Magic variables

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

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`.

Placeholders math (from uWSGI 1.9.20-dev)

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)

The '@' magic

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)

Command line arguments

Example:

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

.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 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:

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

YAML files

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

SQLite configuration

Note

Under construction.

LDAP configuration

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.