Salt API

Salt per HTTP fernsteuern

API installieren

yum install salt-api      # RedHat,CentOS
apt-get install salt-api  # Debian, Ubuntu

Konfiguration

Die nachfolgend verwendete PAM-Autentifizierung verlangt, dass der Salt-Master Leserechte für die Dateien/etc/shadow und /etc/gshadow besitzt.

Seit Version 3006 wird der Salt-Master nicht mehr mit Root-User ausgeführt.

Auf Debian und Ubuntu fügen Sie den salt User zur Gruppe shadow hinzu, um die Leseberechtigung zu erreichen.

usermod -a -G shadow salt

Um die API zu aktivieren, fügen Sie die folgenden Zeilen in eine neue Datei /etc/salt/master.d/api.conf ein:

/etc/salt/master.d/api.conf

external_auth:
  pam:
    salt-api:
      - .*
      - '@wheel'
      - '@runner'

rest_cherrypy:
  host: 127.0.0.1 # omit to listen on all IPs
  port: 8000
  disable_ssl: true
  debug: true
  
netapi_enable_clients: [local]

Starten Sie nach der Änderung der Konfiguration den Salt-Master und die API neu.

service salt-master restart
service salt-api restart

Es können weitreichende Einschränkungen pro User konfiguriert werden, um nicht alle Funktionen und alle Minions über die API verfügbar zu machen. Siehe offizielle Dokumentation.

Dieses einfache Beispiel sollten Sie nicht in den produktiven Betrieb übernehmen. Die API verwendet kein SSL (HTTPS) und der Benutzer hat uneingeschränkte Rechte.

Einen Benutzer anlegen

useradd -m -d /var/lib/salt-api -r -s /usr/sbin/nologin salt-api
passwd salt-api # 123ab

Zugriffe auf Key-Verwaltung beschränken

external_auth:
  pam:
    salt-api:
      - '@wheel':
        - keys*

API Zugriffe auf Minions und Funktionen beschränken

external_auth:
  pam:
    salt-api:
      - 'ubuntu*':        # Limit to Minions
        - test.ping       # Limit to a function

Testen

Erster Test

curl -s http://salt:8000/login \
    -H 'Accept: application/x-yaml' \
    -d username=salt-api \
    -d password=123ab \
    -d eauth=pam

Anmelden und API Token holen

curl -s http://salt:8000/login \
    -H 'Accept: application/x-yaml' \
    -d username=salt-api \
    -d password=123ab \
    -d eauth=pam|grep token|awk '{print $2}'>/tmp/token

Eine Anfrage stellen, z.B. salt '*' test.ping über die API auslösen.

curl -s http://salt:8000 \
    -H 'Accept: application/x-yaml' \
    -H "X-Auth-Token: $(cat /tmp/token)"\
    -d client=local \
    -d tgt='*' \
    -d fun=test.ping

Als Rückgabeformat kann auch JSON gewählt werden.

$ curl -s http://salt:8000 \
    -H 'Accept: application/json' \
    -H "X-Auth-Token: $(cat /tmp/token)"\
    -d client=local \
    -d tgt='*' \
    -d fun=test.ping|jq
{
  "return": [
    {
      "rachel": true,
      "sara": true,
      "loadbalancer": true,
      "susan": true,
      "ruby": true
    }
  ]
}

API Anfragen können auch ohne Token an den /run Endpunkt gesendet werden. Benutzername, Password und Authentifizierungsmethode müssen dann im Body enthalten sein.

curl -s http://salt:8000/run \
    -H 'Accept: application/x-yaml'\
    -d username=salt-api \
    -d password=123ab \
    -d eauth=pam \
    -d client=local\
    -d tgt='*' \
    -d fun="test.ping"

Ein simples Python-Beispiel

#!/usr/bin/env python3

#
# a simple request to the salt API
#
import requests

headers = {"Accept": "application/json"}

payload = {
        "client": "local",
        "tgt": '*',
        "username": 'salt-api',
        "password": '123ab',
        "eauth": "pam",
        "fun": "test.ping" 
        }
r = requests.post('http://127.0.0.1:8000/run', headers=headers, json=payload)
print(r.text)

State.apply per API durchführen

curl -sSk http://salt:8000 \
    -H 'Accept: application/x-yaml'\
    -H "X-Auth-Token: $(cat /tmp/token)"\
    -d client=local\
    -d tgt='*' \
    -d fun="state.apply" \
    -d arg="test" \
    -d arg="timeout=20"

Beding durch einen Fehler, erwartet die API arg immer als Liste. Sie müssen mindestens zwei Argumente arg="X" angeben, wenn die Funktion mit Argumenten ergänzt werden soll. Geben Sie beispielsweise den Timeout an, obwohl dies nicht zwingend notwendig ist.

Alternativ formatieren Sie arg als Liste, z. B. -d '["arg=test"]'.

Asynchrone Requests durchführen

Egal, ob Sie einen Salt »Befehl« über die Kommandozeile oder die API durchführen, ja nach Anzahl der adressierten Minions und der verwendeten Module oder States kann der Lauf sehr lange dauern. Wenn Sie eigene Applikationen auf Basis der API entwickeln, müssen HTTP Clients u.U. sehr lange auf eine Antwort warten. Ein asynchrones Ausführen ist oft ratsamer. Die API beendet die HTTP Anfrage sofort und gibt eine Job-ID zurück. Die Jobs laufen dann im Hintergrund. Anschließend kann man periodisch im Job-Cache nachschauen, welcher Minion den Job bereits abgearbeitet hat und mit welchem Ergebnis.

curl -sSk http://salt:8000 \
    -H "Accept: application/x-yaml" \
    -H "X-Auth-Token: $(cat /tmp/token)"\
    -d tgt='*' \
    -d fun=test.ping \
    -d client=local_async

curl -sSk http://salt:8000/jobs/<JOBID>\
    -H "Accept: application/x-yaml" \
    -H "X-Auth-Token: $(cat /tmp/token)"

Wenn Sie einen MySQL-Jobcache aktiviert haben, können Sie das Ergebnis eines asynchronen Jobs auch aus der Datenbank lesen.

mysql> select `id`,`return` from salt_returns where jid="20190826163228330773";
+----+--------+
| id | return |
+----+--------+
| u1 | true   |
| u2 | true   |
| u3 | true   |
| u4 | true   |
+----+--------+
4 rows in set (0.00 sec)

Pillars per API schreiben

curl -sS http://salt:8000 \
  -H "Accept: application/x-yaml" \
  -H "X-Auth-Token: $(cat /tmp/token)" \
  -d fun=pillar_roots.write \
  -d client=wheel \
  -d path=new_file.sls -d data='
stuff:
   goes:
     here: True
'

Wenn ein API-User uneingeschränkte @wheel Rechte hat, kann er die vollständige Kontrolle über das Betriebssystem übernehmen.

Die Funktionen pillar_roots.read und pillar_roots.writekönnen auf das komplette Dateisystem zugreifen. Lesend und schreibend!

curl -sS http://salt:8000 -H "Accept: application/x-yaml" -H "X-Auth-Token: $(cat /tmp/token)" -d fun=pillar_roots.read -d client=wheel -d path=../../etc/passwd

Einen neuen Minion registrieren

Prüfen, ob für einen Minion schon Zertifikate generiert wurden:

curl -sSk http://salt:8000/keys \
    -H 'Accept: application/x-yaml' \
    -H "X-Auth-Token: $(cat /tmp/token)"

Wenn kein Zertifikat vorhanden, ein neues generieren und downloaden. Der Download besteht aus einem Tar-File, in welchem minion-Key und Minion-Zerifikat enthalten sind.

curl -sSk http://salt:8000/keys \
        -d mid=$(cat /etc/salt/minion_id) \
        -d username=salt-api \
        -d password=123ab \
        -d eauth=pam \
        | tar -C /etc/salt/pki/minion -xmf -

Beispiel Systeme beim Hochfahren automatisch registrieren

lxc launch images:debian/11 doreen
lxc exec doreen bash<<"EOF"
set -e
apt-get -y install curl
curl -LSs https://bootstrap.saltproject.io/ -o install_salt.sh
sh install_salt.sh -x python3 -X
service salt-minion stop
echo "10.27.119.1 salt">>/etc/hosts
curl -fs http://salt:8000/keys \
  -d mid=$(cat /etc/salt/minion_id) \
  -d username=salt-api \
  -d password=123ab \
  -d eauth=pam \
  | tar -vC /etc/salt/pki/minion -xmf -
cat /etc/salt/pki/minion/minion.pem
cat /etc/salt/pki/minion/minion.pub
service salt-minion start
service salt-minion status
EOF

Achten Sie darauf, dass die Salt-API im Netzwerk lauscht und nicht nur auf localhost.

Passen Sie ggf. die Datei /etc/salt/master.d/api.conf an und starten Sie die API mit service salt-api restart neu.

Link zur offiziellen Dokumentation der Salt-API.