SaltPad is a GUI tool to manage SaltStack deployments + orchestration. It's still very young and it should be considered as Alpha.

A walkthrough using screenshots is available in the screenshots directory (not up-to-date).

This version of saltpad is a full-rewrite as a single app page. The old version in python is still available in the saltpad_v1 branch (https://github.com/tinyclues/saltpad/tree/saltpad_v1). If you cannot use this version, please open an issue to ease migration and see the Changelog (https://github.com/tinyclues/saltpad/blob/master/Changelog.md).

SaltPad is mainly coded in Javascript and should be compatible with all modern browsers.

SaltPad communicate with Salt through the salt-api and thus requires access to the salt-api from the browser. If this is an issue, please drop a comment on [this issue](http://github.com/tinyclues/saltpad) to discuss the possible solutions. The salt-api format / specification is not yet stable, so SaltPad could only provide limited compatibility with salt-api. The salt-api format depends on 3 variables, salt version, the netapi used (cherrypy or tornado) and the master_job_cache used for storing and retrieving jobs results.

SaltPad required some upgrade on salt-api side (for CORS support mainly) and will only work with a develop version of saltstack.

Here is the list of issues about the salt-api format standardization that would make the saltpad job much much easier:

• saltstack/salt#23131
• saltstack/salt#19018
• saltstack/salt#13698

You have several solutions to install saltpad, but before installing saltpad, you need to install and configure salt-api.

The Web GUI uses the HTTP Api of SaltStack to interact with the Salt-Master. You should first install the Salt-Api on your Salt-Master. You can find the documentation in the SaltStack documentation.

The Salt-Api project has been merged into SaltStack in release 2014.7.0, so you can use the salt-api with SaltStack 2014.7.0 release or install salt-api with previous releases, you can install it using pip:

pip install salt-api

Or if you're using a Debian-derived linux:

sudo apt-get install salt-api

The salt-api requires some configuration too. Salt-api supports multiple implementation, but the rest_tornado implementation is the more mature and the recommended one when using saltpad. If you want to run salt-api and saltpad on the same host, you can configuration salt-api as followed in the file /etc/salt/master:

rest_tornado:
  port: 5417
  host: 127.0.0.1
  disable_ssl: true
  websockets: True
  cors_origin: '*'

Warning, this configuration has ssl disabled and it only listens to localhost, if you want to expose the salt-api to the network, you should really deploy it behind nginx with ssl, do not change the host to 0.0.0.0 without proper ssl support as well!

With this salt-api configuration, the saltpad default configuration should work, if the salt-api and saltpad are not located on your device, you either could change the HOST settings in saltpad (but only for testing purposes, it will not use tls so all your data will be sent in clear text) or deploy it behind nginx with ssl configured.

Then you can launch the API using the following command:

sudo /etc/init.d/salt-api restart

Or if you want to launch salt-api by hand.

salt-api

You will also need to configure the external auth in your salt master. For example in master config:

external_auth:
  pam:
    myusername:
        - .*
        - '@runner'
        - '@wheel'

Currently SaltPad requires exactly these permissions, for various reasons. There is ongoing improvements on SaltStack part and in Saltpad to require less permissions. Saltpad will not allow you to connect if you don't have this set of permissions and will show you an error message.

You can check you salt-api installation and configuration with this command on the salt-api host:

curl -i -H accept=application/json -d username=USER -d password=PASSWORD -d eauth=pam http://localhost:5417/login

In case of successful login you should have the response body that looks like that:

{"return": [{"perms": [".*", "@runner", "@wheel"], "start": 1431010274.426576, "token": "70604a26facfe2aa14038b9abf37b639c32902bd", "expire": 1431053474.426576, "user": "salt", "eauth": "pam"}]}

If the output includes "HTTP/1.1 401 Unauthorized", double-check the salt-api config in salt-master config file.

If you just want to test SaltPad, you can use the Vagrantfile provided in vagrant directory. Just follow README in the same repository and have fun!

If your checklist is done, you can now configure SaltPad.

Get into the saltpad directory, copy the file named "settings.json.sample" as "settings.json". You will need to edit it. Set your API_URL if your salt-master is not local and if your salt-api is served over SSL, set the SECURE_HTTP key to true. You can also configure job templates in this file, see the corresponding part for more details. You will need to strip all comments starting with '#' from the file.

Here is an example of a settings.json file:

{
    "API_URL": "localhost:5417",
    "SECURE_HTTP": false,
    "templates": {
        "basic": {
            "description": "Basic template",
            "matcher": "glob",
            "target": "*",
            "moduleFunction": "test.fib",
            "arguments": {
                "num": 10
            }
        },

        "version": {
            "description": "Basic version",
            "matcher": "glob",
            "target": "Celeste",
            "moduleFunction": "test.version",
            "arguments": {}
        }
    },
    "EAUTH": "pam"
}

Job templates are now defined in the configuration file directly instead of storing them in salt master configuration file. They are stored under the "templates" key and their format are the following:

"basic": { # Template name
    "description": "Basic template", # Template description
    "matcher": "glob", # Matcher, one of salt matcher (see salt --help, Target Options)
    "target": "*", # The target
    "moduleFunction": "test.fib", # Which function
    "arguments": { # The function arguments
        "num": 10
    }
}

You can add as many templates as you want, but they need to have a distinct name.

You can install a release version of saltpad with a web server like nginx or apache.

Released versions are available on github (https://github.com/tinyclues/saltpad/releases). Download the distribution zip:

wget https://github.com/tinyclues/saltpad/releases/download/v0.1/dist.zip

Unzip to a location of your choosing:

unzip dist.zip -d /opt/saltpad

You will also need to create the file settings.json in the same directory that you have unzipped to, e.g. /opt/saltpad/settings.json. You can use the example settings.json found above (https://github.com/tinyclues/saltpad#configure-saltpad).

Then point your favorite webserver at the saltpad directory.

Warning, the following example configurations ARE NOT SUITABLE for production, for configuring a ssl enabled site with nginx or apache, you can use the excellent Mozilla SSL Configuration Generator. Configuring a website in a secure manner is a job by itself, please ask the more qualified person to do it.

For example, for an unsecured (HTTP) saltpad install with nginx, the configuration will be:

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;

    root /opt/saltpad/;
    index index.html;

    server_name SALTPAD.YOURDNS;

    location / {
            try_files $uri /index.html;
    }
}

You can put this configuration and replace the content of the file "/etc/nginx/sites-enabled/default" or ask your system administrator to configure Nginx or Apache.

Now reload the webserver:

sudo /etc/init.d/nginx reload

For an equivalent apache config on debian place the following in /etc/apache2/sites-available/saltpad.conf

<VirtualHost *:80>
  ServerName saltpad.example.com
  ServerAdmin [email protected]
  LogLevel warn
  DocumentRoot /opt/saltpad
  <Directory "/opt/saltpad">
    RewriteEngine On
    RewriteBase /
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_URI} !index
    RewriteRule (.*) /index.html [L]
    #FallbackResource /index.html
  </Directory>
  ErrorLog "/var/log/apache2/saltpad-error.log"
  CustomLog "/var/log/apache2/saltpad-access.log" combined
</VirtualHost>

Note: the much simpler 'FallbackResource' which does not require mod_rewrite, requires apache/httpd version >= 2.2.16.

Enable the site and reload apache .. code-block:: bash

sudo a2ensite saltpad sudo service apache2 reload

And now, saltpad should be available on the web server, you can check with this command:

curl http://localhost

The output should look like:

<!doctype html>
<html lang="en" data-framework="react">
  <head>
    <meta charset="utf-8">
    <title>SaltPad</title>
  <link href="/styles.css" rel="stylesheet"></head>
  <body>
    <div class="app"></div>
  <script src="/vendors.js"></script><script src="/app.js"></script></body>
</html>

There is a beginning of deployment formula located here (https://github.com/tinyclues/saltpad/blob/saltpad_v2/vagrant/salt/roots/salt/saltpad.sls), I still try to make the cleanest integration possible with the nginx-formula (https://github.com/saltstack-formulas/nginx-formula).

If you want to hack on saltpad and start the dev environment, go on the repository root and launch these commands:

npm install # install javascript dependencies
./node_modules/bower/bin/bower install # install browser dependencies
cp settings.json.sample settings.json

You can now launch the dev environment:

npm start

SaltPad will be available on localhost:3333(localhost:3333).

If an any time you want to generate a new release and as a reminder for core-developper, here is how you can generate a dist.zip:

npm run build

It should generate a dist.zip file with every required file, the dist.zip.md5 file which contains the md5sum of the dist.zip file and the dist.zip.sha1 which contains the sha1sum of the dist.zip file.

Please note that you need first to follow the Hack on saltpad instructions to have the required dependencies.

• Get overview of all your minion.
• Get details about each minions, its Salt version.
• Easy launch of state.highstate jobs with or without dry-run mode.
• Manage minion keys.
• Launch jobs.
• Access jobs details easily.
• Save job configuration as templates and launch them with one click on a button.
• Quick debug minion, get all usefull information in one place.

• When getting single job output, SaltStack renders it even if it's not necessary. This can cause severe slowdown and so slow the interface. It's a known issue in SaltStack (saltstack/salt#18518) and it's should be solved in next release. If it's a problem, you can comment this line https://github.com/saltstack/salt/blob/v2014.7.0/salt/runners/jobs.py#L102 and this line https://github.com/saltstack/salt/blob/v2014.7.0/salt/runners/jobs.py#L81 in your salt master to speed up the job retrieval system.