Connecter Proxmox VE

Velnex vend des VPS KVM créés sur votre nœud Proxmox VE : au paiement, il clone un modèle cloud-init, lui applique les ressources de l’offre, un mot de passe aléatoire et une adresse IP, puis le démarre. Il gère ensuite la suspension, la résiliation, le changement d’offre, et donne à vos clients une vraie page VPS : état, graphiques, réinstallation et console web.

Ce qu’il vous faut

Velnex utilise toujours un clone complet (jamais lié) du modèle, sur le nœud indiqué dans le serveur : les modèles doivent se trouver sur ce nœud.

1. Créer l’utilisateur, le rôle et le jeton API

Sur le nœud, en root (shell du nœud ou SSH), créez un utilisateur dédié et un rôle limité aux droits dont Velnex a besoin.

Proxmox VE 9 :

pveum user add velnex@pve --comment "Facturation Velnex"
pveum role add VelnexProvisioning --privs "VM.Allocate VM.Clone VM.Config.CPU VM.Config.Memory VM.Config.Disk VM.Config.Network VM.Config.Cloudinit VM.Config.Options VM.PowerMgmt VM.Audit VM.Console VM.GuestAgent.Audit Datastore.AllocateSpace Datastore.Audit SDN.Use Sys.Audit"
pveum acl modify / --users velnex@pve --roles VelnexProvisioning
pveum user token add velnex@pve billing --privsep 0

Proxmox VE 8 : même chose, mais VM.Monitor remplace VM.GuestAgent.Audit (qui n’existe pas encore en version 8) :

pveum role add VelnexProvisioning --privs "VM.Allocate VM.Clone VM.Config.CPU VM.Config.Memory VM.Config.Disk VM.Config.Network VM.Config.Cloudinit VM.Config.Options VM.PowerMgmt VM.Audit VM.Monitor VM.Console Datastore.AllocateSpace Datastore.Audit SDN.Use Sys.Audit"

La dernière commande affiche l’ID complet du jeton (velnex@pve!billing) et sa valeur (le secret, un UUID) : copiez-la tout de suite, Proxmox ne la réaffiche jamais.

À quoi sert chaque droit :

Séparation des privilèges : avec --privsep 0, le jeton a exactement les droits de l’utilisateur velnex@pve. Si vous préférez --privsep 1, donnez aussi le rôle au jeton : pveum acl modify / --tokens 'velnex@pve!billing' --roles VelnexProvisioning.

Tout se fait aussi dans l’interface : Datacenter → Permissions → Users (Add), Roles (Create), API Tokens (Add), puis Permissions → Add → User Permission sur le chemin /.

2. Préparer le réseau

Choisissez comment vos VPS obtiennent leur adresse :

• DHCP : un serveur DHCP répond sur le pont des VM (celui de votre hébergeur, un dnsmasq, ou le DHCP des zones SDN de Proxmox). L’adresse obtenue est lue par l’agent invité : sans lui, le client voit « Adresse en cours d’attribution… ».
• IP fixes (conseillé pour de l’hébergement) : vous déclarez vos blocs d’adresses dans Velnex (étape 6) ; chaque VM reçoit une IPv4 libre (et une IPv6 si vous en déclarez), écrite par cloud-init. Aucun DHCP n’est nécessaire.

3. Construire un modèle cloud-init

Chaque modèle doit avoir un lecteur cloud-init et qemu-guest-agent. Exemple avec l’image cloud officielle de Debian 12 (VMID 9000, stockage local-lvm, pont vmbr0) :

cd /root
wget https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2

qm create 9000 --name debian12-cloud --memory 1024 --cores 1 --ostype l26 \
  --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-pci
qm importdisk 9000 debian-12-genericcloud-amd64.qcow2 local-lvm
qm set 9000 --scsi0 local-lvm:vm-9000-disk-0
qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --boot order=scsi0
qm set 9000 --serial0 socket --vga serial0
qm set 9000 --agent enabled=1

• qm importdisk (ou qm disk import) ajoute le disque en « unused » : vérifiez son nom avec qm config 9000 avant qm set --scsi0 (sur un stockage de type répertoire, il ressemble à local:9000/vm-9000-disk-0.raw). Variante en une ligne : qm set 9000 --scsi0 local-lvm:0,import-from=/root/debian-12-genericcloud-amd64.qcow2.
• --serial0 socket --vga serial0 : la console web du client sera un terminal série (xterm.js), léger et net. Sans ces options (écran VGA standard), elle sera en noVNC.
• Ne réglez pas l’utilisateur, le mot de passe ni l’IP cloud-init du modèle : Velnex les écrit sur chaque VM.
• Gardez un petit disque (2–3 Go) : Velnex l’agrandit à la taille de l’offre après le clone (jamais il ne le réduit), et un petit modèle se clone plus vite.

Pour Ubuntu 24.04, même recette avec https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img.

Installer qemu-guest-agent

Les images cloud ne contiennent pas l’agent. Deux méthodes, au choix :

Option A — image préparée hors ligne (conseillé en production) : l’agent est déjà dans l’image, rien n’est téléchargé au démarrage des VM. À faire avant qm importdisk :

apt install -y libguestfs-tools
# Sans virtualisation imbriquée : export LIBGUESTFS_BACKEND=direct (plus lent, mais fonctionne)
virt-customize -a debian-12-genericcloud-amd64.qcow2 \
  --install qemu-guest-agent \
  --run-command 'systemctl enable qemu-guest-agent' \
  --truncate /etc/machine-id

Option B — snippet cloud-init « vendor » : l’agent est installé au premier démarrage de chaque VM (il faut alors un accès Internet et DNS à ce moment-là) :

pvesm set local --content iso,vztmpl,backup,snippets
mkdir -p /var/lib/vz/snippets
cat > /var/lib/vz/snippets/velnex-qga.yaml <<'EOF'
#cloud-config
package_update: true
packages:
  - qemu-guest-agent
runcmd:
  - [systemctl, enable, --now, qemu-guest-agent]
EOF
qm set 9000 --cicustom "vendor=local:snippets/velnex-qga.yaml"

Seul le fichier « vendor » est remplacé : utilisateur, mot de passe, clés SSH et réseau restent générés par Proxmox à partir des réglages de Velnex. Avec pvesm set, gardez bien les contenus existants de votre stockage local.

Convertir en modèle

qm template 9000

Nommez vos modèles clairement (debian12-cloud, ubuntu-2404…) : Velnex en déduit le nom montré au client (« Debian 12 », « Ubuntu 24.04 ») si vous ne lui en donnez pas.

4. Ajouter le serveur dans Velnex

Catalogue → Serveurs → Nouveau serveur, fournisseur Proxmox VE :

Enregistrez, puis Tester la connexion : « Connexion réussie » confirme que le nœud répond et que le jeton est valide. En cas d’échec, le détail exact (erreur TLS, 401, 403…) est dans storage/logs/laravel.log.

Certificat : plutôt que de désactiver la vérification, donnez au nœud un vrai certificat (Datacenter → ACME, puis nœud → System → Certificates → Order Certificates Now) et gardez « Oui ».

Le secret est chiffré et n’est jamais réaffiché ; laissez le champ vide pour le conserver. Si vous changez l’URL, ressaisissez-le.

5. Configurer un produit

Catalogue → Produits → Nouveau produit, section Provisioning : fournisseur Proxmox VE, puis votre serveur. Les listes (modèles, stockages, ponts) se chargent depuis le nœud.

Le mot de passe du VPS est toujours généré par Velnex (20 caractères) et montré, masqué, au client.

Laisser le client choisir (RAM, disque, système…) : ajoutez des Options de commande au produit et choisissez comme Réglage remplacé l’option à remplacer, par exemple memory avec les valeurs 4096 (+ 5 €/mois) et 8192 (+ 12 €/mois), ou template avec le VMID de chaque système.

6. Pools d’adresses IP

En mode Fixe, les adresses viennent des pools du serveur : Catalogue → Serveurs → votre serveur Proxmox → Adresses IP. Un pool est partagé par tous les produits de ce serveur.

1. Nouveau pool : Nom du pool (ex. « Bloc /27 principal »), Passerelle IPv4, Préfixe IPv4 (ex. 24), Passerelle IPv6 et Préfixe IPv6 (facultatifs), Serveurs DNS séparés par des espaces (ex. 1.1.1.1 9.9.9.9 2606:4700:4700::1111).
2. Adresses : une plage ou une adresse par ligne.

203.0.113.10-203.0.113.50
203.0.113.60-70
203.0.113.80
198.51.100.10-50/24 gw 198.51.100.1   # autre réseau, sa propre passerelle
2001:db8::10-2001:db8::1f/64 gw 2001:db8::1

# commence un commentaire ; une ligne compte au plus 4096 adresses (inutile de lister un /64 entier). Si la passerelle ou le préfixe du pool sont vides, ils sont repris de la première ligne.

Chaque nouveau VPS reçoit une IPv4 libre (et une IPv6 si le serveur en a), écrite par cloud-init avec la passerelle et les DNS du pool. À la résiliation, les adresses reviennent automatiquement dans le pool.

Sur la page, filtrez par état (Libre, Utilisée, Réservée), par pool ou par recherche, et :

• Réserver une adresse libre (avec une note, ex. « passerelle du client X ») pour qu’elle ne soit jamais attribuée ;
• Libérer une adresse réservée, ou détachée d’un service qui n’existe plus (refusé tant que le service est actif) ;
• Supprimer l’adresse, Modifier le pool, Supprimer le pool (refusé tant que des services utilisent ses adresses).

Quand il n’y a plus d’adresse, la création échoue avec « Plus aucune adresse IPv4 libre dans les pools du serveur … » : ajoutez des adresses, puis relancez la création depuis la fiche du service.

7. Ce que voit votre client

La page du VPS dans l’espace client affiche :

• état (en ligne / hors ligne), boutons Démarrer, Arrêter (arrêt immédiat) et Redémarrer ;
• consommation en direct : CPU, mémoire, disque (avec l’agent invité), réseau et durée de fonctionnement ;
• graphiques CPU, mémoire, réseau et disque sur 1 h, 24 h, 7 j ou 30 j ;
• système, nom d’hôte, localisation, IPv4 / IPv6, passerelle, DNS, adresse MAC, ressources ;
• accès : utilisateur, mot de passe masqué (révélé ou copié à la demande) et la commande ssh utilisateur@ip à copier ;
• Réinstaller le serveur avec le choix du système : le client tape le nom du service pour confirmer. Limite de 3 réinstallations par jour. L’adresse IP, les ressources et l’abonnement sont conservés, un nouveau mot de passe est généré. Le nouveau système est cloné à côté de l’ancien, puis les VM sont échangées : en cas d’échec, l’ancien serveur est remis en service tel quel ;
• Console : écran noVNC ou terminal série selon le modèle, avec Ctrl+Alt+Suppr, plein écran et reconnexion. Le serveur doit être démarré.

8. La console web

Le navigateur ne peut pas se connecter directement à Proxmox (il faudrait lui donner le jeton API) : Velnex passe par un relais. Le client reçoit un jeton à usage unique valable 60 secondes, se connecte au relais sur wss://votre-domaine/console-ws, et le relais ouvre la session chez Proxmox avec le jeton API.

L’installateur de Velnex met tout en place : le service velnex-console (relais sur 127.0.0.1:8090, mémoire limitée), le bloc Nginx location /console-ws et ses limites par adresse IP (/etc/nginx/conf.d/velnex-console.conf). Pour vérifier :

systemctl status velnex-console
grep -A12 "location /console-ws" /etc/nginx/sites-available/velnex.conf
cat /etc/nginx/conf.d/velnex-console.conf

Si votre Nginx a été configuré à la main, créez /etc/nginx/conf.d/velnex-console.conf (limites par adresse IP, déclarées au niveau http) :

limit_conn_zone $binary_remote_addr zone=velnex_console_conn:10m;
limit_req_zone $binary_remote_addr zone=velnex_console_req:10m rate=30r/m;

puis ajoutez dans le bloc server HTTPS du site (sans journal d’accès : l’adresse contient le jeton à usage unique) :

location /console-ws {
    limit_conn velnex_console_conn 8;
    limit_req zone=velnex_console_req burst=10 nodelay;
    limit_conn_status 429;
    limit_req_status 429;
    access_log off;
    error_log /var/log/nginx/error.log crit;
    proxy_pass http://127.0.0.1:8090;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_buffering off;
    proxy_connect_timeout 5s;
    proxy_send_timeout 3600s;
    proxy_read_timeout 3600s;
}

Et bornez la mémoire du service : dans /etc/systemd/system/velnex-console.service, ExecStart=/usr/bin/php -d memory_limit=256M artisan vexora:console-relay --host=127.0.0.1 --port=8090 et MemoryMax=384M (section [Service]), puis systemctl daemon-reload && systemctl restart velnex-console && nginx -t && systemctl reload nginx.

Le relais se protège aussi lui-même : messages de 1 Mio au plus, 200 consoles ouvertes au total et 4 par client, quelques secondes pour s’authentifier, et chaque sens attend que l’autre lise au lieu d’accumuler en mémoire. Une console ouverte se ferme d’elle-même dans les secondes qui suivent la suspension ou la résiliation du service, et le relais revérifie chaque minute que le service est toujours actif et au même client. Ces limites se règlent dans la section console de config/vexora.php.

Redémarrez le relais après chaque mise à jour de Velnex : systemctl restart velnex-console.

9. Pare-feu et sécurité

• N’exposez pas le port 8006 à tout Internet. Autorisez-le seulement depuis l’IP publique du serveur Velnex et vos propres IP d’administration : pare-feu de Proxmox (Datacenter → Firewall, un IPSet avec ces adresses et une règle ACCEPT TCP 8006), ou pare-feu de votre réseau / hébergeur. Gardez une session SSH ouverte pendant que vous activez le pare-feu de Proxmox.
• Le serveur Velnex doit joindre le nœud sur 8006 : l’API et la console passent par là. Aucun port n’est à ouvrir du nœud vers Velnex.
• Utilisez un utilisateur et un jeton dédiés à Velnex, avec le rôle ci-dessus : jamais root@pam. Pour révoquer l’accès : pveum user token remove velnex@pve billing.
• Velnex ne touche qu’aux VM qu’il a créées (nommées vexora-service-<numéro>) : si un VMID a été réutilisé par une autre VM, il refuse d’y toucher.

Cycle de vie d’un VPS

Une création qui échoue est retentée automatiquement 4 fois (après 1, 5 puis 15 minutes) et reprend la même VM ; ensuite le service passe en « Échec de création » et l’équipe est prévenue par e-mail. Corrigez la cause, puis relancez la création depuis la fiche du service.

Dépannage