Construction nginx et modules

Gestion du binaire nginx (RPM ou build WSA), HTTP/3, compilation et configuration Brotli.

La page Nginx Build & Modules centralise la gestion du binaire nginx et de ses modules dynamiques — Brotli et HTTP/3. C'est ici que l'administrateur :

Choisit entre le paquet nginx du dépôt RPM standard ou un build personnalisé WSA (avec HTTP/3).
Compile et active la compression Brotli.
Active ou désactive l'émission QUIC (HTTP/3) sur les vhosts SSL.
Surveille les versions épinglées contre les versions installées.

Accès : Barre latérale → Nginx Build & Modules.

⚠️ Les actions de cette page modifient le binaire nginx ou recompilent des modules. Elles prennent plusieurs minutes et peuvent brièvement interrompre le service. À exécuter de préférence en dehors des périodes de pointe.

1. Organisation par onglets

La page est divisée en 2 onglets :

   [ Nginx | Brotli ]

Onglet	Contenu
Nginx	Choix du binaire nginx, HTTP/3, QUIC, versions épinglées.
Brotli	Installation/reconstruction du module Brotli, paramètres de compression.

2. Onglet Nginx

Onglet Nginx — binaire, mise à jour, build HTTP/3, QUIC, versions épinglées

2.1 Section Nginx binary

2.1.1 Current build

   Current build
   Where the running /usr/sbin/nginx came from.
   ┌──────────────────────────────────────────────────────┐
   │  [ WSA custom build · 1.30.1 ]                       │
   │  Compiled with --with-http_v3_module + bundled       │
   │  QuicTLS.                                            │
   │  RPM preserved at /usr/sbin/nginx.upstream.bak       │
   │                                       [ Revert to RPM ] │
   └──────────────────────────────────────────────────────┘

Affiche l'origine du binaire nginx actuellement en service :

État	Affichage
WSA custom build · 1.30.1	Build personnalisé WSA, contient HTTP/3 et QuicTLS. Le RPM standard est préservé en backup.
Stock RPM · 1.30.0	Binaire standard nginx du dépôt RPM. Pas de HTTP/3.

Bouton Revert to RPM (visible uniquement en mode WSA custom build) — Restaure le paquet RPM standard :

Désactive HTTP/3 (vhosts SSL retirent listen 443 quic;).
Restaure /usr/sbin/nginx.upstream.bak → /usr/sbin/nginx.
Reconstruit les configurations.
Recharge nginx.

⚠️ Demande confirmation : « Roll back to the stock RPM nginx? The custom build will be removed and the original /usr/sbin/ nginx.upstream.bak restored. »

2.1.2 Update available

   Update available
   Cached daily by the checkNginxUpgrade cron — no
   synchronous dnf check on page load.
   ┌──────────────────────────────────────────────────────┐
   │  [ Update → 1.30.2 ]            [ Upgrade nginx ]    │
   └──────────────────────────────────────────────────────┘

Détection d'une nouvelle version de nginx disponible via dnf. La détection tourne quotidiennement en arrière-plan (cron checkNginxUpgrade) — pas de probe dnf synchrone au chargement de la page.

État Up to date : pastille verte, pas de bouton.

État Update available : pastille jaune avec la version cible + bouton Upgrade nginx :

Lance un dnf upgrade nginx en streamé.
Recompile Brotli automatiquement (le module est lié à l'ABI nginx — un upgrade casserait Brotli sans cette étape).
Recharge nginx.

⚠️ Demande confirmation : « Run WSA-managed nginx upgrade? Will rebuild Brotli automatically. »

💡 Le mécanisme Tier 2 (verrou dnf versionlock) empêche les mises à jour dnf-automatic de remplacer le binaire WSA custom build sans cette procédure. C'est pourquoi l'upgrade-via-WSA est la seule façon correcte d'avancer les versions.

2.1.3 HTTP/3 build

   HTTP/3 build
   Replace /usr/sbin/nginx with the WSA HTTP/3 binary,
   or roll back to the upstream RPM.
   ┌──────────────────────────────────────────────────────┐
   │  Installed                                           │
   │                            [ Rebuild ] [ Revert to RPM ] │
   └──────────────────────────────────────────────────────┘

Gestion du build HTTP/3 personnalisé. 3 états possibles :

État 1 — HTTP/3 non installé (binaire = RPM standard)

Bouton unique : Build HTTP/3.

Démarre la compilation streamée :

Téléchargement nginx + QuicTLS depuis les sources officielles.
Vérification SHA256 (intégrité tarball).
Compilation (~3 à 8 minutes selon le serveur).
Test nginx -t sur le nouveau binaire.
Backup du RPM en /usr/sbin/nginx.upstream.bak.
Bascule du binaire actif vers le nouveau build.
Ouverture du port UDP/443 (CSF ou firewalld détecté).
Reload nginx.

⚠️ Demande confirmation : « Build the WSA HTTP/3 nginx? Takes 3-8 minutes; the stock RPM stays running until the new binary passes nginx -t. »

État 2 — HTTP/3 installé et à jour

Deux boutons :

Rebuild — Reconstruit même si pas de changement de version épinglée. Utile après un changement de pin manuel ou pour forcer un nouveau build.
Revert to RPM — Désinstalle le build HTTP/3 et restaure le paquet RPM standard. Désactive aussi QUIC sur les vhosts.

État 3 — Non supporté sur ce serveur

Pastille neutre « Not supported on this OS » avec la raison (par exemple : « EL 8 requires manual OpenSSL 3.0 backport — not automated »). Le bouton est désactivé.

HTTP/3 nécessite EL 9 ou EL 10. EL 7 et EL 8 ne sont pas supportés.

2.1.4 QUIC emission (visible uniquement quand HTTP/3 installé)

   QUIC emission                            (Default: 0)
   When On, every SSL vhost gets listen 443 quic; + Alt-Svc,
   and UDP/443 is opened.
                                                [ OFF ]  ↺

Type : toggle Défaut : Off

Quand On, WSA ajoute listen 443 quic; et l'en-tête Alt-Svc aux configurations vhost SSL. Les visiteurs sur navigateurs modernes basculent automatiquement vers HTTP/3 ; les autres restent sur HTTP/2.

Quand Off, le binaire HTTP/3 est installé mais aucun vhost n'émet de QUIC. Utile pour :

Tester le build avant de l'activer en production.
Désactiver temporairement HTTP/3 sans désinstaller le build.

L'activation ou désactivation déclenche une reconstruction de tous les vhosts suivie d'un reload nginx — sortie streamée en direct dans une vue Process status.

2.1.5 Pinned versions (tableau)

   Pinned versions
   What the current WSA release will build, vs. what is
   actually built.
   ┌───────────────┬──────────────────────┬──────────────────┐
   │ Component     │ Pinned               │ Built            │
   ├───────────────┼──────────────────────┼──────────────────┤
   │ nginx         │ 1.30.1               │ 1.30.1           │
   │ QuicTLS       │ openssl-3.0.15-quic1 │ openssl-3.0.15-quic1 │
   │ ngx_brotli    │ a71f9312c2de         │ a71f9312c2de     │
   └───────────────┴──────────────────────┴──────────────────┘

Compare les versions épinglées (ce que la release WSA actuelle veut construire) avec les versions réellement buildées sur ce serveur.

Colonne	Source
Pinned	Constantes `HTTP3_*` dans `lib/bootstrap.php` (mises à jour à chaque release WSA).
Built	État SQLite `http3_state` (mis à jour à chaque compilation HTTP/3 réussie).

Une divergence indique que le build est stale — une mise à jour WSA a bumpé un pin, mais le serveur n'a pas encore recompilé. La tuile Brotli du dashboard et la bannière d'alerte signalent ce cas avec une CTA Rebuild.

Si les champs sont vides (—), c'est que HTTP/3 n'a jamais été buildé sur ce serveur (binaire actuel = RPM standard).

3. Onglet Brotli

Onglet Brotli — état, build et paramètres de compression

3.1 Status

   Status
   Brotli compresses text ~15-25% smaller than gzip.
   Loaded as a dynamic .so.
   ┌──────────────────────────────────────────────────────┐
   │  [ Active ]                                          │
   │  built for nginx 1.30.0                              │
   └──────────────────────────────────────────────────────┘

4 états possibles :

État	Pastille	Signification
Active	Verte	Compilé, activé, sert des réponses compressées.
Installed, disabled	Neutre	Compilé et chargé, mais master switch `brotli_enable=0`.
Rebuild needed	Jaune	Compilé pour une ancienne version nginx (drift ABI).
Not installed	Rouge	Aucun build Brotli sur ce serveur.

Sous-ligne : version nginx pour laquelle Brotli a été compilé (built for nginx 1.30.0).

3.2 Build / rebuild

   Build / rebuild
   Compiles ngx_brotli against the current nginx headers.
   Takes 2-5 min.
   ┌──────────────────────────────────────────────────────┐
   │   [ Rebuild ]  [ Uninstall ]                         │
   └──────────────────────────────────────────────────────┘

3 boutons selon l'état :

État 1 — Pas installé

Install Brotli — Compile et installe le module :

Téléchargement du source ngx_brotli (git clone à HTTP3_NGX_BROTLI_COMMIT).
Compilation contre les headers de la version nginx actuelle (~2 à 5 minutes).
Installation du .so dans /etc/nginx/modules/.
Ajout du load_module dans la config principale.
Reload nginx.

État 2 — Installé

Rebuild — Recompile contre la version nginx actuelle. Utile après un upgrade nginx pour éviter le drift ABI.
Uninstall — Supprime le module .so, retire le load_module, reload nginx.

État 3 — Non éligible

Pastille Cannot install avec raison (par exemple : « Nginx 1.30.0 is too old, minimum 1.30.0 », « Distribution not supported », etc.).

3.3 Configuration de compression (visible quand Brotli est installé)

Quatre paramètres détaillés :

3.3.1 Enable Brotli compression

   Enable Brotli compression                     [ OFF ]
   Globally enable / disable Brotli emission.
   (Default: Disabled)

Champ : brotli_enable Type : toggle Défaut : Off

Master switch global. Quand Off, le module reste chargé mais n'émet aucune réponse compressée Brotli (les visiteurs recevront du gzip si activé, sinon non compressé).

3.3.2 Brotli compression level

   Brotli compression level (0-11)        (Default: 4)
   Higher is smaller but slower.
                                              [ 4 ]   ↺

Champ : brotli_comp_level Type : entier 0–11 Défaut : 4

Niveau	Trade-off
0	Pas de compression. Tester uniquement.
1–3	Très rapide, compression minime. CPU négligeable.
4 (défaut)	Excellent compromis vitesse/taux.
5–6	Plus compressé, ~10–20 % de CPU en plus.
7–9	Compression élevée, CPU non négligeable.
10–11	Maximum, très lent. Approprié seulement avec serve `.br` pré-compressé.

Recommandation : 4 pour la compression à la volée. 11 si tu utilises serve .br (pré-compression statique).

3.3.3 Brotli minimum length

   Brotli minimum length (bytes)        (Default: 256)
   Do not compress responses smaller than this.
                                            [ 256 ]   ↺

Champ : brotli_min_length Type : entier (octets) Défaut : 256

Seuil en dessous duquel les réponses ne sont pas compressées. La compression sur des charges utiles très petites coûte plus en CPU que le gain en taille.

Recommandation : 256 est le défaut équilibré. À monter à 1024 ou 2048 sur des serveurs CPU-limités.

3.3.4 Serve pre-compressed .br files

   Serve pre-compressed .br files                [ ON ]
   If a sibling .br file exists, send it without
   compressing on the fly.
   (Default: Enabled)

Champ : brotli_static_enable Type : toggle Défaut : On

Quand un fichier .br pré-compressé existe à côté du fichier original (style.css + style.css.br), nginx le sert directement au lieu de compresser à la volée.

Aucun inconvénient — gain pur quand les outils de build du client génèrent les .br (Webpack avec CompressionPlugin({ algorithm: 'brotliCompress' }), plugin WordPress, etc.).

4.1 Sauvegarde de la config Brotli

Bouton Save configuration en bas de l'onglet Brotli (visible seulement quand le module est installé). Sauvegarde les 4 paramètres Brotli (enable / level / min_length / static), puis reload nginx.

4.2 Sauvegarde du toggle QUIC

Bouton Save configuration en bas de l'onglet Nginx (visible seulement quand HTTP/3 est installé). Sauvegarde la valeur du toggle QUIC emission, puis lance la reconstruction des vhosts streamée.

4.3 Boutons d'actions (Build, Upgrade, Revert)

Ces boutons ne nécessitent pas de Save — ils déclenchent directement leur action sur clic (avec confirmation modale pour les actions destructives).

5. Architecture interne (informatif)

5.1 Source des versions épinglées

Définies en dur dans src/lib/bootstrap.php :

define('HTTP3_NGINX_VERSION',     '1.30.1');
define('HTTP3_NGINX_SHA256',      '99765000d97...');
define('HTTP3_QUICTLS_TAG',       'openssl-3.0.15-quic1');
define('HTTP3_NGX_BROTLI_COMMIT', 'a71f9312c2deb28875acc7bacfdd5695a111aa53');

Ces constantes sont bumpées à chaque release WSA quand l'équipe Astral Internet valide une nouvelle version upstream.

5.2 État local

Persisté dans la table options de /etc/wsa/conf/wsa.sqlite :

Clé	Contenu
`http3_state`	JSON : `{nginx_version_built, quictls_tag_built, ngx_brotli_built, binary_sha256, built_at, wsa_version_built}`
`http3_enable`	`0` ou `1` — état du toggle QUIC emission
`http3_auto_rebuild`	`0` ou `1` — auto-rebuild quand les pins bougent (CLI uniquement aujourd'hui)
`brotli_enable`	`0` ou `1`
`brotli_comp_level`	`0` à `11`
`brotli_min_length`	entier
`brotli_static_enable`	`0` ou `1`

6. Pour aller plus loin

Tableau de bord — Vue d'ensemble incluant les tuiles Brotli et HTTP/3.
Notes de version — Historique des bumps d'épingles sécurité (CVE nginx, etc.).
Qu'est-ce que WSA ? — Explication conceptuelle de HTTP/3 et Brotli.
Ligne de commande — Commandes wsa --http3-* et wsa --nginx-*.