Prepare the master

Salt Shaker needs salt-api (rest_cherrypy) on the master and one account for the server to sign in with. That account doesn’t have to be a Linux user: any Salt eauth backend works.

Salt Shaker needs Salt 3006 or newer.

1. Install salt-api

sudo apt install salt-api      # or: sudo dnf install salt-api

2. Configure salt-api and the service account

Create /etc/salt/master.d/salt-shaker.conf. The recommended setup uses the sharedsecret eauth backend, so no system account is needed.

sharedsecret (recommended)

Generate a secret:

openssl rand -base64 32

/etc/salt/master.d/salt-shaker.conf

rest_cherrypy:
  port: 8000
  ssl_crt: /etc/pki/tls/certs/salt-api.crt
  ssl_key: /etc/pki/tls/private/salt-api.key

# Salt 3006+ disables all netapi clients by default
netapi_enable_clients: [local, local_async, runner, runner_async, wheel]

sharedsecret: <the generated secret>

external_auth:
  sharedsecret:
    salt-shaker:
      - '.*'
      - '@wheel'
      - '@runner'
      - '@jobs'

Salt Shaker then signs in with:

SALT_API_EAUTH=sharedsecret
SALT_API_USERNAME=salt-shaker
SALT_API_PASSWORD=<the generated secret>

The username only picks the permissions entry under external_auth.sharedsecret. Anyone who knows the secret can sign in as any user listed there, so list only salt-shaker.

PAM

A dedicated local account, used only by the server:

sudo useradd -r -M -s /usr/sbin/nologin salt-shaker
sudo passwd salt-shaker

/etc/salt/master.d/salt-shaker.conf

rest_cherrypy:
  port: 8000
  ssl_crt: /etc/pki/tls/certs/salt-api.crt
  ssl_key: /etc/pki/tls/private/salt-api.key

netapi_enable_clients: [local, local_async, runner, runner_async, wheel]

external_auth:
  pam:
    salt-shaker:
      - '.*'
      - '@wheel'
      - '@runner'
      - '@jobs'

Use SALT_API_EAUTH=pam with that account’s name and password.

Other backends, such as file or ldap, work the same way: put the account under that backend in external_auth and set SALT_API_EAUTH to its name.

Caution

The service account is as powerful as the most powerful role you hand out. Keep its password or secret in a secret store, and don’t use it for anything else. Who did what is still recorded: in Salt Shaker’s audit log, and in each job’s metadata as salt_shaker_user.

Without TLS on the same host

If Salt Shaker runs on the master itself, salt-api can listen on localhost only, without a certificate:

rest_cherrypy:
  host: 127.0.0.1
  port: 8000
  disable_ssl: True

Point SALT_API_URL at http://127.0.0.1:8000, and run the container with --network host so it can reach it.

With a self-signed or internal CA certificate

Salt Shaker checks salt-api’s certificate. If it’s self-signed (for example made with tls.create_self_signed_cert) or signed by your own CA, give the container that certificate or CA and point NODE_EXTRA_CA_CERTS at it:

docker run … -v /etc/pki/tls/certs/salt-api.crt:/certs/salt-api-ca.crt:ro \
  -e NODE_EXTRA_CA_CERTS=/certs/salt-api-ca.crt ghcr.io/pipozzz/salt-shaker:latest

In Compose, add the same volumes entry and environment variable to the salt-shaker service. The certificate must also be issued for the host name in SALT_API_URL.

If it isn’t trusted, the server says so in its log and in the UI: Cannot reach salt-api at …: its TLS certificate isn’t trusted.

3. Restart and check

sudo systemctl restart salt-master salt-api
curl -sk https://localhost:8000/login -H 'Accept: application/json' \
  -d username=salt-shaker -d password='<secret or password>' -d eauth=sharedsecret

A reply with a token and a perms list means salt-api accepts the account. Then run the container.