Astral 360 WSA — Accélérateur de sites

Ligne de commande (CLI)

Référence complète des commandes wsa, pour l'automatisation, le dépannage et les opérations de masse.

WSA expose une CLI complète pour automatiser ses opérations (scripts shell, Ansible, cron tasks, déploiements). L'utilitaire est installé à /etc/wsa/wsa et se lance en tant que root.

⚠️ La CLI requiert un accès root. Toutes les commandes doivent être lancées depuis une session SSH connectée en root.

💡 Si la commande échoue avec « Permission denied » alors que vous êtes root, c'est généralement parce que le bit d'exécution a été retiré (hardening, restorecon, etc.). Deux alternatives :

  • /etc/wsa/./wsa <flags>
  • /usr/local/cpanel/3rdparty/bin/php /etc/wsa/wsa <flags>

1. Référence rapide — toutes les options

Tableau récapitulatif de toutes les options disponibles, par catégorie. Voir les sections suivantes (§2 à §10) pour les recommandations détaillées et les exemples d'utilisation complets.

Aide et information

Option Description
-h / --help Affiche l'aide intégrée
-v / --version Affiche la version installée
--verbose Mode verbeux (à combiner avec une autre commande)

Gestion du module

Option Description
--enable Active le module WSA
--disable Désactive le module (préserve la config)
--update Force la mise à jour vers la dernière version

Reconstruction de la configuration

Option Description
--rebuild Régénère uniquement les configs qui ont changé
--rebuild-user=<u> Régénère un seul compte cPanel
--rebuild-forced Reconstruit TOUTES les configurations
--no-lock Bypass le verrou .progress (à combiner)

Gestion de nginx

Option Description
--restart-nginx Redémarrage complet nginx
--reload-nginx Reload à chaud nginx
--check-httpd-conf Détecte changement de config Apache
--check-wsad Vérifie le démon wsad
--update-disk-usage MAJ stats de cache disque

Gestion du cache

Option Description
--purgecache-all Vide toute la cache (tous comptes)
--purgecache-user=<u> Vide la cache d'un compte cPanel
--purgecache-domain=<d> Vide la cache d'un domaine (+ --user=)
--purgecache-url=<url> Vide une seule URL du cache
--user=<u> Drapeau auxiliaire pour --purgecache-domain

Modules nginx (Brotli, HTTP/3, …)

Option Description
--nginx-list Liste les modules supportés
--nginx-status=<m> Snapshot JSON d'un module
--nginx-caninstall=<m> Test : compilation possible ?
--nginx-isinstalled=<m> Test : module installé ?
--nginx-isstatic=<m> Test : compilé statiquement ?
--nginx-isenabled=<m> Test : module activé ?
--nginx-install=<m> Compile et installe (+ --force, --verbose)
--nginx-uninstall=<m> Désinstalle
--nginx-enable=<m> Active dans nginx.conf
--nginx-disable=<m> Désactive dans nginx.conf
--nginx-upgrade-status MAJ paquet nginx disponible ? (JSON)
--nginx-upgrade Lance dnf upgrade nginx
--nginx-check-update Rafraîchit le cache de version
--nginx-recover-upgrade Auto-recovery post-upgrade
--nginx-recovery-state Snapshot dernier événement recovery
--nginx-recovery-clear Efface l'état de recovery
--nginx-protect-repos Applique versionlock anti-revert
--nginx-relock Réconcilie le lock dnf
--nginx-unlock Libère tous les locks WSA
--nginx-lock-status État JSON du lock complet

HTTP/3 (EL 9 / EL 10 uniquement)

Option Description
--http3-status Snapshot JSON : installé, stale, pins
--http3-caninstall Test d'éligibilité HTTP/3
--http3-install Compile + USR2 swap
--http3-uninstall USR2 swap retour RPM
--http3-rebuild Alias --http3-install --force
--http3-auto-rebuild[=on\|off] Lit/écrit l'auto-rebuild
--http3-enable Émet QUIC + Alt-Svc
--http3-disable Arrête émission QUIC

Surveillance et divers

Option Description
--list-watch-folders Liste les dossiers surveillés par inotify
--migrate-bp-v2131 Migration ponctuelle Bot Protection v2

💡 Drapeaux internes (à ne pas utiliser manuellement) : --secret-cron-bypass-oiusdtgsh, -q, -s. Voir §11 Drapeaux internes en bas de page.

2. Aide et version

--help (ou -h)

Affiche l'aide intégrée à la CLI. Liste toutes les options disponibles avec une brève description.

/etc/wsa/wsa --help

Sortie de /etc/wsa/wsa --help

--version (ou -v)

Affiche la version du module installé.

/etc/wsa/wsa --version
# 2.2.0

--verbose

Mode verbeux. À combiner avec n'importe quelle autre commande pour afficher des détails étape par étape. Particulièrement utile pour --update, --rebuild-forced, --http3-install, --nginx-install=brotli, qui streament leur sortie.

/etc/wsa/wsa --rebuild-forced --verbose

3. Gestion du module

--enable

Active le module WSA (vhosts nginx montés, démon wsad démarré, hooks cPanel activés). À utiliser après un --disable pour restaurer le service.

/etc/wsa/wsa --enable --verbose

--disable

Désactive complètement le module. nginx retire les vhosts WSA et Apache reprend les ports 80/443. Les configurations existantes sont préservées sur disque — un --enable ultérieur les restaure intégralement.

/etc/wsa/wsa --disable --verbose

--update

Force une mise à jour immédiate vers la dernière version disponible sur la branche de release configurée (stable, current, edge, dev).

/etc/wsa/wsa --update --verbose

L'opération est non-bloquante pour les sites — le code est remplacé atomiquement et post_update.php migre les données SQLite si nécessaire.

4. Reconstruction de la configuration

--rebuild

Régénère uniquement les configurations nginx qui ont changé depuis la dernière reconstruction. Rapide pour un usage cron ou un hook (cPanel SSL renewal, addon domain creation).

/etc/wsa/wsa --rebuild

--rebuild-user=<utilisateur>

Régénère la configuration nginx pour un seul compte cPanel. Utile après une modification per-user (mode avancé, preset apply) qui n'affecte que ce compte.

/etc/wsa/wsa --rebuild-user=astralinternet --verbose

--rebuild-forced

Reconstruit TOUTES les configurations nginx, même sans changement détecté. Effectue ensuite un nginx reload à chaud (les visiteurs en cours ne sont pas affectés).

/etc/wsa/wsa --rebuild-forced --verbose --no-lock

C'est ce que le bouton Rebuild Nginx conf du WHM exécute. À utiliser quand vous avez modifié manuellement quelque chose (pre/post_virtual_host.conf, default.conf) et voulez forcer la prise en compte.

--no-lock

À combiner avec --rebuild* : ignore le verrou .progress qui empêche normalement deux processus WSA de tourner en parallèle. Le verrou existe pour éviter les corruptions quand inotify déclenche un rebuild en même temps qu'une action manuelle.

/etc/wsa/wsa --rebuild-forced --no-lock --verbose

À utiliser uniquement quand vous savez qu'il n'y a pas d'autre WSA en cours. Le WHM passe ce flag automatiquement pour les actions explicites de l'opérateur.

5. Gestion de nginx

--restart-nginx

Arrête puis redémarre complètement le processus nginx. Les connexions ouvertes sont fermées brutalement.

/etc/wsa/wsa --restart-nginx --verbose

--reload-nginx

Recharge la configuration nginx à chaud (sans interrompre les connexions actuelles). À privilégier sur --restart-nginx quand c'est possible.

/etc/wsa/wsa --reload-nginx

--check-httpd-conf

Vérifie si la configuration Apache a changé depuis la dernière exécution de WSA. Si oui, déclenche une reconstruction. Idempotent — peut tourner en cron sans risque.

/etc/wsa/wsa --check-httpd-conf --verbose

--check-wsad

Vérifie que le démon wsad (inotify watcher) tourne. Le redémarre s'il est arrêté.

/etc/wsa/wsa --check-wsad --verbose

--update-disk-usage

Met à jour le fichier usage.stats lu par la tuile Cache Utilisation du dashboard WHM. Tourne automatiquement toutes les 2 heures via cron interne, mais peut être forcé manuellement pour obtenir des chiffres frais immédiatement.

/etc/wsa/wsa --update-disk-usage --verbose

6. Gestion du cache

--purgecache-all

Vide entièrement le cache nginx pour tous les comptes du serveur. Opération atomique : les répertoires de cache sont renommés instantanément, recréés vides, puis supprimés en arrière-plan.

/etc/wsa/wsa --purgecache-all --verbose

--purgecache-user=<utilisateur>

Vide uniquement le cache d'un seul compte cPanel.

/etc/wsa/wsa --purgecache-user=astralinternet --verbose

--purgecache-domain=<domaine>

Vide le cache d'un domaine spécifique (utile pour les comptes multi-domaines). Requiert --user=<utilisateur> pour identifier le propriétaire.

/etc/wsa/wsa --purgecache-domain=example.com --user=astralinternet --verbose

--purgecache-url=<url>

Vide une seule URL du cache. L'URL doit inclure le schéma (http:// ou https://).

/etc/wsa/wsa --purgecache-url=https://example.com/blog/article-42 --verbose

Utile pour purger sélectivement après une mise à jour de contenu spécifique sans toucher au reste du cache.

--user=<utilisateur>

Drapeau auxiliaire requis par certaines commandes (--purgecache-domain) pour identifier le propriétaire d'une ressource.

7. Modules nginx (Brotli, HTTP/3, …)

WSA peut compiler et gérer plusieurs modules dynamiques nginx. La famille de commandes --nginx-* centralise ces opérations.

--nginx-list

Liste les modules supportés.

/etc/wsa/wsa --nginx-list
# brotli
# http3

--nginx-status=<module>

Affiche un snapshot JSON de l'état d'un module : installé, activé, version compilée, version cible.

/etc/wsa/wsa --nginx-status=brotli

--nginx-caninstall=<module>

Exit 0 si le module peut être compilé sur ce serveur. Sinon exit non-zéro avec un message expliquant pourquoi (OS non supporté, nginx trop ancien, dépendances manquantes).

/etc/wsa/wsa --nginx-caninstall=http3 && echo "OK" || echo "Non éligible"

--nginx-isinstalled=<module>

Exit 0 si le module est installé.

/etc/wsa/wsa --nginx-isinstalled=brotli && echo "Brotli OK"

--nginx-isstatic=<module>

Exit 0 si le module est statiquement compilé dans nginx (par opposition à un module dynamique .so chargé via load_module).

--nginx-isenabled=<module>

Exit 0 si le module est activé (flag SQLite <module>_enable=1).

--nginx-install=<module>

Compile et installe le module. À combiner avec :

  • --force : recompile même si le module est déjà installé.
  • --verbose : streame la sortie de compilation (recommandé — la compilation peut prendre 2-5 minutes).
/etc/wsa/wsa --nginx-install=brotli --verbose

--nginx-uninstall=<module>

Désinstalle le module (supprime les fichiers .so, retire le load_module de la config nginx).

/etc/wsa/wsa --nginx-uninstall=brotli --verbose

--nginx-enable=<module> / --nginx-disable=<module>

Active ou désactive les directives du module dans nginx.conf sans toucher au binaire compilé. Permet d'avoir un module installé mais momentanément inactif (par exemple, pour tester un fallback).

/etc/wsa/wsa --nginx-enable=brotli
/etc/wsa/wsa --nginx-disable=brotli

--nginx-upgrade-status

Affiche JSON : est-ce qu'une mise à jour du paquet nginx est disponible via dnf ?

/etc/wsa/wsa --nginx-upgrade-status

--nginx-upgrade

Lance la mise à jour du paquet nginx via dnf, en streamé. Recompile automatiquement Brotli après la mise à jour si le module est installé (le module est lié à l'ABI nginx).

/etc/wsa/wsa --nginx-upgrade --verbose

--nginx-check-update

Rafraîchit le cache disque utilisé par les tuiles WHM et le bouton « ↻ Refresh » de l'interface. Tourne automatiquement en cron quotidien.

/etc/wsa/wsa --nginx-check-update --verbose

--nginx-recover-upgrade

Auto-récupération après une mise à jour nginx hors-bande (par exemple, dnf-automatic qui a contourné le versionlock de WSA). Détecte le drift ABI :

  • Plan A : recompile Brotli contre la nouvelle ABI.
  • Plan B : désactive Brotli si Plan A échoue.

Idempotent — peut être appelé en cron sans danger.

/etc/wsa/wsa --nginx-recover-upgrade --verbose

--nginx-recovery-state

Affiche JSON : snapshot du dernier événement de recovery (exit 0 quand un événement existe, 1 quand aucun n'est enregistré).

--nginx-recovery-clear

Efface l'état de recovery (ferme la bannière correspondante dans le WHM).

--nginx-protect-repos

Applique ou rafraîchit le verrou anti-revert sur le paquet nginx (mécanisme Tier 2 — empêche dnf-automatic de remplacer un build personnalisé).

--nginx-relock

Réconcilie le lock dnf avec l'état d'installation actuel. Idempotent — ajoute le lock si Brotli ou HTTP/3 est installé, le retire si aucun n'est actif.

--nginx-unlock

Libère TOUS les locks WSA sur le paquet nginx. À utiliser UNIQUEMENT avant un dnf upgrade nginx manuel délibéré, et à suivre de --nginx-recover-upgrade pour reconstruire Brotli avec la nouvelle ABI.

--nginx-lock-status

Affiche JSON : état du lock à travers toutes les couches (versionlock, dnf.conf [main], automatic.conf).

8. HTTP/3 (EL 9 / EL 10 uniquement)

--http3-status

Snapshot JSON : installé, stale, pins compilés vs pins épinglés.

/etc/wsa/wsa --http3-status

--http3-caninstall

Exit 0 si le serveur peut compiler HTTP/3. Détecte la distribution (EL 9/10 only) et la présence des dépendances.

/etc/wsa/wsa --http3-caninstall && echo "OK" || echo "Non supporté"

--http3-install

Compile et installe le binaire nginx HTTP/3 personnalisé, swap via USR2 (zero-downtime). La compilation prend 3 à 8 minutes ; toujours utiliser --verbose.

/etc/wsa/wsa --http3-install --verbose

À combiner avec --force pour recompiler même si déjà à jour.

--http3-uninstall

USR2 swap retour vers le paquet RPM nginx standard. Désactive QUIC sur tous les vhosts.

/etc/wsa/wsa --http3-uninstall --verbose

--http3-rebuild

Alias pour --http3-install --force. Reconstruit le binaire HTTP/3 même si pas de changement de pin.

/etc/wsa/wsa --http3-rebuild --verbose

--http3-auto-rebuild[=on|off]

Lit ou écrit l'option SQLite http3_auto_rebuild. Quand on, WSA reconstruit HTTP/3 automatiquement quand un pin WSA bouge.

/etc/wsa/wsa --http3-auto-rebuild        # affiche l'état
/etc/wsa/wsa --http3-auto-rebuild=on     # active
/etc/wsa/wsa --http3-auto-rebuild=off    # désactive

--http3-enable

Émet listen 443 quic; + en-tête Alt-Svc dans tous les vhosts SSL. Ouvre UDP/443 dans le pare-feu (CSF ou firewalld détecté automatiquement). Reload nginx.

/etc/wsa/wsa --http3-enable --verbose

Requiert que HTTP/3 soit installé au préalable (--http3-install).

--http3-disable

Retire les directives QUIC des vhosts. Reload nginx. Ne ferme pas UDP/443 dans le pare-feu (l'admin peut l'utiliser pour d'autres services).

/etc/wsa/wsa --http3-disable --verbose

9. Surveillance et opérations diverses

--list-watch-folders

Liste les dossiers actuellement surveillés par le démon inotify (/etc/wsa/ + tous les /home/*/.wsa/). Utile pour diagnostiquer pourquoi un changement n'est pas détecté.

/etc/wsa/wsa --list-watch-folders

--migrate-bp-v2131

Migration ponctuelle (one-shot) : sépare l'ancien blob SQLite list_ai combiné en trois buckets séparés (training / search / userinit). Idempotent — saute automatiquement après la première exécution réussie.

À ne lancer manuellement que pour récupérer après une corruption SQLite, en combinant avec --force :

/etc/wsa/wsa --migrate-bp-v2131 --force --verbose

10. Exemples d'automatisation

10.1 Hook post-déploiement

Script à exécuter après chaque déploiement de code :

#!/bin/bash
# /usr/local/bin/post-deploy-wsa.sh
USER="$1"
DOMAIN="$2"

# Vider le cache du domaine fraîchement déployé
/etc/wsa/wsa --purgecache-domain="$DOMAIN" --user="$USER" --verbose

# Rebuild si la config nginx a besoin d'être mise à jour
/etc/wsa/wsa --rebuild-user="$USER" --verbose

10.2 Health check Ansible

- name: Verify WSA module is enabled
  command: /etc/wsa/wsa --check-wsad
  changed_when: false

- name: Brotli installed and active?
  command: /etc/wsa/wsa --nginx-isenabled=brotli
  register: brotli_status
  failed_when: brotli_status.rc != 0
  changed_when: false

10.3 Backup avant upgrade nginx manuel

# 1. Snapshot de l'état actuel
/etc/wsa/wsa --nginx-status=brotli > brotli-pre-upgrade.json
/etc/wsa/wsa --http3-status > http3-pre-upgrade.json

# 2. Libérer le lock
/etc/wsa/wsa --nginx-unlock --verbose

# 3. Faire le `dnf upgrade nginx` à la main
dnf upgrade nginx

# 4. Auto-recover
/etc/wsa/wsa --nginx-recover-upgrade --verbose

# 5. Re-appliquer le lock
/etc/wsa/wsa --nginx-relock

10.4 Cron de vérification quotidienne

# /etc/cron.d/wsa-daily-health
0 4 * * * root /etc/wsa/wsa --nginx-check-update > /dev/null 2>&1
0 4 * * * root /etc/wsa/wsa --check-httpd-conf > /dev/null 2>&1

Note : ces tâches tournent déjà automatiquement via le cron interne de WSA. Le cron système ci-dessus garantit qu'elles tournent même si le démon wsad est temporairement arrêté.

11. Drapeaux internes (à ne pas utiliser)

Certains drapeaux apparaissent dans le code source mais sont internes au module :

  • --secret-cron-bypass-oiusdtgsh — Bypass de l'auto-cron utilisé par le démon wsad lui-même. Ne jamais utiliser manuellement.
  • -q — Force le mode queue. Drapeau interne legacy.
  • -s — Délai de queue (2 s). Drapeau interne legacy.

12. Pour aller plus loin