Admin Companion Gateway - Installationsanleitung

Terminologie:

• Zielhost: die entfernte Maschine, die die Quelle eines eingehenden Events ist (z. B. ein Alert) und die Maschine, zu der sich das Gateway per SSH als Benutzer acops verbindet, um ac-ops zur Analyse auszuführen.

Dieses Dokument beschreibt, wie Admin Companion Gateway auf einem Linux-Host mit Docker Compose installiert wird.

Das Gateway ist für Intranet-Deployments vorgesehen. Es empfängt Webhooks (z. B. Prometheus Alertmanager), normalisiert JSON-Payloads über Profiles und führt remote ac-ops Use-Cases per SSH auf Zielhosts aus.

Inhalt

• Voraussetzungen
• Quickstart: Alertmanager zu Slack
• Download
• Installation (Standard, mit Internetzugang)
• Installation (Air-gapped)
• Nach der Installation: Profiles und Use-Cases konfigurieren
• Zielhosts: erforderliche Einrichtung
• Betrieb des Gateways
• Deinstallation
• Fehlerbehebung

Voraussetzungen

Gateway-Host

• Linux-Host mit einer funktionierenden Docker-Installation.
• Docker Compose verfügbar als entweder:
  • docker compose (Compose v2 Plugin), oder
  • docker-compose
• Ausgehende SSH-Konnektivität vom Gateway-Host zu den Zielhosts.

Hinweise:

• Der Container läuft als Non-root UID (20102). Host-gemountete Secrets müssen für diese UID lesbar sein.

Zielhosts

Jeder Zielhost, gegen den das Gateway ausführen darf, muss Folgendes bereitstellen:

• Admin Companion installiert (damit ac-ops auf dem Zielhost vorhanden ist)
• Einen OS-Benutzer acops
• SSH-Zugriff für das Gateway (Public-Key Auth) mit Einschränkungen
• Die referenzierten Use-Case YAML-Dateien in erlaubten Use-Case Verzeichnissen

Quickstart: Alertmanager zu Slack

Dieser Quickstart verbindet Prometheus Alertmanager - Gateway - ac-ops - Slack mit dem mitgelieferten Beispiel-Profil.

Voraussetzungen:

• Prometheus Alertmanager
• Eine Slack Incoming Webhook URL

Schritte (High level):

1) Gateway installieren und starten (siehe unten).

2) Die installierte Profiles-Datei bearbeiten und die Slack-Webhook-URL setzen:

- `/etc/admin-companion/ac-ops-gateway.profiles.yaml`

3) Alertmanager so konfigurieren, dass Alerts an den Gateway-Endpoint gesendet werden.

Der benötigte Alertmanager Receiver-Snippet ist als Kommentar in derselben Profiles-Datei enthalten.

4) Sicherstellen, dass die Zielhosts vorbereitet sind (SSH-User acops, Forced-Command-Modus und benötigte Use-Cases verfügbar).

Das Quickstart-Profil nutzt docker-issue-analysis.yaml (wird mit dem Admin Companion Client / ac-ops ausgeliefert).

5) Gateway nach Änderungen neu starten:

sudo ac-gatewayctl restart

Für Konfigurationsdetails (Expression-Sprache, Sinks, Templating, Security) siehe:

https://www.admin-companion.ai/de/documentation?sub=ac-gw#ac-gw

Download

Typischerweise laden Sie eines oder beide dieser Artefakte herunter:

• Compose-Bundle:

  • admin-companion-gateway_compose_<version>.tar.gz
  • admin-companion-gateway_compose_<version>.tar.gz.asc (optionale Detached-Signatur)

• Image-Archiv (nur für Air-gapped Installationen benötigt):

  • admin-companion-gateway_image_<version>.tar.gz
  • admin-companion-gateway_image_<version>.tar.gz.asc (optionale Detached-Signatur)

Optional: Detached-Signatur (.asc) prüfen

Wenn Sie Detached-Signaturen erhalten haben, können Sie diese verifizieren (Beispiel):

wget https://www.admin-companion.ai/static/downloads/admin-companion-2025_public.key
gpg --import admin-companion-2025_public.key

gpg --verify admin-companion-gateway_compose_<version>.tar.gz.asc \
            admin-companion-gateway_compose_<version>.tar.gz

Wiederholen Sie das gleiche für das Image-Tarball, falls Sie es heruntergeladen haben.

Hinweis zur GPG-Warnung

Beim Prüfen von Signaturen sehen Sie ggf.:

gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.

Das ist normal und bedeutet nicht, dass der Download beschädigt ist.

• gpg: Good signature ... bedeutet: Datei passt zur Signatur (Integrität OK).
• Die Warnung bedeutet nur: GPG wurde auf diesem System noch nicht mitgeteilt, dass diesem Signaturschlüssel vertraut werden soll (Web-of-Trust / lokale Trust-Datenbank).

Installation (Standard, mit Internetzugang)

Dabei wird das veröffentlichte Image aus GHCR verwendet (ghcr.io/ayonik-gmbh/admin-companion-gateway:<version>).

1) Compose-Bundle entpacken

tar -xzf admin-companion-gateway_compose_<version>.tar.gz
cd admin-companion-gateway_compose_<version>

2) Installer ausführen

sudo ./install.sh

Was es macht:

• Installiert den Compose-Stack nach /opt/admin-companion-gateway/
• Installiert Konfigurations-Templates (nur falls fehlend) nach /etc/admin-companion/
• Erstellt das Secrets-Verzeichnis /etc/admin-companion/ac-ops-gateway-secrets/ mit strikten Berechtigungen
• Generiert im Secrets-Verzeichnis (falls fehlend):
  • Bearer Token: ac_ops_gateway_token
  • SSH Keypair: acops_gateway_ed25519 / .pub
  • leere known_hosts (wird nur genutzt, wenn AC_OPS_GATEWAY_SSH_STRICT_HOST_KEY_CHECKING=true; sonst ignoriert)
• Installiert ac-gatewayctl nach /usr/local/bin/ac-gatewayctl

3) Gateway starten

sudo ac-gatewayctl up -d

4) Status/Logs prüfen

sudo ac-gatewayctl ps
sudo ac-gatewayctl logs -f

Installation (Air-gapped)

Air-gapped bedeutet, dass die Zielmaschine nicht aus GHCR ziehen kann.

Zusätzlicher Schritt (vor der normalen Installation): das Image in Docker laden.

1) Beide Dateien auf die Zielmaschine übertragen:

- `admin-companion-gateway_compose_<version>.tar.gz`
- `admin-companion-gateway_image_<version>.tar.gz`

2) Image laden:

gunzip -c admin-companion-gateway_image_<version>.tar.gz | docker load

Falls Ihr Docker Root benötigt:

gunzip -c admin-companion-gateway_image_<version>.tar.gz | sudo docker load

3) Mit dem Standardverfahren fortfahren

- Compose-Bundle entpacken
- `sudo ./install.sh`
- `sudo ac-gatewayctl up -d`

Nach der Installation: Profiles und Use-Cases konfigurieren

Quickstart: Minimal erforderliche Änderungen (Alertmanager - Gateway - ac-ops - Slack)

Wenn Sie dem Quickstart-Profil folgen, sind dies die effektiven Änderungen, die Sie vornehmen müssen:

1) Gateway: Slack-Webhook-URL setzen

• Bearbeiten: /etc/admin-companion/ac-ops-gateway.profiles.yaml
• Tragen Sie Ihre Slack Incoming Webhook URL im webhook-Sink des mitgelieferten Alertmanager-Profils ein.

2) Alertmanager: Receiver-Snippet hinzufügen + Bearer-Token konfigurieren

• In der Alertmanager-Konfiguration (typischerweise /etc/alertmanager/alertmanager.yml) fügen Sie diesen Receiver hinzu und verweisen Sie auf den Gateway-Endpoint.
• Die Receiver-Snippet-Vorlage ist als Kommentar in der Gateway-Profiles-Datei enthalten:
  • /etc/admin-companion/ac-ops-gateway.profiles.yaml
• Passen Sie den Parameter bearer_token_file an den Pfad an, unter dem Sie die Datei bereitstellen.
• Empfehlung: Kopieren Sie die Datei /etc/admin-companion/ac-ops-gateway-secrets/ac_ops_gateway_token (von install.sh erzeugt) an einen Ort, auf den Alertmanager zugreifen kann.
• Passen Sie die Zugriffsrechte der Kopie so an, dass Alertmanager darauf zugreifen kann.

• Die Admin-Companion-Datei hat Mode 0600 und UID:GID 20102:20102, daher können Sie nicht direkt auf diese Datei verweisen.

• Anforderungen an das Alert-Payload (Quickstart-Profil):

  • commonLabels.instance (oder alerts[0].labels.instance) wird als target_host verwendet
  • commonLabels.alertname (oder service/job) wird zur Auswahl des Use-Cases verwendet; acopsdemocontainermissing ist nur ein Beispiel-Alertname
  • das mitgelieferte Profil behält einen Default-Use-Case (docker-issue-analysis.yaml), wenn es keinen Match gibt

3) Target Hosts: erforderliches Setup

• ac-ops installiert
• Benutzer acops mit Forced-Command-SSH-Modus (ac-ops --ssh-restricted)
• erforderlicher Use-Case vorhanden (Quickstart verwendet docker-issue-analysis.yaml)

Nach den Änderungen starten Sie das Gateway neu:

sudo ac-gatewayctl restart

Gateway-Konfigurationsdateien

Nach install.sh bearbeiten Sie typischerweise:

• /etc/admin-companion/ac-ops-gateway.cfg
• /etc/admin-companion/ac-ops-gateway.profiles.yaml

Dann neu starten:

sudo ac-gatewayctl restart

Secrets und Berechtigungen

Secrets-Verzeichnis (in den Container gemountet als /run/secrets):

• /etc/admin-companion/ac-ops-gateway-secrets/

Default Ownership Model (empfohlen):

• Verzeichnis: 0700, owned by 20102:20102
• Token-Datei: 0600, owned by 20102:20102
• SSH Private Key: 0600, owned by 20102:20102 (erforderlich für OpenSSH)

Zielhosts: erforderliche Einrichtung

1) Admin Companion Client installieren (ac-ops muss existieren)

Auf jedem Zielhost:

command -v ac-ops

Wenn ac-ops fehlt, installieren Sie das Admin Companion Client Paket, das es bereitstellt.

2) Benutzer acops anlegen (empfohlen)

Auf jedem Zielhost einen dedizierten Service-User anlegen und das SSH-Verzeichnis vorbereiten:

# Empfehlung: dedizierter Service-User ohne interaktiven Login
id acops >/dev/null 2>&1 || sudo useradd -m -s /usr/sbin/nologin acops

# SSH-Verzeichnis und authorized_keys
sudo install -d -m 0700 -o acops -g acops /home/acops/.ssh
sudo install -m 0600 -o acops -g acops /dev/null /home/acops/.ssh/authorized_keys

Wenn Ihr OS useradd nicht bereitstellt, verwenden Sie OS-spezifische Tools, um einen normalen Benutzer acops mit Home-Verzeichnis anzulegen.

Optionales Hardening (empfohlen): Forced-Command auch in sshd erzwingen und Session-Features deaktivieren:

cat <<'EOF' | sudo tee /etc/ssh/sshd_config.d/90-acops-admin-companion.conf >/dev/null
Match User acops
  ForceCommand ac-ops --ssh-restricted
  PermitTTY no
  AllowTcpForwarding no
  X11Forwarding no
  PermitTunnel no
EOF
sudo systemctl reload ssh

3) Gateway-Public-Key mit Einschränkungen installieren

Auf dem Gateway-Host befindet sich der Public Key unter:

• /etc/admin-companion/ac-ops-gateway-secrets/acops_gateway_ed25519.pub

Auf dem Zielhost fügen Sie ihn an diese Datei an:

• /home/acops/.ssh/authorized_keys

Empfohlene Einschränkungen:

• erzwungene, eingeschränkte Ausführung:
  • command="ac-ops --ssh-restricted"
• interaktive/Session-Features deaktivieren:
  • no-pty,no-port-forwarding,no-agent-forwarding,no-X11-forwarding,no-user-rc

Beispiel (ersetzen Sie <PUBKEY> durch die wörtliche Public-Key-Zeile aus .../acops_gateway_ed25519.pub des Gateways):

umask 077
printf '%s\n' 'command="ac-ops --ssh-restricted",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding <PUBKEY>' \
  >> /home/acops/.ssh/authorized_keys
chown acops:acops /home/acops/.ssh/authorized_keys
chmod 0600 /home/acops/.ssh/authorized_keys

4) Sicherstellen, dass Use-Cases existieren und erlaubt sind

Das Gateway wird (auf dem Zielhost) aufrufen:

• ac-ops --ssh-restricted --use-case <name> --event -

Im ssh-restricted Modus akzeptiert ac-ops nur Use-Cases aus erlaubten Verzeichnissen.

Platzieren Sie Ihre Use-Case YAML-Dateien auf den Zielhosts in den erlaubten Use-Case Verzeichnissen (häufig unter /etc/admin-companion/ops/use-cases plus Vendor libexec Paths).

Betrieb des Gateways

ac-gatewayctl ist ein dünner Wrapper um Compose.

Häufige Befehle:

sudo ac-gatewayctl up -d
sudo ac-gatewayctl ps
sudo ac-gatewayctl logs -f
sudo ac-gatewayctl restart
sudo ac-gatewayctl down
sudo ac-gatewayctl pull

Deinstallation

Konfiguration/Secrets behalten:

sudo ac-gatewayctl uninstall

Alles entfernen (gefährlich; löscht Secrets und entfernt auch das Gateway-Image):

sudo ac-gatewayctl uninstall --purge

Fehlerbehebung

Wenn Port 8080 bereits belegt ist

Standardmäßig veröffentlicht der Compose-Stack das Gateway auf Host-Port 8080:

• ports: ["8080:8080"]

Wenn Port 8080 auf dem Gateway-Host bereits genutzt wird, ändern Sie die linke Seite (Host-Port) in:

• /opt/admin-companion-gateway/docker-compose.yml

Beispiel: Stattdessen auf Host-Port 18080 veröffentlichen:

ports:
  - "18080:8080"

Dann die Änderung anwenden:

sudo ac-gatewayctl up -d

Tipp: Sie können prüfen, was aktuell auf 8080 lauscht, mit:

sudo ss -ltnp | grep ':8080' || true

Gateway startet, findet aber keine Use-Cases

Symptom: - SSH Output enthält: ssh-restricted: use-case not found in allowed use-case dirs

Fix: - Sicherstellen, dass der Use-Case auf dem Zielhost unter erlaubten Use-Case Verzeichnissen vorhanden ist. - Sicherstellen, dass der angeforderte Use-Case Name exakt übereinstimmt.

Webhook-Sink liefert HTTP 400 (z. B. Slack)

• Prüfen Sie sink_done.detail und sink_done.params in DEBUG Logs.
• Für Slack Incoming Webhooks muss der Request Body gültiges JSON sein (z. B. {"text":"..."}) und sollte JSON-escaped Template-Inserts verwenden.

Debug-Logging aktivieren (Gateway)

In /etc/admin-companion/ac-ops-gateway.cfg:

• AC_OPS_GATEWAY_LOG_LEVEL=DEBUG

Um vollen Request Input/Output zu loggen, zusätzlich setzen:

• AC_OPS_GATEWAY_LOG_FULL_INPUT=true
• AC_OPS_GATEWAY_LOG_FULL_OUTPUT=true

Wichtig: Full Input/Output Logging ist nur mit DEBUG erlaubt.