Génération contrib : vhosts nginx h3 edge + appsettings (jq) + QUIC logiciel Kestrel
Vhosts nginx (contrib/template.vhost + Makefile, envsubst allowlist) :
HTTP/3 edge per contrib/quic.md — listen 443 quic reuseport (Org only),
http2/http3 on, Alt-Svc, ssl_protocols TLSv1.3. Cibles generate-nginx /
generate-nginx-prod -> generated/nginx/ (gitignoré). Allowlist préserve
les variables nginx intrinsèques ($host, $scheme, ...).
Appsettings (contrib/template.appsettings-{org,api,blogs}.json + Makefile) :
génération via jq (et non envsubst) car le mot de passe SMTP contient un qui cassait le JSON. Substitue $DOMAIN (DOMAIN_ROOT) partout et injecte
$SMTP_PASSWORD depuis env (échappement JSON, secret non exposé en cmd).
Cible generate-appsettings -> generated/appsettings/.
QUIC logiciel : Kestrel:Endpoints:Https:Protocols = Http1AndHttp2AndHttp3
sur les 3 templates appsettings (capacité, non joignable derrière nginx).
Fix bonus : générateur systemd HTTP_PORT"$($*_PORT)" (était
"$*_$(HTTP_PORT)" -> port vide localhost:Org_).
Runbook contrib/README.nginx.md. Prérequis host : nginx http_v3_module,
UDP 443, libmsquic (Kestrel h3).
Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
parent
3fe7b8b46c
commit
5553f2f290
GPG key ID:
AD4B9B545FBD7D12
6 changed files with 132 additions and 83 deletions
|
|
@ -3,11 +3,50 @@
|
|||
Les vhosts nginx sont **générés** à l'image des unités de service systemd
|
||||
(`template.service` + `envsubst` → `generated/*.service`) : un template
|
||||
unique `contrib/template.vhost` est substitué par `envsubst` vers
|
||||
`contrib/generated/nginx/`, qui est **gitignoré** (comme `generated/`).
|
||||
`contrib/generated/nginx/`, qui est **gitignoré**.
|
||||
|
||||
HTTP/3 (QUIC) **termine au edge nginx** sur 443/udp. Kestrel reste en
|
||||
h1/h2 sur son port backend ; nginx lui parle en HTTP/1.1
|
||||
(`proxy_http_version 1.1`).
|
||||
## Rôle de nginx : edge HTTP/3 (plan `contrib/quic.md`)
|
||||
|
||||
nginx termine HTTP/3 (QUIC) au edge sur 443/udp, en coexistence avec
|
||||
h1/h2 sur 443/tcp. Kestrel reste backend h1/h2 (`proxy_http_version 1.1`).
|
||||
Le « QUIC logiciel » Kestrel (`Protocols: Http1AndHttp2AndHttp3` dans les
|
||||
`template.appsettings-*.json`) est une capacité complémentaire — non
|
||||
joignable par les clients derrière nginx (nginx OSS = upstream h1.1
|
||||
uniquement), mais disponible si Kestrel est un jour exposé en direct.
|
||||
|
||||
Directives générées (par vhost) :
|
||||
```nginx
|
||||
listen 443 ssl; listen [::]:443 ssl; http2 on;
|
||||
listen 443 quic $QUIC_OPTS; listen [::]:443 quic $QUIC_OPTS; http3 on;
|
||||
add_header Alt-Svc 'h3=":443"; ma=86400' always;
|
||||
ssl_protocols TLSv1.3;
|
||||
```
|
||||
`$QUIC_OPTS = reuseport` sur **Org uniquement**, vide sur Api/Blogs (règle
|
||||
`contrib/quic.md` : `reuseport` une seule fois par addr:port, tous vhosts
|
||||
confondus).
|
||||
|
||||
## Prérequis côté host
|
||||
|
||||
1. **nginx avec `http_v3_module`** (≥ 1.25 ; la directive `http3 on;`
|
||||
exige ≥ 1.27.4 — sur une version 1.25–1.27.3, retirer `http3 on;`,
|
||||
`listen ... quic` suffit à activer h3) :
|
||||
```bash
|
||||
nginx -V 2>&1 | grep -o 'http_v3_module' # doit être non vide
|
||||
```
|
||||
Debian 13 « trixie » fournit `nginx` avec `http_v3_module`. Sinon,
|
||||
backports ou `nginx-full`.
|
||||
2. **UDP 443 ouvert** :
|
||||
```bash
|
||||
sudo ufw allow 443/udp
|
||||
sudo ufw status | grep '443/udp' # → ALLOW
|
||||
```
|
||||
3. **IPv6** : le template émet `listen [::]:443 ...` (et `[::]:80`). Si le
|
||||
host n'a pas d'IPv6, retirer/commenter ces lignes (sinon `nginx -t`
|
||||
échoue sur le bind IPv6).
|
||||
4. Certbot / certs Let's Encrypt déjà en place (chemins
|
||||
`/etc/letsencrypt/live/<domain>/{fullchain,privkey}.pem` référencés).
|
||||
5. (Optionnel, pour le QUIC logiciel Kestrel) `apt install libmsquic` —
|
||||
sinon Kestrel désactive h3 silencieusement (fallback h1/h2 gracieux).
|
||||
|
||||
## Génération
|
||||
|
||||
|
|
@ -23,56 +62,28 @@ make generate-nginx-prod
|
|||
make generate-nginx APP_INSTALL_ENV=production APP_INSTALL_PREFIX=
|
||||
```
|
||||
|
||||
Les ports backend et `HTTP_HOST` proviennent de `.preprod.env` /
|
||||
`.production.env` (ex. prod Org=83, Api=87, Blogs=85 ; preprod 89/93/91).
|
||||
Le schéma backend est `https` en prod (Kestrel écoute HTTPS, cert
|
||||
Let's Encrypt) et `http` en preprod (Kestrel écoute HTTP simple).
|
||||
Ports backend et `HTTP_HOST` depuis `.preprod.env` / `.production.env`
|
||||
(prod Org=83, Api=87, Blogs=85 ; preprod 89/93/91). Schéma backend
|
||||
`https` en prod, `http` en preprod.
|
||||
|
||||
| Hôte | Sous-domaine | `reuseport` | Backend prod | Backend preprod |
|
||||
|-------|--------------|-------------|--------------|-----------------|
|
||||
| Org | yavsc | **oui** | `https://localhost:83` | `http://localhost:89` |
|
||||
| Api | api | non | `https://localhost:87` | `http://localhost:93` |
|
||||
| Blogs | blogs | non | `https://localhost:85` | `http://localhost:91` |
|
||||
| Hôte | Sous-domaine | `reuseport` | Backend prod | Backend preprod |
|
||||
|-------|--------------|-------------|-------------------------|------------------------|
|
||||
| Org | yavsc | **oui** | `https://localhost:83` | `http://localhost:89` |
|
||||
| Api | api | non | `https://localhost:87` | `http://localhost:93` |
|
||||
| Blogs | blogs | non | `https://localhost:85` | `http://localhost:91` |
|
||||
|
||||
Domaines : `<prefix><subdomain>.pschneider.fr`
|
||||
(prod : `yavsc.pschneider.fr` ; preprod : `preprod-yavsc.pschneider.fr`).
|
||||
(prod `yavsc.pschneider.fr` ; preprod `preprod-yavsc.pschneider.fr`).
|
||||
|
||||
## Déploiement sur le host
|
||||
|
||||
```bash
|
||||
# depuis le host, après avoir copié les fichiers générés :
|
||||
sudo cp generated/nginx/yavscOrg /etc/nginx/sites-available/yavscOrg
|
||||
sudo ln -sf /etc/nginx/sites-available/yavscOrg /etc/nginx/sites-enabled/yavscOrg
|
||||
# (idem pour yavscApi, yavscBlogs)
|
||||
# (idem yavscApi, yavscBlogs)
|
||||
sudo nginx -t && sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
## Prérequis côté host
|
||||
|
||||
1. **nginx ≥ 1.25** compilé avec `http_v3_module` :
|
||||
```bash
|
||||
nginx -V 2>&1 | grep -o 'http_v3_module' # doit être non vide
|
||||
```
|
||||
Debian 13 « trixie » fournit `nginx` avec `http_v3_module`. Sinon,
|
||||
`nginx-full` ou les backports.
|
||||
2. **UDP 443 ouvert** :
|
||||
```bash
|
||||
sudo ufw allow 443/udp
|
||||
sudo ufw status | grep '443/udp' # → ALLOW
|
||||
```
|
||||
3. Certbot / certs Let's Encrypt déjà en place (réutilisés tels quels —
|
||||
les chemins `/etc/letsencrypt/live/<domain>/{fullchain,privkey}.pm`
|
||||
sont référencés par le template).
|
||||
|
||||
## Règle : un seul `reuseport` sur 443/quic
|
||||
|
||||
`listen 443 quic reuseport;` ne peut figurer **qu'une seule fois** par
|
||||
couple adresse:port, pour tous les vhosts confondus. Le template le
|
||||
pose sur **Org** seulement (`QUIC_OPTS=reuseport` pour Org, vide pour
|
||||
Api/Blogs — règle `$(if $(filter Org,$*),reuseport,)` dans le
|
||||
`Makefile`). Si vous réordonnez les vhosts, gardez `reuseport` sur un
|
||||
seul.
|
||||
|
||||
## Vérification (sur le host)
|
||||
|
||||
```bash
|
||||
|
|
@ -85,46 +96,39 @@ sudo ufw status | grep '443/udp'
|
|||
# 3. En-tête Alt-Svc annoncé
|
||||
curl -sI https://yavsc.pschneider.fr/ | grep -i alt-svc # → h3=":443"
|
||||
|
||||
# 4. Requête HTTP/3 effective (curl doit être compilé avec HTTP/3)
|
||||
# 4. Requête HTTP/3 effective (curl compilé avec HTTP/3)
|
||||
curl -v --http3 https://yavsc.pschneider.fr/ 2>&1 | grep -i 'HTTP/3'
|
||||
|
||||
# 5. Fallback h2 et h1 toujours fonctionnels
|
||||
curl --http2 https://yavsc.pschneider.fr/ -o /dev/null -w '%{http_code}\n'
|
||||
curl --http1.1 https://yavsc.pschneider.fr/ -o /dev/null -w '%{http_code}\n'
|
||||
```
|
||||
|
||||
Répéter 3-5 pour `api.pschneider.fr` et `blogs.pschneider.fr` (prod),
|
||||
et pour les trois domaines preprod. Sans curl HTTP/3, utiliser un
|
||||
navigateur : DevTools → Network → colonne « Protocole » affiche `h3`
|
||||
après la première mise à niveau.
|
||||
Répéter 3-5 pour `api.pschneider.fr` et `blogs.pschneider.fr` (prod) et
|
||||
les trois domaines preprod. Sans curl HTTP/3, un navigateur : DevTools →
|
||||
Network → colonne « Protocole » → `h3` après mise à niveau.
|
||||
|
||||
## Comment ça marche (template + envsubst)
|
||||
|
||||
`contrib/template.vhost` contient des placeholders `$DOMAIN`,
|
||||
`$BACKEND_SCHEME`, `$HTTP_HOST`, `$BACKEND_PORT`, `$QUIC_OPTS`. La
|
||||
règle `generated/nginx/$(APP_INSTALL_PREFIX)yavsc%` du `Makefile` les
|
||||
substitue via `envsubst` avec une **allowlist** :
|
||||
`contrib/template.vhost` contient les placeholders `$DOMAIN`,
|
||||
`$BACKEND_SCHEME`, `$HTTP_HOST`, `$BACKEND_PORT`, `$QUIC_OPTS`. La règle
|
||||
`generated/nginx/$(APP_INSTALL_PREFIX)yavsc%` du `Makefile` les substitue
|
||||
via `envsubst` avec une **allowlist** :
|
||||
|
||||
```makefile
|
||||
envsubst '$DOMAIN $BACKEND_SCHEME $HTTP_HOST $BACKEND_PORT $QUIC_OPTS'
|
||||
```
|
||||
|
||||
Cette allowlist est **critique** : elle limite la substitution aux 5
|
||||
variables citées, de sorte que les variables nginx intrinsèques
|
||||
(`$host`, `$scheme`, `$remote_addr`, `$proxy_add_x_forwarded_for`,
|
||||
`$request_uri`) survivent intactes dans le vhost généré. Sans
|
||||
Cette allowlist limite la substitution aux 5 variables citées, de sorte
|
||||
que les variables nginx intrinsèques (`$host`, `$scheme`, `$remote_addr`,
|
||||
`$proxy_add_x_forwarded_for`, `$request_uri`) survivent intactes. Sans
|
||||
allowlist, `envsubst` détruirait ces variables nginx.
|
||||
|
||||
## Hors périmètre
|
||||
|
||||
- **Kestrel inchangé** : ni `Protocols: Http1AndHttp2AndHttp3`, ni
|
||||
`libmsquic`. Si l'on veut plus tard que Kestrel parle aussi h3
|
||||
(accès direct sans nginx / topo L4), ajouter
|
||||
`Kestrel:Endpoints:Https:Protocols = "Http1AndHttp2AndHttp3"` dans
|
||||
les `appsettings-{app}*.json` + `apt install libmsquic` sur le host
|
||||
(Kestrel désactive h3 silencieusement si libmsquic absent — fallback
|
||||
gracieux).
|
||||
- **docker-compose / Dockerfile** : non touchés (déploiement réel
|
||||
bare-metal systemd + nginx).
|
||||
- **Backend HTTP/2** : nginx open-source ne supporte que HTTP/1.1 en
|
||||
upstream ; on garde `proxy_http_version 1.1`.
|
||||
- `docker-compose` / `Dockerfile` : non touchés (déploiement bare-metal
|
||||
systemd + nginx).
|
||||
- Backend HTTP/2 vers Kestrel : nginx open-source ne supporte que
|
||||
HTTP/1.1 en upstream ; on garde `proxy_http_version 1.1`.
|
||||
- `ssl_protocols TLSv1.3` (suivant `contrib/quic.md`) désactive TLS 1.2
|
||||
côté TCP aussi. Pour conserver la compat TLS 1.2 sur le fallback TCP,
|
||||
relâcher en `ssl_protocols TLSv1.2 TLSv1.3;` (QUIC reste en 1.3).
|
||||
Loading…
Reference in a new issue