Astral 360 WSA — Accélérateur de sites

Modifications nginx manuelles

Utiliser pre_virtual_host.conf et post_virtual_host.conf pour ajouter des configurations nginx personnalisées qui survivent aux reconstructions.

WSA régénère automatiquement la configuration nginx (/etc/nginx/nginx.conf + tous les fichiers dans /etc/nginx/conf.d/) à chaque changement. Si vous éditez ces fichiers directement, vos modifications seront écrasées à la prochaine reconstruction.

WSA fournit deux fichiers spéciaux conçus pour persister les modifications de l'administrateur :

  • /etc/nginx/pre_virtual_host.conf
  • /etc/nginx/post_virtual_host.conf

Cette page explique quand et comment les utiliser.

1. Où ces fichiers s'insèrent dans la config nginx

WSA construit la configuration nginx finale en injectant ces deux fichiers à des moments précis du fichier nginx.conf principal :

   http {
       ...                                          # config http globale (WSA)
       proxy_cache_path /var/cache/nginx/...        # zones de cache (WSA)
       map $http_user_agent ...                     # protection bots (WSA)
       ...

       include /etc/nginx/pre_virtual_host.conf;    ← VOS directives, AVANT les vhosts
       include /etc/nginx/conf.d/*.conf;            # vhosts par-compte (WSA)
       include /etc/nginx/post_virtual_host.conf;   ← VOS directives, APRÈS les vhosts
   }

Les deux fichiers sont à l'intérieur du bloc http {}. Vous pouvez donc y placer toutes les directives nginx valides à ce niveau : map, geo, upstream, limit_req_zone, limit_conn_zone, proxy_cache_path additionnel, log_format, server {} complets, etc.

⚠️ Vous ne pouvez PAS y mettre des directives qui se placent au niveau main (au-dessus de http {}) — par exemple worker_processes, worker_rlimit_nofile, events {}. Ces directives sont gérées par WSA dans le haut de nginx.conf et ne peuvent pas être surcharées via ces fichiers.

2. Quand utiliser pre_virtual_host.conf

Ce fichier est inclus avant la liste des vhosts. Vos directives ici sont définies avant que nginx ne lise les configurations par-compte. C'est l'endroit idéal pour :

2.1 Définir des map, geo, upstream personnalisés

Ces directives sont fréquemment référencées depuis les vhosts. Elles doivent donc être déclarées avant.

# /etc/nginx/pre_virtual_host.conf

# Map personnalisée pour identifier les visiteurs mobiles
map $http_user_agent $is_mobile {
    default 0;
    "~*Mobile|Android|iPhone" 1;
}

# Upstream pour un service applicatif spécifique
upstream backend_api {
    server 10.0.0.42:8080 max_fails=3 fail_timeout=30s;
    server 10.0.0.43:8080 backup;
    keepalive 16;
}

2.2 Définir des zones de rate limiting custom

# Limite spéciale pour une API publique gourmande
limit_req_zone $binary_remote_addr zone=api_strict:10m rate=10r/s;

Ces zones peuvent ensuite être utilisées dans post_virtual_host.conf ou dans un server {} personnalisé.

2.3 Définir un log_format personnalisé

log_format custom_combined
    '$remote_addr - $remote_user [$time_local] "$request" '
    '$status $body_bytes_sent "$http_referer" '
    '"$http_user_agent" '
    '$upstream_cache_status $request_time';

3. Quand utiliser post_virtual_host.conf

Ce fichier est inclus après tous les vhosts. C'est l'endroit idéal pour :

3.1 Ajouter un serveur server {} complet

Par exemple, un endpoint de monitoring privé ou un proxy vers un service applicatif tiers :

# /etc/nginx/post_virtual_host.conf

# Endpoint nginx de status (Prometheus, Grafana, ...)
server {
    listen 127.0.0.1:8889;
    server_name _;

    location /nginx-status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

3.2 Proxy vers un service externe

# Service de webhook hébergé séparément
server {
    listen 443 ssl;
    server_name webhook.example.com;

    ssl_certificate /etc/letsencrypt/live/webhook.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/webhook.example.com/privkey.pem;

    location / {
        proxy_pass http://backend_api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

4. Procédure d'édition

4.1 Étape par étape

  1. Éditer le fichier avec votre éditeur favori :

    nano /etc/nginx/pre_virtual_host.conf
# ou
vim /etc/nginx/post_virtual_host.conf

  2. Tester la configuration avant de recharger :

    nginx -t

    Si la sortie indique « syntax is ok » et « test is successful », vous êtes bon. Sinon, l'erreur indique exactement la ligne à corriger.

  3. Recharger nginx pour appliquer :

    /etc/wsa/wsa --reload-nginx
# ou
systemctl reload nginx

Le rechargement à chaud n'interrompt pas les connexions actives.

4.2 Que se passe-t-il à la prochaine reconstruction WSA ?

Vos modifications persistent — WSA ne touche jamais à pre_virtual_host.conf ni à post_virtual_host.conf après l'installation initiale. La régénération de nginx.conf inclut ces fichiers tels quels.

5. Mises en garde

5.1 Une erreur de syntaxe bloque tout nginx

Une directive invalide dans ces fichiers fait échouer nginx -t, et donc bloque TOUS les rechargements ultérieurs. nginx continue de tourner avec l'ancienne config mais aucun changement WSA ne pourra prendre effet.

Toujours tester avec nginx -t avant de recharger.

5.2 Pas de conflit avec les vhosts WSA

Si vous définissez un server { listen 80; server_name example.com; ... } qui chevauche un vhost cPanel existant, nginx affiche un warning au démarrage et utilise le premier server rencontré (généralement celui de WSA, parce que pre_ et post_ sont en dehors du sous-dossier conf.d/).

Pour éviter les surprises, préfixez vos server_name ou utilisez un port différent :

# Bon : nom unique
server { server_name internal-monitoring.example.com; ... }

# Bon : port différent
server { listen 127.0.0.1:9999; ... }

# À éviter : collision avec un vhost cPanel
server { listen 80; server_name example.com; ... }

5.3 Pas de directives proxy_cache_* redondantes

WSA définit déjà 3 zones de cache nommées (wsa_dynamic, wsa_cssjs, wsa_static) — n'utilisez pas ces noms dans votre code. Si vous voulez votre propre cache nginx pour un service personnalisé, choisissez un nom unique :

proxy_cache_path /var/cache/nginx/monitoring_cache
                 levels=1:2
                 keys_zone=monitoring:10m
                 max_size=100m
                 inactive=1d;

5.4 Backup avant modification

Toujours sauvegarder avant une grosse modification :

cp /etc/nginx/pre_virtual_host.conf /etc/nginx/pre_virtual_host.conf.bak
cp /etc/nginx/post_virtual_host.conf /etc/nginx/post_virtual_host.conf.bak

En cas de problème, le rollback est immédiat :

cp /etc/nginx/pre_virtual_host.conf.bak /etc/nginx/pre_virtual_host.conf
nginx -t && systemctl reload nginx

6. Exemples complets

6.1 Authentification basique sur un sous-domaine

# /etc/nginx/post_virtual_host.conf

server {
    listen 443 ssl;
    server_name admin.example.com;

    ssl_certificate     /etc/letsencrypt/live/admin.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/admin.example.com/privkey.pem;

    # Authentification HTTP Basic en plus de l'app
    auth_basic           "Restricted Area";
    auth_basic_user_file /etc/nginx/htpasswd;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Création du fichier htpasswd :

yum install httpd-tools  # ou dnf
htpasswd -c /etc/nginx/htpasswd admin
chown nginx:nginx /etc/nginx/htpasswd
chmod 640 /etc/nginx/htpasswd

6.2 Redirection HTTP → HTTPS pour un domaine externe

# /etc/nginx/post_virtual_host.conf

server {
    listen 80;
    server_name external.example.com;

    return 301 https://main.example.com$request_uri;
}

6.3 Endpoint de health-check public

# /etc/nginx/post_virtual_host.conf

server {
    listen 80;
    server_name health.example.com;

    location /health {
        access_log off;
        add_header Content-Type text/plain;
        return 200 "OK\n";
    }
}

7. Diagnostic en cas de problème

7.1 « nginx: [emerg] ... in /etc/nginx/pre_virtual_host.conf:42 »

Erreur de syntaxe à la ligne 42 du fichier. Lire le message complet de nginx -t pour le détail.

7.2 « conflicting server name "example.com" on 0.0.0.0:443 »

Un de vos server_name chevauche un vhost cPanel. Utilisez un sous-domaine unique ou un port différent.

7.3 Configuration WSA semble ne pas s'appliquer

Vérifier que vos modifications dans pre_/post_virtual_host.conf ne déclarent pas une zone de cache ou un map qui surcharge les valeurs WSA. Renommer la zone résout généralement le conflit.

7.4 Voir la configuration finale assemblée

# Affiche le nginx.conf principal (généré par WSA)
cat /etc/nginx/nginx.conf

# Voir comment vos fichiers sont inclus
grep -n "include.*virtual_host" /etc/nginx/nginx.conf

8. Pour aller plus loin

  • Ligne de commande — Commande nginx -t (via --reload-nginx) et --rebuild-forced.
  • Configuration nginx WHM — Les options exposées par WSA suffisent souvent ; utiliser les fichiers manuels uniquement pour ce qui n'est pas surface dans l'UI.
  • Documentation officielle nginx : nginx.org/en/docs.