Documentatie

Agent-updates

De agent werkt zichzelf bij volgens een schema dat je instelt, of op het moment dat je de knop indrukt. Deze pagina legt uit wat een release betrouwbaar maakt, wanneer het platform er zelf een uitdeelt, en hoe je er met de hand een installeert.

Wat een release betrouwbaar maakt

Twee onafhankelijke feiten moeten kloppen voordat een nieuwe binary op je host draait: hij moet dezelfde hashwaarde opleveren als het platform publiceerde, en hij moet een geldige handtekening over zijn ruwe bytes dragen, gezet met de release-sleutel van het platform.

De checksum bewijst dat de download intact is. Over wie hem gemaakt heeft zegt hij niets.
De handtekening bewijst wie hem gemaakt heeft. Hij wordt gecontroleerd door de agent voordat er iets wordt klaargezet, en nog eens door een script dat alleen root kan aanpassen voordat de binary geïnstalleerd wordt.
De publieke sleutel voor die tweede controle is van root. Het serviceaccount waaronder de agent draait kan hem niet vervangen, dus met een gekraakte agent krijg je nog steeds geen binary als root aan de praat.
Een release zonder handtekening wordt geweigerd. Net als een release waarvan de handtekening niet klopt, ook als de checksum wel klopt.

Bijwerken vanuit het paneel

Loopt een agent achter, dan zegt het paneel dat bovenaan zijn pagina en in de agentlijst. Druk op de knop en het platform geeft de agent een kortlevende downloadlink over de verbinding die al openstaat.

Eén agent: de banner op zijn pagina, of de updatekaart op het tabblad Instellingen.
Meerdere tegelijk: selecteer ze in de agentlijst en werk de selectie bij. Het aantal op de knop telt alleen de agents die nu echt bijgewerkt kunnen worden.
Het dashboard heeft per achterlopende agent een directe knop, zodat je niet hoeft te zoeken.
De voortgang overleeft het herladen van de pagina: hij wordt gelezen uit de opdracht die loopt, niet uit iets dat de browser onthoudt.

Een agent die offline is kan niet bijgewerkt worden. De knop blijft staan met de reden ernaast, want je wilt nog steeds weten dat er een update klaarstaat.

Het nachtelijke schema

Elke agent heeft een schema, en dat staat standaard aan om 03:00 Midden-Europese tijd. Is er op een van je tijdstippen een nieuwere release, dan geeft het platform die aan de agent zoals de knop dat doet. Verder verandert er niets: dezelfde ondertekende binary, dezelfde controles op de host, dezelfde terugval.

Meerdere tijdstippen per agent, hoogstens zes, op een raster van vijf minuten. Zes is genoeg voor elke vier uur en klein genoeg om in één oogopslag te lezen.
De tijdstippen worden gelezen op dezelfde wandklok als de rest van het paneel. Een tijdstip dat niet bestaat in de nacht dat de klok vooruitgaat draait een uur later in plaats van te worden overgeslagen, en een tijdstip dat twee keer bestaat draait één keer.
Er is een inhaalvenster van vijftien minuten en niet meer. Een update die voor 03:00 bedoeld was wil je niet om 09:00: je koos de nacht met een reden.
Een agent die op zijn tijdstip offline was slaat de nacht over zonder zijn slot te verbruiken, en pakt het volgende. Een agent die bereikbaar was maar al bij was verbruikt het slot wél, zodat zijn geschiedenis laat zien dat er gekeken is.
Hoogstens vijf agents van één account vertrekken per minuut. Een vloot van veertig haalt elk ongeveer 22 MB op, uit één netwerk, en dat over acht minuten spreiden past binnen het inhaalvenster.
Je krijgt een melding als een geplande update slaagt en als er een mislukt, gegroepeerd per account. Een falende agent meldt zich hoogstens één keer per dag, zodat een vastgelopen host je meldingen niet volschrijft met dezelfde zin.

De knop verdwijnt niet. Een geplande update en een ingedrukte knop zijn dezelfde handeling, en de agentpagina houdt een geschiedenis van de laatste tien bij, schema en knop in één lijst.

Wat er op de host gebeurt

De agent downloadt de nieuwe binary naast zichzelf, controleert de checksum en de handtekening, en stopt pas dan. Systemd herstart de service, een stap van root controleert de klaargezette binary nog een keer, installeert hem atomair en test of hij echt draait voordat hij hem houdt. Mislukt daar iets, dan blijft de oude binary staan en komt de service daarop terug.

Met de hand

Je hoeft het paneel niet te gebruiken. Alles wat de knop doet is ook een handvol commando's, en het paneel drukt ze voor je af met de huidige checksum en handtekening erin. De twee stappen die het waard zijn om te bewaren als je het zelf scriptt zijn de controlestappen:

Commando's en terminaluitvoer zijn overal Engels, in het paneel en op deze pagina's. Één tekst, één waarheid: wat je hier leest is letterlijk wat je host teruggeeft.

Controleer de checksum van wat je gedownload hebt.

shell

echo "<sha256-from-the-panel>  provibr-agent-linux-x86_64" | sha256sum -c -

Controleer de handtekening tegen de publieke sleutel op de host. Dit is de stap die een gewone download je niet geeft, en het is de stap die telt.

shell

openssl pkeyutl -verify -pubin -inkey /usr/local/lib/provibr-agent/license-signing.pub -rawin \
  -in ./provibr-agent-linux-x86_64 -sigfile ./provibr-agent-linux-x86_64.sig

Installaties van vóór het ondertekenen hebben één keer een nieuwe installerronde nodig, om de publieke sleutel en de bijgewerkte service-unit neer te zetten. Tot dat gebeurd is weigert het paneel de update met een duidelijke reden in plaats van halverwege te falen.

VorigeAgents VolgendeDashboard