salt-api 0.8.0

We are happy to announce the release of salt-api 0.8.0.

This release encompasses bugfixes and new features for the rest_cherrypy netapi module that provides a RESTful interface for a running Salt system.


Requires Salt 0.13


In addition to the usual documentation improvements and bug fixes this release introduces the following changes and additions.

Please note the backward incompatible change detailed below.

RPM packaging

Thanks to Andrew Niemantsvedriet (@kaptk2) salt-api is now available in Fedora package repositories as well as RHEL compatible systems via EPEL.

Thanks also to Clint Savage (@herlo) and Thomas Spura (@tomspur) for helping with that process.

Ubuntu PPA packaging

Thanks to Sean Channel (@seanchannel, pentabular) salt-api is available as a PPA on the SaltStack LaunchPad team.

Authentication information on login


Backward incompatible change

The /login URL no longer responds with a 302 redirect for success.

Although this is behavior is common in the browser world it is not useful from an API so we have changed it to return a 200 response in this release.

We take backward compatibility very seriously and we apologize for the inconvenience. In this case we felt the previous behavior was limiting. Changes such as this will be rare.

New in this release is displaying information about the current session and the current user. For example:

% curl -sS localhost:8000/login \
    -H 'Accept: application/x-yaml'
    -d username='saltdev'
    -d password='saltdev'
    -d eauth='pam'

  - eauth: pam
    expire: 1365508324.359403
      - '@wheel'
      - grains.*
      - state.*
      - status.*
      - sys.*
      - test.*
    start: 1365465124.359402
    token: caa7aa2b9dbc4a8adb6d2e19c3e52be68995ef4b
    user: saltdev

Bypass session handling

A convenience URL has been added (/run) to bypass the normal session-handling process.

The REST interface uses the concept of "lowstate" data to specify what function should be executed in Salt (plus where that function is and any arguments to the function). This is a thin wrapper around Salt's various "client" interfaces, for example Salt's LocalClient() which can accept authentication credentials directly.

Authentication with the REST API typically goes through the login URL and a session is generated that is tied to a Salt external_auth token. That token is then automatically added to the lowstate for subsequent requests that match the current session.

It is sometimes useful to handle authentication or token management manually from another program or script. For example:

curl -sS localhost:8000/run \
    -d client='local' \
    -d tgt='*' \
    -d fun='' \
    -d eauth='pam' \
    -d username='saltdev' \
    -d password='saltdev'

It is a Bad Idea (TM) to do this unless you have a very good reason and a well thought out security model.


An URL has been added (/logout) that will cause the client-side to expire the session cookie and the server-side session to be invalidated.

Running the REST interface via any WSGI-compliant server

The rest_cherrypy netapi module is a regular WSGI application written using the CherryPy framework. It was written with the intent of also running from any WSGI-compliant server such as Apache and mod_wsgi, Gunicorn, uWSGI, Nginx, and FastCGI, etc.

The WSGI application entry point has been factored out into a stand-alone file in this release suitable for calling from an external server. salt-api does not need to be running in this scenario.

For example, an Apache virtual host configuration:

<VirtualHost *:80>
    ServerAlias *


    LogLevel warn
    ErrorLog /var/www/
    CustomLog /var/www/ combined

    DocumentRoot /var/www/

    WSGIScriptAlias / /path/to/salt/netapi/rest_cherrypy/


Please get involved by filing issues on GitHub, discussing on the mailing list, and chatting in #salt-devel on Freenode.