Welcome to SaltWebGui’s documentation!¶

SaltWebGui is a web interface to saltstack.

It aims to be reliable, easy to install and semplify the saltstack administration, both for configuration management as well as orchestration.

The project is developed on github where is possible to fill also issues and push requests.

Licence¶

Contents¶

These documents aim to get you started with SaltWebGui:

Installation¶

For running SaltWebGui it is recommended to use virtualenv in order to satisfy the dependencies (see Virtualenv).
It is also required an access to the salt-api (see Saltstack requirements for further explanation).

The components involved are:

a web server (where to run SaltWebGui)
a salt-master with accessible salt-api

It is possible to deploy the SaltWebGui’s web server on the salt-master itself (in this case the salt-api can be kept private on localhost) or to have them on different server. In the latter be careful the salt-api is made accessible to the web-server: if it is widely accessible use a proper ssl encryption.

Here follows the installation requirements, then an example for Quick installing for testing and a Reference for production installation.

Requirements¶

Analysis of minimum requirements for running SaltWebGui.

Saltstack requirements: minimum configuration for salt and its salt-api
Virtualenv: python dependency installation

Saltstack requirements¶

In order to use SaltWebGui it is required to enable salt-api on the salt master.

For example on a debian distro just install salt-api with

aptitude install salt-api

Then enable the salt-api module through the salt-master‘s configuration file. Here a quick example suitable for local test (not safe for production):

rest_cherrypy:
    disable_ssl: True
    host: 127.0.0.1
    port: 8000

And set-up proper user permission (here enable system user mylinuxuser):

external_auth:
    pam:
        mylinuxuser:
            - ".*"
            - "@runner"
            - "@wheel"

The mylinuxuser has to be a system user (it is possible to create a custom one with adduser mylinuxyser).

Note

In order to use SaltWebGui an authentication method is required. At the time of writing saltstack supports both pam and LDAP, see the eauth manual.

Virtualenv¶

On a Debian system at least the following packages are required:

aptitude install libmysqlclient-dev python-dev libffi-dev gcc

For using a virtualenv locally run

cd SaltWebGui
virtualenv ./venv
source venv/bin/activate
pip install -r requirements.txt

Now it’s possible to launch SaltWebGui from cli, like:

FLASK_APP=./wsgi.py flask run

Quick installing for testing¶

This is a quick reference for having a debuggable installation for tests. I’d recommend to install it on salt-master (and access from an ssh tunnel) or to install it locally on you system and access the salt-api through a tunnel. Here I’ll try the latter.

On salt-master:

install salt-api
```
aptitude install salt-api
```

enable salt-api adding the following configuration in /etc/salt/master adding the following options:

rest_cherrypy:
    disable_ssl: True
    host: 127.0.0.1
    port: 8000
external_auth:
    pam:
        mylinuxuser:
            - ".*"
            - "@runner"
            - "@wheel"

add mylinuxuser:
```
adduser mylinuxuser
```
restart the salt-master:
```
service salt-master restart
```

On your system:

clone the repository

git clone https://github.com/SoftwareWorkersSrl/SaltWebGui.git

install minimum required packages for pip dependency:

aptitude install libmysqlclient-dev python-dev libffi-dev gcc

set-up the virtualenv

cd saltwebgui
virtualenv ./venv
source venv/bin/activate
pip install -r requirements.txt

if the salt-api is not publicly accessible start an SSH tunnel

ssh -L 8000:127.0.0.1:8000 -o ServerAliveInterval=30 sshuser@saltmasterurl

start flask (by default it will be accessible on localhost at port 5000):

cd saltwebgui
source venv/bin/activate
FLASK_APP=./wsgi.py flask run

Warning

When deploying SaltWebGui, if deploying for production, be careful to properly secure enough the system!

Set SSL protection on both the salt-api and the SaltWebGui, and don’t forget to use an enough secure password for the salt user.

Reference for production installation¶

Sorry but this section is still to be implemented.

While waiting for more documentation, I’d suggest to user a WSGI server for running SaltWebGui (use the one that you prefer). Please also do not use the debug mode in production because of its security concerns.

User manual¶

Here a quick overview of the SaltWebGui functionality by screenshots.

Welcome to homepage!

From the homepage go to the login view (link at the right on the top bar) and perform a login:

Here we are on the panel view!

From here first let’s update the Job list (option on the left menu under Jobs’ list > Update JOBS). You will be redirect back to a list of performed jobs:

(the table is interactive for searching and sorting)

Let’s try to run an highstate job. Enter the run view at the bottom of the left menu, insert the target and run:

After performing the job, go back to the jobs’ list in order to open the launched job and see the output of the execution. If the job is still running nothing will be shown, just wait a little and update the view itself. See below here an example of the visualization of the job result (it’s live filterable by output state):

Development and contributions¶

Push requests are welcome¶

Yep, this project is under active development!

Any contribution is welcome, please push against the develop branch. If you are developing special features that required heavy and custom changes create a custom branch.

Found a bug? Fill the issue on github.

Coding style¶

Try to be conformed where possible to PEP8. If need help while using VIM I’d recommend the use of syntastic.

Principles¶

SaltWebGui is based on the python framework Flask.

By now all of the data are stored in custom variables or classes. This is valid for user management as well as for the data received from saltstack.

The first demo of the code was using directly the CLI (there is still a legacy code available under saltwebgui/sat/salt_binding.py), but now it is preferred to user the salt-api. This way is possible to run SaltWebGui on any server as long as there is an access to salt’s api.

The current implementation uses the python pepper module in order to bind to saltstack. For quick references under saltwebgui/salt/views.py are available some the following objects to interact with saltstack:

JOBS = Jobs()
JOB = Job()
KEYS = Keys()
RUN = Run()

The web interface is developed with bootstrap (and little of javascript code).