SaltGUI

SaltGUI is an open source web interface for managing a SaltStack server and its minions. Built using vanilla ES6 and implemented as a wrapper around the rest_cherrypy server a.k.a. salt-api.

Security Note: For production deployments, TLS encryption is strongly recommended. See TLS Configuration for complete setup instructions.

The version tagged release is the latest released version. The version master should be fine, but it may contain changes that are not yet in these release-notes.

See SaltGUI documentation for the complete documentation.

IMPORTANT: since Salt version 3006, it is needed to add the configuration option netapi_enable_clients to allow salt-api - and thus SaltGUI - to work. See also netapi-enable-clients.html. Additionally, any Python packages that the SaltStack installation also depends on, must be installed with salt-pip. This includes authentication plugins such as yubico_client, or execution modules such as boto3_sns.

IMPORTANT: The SaltGUI team can only support SaltStack versions 3006 and higher. Versions before that are no longer published by the SaltStack team. That makes it very hard to perform proper testing for SaltGUI releases. We suggest to upgrade the SaltStack installation when you are still using a version that is older than that.

Screenshots

Features

• Simple setup without the need to add a database
• Login via PAM or any other supported authentication by Salt
• View minions and easily copy IPs
• Run state.highstate for a particular minion or all
• View the seven most recent jobs run on Salt
• Manually run any Salt function and see the output
• View highstate for all minions with details
• View issues for all minions with trivial solutions
• View the values for grains for a particular minion
• View the schedules for a particular minion
• View the values for pillars for a particular minion
• View the beacons for a particular minion
• View the live events on the salt-event bus
• View internal documentation for any salt command
• View external documentation for any salt command
• View minions organized by node-group
• View details optionally in a separate windows
• Define your own custom documentation for commands
• Match list of minions against reference list
• Match status of minions against reference list
• Keyboard control for top-level navigation
• Keyboard control to apply templates
• Choose between live info and cached info for grains/pillar
• View details of orchestrations and allow to start them

Quick start using PAM as authentication method

• Install salt-api - this is available in the Salt repo which should already be known if you're using Salt
• Open the master config /etc/salt/master
• Find external_auth and configure as following (see the note below!):

external_auth:
    pam:
        saltuser1:
            - .*
            - '@runner'
            - '@wheel'
            - '@jobs'

# for SaltStack 3006 and higher
netapi_enable_clients:
    - local
    - local_async
    - runner
    - wheel

• See Permissions for more restricted security configurations.
• The username 'saltuser1' is only an example. Generic accounts are not recommended, use personal accounts instead. Or use a user-group, see EAUTH for details.
• Multiple entries like saltuser1 can be added when you have multiple users.
• saltuser1 is a unix (PAM) user, make sure it exists or create a new one.
• At the bottom of this file, also setup the rest_cherrypy server to access SaltGUI from "http://localhost:3333" (or on any of the hostnames that the server has):

rest_cherrypy:
    port: 3333
    host: 0.0.0.0
    disable_ssl: true
    app: /srv/saltgui/index.html
    static: /srv/saltgui/static
    static_path: /static

• Note that the cherrypy server is part of the salt-api package and has no separate installation. It is configured using the master configuration file. When configured using the above configurations, both the api calls and the html/js files are served by the cherrypy server. Therefore no additional web application server is needed.
• Note that from the SaltGUI GIT repository, only the directory saltgui forms the actual SaltGUI web application.
• Replace each of the /srv/saltgui in the above config with the actual saltgui directory from the GIT repository. Alternatively, you can create a soft-link /src/saltgui that points to the actual saltgui directory.
• To successfully use salt-api with a default PAM setup, if may be needed to grant read access on /etc/shadow to the salt user. This is best done using sudo usermod --append --groups shadow salt.
• Restart everything with pkill salt-master && pkill salt-api && salt-master -d && salt-api -d
• You should be good to go. If you have any problems, open a GitHub issue.

For TLS configuration, see the dedicated TLS Configuration section below for comprehensive setup instructions including enterprise best practices.

Note: With this configuration, the user has access to all salt modules available, maybe this is not what you want

Please read Permissions for more information.

Authentication

SaltGUI supports the following authentication methods supported by salt:

• pam
• file
• ldap
• mysql
• yubico

Since pam by itself is already very powerfull, that one is mentionned as standard. By default, it provides access to the Linux password file. When other authentication methods need to be used, their names can be added to file saltgui/static/salt-auth.txt. There is one name per line in that file. Choose the authentication methods that are activated in the salt-master configuration wisely, as the integrity of the salt-master and all salt-minions depends on it.

When a line CLEAR is present in the configuration file, then only the methods listed in the configuration file are shown. When only one method is listed, the corresponding dropdown-box will not be visible on the login panel. In that case, that method will always be used.

Note that SaltGUI cannot inspect the master file to see which authentication methods are actually in use. This is because the salt-api can only read the file after login.

Note that adding the rest authentication method in configuration section external_auth forces the parameter keep_acl_in_token to become true. That again changes the behavior of the other authentication methods and may lead to unexpected authentication problems.

When the file is absent or empty, the defaults apply. Use an empty file to prevent the otherwise harmless 404 error.

See the EAUTH documentation and the Salt auth source code for more information.

Browser tabs

SaltGUI is a single page web-application. In cases where you would zoom in on details, it is possible to open a new browser tab with the requested details. Use CTRL-click to open the page in a new tab. Use ALT-click to open the page in a new tab and also make that the current tab. This works for clicks on table-rows and for clicks on popup-menu items. These functions are a bit browser-dependent, but all major browsers seem to follow this behavior. When a new tab is opened by SaltGUI, it does not contain the menu bar items, secondary panels or a close-button inside the page.

Command Box

SaltGUI supports entry of commands using the "command-box". Click on >_ in the top right corner to open it.

Enter salt-run commands with the prefix runners.. e.g. runners.jobs.last_run. The target field can remain empty in that case as it is not used.

Enter salt-call commands with the prefix wheel.. e.g. wheel.key.finger. The target field will be added as named parameter target. But note that that parameter may not actually be used depending on the command.

Enter regular commands without special prefix. e.g. test.ping. The command is sent to the minions specified in the target field.

The text ##connected in the target field will be immediatelly replaced by the list of connected minions, or with * when all minions are connected, or with an expression when that is shorter.

Commands can be run normally, in which case the command runs to completion and shows the results. Alternatively, it can be started asynchronously, in which case only a bit of progress information is shown. When variable state_events is set to true, then the progress is shown per state when applicable. Batch commands are not supported at this time.

When executing commands, the setting for api-flag full_return is taken from option saltgui_full_return in salt master configuration file /etc/salt/master. When set to true, this will result in some more information available in the execution result, e.g. the job-id. This flag may (or may not) be applied to the internal commands that SaltGUI uses to show information.

Output

SaltGUI shows the data that is returned by the Salt API. Some variation can be achieved by modifying salt master configuration file /etc/salt/master. e.g. (the default)

saltgui_output_formats: doc,saltguihighstate,json

doc allows reformatting of documentation output into more readable format. Also implies that only the result from one minion is used. saltguihighstate allows reformatting of highstate data in a sorted and more readable format. json, yaml and nested specify how a