rest_cherrypy¶

A hypermedia REST API for Salt using the CherryPy framework

depends:

CherryPy Python module

configuration:

The master config may contain the following options:

port

Required

debug : False

Used during development; does not use SSL

ssl_crt

Required when debug is False

ssl_key

Required when debug is False

static

A filesystem path to static HTML/JavaScript/CSS/image assets. If this directory contains a index.html file, it will be served at the root URL when HTML is requested by a client via the Accept header.

This directory may point to a clone of the salt-ui project to bootstrap a graphical interface for interacting with Salt.

For example:

rest_cherrypy:
  port: 8000
  ssl_crt: /etc/pki/tls/certs/localhost.crt
  ssl_key: /etc/pki/tls/certs/localhost.key

The REST interface requires a secure HTTPS connection. You must provide an SSL certificate to use. If you don't already have a certificate and don't wish to buy one, you can generate a self-signed certificate using the create_self_signed_cert() function in Salt (note the dependencies for this module):

% salt-call tls.create_self_signed_cert

Content negotiation

You may request various output formats by sending the appropriate Accept header. You may also send various formats in POST and PUT requests by specifying the Content-Type.

class saltapi.netapi.rest_cherrypy.LowDataAdapter(opts)¶

The primary purpose of this handler is to provide a RESTful API to execute Salt client commands and return the response as a data structure.

Parameters:	opts -- A dictionary of options from Salt's master config (e.g. Salt's, `__opts__`)

GET()¶

The API entry point

GET /¶

An explanation of the API with links of where to go next.

Example request:

% curl -i localhost:8000

GET / HTTP/1.1
Host: localhost:8000
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

Status 200:	success
Status 401:	authentication required
Status 406:	requested Content-Type not available

POST(**kwargs)¶

The primary execution vector for the rest of the API

POST /¶

You must pass low-data in the requst body either from an HTML form or as JSON or YAML.

Example request:

% curl -si https://localhost:8000 \
        -H "Accept: application/x-yaml" \
        -H "X-Auth-Token: d40d1e1e" \
        -d client=local \
        -d tgt='*' \
        -d fun='test.ping' \
        -d arg

POST / HTTP/1.1
Host: localhost:8000
Accept: application/x-yaml
X-Auth-Token: d40d1e1e
Content-Length: 36
Content-Type: application/x-www-form-urlencoded

fun=test.ping&arg&client=local&tgt=*

Example response:

HTTP/1.1 200 OK
Content-Length: 200
Allow: GET, HEAD, POST
Content-Type: application/x-yaml

return:
- ms-0: true
  ms-1: true
  ms-2: true
  ms-3: true
  ms-4: true

Form lowstate:	lowstate data appropriate for the client interface you are calling. Lowstate may be supplied in any supported format by specifying the Content-Type header in the request. Supported formats are listed in the Alternates response header.
Status 200:	success
Status 401:	authentication required
Status 406:	requested Content-Type not available

class saltapi.netapi.rest_cherrypy.Login(opts)¶

All interactions with this REST API must be authenticated. Authentication is performed through Salt's eauth system. You must set the eauth backend and allowed users by editing the external_auth section in your master config.

Authentication credentials are passed to the REST API via a session id in one of two ways:

If the request is initiated from a browser it must pass a session id via a cookie and that session must be valid and active.

If the request is initiated programmatically, the request must contain a X-Auth-Token header with valid and active session id.

GET()¶

Present the login interface

GET /login¶

An explanation of how to log in.

Example request:

% curl -i localhost:8000/login

GET /login HTTP/1.1
Host: localhost:8000
Accept: text/html

Example response:

HTTP/1.1 200 OK
Content-Type: text/html

Status 401:	authentication required
Status 406:	requested Content-Type not available

POST(**kwargs)¶

Authenticate against Salt's eauth system. Returns a session id and redirects on success.

POST /login¶

Example request:

% curl -si localhost:8000/login \
        -H "Accept: application/json" \
        -d username='saltuser' \
        -d password='saltpass' \
        -d eauth='pam'

POST / HTTP/1.1
Host: localhost:8000
Content-Length: 97
Content-Type: application/x-www-form-urlencoded

username=saltuser&password=saltpass&eauth=pam

Example response:

HTTP/1.1 302 Found
Content-Length: 97
Location: http://localhost:8000/
X-Auth-Token: 6d1b722e
Set-Cookie: session_id=6d1b722e; expires=Sat, 17 Nov 2012 03:23:52 GMT; Path=/

Form eauth:	the eauth backend configured in your master config
Form username:	username
Form password:	password
Status 302:	success
Status 406:	requested Content-Type not available

class saltapi.netapi.rest_cherrypy.Minions(opts)¶

GET(mid=None)¶

A convenience URL for getting lists of minions or getting minion details

GET /minions/(mid)¶

Get grains, modules, functions, and inline function documentation for all minions or a single minion

Example request:

% curl -i localhost:8000/minions/ms-3

GET /minions/ms-3 HTTP/1.1
Host: localhost:8000
Accept: application/x-yaml

Example response:

HTTP/1.1 200 OK
Content-Length: 129005
Content-Type: application/x-yaml

return:
- ms-3:
    grains.items:
      ...

Parameters:	mid -- (optional) a minion id
Status 200:	success
Status 401:	authentication required
Status 406:	requested Content-Type not available

POST(**kwargs)¶

Start an execution command and immediately return the job id

POST /minions¶

You must pass low-data in the requst body either from an HTML form or as JSON or YAML. The client option is pre-set to local_async.

Example request:

% curl -sSi localhost:8000/minions \
    -H "Accept: application/x-yaml" \
    -d tgt='*' \
    -d fun='status.diskusage'

POST /minions HTTP/1.1
Host: localhost:8000
Accept: application/x-yaml
Content-Length: 26
Content-Type: application/x-www-form-urlencoded

tgt=*&fun=status.diskusage

Example response:

HTTP/1.1 202 Accepted
Content-Length: 86
Content-Type: application/x-yaml

- return:
    jid: '20130118105423694155'
    minions: [ms-4, ms-3, ms-2, ms-1, ms-0]

Form lowstate:	lowstate data for the `LocalClient`; the `client` parameter will be set to `local_async` Lowstate may be supplied in any supported format by specifying the Content-Type header in the request. Supported formats are listed in the Alternates response header.
Status 202:	success
Status 401:	authentication required
Status 406:	requested Content-Type not available

class saltapi.netapi.rest_cherrypy.Jobs(opts)¶

GET(jid=None)¶

A convenience URL for getting lists of previously run jobs or getting the return from a single job

GET /jobs/(jid)¶

Get grains, modules, functions, and inline function documentation for all minions or a single minion

Example request:

% curl -i localhost:8000/jobs

GET /jobs HTTP/1.1
Host: localhost:8000
Accept: application/x-yaml

Example response:

HTTP/1.1 200 OK
Content-Length: 165
Content-Type: application/x-yaml

return:
- '20121130104633606931':
    Arguments:
    - '3'
    Function: test.fib
    Start Time: 2012, Nov 30 10:46:33.606931
    Target: ms-3
    Target-type: glob

Example request:

% curl -i localhost:8000/jobs/20121130104633606931

GET /jobs/20121130104633606931 HTTP/1.1
Host: localhost:8000
Accept: application/x-yaml

Example response:

HTTP/1.1 200 OK
Content-Length: 73
Content-Type: application/x-yaml

return:
- ms-3:
  - - 0
    - 1
    - 1
    - 2
  - 9.059906005859375e-06

Parameters:	mid -- (optional) a minion id
Status 200:	success
Status 401:	authentication required
Status 406:	requested Content-Type not available