Vendre de l’hébergement web avec HestiaCP

HestiaCP est le panneau de contrôle libre le plus vivant qui soit. Mesuré sur GitHub le 21 août 2026 : 4 481 étoiles, 345 contributeurs et trois versions publiées en une seule semaine. Il vous donne des comptes, des paquets, du DNS, du courrier, des bases de données et une interface propre, et il ne coûte rien.

Ce qu’il ne vous donne pas, c’est un moyen de vendre tout cela. Pas de formulaire de commande, pas de facture, pas de relance, pas de « ce client ne paie plus, coupez-le ». Cherchez hestiacp billing et, mesuré le même jour, les premiers résultats sont des fils de forum : des gens qui demandent comment vendre des comptes HestiaCP, et d’autres qui répondent avec un demi-script.

Cette page traite de la couche au-dessus : ce que l’API de HestiaCP renvoie réellement, où elle vous mordra, et ce qui doit être juste avant de placer un bouton Commander devant un inconnu.

Ce que HestiaCP vous donne déjà

Deux choses, et ce sont les bonnes.

Les paquets. Un paquet HestiaCP décrit ce qu’un compte peut utiliser : espace disque, trafic, et combien de domaines, de bases de données et de boîtes aux lettres. C’est votre catalogue produit, défini une fois et désigné partout ailleurs par son seul nom.

Un cycle de vie de compte qui épouse un abonnement. Créer, suspendre, réactiver, déplacer vers un autre paquet, supprimer : exactement les états que traverse un compte d’hébergement payant, et il existe une commande pour chacun.

Le reste de cette page traite de l’écart entre ce tableau et quelque chose sur quoi compter à trois heures du matin.

L’API a deux portes, et l’une d’elles ment

POST https://host:8083/api/ accepte deux sortes d’identifiants, et celle que vous envoyez décide quel code traite votre requête. L’ancienne voie prend un nom d’utilisateur et un mot de passe. La plus récente, disponible depuis HestiaCP 1.6, prend une clé d’accès : un identifiant de 20 caractères et un secret de 40 caractères.

Elles ne se comportent pas pareil. En envoyant une commande qui n’existe pas :

La voie historique signale un succès pour une commande qui n’a jamais tourné. La cause est visible dans le source de HestiaCP : elle affiche OK dès que l’authentification a renvoyé zéro et que la commande n’a rien écrit sur la sortie standard. Elle ne regarde jamais le code de sortie de la commande elle-même, et ne pose jamais de statut HTTP ni d’en-tête de code de sortie pour le résultat. Toute commande qui échoue silencieusement revient en OK.

Donc : utilisez les clés d’accès. Non seulement parce que la voie historique peut mentir, mais parce qu’une clé se révoque séparément, figure nommément dans le panneau, et ne met pas le mot de passe administrateur de votre panneau dans le coffre de quelqu’un d’autre. Ne construisez pas non plus de repli de l’une vers l’autre : deux portes signifient deux surfaces d’erreur, et ici la porte de repli est celle qui n’est pas fiable.

Le statut HTTP n’est pas la réponse, le code de sortie si

HestiaCP replie une vingtaine de codes de sortie internes sur quatre statuts HTTP. Deux conséquences, toutes deux mesurées.

Une mutation réussie renvoie 204, pas 200. Chaque v-add-user, v-suspend-user, v-delete-user, v-add-web-domain et v-change-user-package est revenue en HTTP 204 avec un corps vide. Un client qui n’accepte que 200 rejette donc chaque appel qui a fonctionné.

HTTP 401 signifie ici quatre choses différentes : mauvais secret (sortie 9), clé hors de ses permissions (10), adresse non autorisée (10), et « cet utilisateur est déjà suspendu » (5). Un client qui lit 401 comme « identifiants erronés » vous annoncera une clé expirée alors que vous avez seulement suspendu un compte deux fois.

Lisez Hestia-Exit-Code. Le statut n’en est qu’une dérivée.

Celui qui vous met vraiment à terre

Cinq appels refusés et HestiaCP bannit votre adresse. Ce n’est pas une limite de débit dont on peut se retirer : c’est fail2ban, configuré d’origine avec maxretry = 5 sur /var/log/hestia/auth.log, et cela finit en DROP iptables. Ensuite le panneau ne refuse plus vos appels, il ne répond plus du tout : votre supervision affiche des délais dépassés et cela ressemble à un problème réseau.

Ce qui piège, c’est ce qui compte comme connexion refusée. Pas seulement un mauvais secret : la vérification de clé de HestiaCP écrit la même ligne failed to login lorsqu’une clé sert à une commande hors de son jeu de permissions. Mesuré, dans le journal d’authentification du panneau lui-même :

12:57:52 <key> 84.85.173.142 v-list-users successfully launched
12:57:52 <key> 84.85.173.142 failed to login      ← une commande hors de la portee de la cle

Trois règles en découlent, et aucune n’est facultative.

1. 01Ne jamais réessayer automatiquement après une erreur d’authentification ou de permission. Une boucle de réessai sur une mauvaise clé vous enferme dehors en une minute, et le message que voit alors votre client est « panneau injoignable » au lieu de « la clé ne convient pas » : le pire signal possible, puisqu’il désigne le mauvais problème.
2. 02La clé doit être sans portée restreinte, donc celle de l’administrateur. Des permissions vides signifient toutes les commandes, et HestiaCP ne l’accepte que pour l’utilisateur root. Le jeu de permissions billing fourni d’origine s’en approche mais laisse de côté v-list-user-packages et v-list-web-domains, les deux commandes qui lisent votre catalogue de paquets et les domaines d’un compte. Avec ce jeu, les deux restent vides, et une clé restreinte qui les touche une fois par cycle de relevé vous bannit comme prévu.
3. 03Votre texte d’erreur doit le mentionner, car lever le bannissement demande un terminal sur le panneau : v-delete-firewall-ban <adresse> HESTIA.

Vide signifie personne

Encore un piège au premier essai. HestiaCP tient dans API_ALLOWED_IP une liste des adresses autorisées à utiliser l’API. Sur une installation neuve cette liste est vide, et vide signifie ici personne, pas tout le monde. Chaque appel revient en 401 avec IP is not allowed to connect with API alors que votre clé est parfaitement bonne. C’est la panne initiale la plus probable de toute l’intégration, et elle mérite son propre message plutôt qu’un « échec d’authentification » générique.

Créer un compte coûte deux appels, et cet écart est réel

DirectAdmin, cPanel et Virtualmin créent un compte avec son domaine en un seul appel. HestiaCP non :

v-add-user        USER PASSWORD EMAIL [PACKAGE] [NAME]   → cree l'utilisateur
v-add-web-domain  USER DOMAIN [IP] [RESTART] [ALIASES]   → rattache le domaine

Si le second appel échoue, parce que le domaine appartient déjà à quelqu’un ou que sa forme est refusée, il vous reste un vrai utilisateur unix, avec un répertoire personnel, sans site, et une ligne dans chaque comptage que vous faites. Mesuré avec un domaine volontairement invalide : l’utilisateur existait ensuite avec U_WEB_DOMAINS = 0. Quoi que vous construisiez, cela doit compenser : si l’étape deux échoue, supprimez l’utilisateur et signalez l’erreur d’origine.

Ce que Provibr en fait

Provibr se connecte à HestiaCP par un agent qui tourne dans votre propre réseau et sort en connexion sortante : rien n’a donc à être exposé sur le panneau. Vous lui donnez quatre choses : l’adresse du panneau avec le port 8083, l’identifiant de la clé d’accès, le secret, et, tant que le panneau utilise encore son certificat auto-signé, l’empreinte SHA-256 à épingler. L’agent les conserve dans son propre coffre sur votre hôte ; la plateforme ne peut pas les relire.

À partir de là :

• Les paquets deviennent vendables. Une formule d’hébergement web pointe vers un paquet d’une intégration, sous un nom à vous, à un prix que vous fixez.
• Cinq actions, désignées par le nom d’utilisateur : créer avec un domaine et un paquet, suspendre, réactiver, changer de paquet, supprimer. La création en deux appels est compensée comme décrit plus haut.
• La consommation arrive gratuitement avec le relevé. Chaque lecture de v-list-users porte DISK_QUOTA, U_DISK, BANDWIDTH et U_BANDWIDTH pour chaque compte, le tout en mégaoctets : limites et consommation arrivent donc sur la page du serveur et dans les graphiques sans second appel susceptible de prendre du retard sur le premier.
• Les comptes déjà présents s’importent. L’agent énumère ce qui se trouve sur le panneau et vous cochez lesquels deviennent des serveurs dans Provibr.

Ce que cela ne fait pas

Provibr gère des comptes, pas le panneau. Il n’installe pas HestiaCP, ne le met pas à jour, ne modifie aucun réglage serveur et ne touche ni au DNS, ni aux boîtes aux lettres, ni aux bases de données : tout cela reste dans HestiaCP, où vous et vos clients continuez de l’utiliser. Il n’y a pas de console pour un compte d’hébergement, car il n’y a rien à quoi la rattacher.

Et une note de performance honnête : relever un panneau comptant beaucoup de comptes coûte un appel supplémentaire par compte, car HestiaCP n’a aucune commande qui énumère les domaines de tous les comptes d’un coup. Mesuré sur 26 comptes, cela fait en série un peu plus de 8,5 secondes ; en parallèle cela passe sous les deux. Si vous écrivez cela vous-même, ne le faites pas en série : vers 60 comptes, un relevé en série commence à percuter son propre passage suivant.

Vous n’êtes pas obligé de choisir un panneau et de vous y tenir. Provibr fait tourner aujourd’hui ses panneaux de contrôle, ses hyperviseurs et ses panneaux de jeu côte à côte, dans un seul inventaire, avec un seul modèle de droits et un seul journal d’activité. HestiaCP pour les clients qui veulent un panneau ouvert, autre chose pour ceux qui demandent cPanel par son nom, et un seul endroit où vous voyez les deux.