depends: |
|
---|---|
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 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:
See also
You can bypass the session handling via the RunSaltAPIHandler
URL.
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).
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.
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.
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
salt.netapi.rest_tornado.saltnado.
SaltClientsMixIn
¶MixIn class to container all of the salt clients that the API needs
saltclients
¶salt.netapi.rest_tornado.saltnado.
TimeoutException
¶salt.netapi.rest_tornado.saltnado.
get_batch_size
(batch, num_minions)¶Docs for previous releases are available on readthedocs.org.
Latest Salt release: 2015.8.0