Mode mascarade

Le mode Masquerade fait du bext un remplacement complet du nginx. Les outils externes (certbot, logrotate, surveillance, scripts de déploiement) voient nginx et interagissent avec lui normalement, mais bext gère tout le trafic.

Comment ça marche#

Le mode Mascarade comporte trois composants :

1. Shim binaire — installé sur /usr/sbin/nginx, intercepte toutes les invocations CLI
2. systemd drop-in — remplace le nginx.service pour exécuter bext à la place
3. Fichier PID — écrit sur /run/nginx.pid pour la gestion basée sur le signal

Installation#

sudo bext nginx masquerade install

Cela effectue quatre étapes :

1. Sauvegarde le vrai binaire nginx sur /usr/sbin/nginx.real
2. Installe la cale bext - nginx sur /usr/sbin/nginx
3. Écrit un drop-in systemd à /etc/systemd/system/nginx.service.d/bext-masquerade.conf
4. Exécute systemctl daemon-reload

Chemins personnalisés#

sudo bext nginx masquerade install \
  --bext-bin /usr/local/bin/bext-server \
  --shim-bin /usr/sbin/nginx \
  --pid-file /run/nginx.pid

Désinstallation#

sudo bext nginx masquerade uninstall

Cela restaure le binaire nginx d'origine, supprime le drop-in systemd et exécute daemon-reload.

Le binaire de cale#

La cale du /usr/sbin/nginx gère tous les indicateurs CLI standard du nginx :

Les drapeaux combinés fonctionnent également : nginx -tc /etc/nginx/nginx.conf

La cale lit le fichier PID (/run/nginx.pid par défaut, remplacé par BEXT_PID_FILE) pour trouver le processus bext en cours d'exécution pour la transmission du signal.

systemd Drop-In#

Le fichier de remplacement généré :

# /etc/systemd/system/nginx.service.d/bext-masquerade.conf
[Service]
Type=exec
PIDFile=/run/nginx.pid
ExecStartPre=
ExecStart=/usr/local/bin/bext-server --nginx-masquerade
ExecReload=/bin/kill -s HUP $MAINPID
ExecStop=/bin/kill -s TERM $MAINPID
ExecStopPost=/bin/rm -f /run/nginx.pid
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

Cela signifie:

• systemctl start nginx démarre bext
• systemctl stop nginx arrête bext
• systemctl reload nginx envoie SIGHUP (config + rechargement TLS)
• systemctl status nginx affiche l'état de bext
• Redémarrage automatique en cas de panne avec un délai de 5 secondes

Gestion des signaux#

SIGHUP — Rechargement de la configuration#

Lorsque bext reçoit SIGHUP (via nginx -s reload ou systemctl reload nginx ) :

1. Réanalyse le fichier de configuration nginx à partir du disque
2. Enregistre tous les nouveaux avertissements de conversion
3. Reconstruit l'état complet du routage (vhosts, amonts, limiteurs de débit)
4. Recharge tous les certificats TLS du disque dans le résolveur SNI
5. Effectue un échange d'état atomique à l'aide de ArcSwap

Les requêtes en cours continuent avec l'ancienne configuration. Les nouvelles requêtes utilisent immédiatement la nouvelle configuration. Si l'analyse de la configuration échoue, l'ancienne configuration continue d'être diffusée et l'erreur est enregistrée.

Ceci est essentiel pour l'intégration du certbot . — après que Let's Encrypt ait renouvelé un certificat, nginx -s reload (ou le hook de déploiement certbot) recharge le nouveau certificat sans temps d'arrêt.

SIGUSR1 — Réouverture du journal#

Lorsque bext reçoit SIGUSR1 (via nginx -s reopen ) :

1. Rouvre le fichier journal d'accès en mode ajout
2. Met à jour le descripteur de fichier interne

Cela permet des flux de travail de rotation de log standard :

# /etc/logrotate.d/nginx
/var/log/nginx/*.log {
    daily
    rotate 14
    compress
    postrotate
        /usr/sbin/nginx -s reopen
    endscript
}

SIGTERM — Arrêt progressif#

Termine les requêtes en vol, puis quitte. Le fichier PID est nettoyé par la directive ExecStopPost.

Configuration d'écoute#

En mode mascarade, bext :

1. Extrait tous les ports uniques des directives nginx vhost listen
2. Lie HTTP sur chaque port détecté
3. Lie HTTPS sur le port 443 avec une résolution SNI à l'aide de tous les certificats TLS nginx
4. Définit le premier certificat comme solution de secours par défaut
5. Écrit le fichier PID avant d'accepter les connexions

Intégration de Certbot#

Certbot fonctionne de manière inchangée après l'installation de Masquerade :

# Initial certificate issuance
sudo certbot --nginx -d example.com

# The certbot nginx plugin interacts with the shim
# Renewal hooks call nginx -s reload, which sends SIGHUP to bext

Le gestionnaire SIGHUP recharge les certificats à partir du disque, de sorte que le flux de renouvellement de certbot standard fonctionne sans modification.

Compatibilité de surveillance#

Les outils qui vérifient l'état du nginx continuent de fonctionner :

• État du système nginx — affiche l'état du processus bext
• Fichier PID — /run/nginx.pid contient le PID de bext
• nginx -t — valide la syntaxe de configuration via bext
• nginx -V — version des rapports ( bext -mascarade)
• Nom du processus — visible dans ps sous la forme bun run server.ts ou bext-server

En rapport#

• Processus de rachat — le chemin de migration alternatif avec une interface utilisateur de restauration atomique
• Guide de migration — procédure pas à pas complète, y compris la déguisation en option A
• Aperçu de la compatibilité nginx — le pipeline d'analyse → conversion → service en trois étapes
• TLS et HTTPS — comment SIGHUP recharge les nouveaux certificats à partir du disque
• Opérations : invalidation et redémarrages — Sémantique de rechargement et de redémarrage