Agents

Eén agent bedient één netwerk: de plek van waaruit je hypervisors en panelen bereikbaar zijn. Alles wat Provibr met je infrastructuur doet gaat daardoorheen.

• De verbinding is uitgaand. De agent opent hem naar het platform en houdt hem open; er hoeft niets vanaf het internet bereikbaar te zijn en er hoeft geen poort naar hem doorgestuurd te worden.
• Inloggegevens blijven aan jouw kant. Ze gaan één keer naar de agent en worden op die host in een versleutelde kluis weggezet; het platform bewaart alleen de namen van de velden die je invulde.
• Hij meldt wat hij waarneemt. Machines worden op een kort ritme gepold en elke paar minuten loopt er een volledige vergelijking, en zo merkt het paneel dat een machine buiten Provibr om is gestopt.
• Hij raakt alleen aan wat je hebt overgedragen. Een resource zonder registratie in Provibr wordt genegeerd, geteld en weer vergeten. De agent neemt nooit uit zichzelf een machine over.

Niets bijzonders, en vooraf niets te installeren. De agent is één statisch gelinkte binary: hij draagt zijn eigen C-bibliotheek mee, dus er is geen runtime, geen interpreter en geen distributiepakket dat moet passen. Een kleine virtuele machine is genoeg. De maten die we gemeten hebben staan verderop op deze pagina.

Er is geen pakket om te installeren en geen distributie om bij te passen, dus wat hieronder staat is geen lijst met ondersteunde systemen. Het is de lijst met systemen waarop deze build werkelijk gestart is. Alles wat verder een 64-bits x86 Linux-kernel heeft hoort zich hetzelfde te gedragen, en zo niet dan horen we dat graag.

De agent zelf is klein en blijft klein. Wat groeit is de inventaris die hij in de gaten houdt: elke twintig seconden leest hij van elk gekoppeld systeem de volledige lijst machines, vergelijkt die met de ronde ervoor en stuurt alleen door wat er veranderd is. Elke vijf minuten stuurt hij in plaats daarvan het volledige beeld door, en dat is het vangnet voor alles wat een verloren bericht anders gekost zou hebben; het is ook de ronde waarin hij je nodes vraagt hoeveel capaciteit ze hebben.

Verkeer is het andere cijfer dat de moeite waard is. Die duizend machines kosten ongeveer 250 kB per twintig seconden richting je eigen systemen, ruwweg een gigabyte per dag op je eigen netwerk, terwijl tien machines 2,5 kB per ronde kosten. Van dat cijfer voor duizend machines reist ongeveer 17 kB per ronde door naar ons, zo'n 70 MB per dag, omdat alleen doorgestuurd wordt wat er veranderd is.

Maakt het soort systeem uit? Nauwelijks. Of de agent nu met een hypervisor, een controlepaneel of een gamepaneel praat, het werk is hetzelfde: één aanroep per systeem per ronde, één vergelijking, één bericht. Twee verschillen zijn echt maar klein. Aan een hypervisor worden ook de adressen binnen zijn gasten gevraagd, hoogstens eens per vijf minuten per draaiende machine, en een paneel dat niets meet stuurt geen verbruikscijfers. Wat wél enorm verschilt is de machine aan de andere kant, en hoe groot die moet zijn volgt uit wat hij draait en niet uit de agent.

De maten hieronder zijn daarom geen minima die we gemeten hebben; de agent past in veel minder. Het is wat wij zouden bestellen, omdat een besturingssysteem, zijn logboeken en je eigen gereedschap meer ruimte willen dan de agent.

Alles hierboven is wat een agent nodig heeft om je systemen te bekijken en te bedienen. Vier van zijn mogelijkheden verdienen daarbovenop nog een woord, en ze geven allemaal eerlijk toe wanneer het niet kan: is aan een voorwaarde niet voldaan, dan doet de agent de rest gewoon en zegt hij welke mogelijkheid hij niet aanbiedt.

Machines over het netwerk installeren

Hiervoor moet de agent op hetzelfde netwerksegment staan als de machine die geïnstalleerd wordt, want hij beantwoordt het bootverzoek van die machine rechtstreeks. Zijn unit draagt de twee capabilities die hij voor de bootpoorten nodig heeft al; ze zijn zo krap mogelijk toegekend en worden alleen gebruikt zolang er een installatie loopt. Wat het wél kost is schijfruimte: installatiemedia blijven in een cache op de host staan, standaard tot 20 GB, oudste er als eerste uit.

Automatiseringen draaien

Automatiseringen zijn je eigen TypeScript, dus ze draaien in een sandbox die uit kernel-namespaces is opgebouwd, en de runtime daarvoor zit niet in de agent: één vastgezette versie van Bun moet in de map van de agent staan die van root is, waar het account waaronder de agent draait hem niet kan vervangen. Ubuntu 24.04 en nieuwer beperken precies de namespace die hiervoor nodig is; de agent levert een AppArmor-profiel mee dat die ene toestemming teruggeeft voor die ene binary. Ontbreekt een van de twee, dan zegt de agent dat bij het starten, biedt hij de mogelijkheid niet aan en gaat hij verder. Elke run krijgt minstens 4 GB adresruimte. Dat is virtueel, geen geheugen dat er moet zijn. Wat een draaiende automatisering op je host werkelijk kost hebben we niet gemeten.

De host herstarten vanuit het paneel

Herstarten is een kwestie van toestemming en niet van rechten: de agent vraagt het aan logind, logind vraagt het aan polkit, en het installatiescript laat een regel achter die precies twee action-id's toestaat voor precies dit account. Hosts die geïnstalleerd zijn voordat die regel bestond moeten het installatiescript één keer opnieuw draaien, want de agent bijwerken vanuit het paneel vervangt de binary en niets in /etc. Tot die tijd weigert het paneel het, met de reden erbij.

Console en diagnostiek

Niets te installeren. Ping en traceroute gebruiken een ICMP-socket waar geen rechten voor nodig zijn, zolang de host dat voor de groep van het serviceaccount toestaat, en dat deed hij op elke host die we gemeten hebben. Waar dat niet zo is, meet de agent met TCP en zegt hij welke methode hij gebruikte. De console loopt over de verbinding die al openstaat.

Op het tabblad Instellingen van de agent bouwt het paneel één commando met een installatielink erin. Draai het als root op de host. De link werkt één keer: hij houdt op zodra de agent is ingeschreven, en uiterlijk na 72 uur. Je kunt op elk moment een nieuwe maken.

curl -fsSL https://app.provibr.com/api/install/<token> | sh

Wat het commando doet, op volgorde:

• Controleert of het als root draait op een 64-bits x86-host en kiest curl of wget, wat er is.
• Downloadt de binary en zijn checksum en verifieert ze. Heeft de host helemaal geen gereedschap om een checksum te berekenen, dan stopt het in plaats van de controle over te slaan.
• Maakt het serviceaccount en de twee mappen aan, installeert de binary, en zet het updatescript en zijn publieke sleutel neer, allebei van root, zodat het account waaronder de agent draait ze niet kan vervangen.
• Vraagt de activatiecode op de terminal, haalt het licentiebestand op met die code als request-header, en installeert het.
• Enrollt als het serviceaccount, installeert daarna de systemd-unit en start de service.

Het resultaat controleren op de host:

systemctl status provibr-agent
journalctl -u provibr-agent -f

Alles wat de one-liner doet is ook een handvol commando's, en het paneel drukt ze voor je af met de actuele waarden ingevuld. Dit is de vorm ervan.

1. 01

   De host klaarmaken: het serviceaccount, de mappen en de binary.

   shellKopiëren

   # System user without a shell and without a home directory
   id -u provibr-agent >/dev/null 2>&1 || \
     sudo useradd --system --no-create-home --shell /usr/sbin/nologin provibr-agent
   
   # Directories for configuration (license, key) and state (identity, vault)
   sudo install -d -o provibr-agent -g provibr-agent -m 0750 /etc/provibr-agent
   sudo install -d -o provibr-agent -g provibr-agent -m 0700 /var/lib/provibr-agent
   
   # The binary from the download
   sudo install -o root -g root -m 0755 ./provibr-agent-linux-x86_64 /usr/local/bin/provibr-agent
   /usr/local/bin/provibr-agent version

2. 02

   Het licentiebestand neerzetten. Je downloadt het op de agentpagina; het is versleuteld met de activatiecode en kan één keer per token gedownload worden.

   shellKopiëren

   sudo install -o root -g provibr-agent -m 0640 \
     ./provibr-<agent>.plic /etc/provibr-agent/license.plic

3. 03

   Enrollen als het serviceaccount, met de activatiecode.

   shellKopiëren

   sudo -u provibr-agent /usr/local/bin/provibr-agent enroll \
     --license /etc/provibr-agent/license.plic --code XXXXX-XXXXX

4. 04

   De unit installeren en de service starten.

   shellKopiëren

   sudo install -o root -g root -m 0644 provibr-agent.service /etc/systemd/system/provibr-agent.service
   sudo systemctl daemon-reload
   sudo systemctl enable --now provibr-agent

De agent draait ook als container. Het image bevat dezelfde ondertekende release-binary als de Linux-download en verder niets: geen shell en geen pakketbeheerder, en hij draait als gebruiker zonder rootrechten. Hij verbindt alleen uitgaand, dus er zijn geen gepubliceerde poorten en geen service nodig.

Het inschrijven gebeurt bij de eerste start. Geef de container de installatielink uit het paneel en de activatiecode; hij haalt zijn licentiebestand op, schrijft zich in en bewaart zijn identiteit op het volume. Bij elke volgende start wordt die identiteit gebruikt en worden de twee waarden niet meer gelezen.

Het paneel toont dit commando met de link en de code van jouw agent al ingevuld. Het named volume neemt zijn eigenaar over van het image, dus de agent kan erin schrijven zonder chown.

docker run -d --name provibr-agent --restart unless-stopped \
  --hostname provibr-agent \
  --read-only --cap-drop ALL --security-opt no-new-privileges \
  -v provibr-agent-data:/var/lib/provibr-agent \
  -e PROVIBR_INSTALL_URL='https://app.provibr.com/api/install/<token>' \
  -e PROVIBR_ACTIVATION_CODE='XXXXX-XXXXX' \
  ghcr.io/provibr/provibr-agent:latest

Of hetzelfde als Docker Compose-bestand:

# Provibr agent — Docker Compose.
#
# The agent connects outbound to the platform; it needs no published ports.
# On the first start it enrolls itself with the installation link and the
# activation code below, and stores its identity on the volume. After that the
# two values are no longer read; the link expires 72 hours after it was made.
#
# Update: change the image tag, then `docker compose up -d`. The volume keeps
# identity and credentials.
services:
  provibr-agent:
    image: ghcr.io/provibr/provibr-agent:latest
    container_name: provibr-agent
    hostname: provibr-agent
    restart: unless-stopped
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    environment:
      PROVIBR_INSTALL_URL: "https://app.provibr.com/api/install/<token>"
      PROVIBR_ACTIVATION_CODE: "XXXXX-XXXXX"
    volumes:
      - provibr-agent-data:/var/lib/provibr-agent

volumes:
  provibr-agent-data:

Kale manifesten, geen Helm: een namespace, een secret met de link en de code, een volume claim en een deployment. Het paneel vult het secret voor jouw agent in.

# Provibr agent — Kubernetes (plain manifests, no Helm).
#
# kubectl apply -f provibr-agent.yaml
#
# The agent connects outbound to the platform; there is no Service and no port.
# On the first start it enrolls itself with the installation link and the
# activation code from the Secret, and stores its identity on the volume. After
# that the Secret is no longer read; the link expires 72 hours after it was made.
#
# Exactly one replica, and Recreate: one agent is one identity (one
# certificate). Two pods would be two agents fighting over it.
apiVersion: v1
kind: Namespace
metadata:
  name: provibr-agent
---
apiVersion: v1
kind: Secret
metadata:
  name: provibr-agent-enrollment
  namespace: provibr-agent
type: Opaque
stringData:
  PROVIBR_INSTALL_URL: "https://app.provibr.com/api/install/<token>"
  PROVIBR_ACTIVATION_CODE: "XXXXX-XXXXX"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: provibr-agent-data
  namespace: provibr-agent
spec:
  # One pod, and only one, may mount this volume. On clusters older than
  # Kubernetes 1.29 (or storage without it), use ReadWriteOnce instead; the
  # agent also refuses to start a second time on the same data directory.
  accessModes:
    - ReadWriteOncePod
  resources:
    requests:
      storage: 1Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: provibr-agent
  namespace: provibr-agent
  labels:
    app.kubernetes.io/name: provibr-agent
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app.kubernetes.io/name: provibr-agent
  template:
    metadata:
      labels:
        app.kubernetes.io/name: provibr-agent
    spec:
      hostname: provibr-agent
      automountServiceAccountToken: false
      enableServiceLinks: false
      securityContext:
        runAsNonRoot: true
        runAsUser: 65532
        runAsGroup: 65532
        fsGroup: 65532
        # Only when the volume root does not match yet; otherwise the kubelet
        # widens the modes on the private keys at every mount.
        fsGroupChangePolicy: OnRootMismatch
        seccompProfile:
          type: RuntimeDefault
        # The ping check uses an unprivileged ICMP socket. Some container
        # runtimes keep those closed, and then the check reports a source
        # error. This safe sysctl opens them for the agent's group only.
        sysctls:
          - name: net.ipv4.ping_group_range
            value: "65532 65532"
      containers:
        - name: agent
          image: ghcr.io/provibr/provibr-agent:latest
          args: ["run"]
          envFrom:
            # optional: the agent reads it on its first start only, so you can
            # delete the Secret once it is enrolled.
            - secretRef:
                name: provibr-agent-enrollment
                optional: true
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop: ["ALL"]
          resources:
            requests:
              cpu: 50m
              memory: 32Mi
            limits:
              memory: 256Mi
          volumeMounts:
            - name: data
              mountPath: /var/lib/provibr-agent
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: provibr-agent-data

Voor Kubernetes is het licentiebestand de betere weg: zet het licentiebestand en de code in het secret in plaats van de installatielink, koppel het bestand in de pod en zet PROVIBR_LICENSE_FILE op het pad ervan. Het token in het bestand werkt precies één keer, dus het secret bevat niets waarmee de agent een tweede keer kan worden ingeschreven.

Standaard werkt een container zichzelf niet bij: het image is de release. Het paneel toont welk image actueel is; haal het op en maak de container opnieuw aan, of zet de nieuwe tag op de deployment. Het volume bewaart identiteit en inloggegevens. Automatische updates slaan deze agents over; de optie hieronder verandert dat.

docker pull ghcr.io/provibr/provibr-agent:latest
docker stop provibr-agent && docker rm provibr-agent
# then run the same docker run command again with the new image

kubectl -n provibr-agent set image deployment/provibr-agent agent=ghcr.io/provibr/provibr-agent:latest

Zet PROVIBR_SELF_UPDATE=volume, of vink de optie aan in het paneel. De container doet dan mee met de updateknop en de nachtelijke updates: een nieuwe versie wordt gedownload, de handtekening wordt gecontroleerd tegen de platformsleutel die in het image zit, en hij komt op het volume. De container stopt met exitcode 0, Docker of de kubelet start hem opnieuw, en de binary in het image start de nieuwe versie vanaf het volume nadat hij de handtekening nog een keer heeft gecontroleerd.

docker run -d --name provibr-agent --restart unless-stopped \
  --hostname provibr-agent \
  --read-only --cap-drop ALL --security-opt no-new-privileges \
  -v provibr-agent-data:/var/lib/provibr-agent \
  -e PROVIBR_INSTALL_URL='https://app.provibr.com/api/install/<token>' \
  -e PROVIBR_ACTIVATION_CODE='XXXXX-XXXXX' \
  -e PROVIBR_SELF_UPDATE=volume \
  ghcr.io/provibr/provibr-agent:latest

Een nieuwe versie heeft 60 seconden om het platform te bereiken. Lukt dat niet, dan wordt hij op het volume als slecht gemarkeerd en nooit meer gestart, en komt de container terug met de vorige versie. Rol je een nieuwer image uit, dan wint het image: wat er voor het oude image op het volume stond wordt niet meer gebruikt.

Het standaardimage heeft geen runtime voor automatiseringen. Het tools-image, met het tag-achtervoegsel -tools, bevat dezelfde getekende agent op Debian met de vastgepinde runtime voor automatiseringen erbij, zodat automatiseringen in de container kunnen draaien. De Docker-voorbeelden geven het een kleine /tmp en een pids-limiet (--pids-limit); op Kubernetes is /tmp een emptyDir in het geheugen, en een pids-limiet stel je in op de kubelet (podPidsLimit), niet in het manifest. Het root-bestandssysteem blijft alleen-lezen.

docker run -d --name provibr-agent --restart unless-stopped \
  --hostname provibr-agent \
  --read-only --cap-drop ALL --security-opt no-new-privileges \
  --tmpfs /tmp:rw,noexec,nosuid,size=16m --pids-limit 256 \
  -v provibr-agent-data:/var/lib/provibr-agent \
  -e PROVIBR_INSTALL_URL='https://app.provibr.com/api/install/<token>' \
  -e PROVIBR_ACTIVATION_CODE='XXXXX-XXXXX' \
  ghcr.io/provibr/provibr-agent:latest-tools

Sommige functies hebben de host zelf nodig, en die heeft een afgeschermde container niet:

• Netwerkinstallaties (PXE): die hebben het hostnetwerk en poorten onder 1024 nodig.
• De host herstarten vanuit het paneel: de container kan niet bij het init-systeem van de host.
• Automatiseringen in het standaardimage: daar zit geen runtime voor automatiseringen in, en de sandbox die ze op een host krijgen heeft user namespaces nodig, die een afgeschermde container niet geeft. Het tools-image draait ze in plaats daarvan in de container zelf.
• Hostmetingen: cpu, geheugen en uptime beschrijven de machine waarop de container draait, niet de eigen limieten van de container.

Als je een agent aanmaakt, toont het paneel één keer een activatiecode. Hij wordt nergens vastgelegd, ook niet als hash. De code is waarmee het licentiebestand versleuteld is, dus het bestand op je host is versleuteld met iets dat niet op die host staat.

Het licentiebestand zelf draagt geen geheim over je infrastructuur. Het vertelt de agent bij welk platform hij hoort, welke certificaatautoriteit hij moet vertrouwen, en het eenmalige token waarmee hij enrollt.

De agentlijst laat alles in één keer zien: status, versie, of hij nu verbonden is, wanneer hij voor het laatst gezien is en wanneer zijn certificaat verloopt.

• Naam en omschrijving mag je zelf wijzigen en zijn alleen labels. Een naam die al in een afgeleverd licentiebestand staat blijft zoals hij was; dat is cosmetisch en geen reden om opnieuw te enrollen.
• Verbonden of niet wordt gelezen uit een live signaal met een korte houdbaarheid, niet uit het moment waarop er voor het laatst een regel is weggeschreven. Kunnen we het niet vaststellen, dan zegt het paneel dat, in plaats van te beweren dat je agent eruit ligt.
• Versie en besturingssysteem zijn wat de agent bij zijn laatste verbinding meldde. Een agent die nooit verbond toont een streepje in plaats van een gok.
• Selecteer meerdere agents in de lijst om ze in één keer bij te werken. De knop telt alleen de agents die nu echt bijgewerkt kunnen worden, dus je ziet vóór het klikken dat twaalf geselecteerd er drie bijgewerkt betekent.
• De voortgang wordt gelezen uit de opdracht die loopt, niet uit iets dat je browser onthouden had, dus een herlaadbeurt pakt hem weer op.

Wacht op enrollment

Aangemaakt in het paneel, nog niet geënrolld. Er staat een token en een activatiecode voor hem klaar, en nog geen certificaat.

Geënrolld

Hij heeft zijn eigen certificaat en mag verbinden. Dit is de enige toestand waarin hij werk kan krijgen, en de enige waarin hij niet verwijderd kan worden.

Ingetrokken

Door jou ingetrokken. Zijn sessie is gesloten, openstaande tokens zijn vervallen, en terugkomen mag hij niet.

Intrekken is de knop waar je naar grijpt als een host gecompromitteerd is, uit dienst gaat of gewoon niet meer van jou is. Het werkt zonder dat je de host aanraakt.

• Een lopende sessie wordt binnen de minuut gesloten. De agent krijgt te horen waarom, in plaats van er zomaar uit te vliegen.
• De agent wist daarna zijn eigen identiteit, zijn certificaat en zijn credential-vault. De inloggegevens van je hypervisor zijn van die host verdwenen.
• Openstaande enrollment-tokens vervallen, dus een licentiebestand dat al gedownload was kan niet gebruikt worden om terug te komen.

Verwijderen haalt de agent uit het paneel. Het is een aparte stap naast intrekken, en het is met opzet kieskeurig over wanneer het mag.

• Een geënrollde agent kan niet verwijderd worden. Trek hem eerst in, want anders zou je de registratie weghalen van iets dat nog verbonden is.
• Een agent met integraties of servers eronder kan ook niet verwijderd worden, en de weigering noemt allebei de aantallen. Die regels hangen aan de agent, dus één klik zou je inventaris meenemen.
• Heeft de agent nooit een opdracht uitgevoerd en nooit een server gehad, dan verdwijnt de registratie echt. Anders wordt hij overal verborgen maar blijft zijn opdrachtgeschiedenis bewaard, want een auditspoor dat je kunt wissen door zijn onderwerp te verwijderen is geen auditspoor.

Intrekken wist de geheimen van de agent maar laat de bestanden staan. Om de host op te ruimen biedt het paneel een tweede one-liner, en dezelfde vier stappen met de hand.

1. 01

   De service stoppen, uitzetten en de unit verwijderen.

   shellKopiëren

   # Stop the service and forget the unit
   sudo systemctl disable --now provibr-agent
   sudo rm -f /etc/systemd/system/provibr-agent.service
   sudo systemctl daemon-reload
   sudo systemctl reset-failed provibr-agent 2>/dev/null || true

2. 02

   De binary, het updatescript en de updatesleutel verwijderen.

   shellKopiëren

   # Binary, update script and the trust anchor of the update step
   sudo rm -f /usr/local/bin/provibr-agent
   sudo rm -f /usr/local/lib/provibr-agent/apply-update.sh /usr/local/lib/provibr-agent/license-signing.pub
   
   # The polkit rule that allowed host.reboot (and its 0.105 fallback)
   sudo rm -f /etc/polkit-1/rules.d/49-provibr-agent-reboot.rules /etc/polkit-1/localauthority/50-local.d/49-provibr-agent-reboot.pkla
   
   # Only if nothing else lives in there
   sudo rmdir /usr/local/lib/provibr-agent 2>/dev/null || true

3. 03

   De data verwijderen. Dit is de stap die telt: de licentie, de vault-sleutel en de versleutelde inloggegevens staan hier.

   shellKopiëren

   # License and vault key
   sudo rm -rf /etc/provibr-agent
   
   # Identity, encrypted credential vault, outbox and staged updates
   sudo rm -rf /var/lib/provibr-agent

4. 04

   Het serviceaccount verwijderen.

   shellKopiëren

   sudo userdel provibr-agent
   sudo groupdel provibr-agent 2>/dev/null || true

Daarna horen deze twee allebei helemaal niets af te drukken:

ls -d /etc/provibr-agent /var/lib/provibr-agent /usr/local/lib/provibr-agent /usr/local/bin/provibr-agent /etc/systemd/system/provibr-agent.service /etc/polkit-1/rules.d/49-provibr-agent-reboot.rules /etc/polkit-1/localauthority/50-local.d/49-provibr-agent-reboot.pkla 2>/dev/null
id provibr-agent 2>/dev/null
# Both commands should print nothing at all