Variables d'environnement
Cette page décrit les variables du dashboard, puis les variables essentielles des autres composants. Elle suit la page Système du dashboard, réservée aux administrateurs, qui affiche pour chaque réglage sa valeur courante, sa valeur par défaut et l'endroit où le modifier.
Règles générales
- Les variables se placent dans le fichier
.env à côté du fichier compose. Pas de guillemets autour des valeurs.
- Pour un même réglage, la priorité est : variable d'environnement, puis fichier YAML de
config/ lorsqu'il existe, puis valeur par défaut. Une valeur définie dans .env l'emporte donc toujours.
- Aucun secret n'est obligatoire pour démarrer. Quand ils sont absents, le dashboard génère une fois les secrets suivants et les conserve dans
config/.generated-secrets.json : SESSION_SECRET, WAF_TOKEN, SHIPPER_LOCAL_TOKEN, NC_SECRET et INSTANCE_ID.
- Les secrets s'affichent dans la page Système sous la forme « configuré » ou « non configuré », jamais en clair.
- Une variable marquée build se fixe à la construction de l'image (
build.args du compose) et peut aussi être surchargée à l'exécution.
- Pour générer un secret :
openssl rand -hex 32.
Dashboard
Général
| Variable |
Défaut |
Rôle |
PORT |
3000 |
Port d'écoute interne. Le port publié se règle dans ports: du compose |
NGINX_CONTAINER |
nginx |
Nom du conteneur Nginx à piloter (test, rechargement, statistiques) |
NGINX_IMAGE |
détectée |
Image du conteneur éphémère qui teste une configuration avant déploiement |
NGINX_NETWORK |
nginx-net |
Réseau Docker partagé, utilisé pour le conteneur de test et la résolution DNS |
NGINX_VTS_URL |
http://nginx:8080/status.json |
Point d'accès du module VTS qui fournit les statistiques par vhost |
NGINX_CONF_FILE |
/etc/nginx/nginx.conf |
Chemin de nginx.conf dans le conteneur Nginx |
NOTIF_POLL_INTERVAL_SEC |
5 |
Fréquence d'interrogation des notifications par le navigateur (minimum 2) |
INSTANCE_ID |
généré |
Identifiant unique de l'installation (UUID), qui n'est pas un secret |
HTTP_USER_AGENT |
NGXOps |
User-Agent de toutes les requêtes sortantes, sans numéro de version pour pouvoir le filtrer |
DOCKER_SOCKET |
/var/run/docker.sock |
Socket Docker utilisé pour piloter Nginx et les conteneurs gérés |
Sécurité et sessions
| Variable |
Défaut |
Rôle |
SESSION_SECRET |
généré |
Clé de signature des sessions |
SESSION_TTL_HOURS |
8 |
Durée d'une session, renouvelée tant que l'utilisateur est actif |
SESSION_MAX_HOURS |
24 |
Durée maximale d'une session, même active |
LOGIN_MAX_ATTEMPTS |
10 |
Échecs de connexion tolérés avant blocage temporaire |
LOGIN_WINDOW_MIN |
15 |
Fenêtre de comptage des échecs, en minutes |
LOGIN_LOCKOUT_MIN |
15 |
Durée du blocage, en minutes |
API_TOKEN |
désactivé |
Jeton de l'API REST (Authorization: Bearer). Il reste inactif s'il est vide, s'il commence par changeme ou s'il fait moins de 16 caractères |
WEBHOOK_SECRET |
non configuré |
Secret de signature des webhooks sortants |
CORS_ORIGIN |
vide |
Origine autorisée en cross-origin. Vide : même origine uniquement, ce qui est recommandé |
TRUSTED_PROXIES |
réseaux privés et loopback |
Adresses autorisées à fixer X-Forwarded-For |
HEALTH_PUBLIC |
true |
Route publique /health. false la désactive |
MFA_RP_ID |
déduit de Host |
Domaine WebAuthn pour les clés de sécurité. À fixer derrière un proxy qui réécrit Host |
MFA_ORIGIN |
déduit |
Origines HTTPS autorisées pour WebAuthn, séparées par des virgules |
L'API et les webhooks se règlent aussi depuis la page Système : le bouton Générer affiche la valeur une seule fois et ne conserve que son empreinte.
Déploiement et sauvegardes
| Variable |
Défaut |
Rôle |
ALLOW_EDIT |
false |
Autorise l'édition des fichiers de configuration depuis l'interface |
ALLOW_CREATE |
false |
Autorise la création de fichiers. Sans effet quand Git est configuré |
DEPLOY_SYNC_SSL |
true |
Inclut ssl/ dans le déploiement Git. certs/ n'est jamais synchronisé |
GIT_REPO_URL |
vide |
Dépôt de référence. Vide : déploiement Git désactivé |
GIT_BRANCH |
main |
Branche source |
GIT_BACKUP_BRANCH |
backup |
Branche qui reçoit l'état précédent avant chaque déploiement |
GIT_TOKEN |
vide |
Jeton HTTPS du dépôt |
GIT_SSH_KEY |
vide |
Chemin de la clé SSH dans le conteneur, à monter en volume |
GIT_USER_NAME, GIT_USER_EMAIL |
Nginx Dashboard, dashboard@localhost |
Identité des commits |
BACKUP_KEEP |
20 |
Nombre de sauvegardes ZIP locales conservées |
BACKUP_PASSPHRASE |
vide |
Phrase de passe commune de repli pour les archives chiffrées |
HUB_BACKUP_PASSPHRASE |
vide |
Phrase de passe des sauvegardes envoyées au Hub |
S3_BACKUP_PASSPHRASE |
vide |
Phrase de passe de l'archive envoyée vers S3 |
Une phrase de passe perdue rend l'archive chiffrée irrécupérable : conservez-les en dehors du dashboard.
Répertoires
Les variables DIR_* indiquent où les volumes sont montés dans le conteneur du dashboard. Elles doivent correspondre aux volumes du compose.
| Variable |
Défaut |
DIR_SITES |
/nginx/sites |
DIR_CONF |
/nginx/conf |
DIR_SNIPPETS |
/nginx/snippets |
DIR_STREAMS |
/nginx/streams |
DIR_SSL |
/nginx/ssl |
DIR_CERTS |
/nginx/certs |
DIR_LOGS |
/nginx/logs |
DIR_CACHE |
vide, ce qui désactive le bouton de vidage du cache |
DIR_BACKUPS |
/nginx/backups |
DIR_GIT_WORK |
/git-work |
DIR_GOACCESS |
/nginx/goaccess |
DIR_GEOIP |
/geoip |
HOST_LOGS et HOST_GOACCESS sont différentes : ce sont des chemins absolus sur l'hôte, utilisés pour les volumes des conteneurs que le dashboard crée. Docker résout ces chemins côté hôte, un chemin qui n'existe que dans le conteneur du dashboard monterait un dossier vide.
Intégrations
| Variable |
Défaut |
Rôle |
CROWDSEC_PROMETHEUS_URL |
vide |
Point d'accès Prometheus du moteur CrowdSec (recommandé) |
CROWDSEC_LOCAL_ONLY |
false |
N'affiche que les décisions locales |
CROWDSEC_URL, CROWDSEC_API_KEY |
vides |
API locale CrowdSec et clé de bouncer, en lecture seule |
CROWDSEC_MACHINE_ID, CROWDSEC_MACHINE_PASSWORD |
vides |
Identité machine, nécessaire pour bannir, débannir et gérer les listes blanches |
GOACCESS_IMAGE |
allinurl/goaccess:latest |
Image de GoAccess |
GOACCESS_LOG_FORMAT |
COMBINED |
Format de journal lu par GoAccess |
GOACCESS_REFRESH |
30 |
Régénération du rapport, en secondes |
GEOIP_CITY_DB, GEOIP_COUNTRY_DB, GEOIP_ASN_DB |
/geoip/GeoLite2-*.mmdb |
Chemins des bases MaxMind |
GODNS_IP_CHECK |
true |
Vérifie l'IP publique rapportée par GoDNS auprès de plusieurs services |
GODNS_IP_CHECK_URLS |
ipify, icanhazip, ifconfig.me |
Services interrogés pour cette vérification |
REDIS_URL |
vide |
Adresse du Redis optionnel, par exemple redis://redis:6379/0 |
REDIS_PASSWORD |
vide |
Mot de passe Redis, obligatoire quand Redis est utilisé |
REDIS_PREFIX |
INSTANCE_ID ou ngx |
Préfixe des clés Redis |
Analyse, WAF, challenge et journal centralisé
| Variable |
Défaut |
Rôle |
ANALYZER_DEFAULT_IMAGE |
image de l'analyseur de la suite (build) |
Image par défaut du conteneur d'analyse |
WAF_DEFAULT_IMAGE |
ANALYZER_DEFAULT_IMAGE (build) |
Image du WAF émulé |
WAF_TOKEN |
généré |
Secret partagé avec le WAF émulé |
CHALLENGE_DEFAULT_IMAGE |
image du challenge de la suite (build) |
Image du challenge navigateur |
ANUBIS_DEFAULT_IMAGE |
ghcr.io/techarohq/anubis:latest (build) |
Image du moteur Anubis |
AGENT_DEFAULT_IMAGE |
image de l'agent de la suite (build) |
Image proposée dans le kit de déploiement des agents |
NC_SECRET |
généré |
Secret de signature des cookies du challenge |
NC_DIFFICULTY_BITS |
16 |
Difficulté de la preuve de travail (8 à 64) |
NC_COOKIE_HOURS |
24 |
Validité du cookie « navigateur vérifié », de 1 à 720 heures |
NC_GOODBOTS |
true |
Laisse passer les robots d'indexation dont le DNS inverse est confirmé |
NC_GOODBOTS_EXTRA |
vide |
Robots supplémentaires : nom, expression régulière du User-Agent et suffixe DNS, séparés par une barre verticale (format détaillé dans sample.env) |
NC_LANG |
auto |
Langue de la page de vérification : auto, fr ou en |
SHIPPER_DEFAULT_IMAGE |
ANALYZER_DEFAULT_IMAGE |
Image du shipper |
SHIPPER_LOCAL_TOKEN |
généré |
Jeton local partagé entre dashboard, shipper et WAF (24 caractères minimum) |
LOGSINK_TOKEN |
vide |
Jeton write de cette instance, utilisé par le shipper |
LOGSTORE_READ_TOKEN |
vide |
Jeton read du log store, utilisé par la page Journaux |
INTEL_API_URL |
vide (build) |
Adresse de la plateforme Intelligence |
INTEL_TOKEN |
vide |
Jeton du mode identifié d'Intelligence |
Les réglages de ces fonctions (activation, limites, chemins) se trouvent dans les fichiers de config/ : analyzer.yml, waf.yml, challenge.yml, logstore.yml, intelligence.yml. Ils sont modifiables depuis les pages correspondantes du dashboard.
Rétention et maintenance
| Variable |
Défaut |
Rôle |
EVENTS_RETENTION_DAYS |
30 |
Conservation du journal d'événements |
MONITOR_RETENTION_DAYS |
30 |
Conservation de l'historique de supervision. Un incident ouvert n'est jamais purgé |
NOTIF_CENTER_RETENTION_DAYS |
90 |
Conservation des notifications |
DB_COMPACT_ON_START |
auto |
Compactage SQLite au démarrage : auto, always ou off |
DB_COMPACT_MIN_FREE_MB |
16 |
Espace libre minimal qui déclenche le compactage en mode auto |
DB_COMPACT_MIN_FREE_PCT |
20 |
Part minimale de pages libres qui déclenche le compactage en mode auto |
| Variable |
Défaut |
Rôle |
BRANDING_HEADER_TEXT |
vide |
Texte affiché dans l'en-tête (nom de client, environnement) |
BRANDING_DOC, BRANDING_DOC_LABEL |
vide, Documentation |
Lien vers la documentation, en bas du menu (build) |
BRANDING_SITE, BRANDING_SITE_LABEL |
vides |
Lien vers un site (build) |
BRANDING_REPO, BRANDING_REPO_LABEL |
vide, Source repository |
Lien vers le dépôt (build) |
BRANDING_KOFI, BRANDING_KOFI_LABEL |
vide, Support on Ko-fi |
Lien de soutien. Vide : masqué (build) |
MENU_WAF, MENU_GODNS, MENU_API, MENU_WEBHOOKS, MENU_DOCKER_AUTOCONFIG, MENU_AGENTS, MENU_GOACCESS |
auto |
Visibilité des menus optionnels : auto, show ou hide (GoDNS n'a pas de mode auto : show par défaut). Réglable aussi dans menu.yml |
Mise à jour et synchronisation
| Variable |
Défaut |
Rôle |
SYNC_REF_URL |
vide |
Dépôt de référence pour la synchronisation de snippets et de configuration |
SYNC_REF_PATH_PREFIX |
vide |
Sous-dossier du dépôt de référence, si conf, sites, snippets et streams n'y sont pas à la racine |
DASHBOARD_VERSION_URL, NGINX_VERSION_URL |
vides |
Adresses consultées pour détecter une nouvelle version. Vides : vérification désactivée |
CHANGELOG_URL |
vide |
Adresse du changelog affiché par le bouton Changelog |
ALERTING_URL, ALERTING_POLL_INTERVAL_MIN |
vide, 60 |
Messages importants distribués par une adresse Markdown, avec un intervalle minimal de 5 minutes |
Nginx
Variables lues par le compose, dans .env :
| Variable |
Défaut |
Rôle |
NGINX_TAG |
voir sample.env |
Tag de l'image Nginx |
NGINX_RESTART_POLICY |
always |
Politique de redémarrage |
NGINX_WORKER_PROCESSES |
auto |
Nombre de processus de travail |
NGINX_WORKER_CONNECTIONS |
768 |
Connexions par processus |
Hub
Fichier .env de nginx-hub/. Le reste de la configuration est dans config/hub.yml.
| Variable |
Rôle |
HUB_SECRET_KEY |
Clé maître qui chiffre les jetons des instances. Se génère avec docker compose run --rm hub node bin/hub-admin.js generate-key. À sauvegarder avec les données |
HUB_PORT |
Port d'écoute, 8090 par défaut |
HUB_BOOTSTRAP_ADMIN_PASSWORD |
Mot de passe initial imposé au compte admin (12 caractères minimum, changement obligatoire à la première connexion). Sans lui, un mot de passe aléatoire est affiché une fois dans les logs |
HUB_LOG_LEVEL |
Niveau de journalisation, info par défaut |
HUB_LOGSTORE_TOKEN, HUB_LOGSTORE_URL |
Jeton read global et adresse du log store, pour la vue Journaux |
HUB_DB_DRIVER, HUB_DB_HOST |
Utilisation de PostgreSQL à la place de SQLite |
En production, préférez un secret Docker (HUB_SECRET_KEY_FILE, HUB_LOGSTORE_TOKEN_FILE) à une variable en clair.
Log store
| Variable |
Défaut |
Rôle |
LOGSTORE_DB_PASSWORD |
à définir |
Mot de passe PostgreSQL |
LOGSTORE_ADMIN_TOKEN |
à définir |
Jeton d'administration (32 caractères minimum) qui sert à créer les jetons write et read |
LOGSTORE_IP_MODE |
clear |
Mode initial des adresses IP : clear, pseudonymized ou truncated |
LOGSTORE_PSEUDO_KEY |
vide |
Clé de pseudonymisation, obligatoire en mode pseudonymized (32 caractères minimum) |
LOGSTORE_RETENTION_DAYS |
30 |
Rétention initiale des journaux bruts, de 7 à 30 jours |
LOGSTORE_TLS_CERT, LOGSTORE_TLS_KEY |
vides |
Certificat TLS monté dans le conteneur |
LOGSTORE_INSECURE_HTTP |
true dans l'exemple |
HTTP clair, réservé au réseau interne ou derrière un proxy TLS de confiance |
LOGSTORE_LISTEN |
:8443 |
Adresse d'écoute |
LOGSTORE_REQUIRE_TIMESCALE |
voir sample.env |
Refuse de démarrer sans TimescaleDB |
LOGSTORE_RATE_READ, LOGSTORE_RATE_WRITE |
20, 10 |
Requêtes par seconde et par jeton |
LOGSTORE_MAX_BODY_BYTES, LOGSTORE_MAX_BATCH_EVENTS |
4194304, 5000 |
Limites d'un lot |
LOGSTORE_QUERY_TIMEOUT_SECONDS |
15 |
Délai maximal d'une requête |
LOGSTORE_MAINTENANCE, LOGSTORE_MAINTENANCE_HOURS |
true, 24 |
Maintenance planifiée de la base et son intervalle |
LOGSTORE_UI |
true |
Interface web /ui/ de gestion des jetons |
Agent
Fichier .env du dossier nginx-agent/, sur le serveur distant. Le dashboard peut générer ce fichier et le fichier compose depuis la page des hôtes distants.
| Variable |
Défaut |
Rôle |
DASHBOARD_URL |
à définir |
Adresse du dashboard, joignable depuis le serveur distant |
AGENT_HOSTNAME |
nom du conteneur |
Nom proposé lors de l'enrôlement |
AGENT_FINGERPRINT |
vide |
Empreinte libre affichée à l'opérateur au moment de l'approbation |
POLL_INTERVAL |
30s |
Intervalle entre deux envois du manifeste |
TUNNEL_ENABLE |
true |
Ouvre la connexion tunnel quand un vhost est en mode tunnel |
RELAY_HTTP_LISTEN, RELAY_HTTPS_LISTEN |
vides |
Ports d'écoute du mode relais. Vides : relais désactivé |
RELAY_HTTP_ADVERTISE, RELAY_HTTPS_ADVERTISE |
vides |
Adresse complète (http://ip:port) que Nginx utilisera pour joindre le relais |
RELAY_HTTPS_CERT, RELAY_HTTPS_KEY |
vides |
Certificat du relais HTTPS. Vides : certificat auto-signé généré en mémoire |
RELAY_BACKEND_INSECURE_SKIP_VERIFY |
false |
Accepte un backend HTTPS au certificat auto-signé |
TARGETS_FILE |
vide |
Fichier JSON qui décrit plusieurs dashboards cibles |
INSECURE_SKIP_VERIFY |
false |
Désactive la vérification TLS du dashboard. À ne jamais activer en production |
Le détail des modes direct, tunnel et relais est dans le README de nginx-agent/.