HestiaCP-facturatie en -provisioning automatiseren

Een geautomatiseerd hostingproduct heeft precies drie momenten waarop geld en machines elkaar raken:

1. 01De bestelling is betaald: er moet binnen enkele seconden een account bestaan, met het juiste pakket.
2. 02De factuur is te laat: het account moet uit, en terug zodra er betaald wordt.
3. 03Het abonnement eindigt: het account moet weg, echt weg, inclusief de data.

HestiaCP heeft voor elk daarvan een commando. Wat het niet heeft is iets dat beslist wanneer je ze draait. Deze pagina gaat over het aan elkaar knopen van die twee helften, en over de plekken waar de API van HestiaCP antwoordt op een manier die een eerste poging stilletjes sloopt.

De drie momenten, en de commando's eronder

Let op de antwoordkolom. Een geslaagde mutatie op HestiaCP is HTTP 204 met niets in de body. Geen 200. Een client die geschreven is met de aanname dat succes 200 is, weigert elke aanroep die werkte, en probeert het daarna meestal opnieuw, en zo wordt een werkende koppeling een buitengesloten koppeling (zie hieronder).

Het echte antwoord staat in een responskop, Hestia-Exit-Code, met een getal uit een vaste tabel. De HTTP-status is daarvan afgeleid en vouwt zo'n twintig codes op vier statussen. Lees de kop; behandel de status als een hint.

Opschorten is niet symmetrisch, en dat telt hier zwaarder dan elders

Dit is de valkuil die specifiek een facturatiekoppeling raakt, want een facturatiekoppeling is het enige dat hetzelfde account twee keer opschort.

Gemeten, op hetzelfde account:

v-suspend-user   op een actief account       → 204, exit 0
v-suspend-user   op een opgeschort account   → 401, exit 5   ("user X is suspended")
v-unsuspend-user op een opgeschort account   → 204, exit 0
v-unsuspend-user op een actief account       → 204, exit 0

Hervatten is idempotent. Opschorten niet. En de fout die het oplevert is HTTP 401, dezelfde status als bij een verkeerd geheim, een sleutel buiten zijn scope, en een geblokkeerd adres.

Een aanmaanronde die alles opschort wat te laat is, inclusief wat gisteren al opgeschort werd, meldt dus authenticatiefouten voor accounts die precies in de stand staan die je wilde. Exitcode 5 op v-suspend-user betekent "stond al zo" en moet als succes gelezen worden.

Nooit opnieuw proberen na een authenticatiefout

HestiaCP blokkeert een adres na vijf geweigerde aanmeldingen, met fail2ban, maxretry = 5 en een iptables-DROP. Zodra dat vuurt lopen aanroepen niet meer op applicatieniveau in een timeout maar op netwerkniveau. Je monitoring zegt dat het paneel onbereikbaar is, en niets in je logs wijst naar een inloggegevensprobleem.

Voor een facturatiekoppeling telt dat zwaarder dan voor wat dan ook, want een facturatiekoppeling is wat 's nachts onbemand draait. Twee gevolgen:

• Exitcodes 9, 10 en 21 mogen nooit een automatische herhaling uitlokken. Dat zijn respectievelijk verkeerd geheim, permissie geweigerd en API uit. Geen van drieën is een tijdelijke storing, en alle drie tellen mee voor de blokkade.
• Een commando buiten de permissies van de sleutel telt óók als mislukte aanmelding. Dat is niet vanzelfsprekend: dezelfde logregel wordt geschreven voor een verkeerd geheim en voor een geldige sleutel die naar een commando reikt dat hij niet mag draaien. Een sleutel gescoped met de meegeleverde billing-set mist v-list-user-packages en v-list-web-domains, dus een pollronde die pakketten en domeinen leest brandt de blokkadeteller volgens schema op. Gebruik een ongescopete sleutel voor de admin.

Een blokkade opheffen vergt een shell op de paneelhost: v-delete-firewall-ban <adres> HESTIA. Als de software die je bouwt die zin niet kan zeggen, besteedt degene die om drie uur 's nachts piket heeft de nacht aan het verkeerde probleem.

Een betaalde bestelling kost twee aanroepen, en dus een terugrol

HestiaCP heeft geen commando dat een gebruiker aanmaakt en meteen een domein eronder hangt. Dat laat een venster open:

v-add-user       provibrtest1 …                        → 204, exit 0
v-add-web-domain provibrtest1 "geen geldig domein"      → 422, exit 2
v-list-user      provibrtest1                           → het account bestaat, met nul domeinen

Een echte unix-gebruiker, met een home-directory, zonder website, en met een rij in elke telling. Was het domein van de klant al bezet op je paneel (en dat gebeurt, want klanten verhuizen), dan faalt de bestelling en hou je een half account over dat niemand ooit opmerkt.

De regel is simpel en moet ingebouwd zijn: mislukt stap twee, verwijder dan de gebruiker en meld de oorspronkelijke fout. Een geweigerd domein mag nooit een half account achterlaten.

Provibr doet precies dat, en de fout die de klant ziet is die van HestiaCP over het domein, niet een tweede fout over een opruimactie.

Waar de factuur eigenlijk staat

De moeite waard om expliciet te zijn, want het is het meest voorkomende misverstand: Provibr factureert jouw klanten niet. Het stuurt ze geen rekening, maant ze niet aan, en weet niet wat je ze in rekening brengt. Die relatie is van jou.

Wat Provibr factureert is de capaciteit die jij reserveert: hoeveel hostingaccounts je tegelijk mag draaien, per maand, tegen een staffelprijs. Wat je je eigen klanten voor een HestiaCP-account rekent, en hoe, blijft volledig binnen je eigen facturatiesysteem.

Er zijn twee manieren om de twee helften te verbinden:

Een WHMCS-module. Draai je al WHMCS, installeer dan de Provibr-provisioningmodule en laat één WHMCS-product naar één Provibr-webhostingplan wijzen. Een betaalde bestelling maakt het account, een opschorting schort het op, een beëindiging verwijdert het. Je klant houdt één account, één factuur en één login. De module is een gewone zip die je zelf installeert en die in jouw WHMCS draait. Aan onze kant hoeft er niets aangezet te worden.

De REST-API. Draai je FOSSBilling, Blesta, iets eigens, of een spreadsheet met een cronjob, stuur het dan rechtstreeks aan. Eén sleutel, één basis-URL, en precies de rechten die het lid achter die sleutel al heeft.

De ene regel voor aansturing uit eigen code

Alles wat een machine raakt is asynchroon, en dat moet ook. Je infrastructuur is alleen bereikbaar via de agent in je eigen netwerk, en die verbindt uitgaand. Een endpoint dat een account wijzigt kan dus niet met het resultaat antwoorden. Het antwoordt dat de opdracht is aangenomen en geeft je een commando om te volgen, dat je leest tot de status definitief is: klaar, mislukt, verlopen of geannuleerd. Een mislukt commando draagt de foutcode van de agent zelf mét zijn parameters, dezelfde die het paneel op je scherm rendert.

Lezen werkt nooit zo. Een inventaris, een adres of een factuur antwoordt meteen, want dat antwoord komt uit een database en niet van jouw host.

Het praktische gevolg voor een facturatiehook: markeer de bestelling niet als afgerond op het aangenomen-antwoord. Op HestiaCP kost v-add-user ongeveer een seconde en v-delete-user ongeveer drie, dus het wachten is kort, maar het antwoord dat je eerst krijgt is "we hebben het verstuurd", niet "het is gelukt".

Opschorten is ook je eigen kostenbeheersing

Eén verband dat makkelijk te missen is. In Provibr telt een opgeschorte server niet mee voor je capaciteit, en voor een hostingaccount bestaat er geen "gestopt": er is actief en opgeschort.

De aanmaanactie die je om commerciële redenen toch al wilde draaien is dus ook degene die de plek vrijmaakt waarvoor je betaalt. Schort een te laat account op en het telt meteen niet meer mee; verwijder het en het telt ook niet meer mee; laat het draaien en onbetaald en je betaalt ervoor.

Wat dit niet automatiseert

Provibr beheert accounts, niet het paneel. Het installeert HestiaCP niet, werkt het niet bij, wijzigt geen serverinstellingen en raakt DNS, mailboxen en databases niet aan. Een klant die zijn eigen mailbox via HestiaCP verwijdert doet dat zonder dat iets erboven het weet of erom geeft. Er is geen console voor een hostingaccount. En er is geen gedeeltelijke opschorting: een account is actief of niet.

Verkoop je ook VPS'en, gameservers of cPanel-accounts, dan gelden dezelfde drie momenten daar net zo goed, en ze kunnen in één inventaris leven. Provibr draait vandaag zijn controlepanelen, hypervisors en gamepanelen naast elkaar, met één rechtenmodel en één activiteitenlog over het geheel.