Asset-Agent einrichten

Nutzen Sie nucleus-asset-agent, um Linux-Geräte regelmäßig an das Asset-Register zu melden. Nach der Einrichtung aktualisiert der Agent das IT-Profil eines vorhandenen Assets. Er legt keine Assets an und führt keine Remote-Befehle aus.

Voraussetzungen

Legen Sie zuerst das Gerät als Asset in Assets an. Sie benötigen außerdem eine Rolle mit den Scopes managed_asset_agents:create und managed_asset_agents:update, um Agent-Credentials zu erzeugen oder zu rotieren.

Für den Rollout benötigen Sie:

  • die Workspace-URL, zum Beispiel https://workspace.example.com,
  • die Asset-ID des vorhandenen Assets,
  • die Agent-ID aus der Agent-Credential,
  • das einmalig angezeigte Agent-Token,
  • ein Linux-amd64-System mit systemd oder eine NixOS-Konfiguration.

Die Release-Artefakte liefern ein Linux-amd64-Tarball. Debian, Ubuntu und Fedora nutzen denselben Binary-Rollout. NixOS nutzt eine deklarative systemd-Unit.

Fingerprint ermitteln

Ermitteln Sie auf dem Gerät den erwarteten Fingerprint:

sh
nucleus-asset-agent fingerprint

Der Fingerprint ist ein sha256:-Hash aus stabilen lokalen Gerätekennungen. Er ist kein Passwort, aber eine stabile Gerätekennung. Behandeln Sie ihn wie Inventarinformationen.

Agent-Credential anlegen

Erzeugen Sie im Tenant eine Agent-Credential für das vorhandene Asset und den erwarteten Fingerprint. Workspace gibt das Token nur einmal zurück.

Speichern Sie das Token auf dem Gerät in einer Datei, die nur root lesen kann:

sh
install -d -m 0750 /etc/nucleus-asset-agent
install -m 0600 /dev/null /etc/nucleus-asset-agent/token
printf '%s\n' '<agent-id>:<secret>' > /etc/nucleus-asset-agent/token

Schreiben Sie das Token nicht in Images, NixOS-Module, Shell-History, Konfigurationsmanagement-Logs oder normale Environment-Dateien.

Konfiguration hinterlegen

Hinterlegen Sie Host, Agent-ID und Asset-ID in einer Environment-Datei:

sh
cat >/etc/nucleus-asset-agent.env <<'EOF'
NUCLEUS_ASSET_AGENT_HOST=https://workspace.example.com
NUCLEUS_ASSET_AGENT_ID=018ffd2f-9d54-7a18-a0cf-19f77e879001
NUCLEUS_ASSET_ID=018ffd30-0d31-75ef-a89f-245351c10011
EOF
chmod 0640 /etc/nucleus-asset-agent.env

Prüfen Sie die Konfiguration ohne Serveraufruf:

sh
nucleus-asset-agent report \
  --token-file /etc/nucleus-asset-agent/token \
  --dry-run

Der Dry-Run gibt den Report aus, aber nie das Token.

Debian, Ubuntu und Fedora

Installieren Sie das Binary aus dem Release-Artefakt. Ersetzen Sie 1.2.3 durch die gewünschte Release-Version:

sh
version=1.2.3
curl -fL -o /tmp/nucleus-asset-agent.tar.gz \
  "https://git.schukai.me/releases/nucleus-asset-agent/releases/download/${version}/nucleus-asset-agent-linux-x86_64.tar.gz"
tar -xzf /tmp/nucleus-asset-agent.tar.gz -C /tmp nucleus-asset-agent-linux-x86_64
install -m 0755 /tmp/nucleus-asset-agent-linux-x86_64 /usr/local/bin/nucleus-asset-agent

Legen Sie eine systemd-Service-Unit an:

sh
cat >/etc/systemd/system/nucleus-asset-agent.service <<'EOF'
[Unit]
Description=Report Workspace asset inventory data
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
EnvironmentFile=/etc/nucleus-asset-agent.env
ExecStart=/usr/local/bin/nucleus-asset-agent report --token-file /etc/nucleus-asset-agent/token
EOF

Legen Sie einen Timer an:

sh
cat >/etc/systemd/system/nucleus-asset-agent.timer <<'EOF'
[Unit]
Description=Run Workspace asset inventory report regularly

[Timer]
OnBootSec=5min
OnUnitActiveSec=6h
RandomizedDelaySec=15min
Persistent=true

[Install]
WantedBy=timers.target
EOF

Aktivieren Sie Timer und ersten Lauf:

sh
systemctl daemon-reload
systemctl enable --now nucleus-asset-agent.timer
systemctl start nucleus-asset-agent.service

NixOS

Nutzen Sie auf NixOS eine deklarative systemd-Unit. Legen Sie das Token über Ihr Secret-Management, zum Beispiel sops-nix, agenix oder eine Deployment-Prozedur, außerhalb des Nix-Stores unter /run/secrets/nucleus-asset-agent.token ab.

Beispiel:

nix
{ inputs, pkgs, ... }:

let
  agent = inputs.workspace.packages.${pkgs.system}.nucleus-asset-agent;
in
{
  environment.etc."nucleus-asset-agent/env".text = ''
    NUCLEUS_ASSET_AGENT_HOST=https://workspace.example.com
    NUCLEUS_ASSET_AGENT_ID=018ffd2f-9d54-7a18-a0cf-19f77e879001
    NUCLEUS_ASSET_ID=018ffd30-0d31-75ef-a89f-245351c10011
  '';

  systemd.services.nucleus-asset-agent = {
    description = "Report Workspace asset inventory data";
    wants = [ "network-online.target" ];
    after = [ "network-online.target" ];
    serviceConfig = {
      Type = "oneshot";
      EnvironmentFile = "/etc/nucleus-asset-agent/env";
      LoadCredential = "credential:/run/secrets/nucleus-asset-agent.token";
      ExecStart = "${agent}/bin/nucleus-asset-agent report --token-file %d/credential";
    };
  };

  systemd.timers.nucleus-asset-agent = {
    wantedBy = [ "timers.target" ];
    timerConfig = {
      OnBootSec = "5min";
      OnUnitActiveSec = "6h";
      RandomizedDelaySec = "15min";
      Persistent = true;
    };
  };
}

Aktivieren Sie die Konfiguration mit nixos-rebuild switch und starten Sie den ersten Lauf:

sh
systemctl start nucleus-asset-agent.service
journalctl -u nucleus-asset-agent.service -n 50

Report manuell senden

Für Diagnose oder Rollout-Tests können Sie den Report manuell starten:

sh
nucleus-asset-agent report \
  --token-file /etc/nucleus-asset-agent/token

Wenn Sie keine Environment-Datei verwenden, übergeben Sie --host, --agent-id und --asset-id direkt.

Einrichtung prüfen

Prüfen Sie nach dem ersten erfolgreichen Lauf:

  • systemctl status nucleus-asset-agent.service zeigt keinen Fehler.
  • journalctl -u nucleus-asset-agent.service enthält keine Token- oder Fingerprint-Werte.
  • Das IT-Profil des Assets zeigt einen aktuellen Agent-Zeitpunkt und den Agent-Status online.
  • Hostname, Betriebssystem, Architektur, CPU, RAM, Disks und Sicherheitsindikatoren wurden aktualisiert.

Betrieb

Rotieren Sie das Token, wenn ein Gerät neu provisioniert wird oder der Secret-Speicher kompromittiert sein könnte. Aktualisieren Sie danach nur die Token-Datei oder das Systemd-Credential; Agent-ID und Asset-ID bleiben gleich, solange dieselbe Credential weiterverwendet wird.

Wenn ein Gerät ersetzt wird, erzeugen Sie eine neue Credential mit neuem Fingerprint. Verwenden Sie keine Credential eines alten Geräts weiter.

Grenzen

Der Linux-Client meldet Hostname, Betriebssystem, Architektur, CPU, RAM, Disks und einfache Sicherheitsindikatoren. Er legt keine Assets an, ändert keine Asset-Stammdaten und führt keine Remote-Kommandos aus.