salt.netapi.rest_tornado.saltnado module

A non-blocking REST API for Salt

depends:
  • tornado Python module
configuration:

All authentication is done through Salt's external auth system which requires additional configuration not described here.

In order to run rest_tornado with the salt-master add the following to the Salt master config file.

rest_tornado:
    # can be any port
    port: 8000
    # address to bind to (defaults to 0.0.0.0)
    address: 0.0.0.0
    # socket backlog
    backlog: 128
    ssl_crt: /etc/pki/api/certs/server.crt
    # no need to specify ssl_key if cert and key
    # are in one single file
    ssl_key: /etc/pki/api/certs/server.key
    debug: False
    disable_ssl: False
    webhook_disable_auth: False

Authentication

Authentication is performed by passing a session token with each request. Tokens are generated via the SaltAuthHandler URL.

The token may be sent in one of two ways:

  • Include a custom header named X-Auth-Token.
  • Sent via a cookie. This option is a convenience for HTTP clients that automatically handle cookie support (such as browsers).

See also

You can bypass the session handling via the RunSaltAPIHandler URL.

Usage

Commands are sent to a running Salt master via this module by sending HTTP requests to the URLs detailed below.

Content negotiation

This REST interface is flexible in what data formats it will accept as well as what formats it will return (e.g., JSON, YAML, x-www-form-urlencoded).

  • Specify the format of data in the request body by including the Content-Type header.
  • Specify the desired data format for the response body with the Accept header.

Data sent in POST and PUT requests must be in the format of a list of lowstate dictionaries. This allows multiple commands to be executed in a single HTTP request.

lowstate

A dictionary containing various keys that instruct Salt which command to run, where that command lives, any parameters for that command, any authentication credentials, what returner to use, etc.

Salt uses the lowstate data format internally in many places to pass command data between functions. Salt also uses lowstate for the LocalClient() Python API interface.

The following example (in JSON format) causes Salt to execute two commands:

[{
    "client": "local",
    "tgt": "*",
    "fun": "test.fib",
    "arg": ["10"]
},
{
    "client": "runner",
    "fun": "jobs.lookup_jid",
    "jid": "20130603122505459265"
}]

Multiple commands in a Salt API request will be executed in serial and makes no gaurantees that all commands will run. Meaning that if test.fib (from the example above) had an exception, the API would still execute "jobs.lookup_jid".

Responses to these lowstates are an in-order list of dicts containing the return data, a yaml response could look like:

- ms-1: true
  ms-2: true
- ms-1: foo
  ms-2: bar

In the event of an exception while executing a command the return for that lowstate will be a string, for example if no minions matched the first lowstate we would get a return like:

- No minions matched the target. No command was sent, no jid was assigned.
- ms-1: true
  ms-2: true

x-www-form-urlencoded

Sending JSON or YAML in the request body is simple and most flexible, however sending data in urlencoded format is also supported with the caveats below. It is the default format for HTML forms, many JavaScript libraries, and the curl command.

For example, the equivalent to running salt '*' test.ping is sending fun=test.ping&arg&client=local&tgt=* in the HTTP request body.

Caveats:

  • Only a single command may be sent per HTTP request.

  • Repeating the arg parameter multiple times will cause those parameters to be combined into a single list.

    Note, some popular frameworks and languages (notably jQuery, PHP, and Ruby on Rails) will automatically append empty brackets onto repeated parameters. E.g., arg=one, arg=two will be sent as arg[]=one, arg[]=two. This is not supported; send JSON or YAML instead.

class salt.netapi.rest_tornado.saltnado.EventListener(mod_opts, opts)

Class responsible for listening to the salt master event bus and updating futures. This is the core of what makes this async, this allows us to do non-blocking work in the main processes and "wait" for an event to happen

clean_timeout_futures(request)

Remove all futures that were waiting for request request since it is done waiting

get_event(request, tag='', callback=None, timeout=None)

Get an event (async of course) return a future that will get it later

class salt.netapi.rest_tornado.saltnado.SaltClientsMixIn

MixIn class to container all of the salt clients that the API needs

saltclients
exception salt.netapi.rest_tornado.saltnado.TimeoutException
salt.netapi.rest_tornado.saltnado.get_batch_size(batch, num_minions)
Return the batch size that you should have
batch: string num_minions: int

Docs for previous releases are available on readthedocs.org.

Latest Salt release: 2015.8.0

Table Of Contents