mirror of
https://github.com/bunkerity/bunkerweb
synced 2026-05-24 09:28:37 +00:00
465 KiB
465 KiB
Fonctionnalités
Cette section contient la liste complète des paramètres pris en charge par BunkerWeb. Si vous n’êtes pas encore familier avec BunkerWeb, commencez par lire la section concepts de la documentation. Suivez ensuite les instructions de votre intégration pour appliquer les paramètres.
Paramètres globaux
Prise en charge STREAM ⚠️
Le plugin General fournit le cadre de configuration de base de BunkerWeb, vous permettant de définir les paramètres essentiels qui régissent la protection et la distribution de vos services web. Ce plugin fondamental gère des aspects clés tels que les modes de sécurité, les valeurs par défaut du serveur, le comportement de journalisation et les paramètres opérationnels critiques pour l’ensemble de l’écosystème BunkerWeb.
Comment ça marche :
- Au démarrage de BunkerWeb, le plugin General charge et applique vos paramètres de configuration principaux.
- Les modes de sécurité sont définis globalement ou par site, déterminant le niveau de protection appliqué.
- Les paramètres par défaut du serveur établissent des valeurs de repli pour toute configuration multisite non spécifiée.
- Les paramètres de journalisation contrôlent les informations enregistrées et leur format.
- Ces paramètres constituent la base sur laquelle s’appuient tous les autres plugins et fonctionnalités de BunkerWeb.
Mode multisite
Lorsque MULTISITE vaut yes, BunkerWeb peut héberger et protéger plusieurs sites web, chacun avec sa propre configuration. Ce mode est utile notamment pour :
- Héberger plusieurs domaines aux configurations distinctes
- Exécuter plusieurs applications avec des exigences de sécurité différentes
- Appliquer des politiques de sécurité adaptées à différents services
En mode multisite, chaque site est identifié par un SERVER_NAME unique. Pour appliquer des paramètres spécifiques à un site, préfixez le nom du paramètre par le SERVER_NAME principal. Par exemple :
www.example.com_USE_ANTIBOT=captchaactive le CAPTCHA pourwww.example.com.myapp.example.com_USE_GZIP=yesactive la compression GZIP pourmyapp.example.com.
Cette approche garantit que les paramètres sont appliqués au bon site dans un environnement multisite.
Paramètres multiples
Certains paramètres de BunkerWeb supportent plusieurs configurations pour une même fonctionnalité. Pour définir plusieurs groupes de paramètres, ajoutez un suffixe numérique au nom du paramètre. Par exemple :
REVERSE_PROXY_URL_1=/subdiretREVERSE_PROXY_HOST_1=http://myhost1définissent le premier reverse proxy.REVERSE_PROXY_URL_2=/anotherdiretREVERSE_PROXY_HOST_2=http://myhost2définissent le second reverse proxy.
Ce modèle permet de gérer plusieurs configurations pour des fonctionnalités comme les reverse proxies, les ports, ou d’autres paramètres nécessitant des valeurs distinctes selon les cas d’usage.
Ordre d'exécution des plugins
Vous pouvez définir l’ordre d’exécution via des listes séparées par des espaces :
- Phases globales :
PLUGINS_ORDER_INIT,PLUGINS_ORDER_INIT_WORKER,PLUGINS_ORDER_TIMER. - Phases par site :
PLUGINS_ORDER_SET,PLUGINS_ORDER_ACCESS,PLUGINS_ORDER_SSL_CERTIFICATE,PLUGINS_ORDER_HEADER,PLUGINS_ORDER_LOG,PLUGINS_ORDER_PREREAD,PLUGINS_ORDER_LOG_STREAM,PLUGINS_ORDER_LOG_DEFAULT. - Sémantique : les plugins listés s’exécutent en premier pour la phase ; les autres s’exécutent ensuite dans leur séquence normale. Séparez les IDs uniquement par des espaces.
Modes de sécurité
Le paramètre SECURITY_MODE détermine la façon dont BunkerWeb gère les menaces détectées. Ce mécanisme flexible vous permet de choisir entre la surveillance et le blocage actif des activités suspectes, selon vos besoins :
detect: Enregistre les menaces potentielles sans les bloquer. Utile pour analyser les faux positifs sans perturber les utilisateurs légitimes.block(par défaut) : Bloque activement les menaces détectées tout en journalisant les incidents pour protéger votre application.
Passer en mode detect aide à identifier et corriger les faux positifs sans impacter les clients légitimes. Une fois ces problèmes résolus, repassez en mode block pour une protection complète.
Paramètres de configuration
=== "Paramètres principaux"
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
| --------------------- | ----------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `SERVER_NAME` | `www.example.com` | multisite | Non | **Domaine principal :** Nom de domaine principal pour ce site. Requis en mode multisite. |
| `BUNKERWEB_INSTANCES` | `127.0.0.1` | global | Non | **Instances BunkerWeb :** Liste des instances BunkerWeb séparées par des espaces. |
| `MULTISITE` | `no` | global | Non | **Sites multiples :** Définir à `yes` pour héberger plusieurs sites avec des configurations différentes. |
| `SECURITY_MODE` | `block` | multisite | Non | **Niveau de sécurité :** `detect` ou `block` pour contrôler l’application de la sécurité. |
| `SERVER_TYPE` | `http` | multisite | Non | **Type de serveur :** Définit si le serveur est de type `http` ou `stream`. |
=== "Paramètres API"
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
| ------------------ | ----------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `USE_API` | `yes` | global | Non | **Activer l’API :** Active l’API pour piloter BunkerWeb. |
| `API_HTTP_PORT` | `5000` | global | Non | **Port de l’API :** Numéro de port d’écoute de l’API. |
| `API_HTTPS_PORT` | `5443` | global | Non | **Port HTTPS de l’API :** Numéro de port d’écoute (TLS) de l’API. |
| `API_LISTEN_HTTP` | `yes` | global | Non | **Écoute HTTP de l’API :** Active l’écoute HTTP pour l’API. |
| `API_LISTEN_HTTPS` | `no` | global | Non | **Écoute HTTPS de l’API :** Active l’écoute HTTPS (TLS) pour l’API. |
| `API_LISTEN_IP` | `0.0.0.0` | global | Non | **IP d’écoute de l’API :** Adresse IP d’écoute de l’API. |
| `API_SERVER_NAME` | `bwapi` | global | Non | **Nom de serveur de l’API :** Nom de serveur (vhost) pour l’API. |
| `API_WHITELIST_IP` | `127.0.0.0/8` | global | Non | **Liste blanche API :** Liste IP/réseaux autorisés à contacter l’API. |
| `API_TOKEN` | | global | Non | **Jeton d’accès API (optionnel) :** Si défini, chaque requête API doit inclure `Authorization: Bearer <token>`. |
Remarque : pour des raisons d’amorçage, si vous activez `API_TOKEN`, vous devez le définir dans l’environnement à la fois de l’instance BunkerWeb et du Scheduler. Le Scheduler ajoute automatiquement l’en-tête `Authorization` quand `API_TOKEN` est présent dans son environnement. S’il n’est pas défini, aucun en-tête n’est envoyé et BunkerWeb n’applique pas l’authentification par jeton. Vous pouvez exposer l’API en HTTPS en définissant `API_LISTEN_HTTPS=yes` (port : `API_HTTPS_PORT`, `5443` par défaut).
Exemple de test avec curl (remplacez le jeton et l’hôte) :
```bash
curl -H "Host: bwapi" \
-H "Authorization: Bearer $API_TOKEN" \
http://<bunkerweb-host>:5000/ping
curl -H "Host: bwapi" \
-H "Authorization: Bearer $API_TOKEN" \
--insecure \
https://<bunkerweb-host>:5443/ping
```
=== "Paramètres réseau et ports"
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
| ----------------------- | ----------------- | -------- | -------- | -------------------------------------------------------------------------------------------------- |
| `HTTP_PORT` | `8080` | global | Oui | **Port HTTP :** Numéro de port pour le trafic HTTP. Laisser vide pour désactiver l'écoute HTTP. |
| `HTTPS_PORT` | `8443` | global | Oui | **Port HTTPS :** Numéro de port pour le trafic HTTPS. Laisser vide pour désactiver l'écoute HTTPS. |
| `USE_IPV6` | `no` | global | Non | **Support IPv6 :** Active la connectivité IPv6. |
| `DNS_RESOLVERS` | `127.0.0.11` | global | Non | **Résolveurs DNS :** Adresses des résolveurs à utiliser. |
| `CLIENT_BODY_TIMEOUT` | `10s` | global | Non | **Timeout corps client :** Délai de lecture du corps de la requête client. |
| `CLIENT_HEADER_TIMEOUT` | `10s` | global | Non | **Timeout en-têtes client :** Délai de lecture des en-têtes de la requête client. |
| `KEEPALIVE_TIMEOUT` | `15s` | global | Non | **Timeout keepalive :** Délai des connexions client en keepalive. |
| `SEND_TIMEOUT` | `10s` | global | Non | **Timeout d'envoi :** Délai maximal de transmission de la réponse au client. |
=== "Paramètres serveur Stream"
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
| ------------------------ | ----------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `LISTEN_STREAM` | `yes` | multisite | Non | **Écoute stream :** Active l'écoute non-ssl (pass-through). |
| `LISTEN_STREAM_PORT` | `1337` | multisite | Oui | **Port stream :** Port d'écoute pour le non-ssl (pass-through). Laisser vide pour désactiver l'écoute stream non-SSL. |
| `LISTEN_STREAM_PORT_SSL` | `4242` | multisite | Oui | **Port stream SSL :** Port d'écoute pour le SSL (pass-through). Laisser vide pour désactiver l'écoute stream SSL. |
| `USE_TCP` | `yes` | multisite | Non | **Écoute TCP :** Active l’écoute TCP (stream). |
| `USE_UDP` | `no` | multisite | Non | **Écoute UDP :** Active l’écoute UDP (stream). |
=== "Paramètres des workers"
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
| ------------------------- | ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WORKER_PROCESSES` | `auto` | global | Non | **Processus workers :** Nombre de processus workers. `auto` utilise le nombre de cœurs. |
| `WORKER_CONNECTIONS` | `1024` | global | Non | **Connexions par worker :** Nombre maximal de connexions par worker. |
| `WORKER_RLIMIT_NOFILE` | `2048` | global | Non | **Limite descripteurs :** Nombre maximal de fichiers ouverts par worker. |
| `WORKER_SHUTDOWN_TIMEOUT` | `30s` | global | Non | **Délai d'arrêt des workers :** Délai pour l'arrêt gracieux des processus workers. Les anciens workers sont arrêtés de force après ce délai lors d'un rechargement. |
=== "Paramètres mémoire"
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
| ------------------------------ | ----------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WORKERLOCK_MEMORY_SIZE` | `48k` | global | Non | **Mémoire workerlock :** Taille de lua_shared_dict pour l’initialisation des workers. |
| `DATASTORE_MEMORY_SIZE` | `64m` | global | Non | **Mémoire datastore :** Taille du datastore interne. |
| `DATASTORE_LRU_SIZE` | `1k` | global | Non | **Taille du LRU datastore :** Nombre d'emplacements pour le LRU du datastore partagé par worker. Accepte un entier ou les suffixes `k`/`m` (par exemple `1k`, `10k`, `1m`). |
| `CACHESTORE_MEMORY_SIZE` | `64m` | global | Non | **Mémoire cachestore :** Taille du cache interne. |
| `CACHESTORE_IPC_MEMORY_SIZE` | `16m` | global | Non | **Mémoire cachestore IPC :** Taille du cache interne (IPC). |
| `CACHESTORE_MISS_MEMORY_SIZE` | `16m` | global | Non | **Mémoire cachestore miss :** Taille du cache interne (miss). |
| `CACHESTORE_LOCKS_MEMORY_SIZE` | `16m` | global | Non | **Mémoire cachestore locks :** Taille du cache interne (locks). |
=== "Paramètres de journalisation"
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LOG_FORMAT` | `$host $remote_addr - $request_id $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\"` | global | Non | **Format des logs :** Format utilisé pour les logs d’accès. |
| `ACCESS_LOG` | `/var/log/bunkerweb/access.log` | global | Oui | **Chemin du log d'accès :** Fichier, `syslog:server=hôte[:port][,param=valeur]` ou tampon partagé `memory:nom:taille` ; mettez `off` pour désactiver les logs. |
| `ERROR_LOG` | `/var/log/bunkerweb/error.log` | global | Oui | **Chemin du log d'erreur :** Fichier, `stderr`, `syslog:server=hôte[:port][,param=valeur]` ou `memory:taille`. |
| `LOG_LEVEL` | `notice` | global | Oui | **Niveau de logs :** Verbosité des logs d’erreur. Options : `debug`, `info`, `notice`, `warn`, `error`, `crit`, `alert`, `emerg`. |
| `TIMERS_LOG_LEVEL` | `debug` | global | Non | **Niveau des timers :** Niveau de log pour les timers. Options : `debug`, `info`, `notice`, `warn`, `err`, `crit`, `alert`, `emerg`. |
!!! tip "Bonnes pratiques de journalisation"
- En production, utilisez les niveaux `notice`, `warn` ou `error` pour limiter le volume de logs.
- Pour le dépannage, passez temporairement le niveau à `debug` pour obtenir plus de détails.
=== "Paramètres d’intégration"
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
| ------------------------ | ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTOCONF_MODE` | `no` | global | Non | **Mode Autoconf :** Active l’intégration Docker Autoconf. |
| `SWARM_MODE` | `no` | global | Non | **Mode Swarm :** Active l’intégration Docker Swarm. |
| `KUBERNETES_MODE` | `no` | global | Non | **Mode Kubernetes :** Active l’intégration Kubernetes. |
| `KEEP_CONFIG_ON_RESTART` | `no` | global | Non | **Garder la configuration au redémarrage :** Conserver la configuration au redémarrage. Mettre à 'yes' pour éviter la réinitialisation de la config au redémarrage. |
| `USE_TEMPLATE` | | multisite | Non | **Utiliser un template :** Modèle de configuration qui surcharge les valeurs par défaut de certains paramètres. |
=== "Paramètres Nginx"
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
| ------------------------------- | ----------------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `NGINX_PREFIX` | `/etc/nginx/` | global | Non | **Préfixe Nginx :** Répertoire où NGINX va chercher les configurations. |
| `SERVER_NAMES_HASH_BUCKET_SIZE` | | global | Non | **Taille du hash :** Valeur pour la directive server_names_hash_bucket_size. |
Exemples de configuration
=== "Configuration de base (production)"
Configuration standard pour un site de production avec une sécurité stricte :
```yaml
SECURITY_MODE: "block"
SERVER_NAME: "example.com"
LOG_LEVEL: "notice"
```
=== "Mode développement"
Configuration pour un environnement de développement avec journalisation détaillée :
```yaml
SECURITY_MODE: "detect"
SERVER_NAME: "dev.example.com"
LOG_LEVEL: "debug"
```
=== "Configuration multisite"
Configuration pour héberger plusieurs sites :
```yaml
MULTISITE: "yes"
# Premier site
site1.example.com_SERVER_NAME: "site1.example.com"
site1.example.com_SECURITY_MODE: "block"
# Second site
site2.example.com_SERVER_NAME: "site2.example.com"
site2.example.com_SECURITY_MODE: "detect"
```
=== "Configuration serveur Stream"
Configuration pour un serveur TCP/UDP :
```yaml
SERVER_TYPE: "stream"
SERVER_NAME: "stream.example.com"
LISTEN_STREAM: "yes"
LISTEN_STREAM_PORT: "1337"
USE_TCP: "yes"
USE_UDP: "no"
```
=== "Désactiver les modes d'écoute"
Vous pouvez désactiver certains modes d'écoute en laissant les paramètres de port vides :
```yaml
# Désactiver l'écoute HTTP (HTTPS uniquement)
HTTP_PORT: ""
HTTPS_PORT: "8443"
# Désactiver l'écoute HTTPS (HTTP uniquement)
HTTP_PORT: "8080"
HTTPS_PORT: ""
# Stream : désactiver l'écoute non SSL (SSL uniquement)
LISTEN_STREAM_PORT: ""
LISTEN_STREAM_PORT_SSL: "4242"
# Stream : désactiver l'écoute SSL (non SSL uniquement)
LISTEN_STREAM_PORT: "1337"
LISTEN_STREAM_PORT_SSL: ""
```
ACME 
(PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ✅
Advanced ACME certificate management with custom CA support, certificate monitoring dashboard, expiry alerting, CT log monitoring, and enhanced OCSP stapling. Complements the built-in Let's Encrypt plugin.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_ACME |
no |
multisite | non | Enable ACME certificate management for this service using a custom ACME-compatible Certificate Authority. |
ACME_PASSTHROUGH |
no |
multisite | non | Pass through ACME HTTP-01 challenge requests to the upstream server. |
ACME_DIRECTORY_URL |
multisite | non | ACME directory URL of the Certificate Authority (e.g. https://ca.example.com/acme/directory for Step CA, https://vault.example.com/v1/pki/acme/directory for Vault PKI). | |
ACME_EMAIL |
multisite | non | Email address for ACME account registration and notifications. | |
ACME_EAB_KID |
multisite | non | External Account Binding Key ID (required by some CAs like Sectigo, Google Trust Services). | |
ACME_EAB_HMAC_KEY |
multisite | non | External Account Binding HMAC key (base64-encoded, required when EAB Key ID is set). | |
ACME_CA_CERT_PATH |
multisite | non | File path to the root CA certificate for private ACME servers (Step CA, Vault PKI). Required when the CA root is not in the system trust store. | |
ACME_CHALLENGE |
http |
multisite | non | ACME challenge type. HTTP-01 is simplest; DNS-01 is required for wildcard certificates; TLS-ALPN-01 works when port 80 is unavailable. |
ACME_DNS_PROVIDER |
multisite | non | DNS provider for DNS-01 challenges. | |
ACME_DNS_CREDENTIAL_ITEM |
multisite | oui | Configuration item for the DNS provider credentials (e.g. 'cloudflare_api_token 123456'). Values can be base64 encoded. | |
ACME_DNS_CREDENTIAL_DECODE_BASE64 |
yes |
multisite | oui | Automatically decode base64 encoded DNS provider credentials. |
ACME_DNS_PROPAGATION |
default |
multisite | non | Time to wait for DNS propagation in seconds for DNS challenges. |
ACME_DNS_ALIAS |
multisite | non | Target zone for DNS-01 CNAME delegation. Passed as --dns--domain-alias to certbot and applied to every challenge for the cert, so DNS credentials only need to control the alias zone. Prerequisite: each cert domain must already have a CNAME _acme-challenge.<domain> -> _acme-challenge.<target> (and the target zone must resolve). Example: 'alias.acmeplay.org'. Silently ignored on older runtimes or with incompatible DNS providers (e.g. route53). |
|
ACME_KEY_TYPE |
ecdsa |
multisite | non | Key type for the certificate. ECDSA is smaller and faster; RSA has broader compatibility. |
ACME_KEY_SIZE |
256 |
multisite | non | Key size in bits. For ECDSA: 256 or 384. For RSA: 2048 or 4096. |
ACME_PREFERRED_CHAIN |
multisite | non | Preferred certificate chain issuer CN. Selects the preferred chain when the CA provides multiple. | |
ACME_RENEWAL_DAYS |
30 |
multisite | non | Renew the certificate when it has fewer than this many days until expiry. |
ACME_SSL_VERIFY |
yes |
multisite | non | Verify SSL certificates when communicating with the ACME server. Disable only for testing with self-signed CA certs. |
ACME_WILDCARD |
no |
multisite | non | Request wildcard certificate (requires DNS-01 challenge). |
ACME_MUST_STAPLE |
no |
multisite | non | Request the OCSP Must-Staple extension in the certificate. |
ACME_MAX_RETRIES |
3 |
multisite | non | Number of times to retry certificate generation on failure (0 disables retries). |
USE_ACME_MONITORING |
yes |
global | non | Enable certificate expiry monitoring and status tracking for all managed certificates (including OSS Let's Encrypt certificates). |
ACME_ALERT_DAYS |
30 14 7 1 |
global | non | Space-separated list of day thresholds that trigger expiry alerts. |
USE_ACME_ALERT_WEBHOOK |
no |
global | non | Send certificate alerts via webhook. |
ACME_ALERT_WEBHOOK_URLS |
global | non | Space-separated list of webhook URLs for certificate alerts. | |
USE_ACME_ALERT_EMAIL |
no |
global | non | Send certificate alerts via email. |
ACME_ALERT_SMTP_EMAILS |
global | non | Space-separated list of email recipients for certificate alerts. | |
ACME_ALERT_SMTP_HOST |
global | non | SMTP host for certificate alert emails. | |
ACME_ALERT_SMTP_PORT |
465 |
global | non | SMTP port for certificate alert emails (SSL=465, TLS=587). |
ACME_ALERT_SMTP_FROM_EMAIL |
global | non | Sender email address for certificate alerts. | |
ACME_ALERT_SMTP_FROM_USER |
global | non | SMTP authentication user for certificate alert emails. | |
ACME_ALERT_SMTP_FROM_PASSWORD |
global | non | SMTP authentication password for certificate alert emails. | |
ACME_ALERT_SMTP_SSL |
SSL |
global | non | Connection type for certificate alert SMTP. |
USE_ACME_CT_MONITORING |
no |
global | non | Enable Certificate Transparency log monitoring. Queries crt.sh to detect unauthorized certificate issuance for your domains. |
ACME_CT_MONITORED_DOMAINS |
global | non | Space-separated list of domains to monitor in CT logs. Leave empty to auto-detect from configured services. | |
USE_ACME_OCSP_STAPLING |
no |
multisite | non | Enable enhanced OCSP stapling with proactive response fetching and caching. |
ACME_OCSP_CACHE_SIZE |
1m |
global | non | Size of the shared dictionary for OCSP response caching. |
Anti DDoS (PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ❌
Provides enhanced protection against DDoS attacks by analyzing and filtering suspicious traffic.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_ANTIDDOS |
no |
global | non | Enable or disable anti DDoS protection to mitigate high traffic spikes. |
ANTIDDOS_METRICS_DICT_SIZE |
10M |
global | non | Size of in-memory storage for DDoS metrics (e.g., 10M, 500k). |
ANTIDDOS_THRESHOLD |
100 |
global | non | Maximum suspicious requests allowed from a single IP before blocking. |
ANTIDDOS_WINDOW_TIME |
10 |
global | non | Time window (seconds) to detect abnormal request patterns. |
ANTIDDOS_STATUS_CODES |
429 403 444 |
global | non | HTTP status codes treated as suspicious for DDoS analysis. |
ANTIDDOS_DISTINCT_IP |
5 |
global | non | Minimum distinct IP count before enabling anti DDoS measures. |
Antibot
Prise en charge STREAM ❌
Les attaquants utilisent souvent des outils automatisés (bots) pour tenter d’exploiter votre site. Pour s’en protéger, BunkerWeb inclut une fonctionnalité « Antibot » qui demande aux utilisateurs de prouver qu’ils sont humains. Si un utilisateur réussit le défi, il obtient l’accès à votre site. Cette fonctionnalité est désactivée par défaut.
Comment ça marche :
- Lorsqu’un utilisateur visite votre site, BunkerWeb vérifie s’il a déjà réussi un défi antibot.
- Sinon, l’utilisateur est redirigé vers une page de défi.
- L’utilisateur doit compléter le défi (ex. résoudre un CAPTCHA, exécuter du JavaScript).
- Si le défi est réussi, l’utilisateur est redirigé vers la page initialement demandée et peut naviguer normalement.
Comment l’utiliser
Suivez ces étapes pour activer et configurer Antibot :
- Choisir un type de défi : décidez du mécanisme à utiliser (ex. captcha, hcaptcha, capjs, javascript).
- Activer la fonctionnalité : définissez le paramètre
USE_ANTIBOTsur le type choisi dans votre configuration BunkerWeb. - Configurer les paramètres : ajustez les autres paramètres
ANTIBOT_*si nécessaire. Pour reCAPTCHA, hCaptcha et Turnstile, créez un compte auprès du service choisi et obtenez des clés API. Pour mCaptcha et Cap.js, vous pouvez auto-héberger le fournisseur ou utiliser un service hébergé, puis configurer la clé de site et la clé secrète requises. - Important : assurez‑vous que
ANTIBOT_URIest une URL unique de votre site et qu’elle n’est pas utilisée ailleurs.
!!! important "À propos du paramètre ANTIBOT_URI"
Assurez‑vous que ANTIBOT_URI est une URL unique de votre site et qu’elle n’est pas utilisée ailleurs.
!!! warning "Sessions en environnement cluster"
La fonction antibot utilise des cookies pour suivre si un utilisateur a complété le défi. Si vous exécutez BunkerWeb en cluster (plusieurs instances), vous devez configurer correctement la gestion des sessions : définissez SESSIONS_SECRET et SESSIONS_NAME avec les mêmes valeurs sur toutes les instances BunkerWeb. Sinon, les utilisateurs pourront être invités à répéter le défi. Plus d’informations sur la configuration des sessions ici.
Paramètres communs
Les paramètres suivants sont partagés par tous les mécanismes de défi :
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
ANTIBOT_URI |
/challenge |
multisite | non | URL du défi : l’URL vers laquelle les utilisateurs sont redirigés pour compléter le défi. Veillez à ce que cette URL ne soit pas utilisée pour autre chose. |
ANTIBOT_TIME_RESOLVE |
60 |
multisite | non | Délai du défi : temps maximum (en secondes) pour compléter le défi. Au‑delà, un nouveau défi est généré. |
ANTIBOT_TIME_VALID |
86400 |
multisite | non | Validité du défi : durée (en secondes) pendant laquelle un défi réussi reste valide. Passé ce délai, un nouveau défi sera requis. |
Exclure du trafic des défis
BunkerWeb permet d’indiquer certains utilisateurs, IP ou requêtes qui doivent contourner totalement le défi antibot. Utile pour des services de confiance, réseaux internes ou des pages à laisser toujours accessibles :
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
ANTIBOT_IGNORE_URI |
multisite | non | URL exclues : liste d’expressions régulières d’URI séparées par des espaces qui doivent contourner le défi. | |
ANTIBOT_IGNORE_IP |
multisite | non | IP exclues : liste d’adresses IP ou de plages CIDR séparées par des espaces qui doivent contourner le défi. | |
ANTIBOT_IGNORE_RDNS |
multisite | non | rDNS exclu : liste de suffixes de DNS inversés séparés par des espaces qui doivent contourner le défi. | |
ANTIBOT_RDNS_GLOBAL |
yes |
multisite | non | IP publiques uniquement : si yes, ne faire des vérifications rDNS que sur des IP publiques. |
ANTIBOT_IGNORE_ASN |
multisite | non | ASN exclus : liste de numéros d’ASN séparés par des espaces qui doivent contourner le défi. | |
ANTIBOT_IGNORE_USER_AGENT |
multisite | non | User‑Agents exclus : liste de motifs regex d’User‑Agent séparés par des espaces qui doivent contourner le défi. | |
ANTIBOT_IGNORE_COUNTRY |
multisite | non | Pays exclus : liste de codes pays ISO 3166-1 alpha-2 séparés par des espaces qui doivent contourner le défi. | |
ANTIBOT_ONLY_COUNTRY |
multisite | non | Pays ciblés : liste de codes pays ISO 3166-1 alpha-2 qui doivent résoudre le défi. Les autres pays sont ignorés. |
!!! note "Comportement des paramètres basés sur le pays"
- Lorsque ANTIBOT_IGNORE_COUNTRY et ANTIBOT_ONLY_COUNTRY sont définis, la liste d’exclusion est prioritaire : un pays présent dans les deux listes contourne le défi.
- Les adresses IP privées ou inconnues contournent le défi lorsque ANTIBOT_ONLY_COUNTRY est défini, car aucun code pays ne peut être déterminé.
!!! tip "Partager l’état du défi entre sous-domaines"
L’état antibot (y compris turnstile, hcaptcha, recaptcha, mcaptcha, captcha, javascript et cookie) est conservé dans le cookie de session de BunkerWeb. Par défaut, ce cookie est limité à l’hôte exact qui l’a émis. Ainsi, un utilisateur qui résout le défi sur a.example.com devra le résoudre à nouveau sur b.example.com. Pour résoudre le défi une seule fois pour tous les sous-domaines frères d’un même domaine enregistrable, définissez SESSIONS_DOMAIN sur le domaine parent (par exemple example.com) pour chaque serveur concerné. SESSIONS_DOMAIN est un paramètre multisite : configurez-le par serveur afin que des tenants non liés hébergés sur la même instance BunkerWeb ne reçoivent jamais un attribut Domain partagé entre tenants.
Exemples :
-
ANTIBOT_IGNORE_URI: "^/api/ ^/webhook/ ^/assets/"Exclut toutes les URI commençant par/api/,/webhook/ou/assets/. -
ANTIBOT_IGNORE_IP: "192.168.1.0/24 10.0.0.1"Exclut le réseau interne192.168.1.0/24et l’IP spécifique10.0.0.1. -
ANTIBOT_IGNORE_RDNS: ".googlebot.com .bingbot.com"Exclut les requêtes provenant d’hôtes dont le DNS inversé se termine pargooglebot.comoubingbot.com. -
ANTIBOT_IGNORE_ASN: "15169 8075"Exclut les requêtes des ASN 15169 (Google) et 8075 (Microsoft). -
ANTIBOT_IGNORE_USER_AGENT: "^Mozilla.+Chrome.+Safari"Exclut les requêtes dont le User-Agent correspond au motif regex spécifié. -
ANTIBOT_IGNORE_COUNTRY: "US CA"Contourne le défi antibot pour les visiteurs situés aux États-Unis ou au Canada. -
ANTIBOT_ONLY_COUNTRY: "CN RU"Ne défie que les visiteurs provenant de Chine ou de Russie. Les requêtes d’autres pays (ou d’adresses IP privées) contournent le défi.
Mécanismes de défi
=== "Cookie"
Le défi Cookie est un mécanisme léger qui repose sur l’installation d’un cookie dans le navigateur de l’utilisateur. Lorsqu’un utilisateur accède au site, le serveur envoie un cookie au client. Lors des requêtes suivantes, le serveur vérifie la présence de ce cookie pour confirmer que l’utilisateur est légitime. Cette méthode est simple et efficace pour une protection de base contre les bots sans nécessiter d’interaction supplémentaire de l’utilisateur.
**Comment ça marche :**
1. Le serveur génère un cookie unique et l’envoie au client.
2. Le client doit renvoyer le cookie dans les requêtes suivantes.
3. Si le cookie est manquant ou invalide, l’utilisateur est redirigé vers la page de défi.
**Paramètres :**
| Paramètre | Défaut | Contexte | Multiple | Description |
| ------------- | ------ | --------- | -------- | ----------------------------------------------------------------- |
| `USE_ANTIBOT` | `no` | multisite | non | Activer Antibot : définir sur `cookie` pour activer ce mécanisme. |
Reportez‑vous aux [Paramètres communs](#paramètres-communs) pour les options supplémentaires.
=== "JavaScript"
Le défi JavaScript demande au client de résoudre une tâche de calcul en utilisant JavaScript. Ce mécanisme garantit que le client a activé JavaScript et peut exécuter le code requis, ce qui est généralement hors de portée de la plupart des bots.
**Comment ça marche :**
1. Le serveur envoie un script JavaScript au client.
2. Le script effectue une tâche de calcul (par exemple, un hachage) et soumet le résultat au serveur.
3. Le serveur vérifie le résultat pour confirmer la légitimité du client.
**Fonctionnalités clés :**
- Le défi génère dynamiquement une tâche unique pour chaque client.
- La tâche de calcul implique un hachage avec des conditions spécifiques (par exemple, trouver un hachage avec un certain préfixe).
**Paramètres :**
| Paramètre | Défaut | Contexte | Multiple | Description |
| ------------- | ------ | --------- | -------- | --------------------------------------------------------------------- |
| `USE_ANTIBOT` | `no` | multisite | non | Activer Antibot : définir sur `javascript` pour activer ce mécanisme. |
Reportez‑vous aux [Paramètres communs](#paramètres-communs) pour les options supplémentaires.
=== "Captcha"
Le défi Captcha est un mécanisme maison qui génère des défis basés sur des images, entièrement hébergés dans votre environnement BunkerWeb. Il teste la capacité des utilisateurs à reconnaître et interpréter des caractères aléatoires, garantissant que les bots automatisés sont bloqués efficacement sans dépendre de services externes.
**Comment ça marche :**
1. Le serveur génère une image CAPTCHA contenant des caractères aléatoires.
2. L’utilisateur doit saisir les caractères affichés dans l’image dans un champ de texte.
3. Le serveur valide la saisie de l’utilisateur par rapport au CAPTCHA généré.
**Fonctionnalités clés :**
- Entièrement auto-hébergé, éliminant le besoin d’API tierces.
- Les défis générés dynamiquement assurent l’unicité pour chaque session utilisateur.
- Utilise un jeu de caractères personnalisable pour la génération du CAPTCHA.
**Caractères pris en charge :**
Le système CAPTCHA prend en charge les types de caractères suivants :
- **Lettres :** Toutes les lettres minuscules (a-z) et majuscules (A-Z)
- **Chiffres :** 2, 3, 4, 5, 6, 7, 8, 9 (exclut 0 et 1 pour éviter toute confusion)
- **Caractères spéciaux :** ```+-/=%"'&_(),.;:?!§`^ÄÖÜßäöüé''‚""„```
Pour obtenir la liste complète des caractères pris en charge, consultez la [table des caractères de la police](https://www.dafont.com/moms-typewriter.charmap?back=theme) utilisée pour le CAPTCHA.
**Paramètres :**
| Paramètre | Défaut | Contexte | Multiple | Description |
| -------------------------- | ------------------------------------------------------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `USE_ANTIBOT` | `no` | multisite | non | **Activer Antibot :** définir sur `captcha` pour activer ce mécanisme. |
| `ANTIBOT_CAPTCHA_ALPHABET` | `abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ` | multisite | non | **Alphabet du Captcha :** une chaîne de caractères à utiliser pour générer le CAPTCHA. Caractères pris en charge : toutes les lettres (a-z, A-Z), les chiffres 2-9 (exclut 0 et 1), et les caractères spéciaux : ```+-/=%"'&_(),.;:?!§`^ÄÖÜßäöüé''‚""„``` |
Reportez‑vous aux [Paramètres communs](#paramètres-communs) pour les options supplémentaires.
=== "reCAPTCHA"
reCAPTCHA de Google propose une validation des utilisateurs qui s’exécute en arrière‑plan (v3) pour attribuer un score basé sur le comportement. Un score inférieur au seuil configuré déclenchera une vérification supplémentaire ou bloquera la requête. Pour les défis visibles (v2), les utilisateurs doivent interagir avec le widget reCAPTCHA avant de continuer.
Il existe désormais deux manières d’intégrer reCAPTCHA :
- La version classique (clés site/secret, point de terminaison de vérification v2/v3)
- La nouvelle version utilisant Google Cloud (ID de projet + clé API). La version classique reste disponible et peut être activée avec `ANTIBOT_RECAPTCHA_CLASSIC`.
Pour la version classique, obtenez vos clés de site et secrète depuis la [console d’administration de Google reCAPTCHA](https://www.google.com/recaptcha/admin).
Pour la nouvelle version, créez une clé reCAPTCHA dans votre projet Google Cloud et utilisez l’ID du projet ainsi qu’une clé API (voir la [console reCAPTCHA de Google Cloud](https://console.cloud.google.com/security/recaptcha)). Une clé de site est toujours requise.
**Paramètres :**
| Paramètre | Défaut | Contexte | Multiple | Description |
| ------------------------------ | ------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `USE_ANTIBOT` | `no` | multisite | non | Activer Antibot : définir sur `recaptcha` pour activer ce mécanisme. |
| `ANTIBOT_RECAPTCHA_CLASSIC` | `yes` | multisite | non | Utiliser reCAPTCHA classique. Mettre à `no` pour utiliser la nouvelle version basée sur Google Cloud. |
| `ANTIBOT_RECAPTCHA_SITEKEY` | | multisite | non | Clé de site reCAPTCHA. Requise pour les deux versions. |
| `ANTIBOT_RECAPTCHA_SECRET` | | multisite | non | Clé secrète reCAPTCHA. Requise pour la version classique uniquement. |
| `ANTIBOT_RECAPTCHA_PROJECT_ID` | | multisite | non | ID de projet Google Cloud. Requis pour la nouvelle version uniquement. |
| `ANTIBOT_RECAPTCHA_API_KEY` | | multisite | non | Clé API Google Cloud utilisée pour appeler l’API reCAPTCHA Enterprise. Requise pour la nouvelle version uniquement. |
| `ANTIBOT_RECAPTCHA_JA3` | | multisite | non | Empreinte TLS JA3 optionnelle à inclure dans les évaluations Enterprise. |
| `ANTIBOT_RECAPTCHA_JA4` | | multisite | non | Empreinte TLS JA4 optionnelle à inclure dans les évaluations Enterprise. |
| `ANTIBOT_RECAPTCHA_SCORE` | `0.7` | multisite | non | Score minimum requis pour passer (s’applique à la v3 classique et à la nouvelle version). |
Reportez‑vous aux [Paramètres communs](#paramètres-communs) pour les options supplémentaires.
=== "hCaptcha"
Lorsqu’il est activé, hCaptcha offre une alternative efficace à reCAPTCHA en vérifiant les interactions des utilisateurs sans reposer sur un mécanisme de score. Il met les utilisateurs au défi avec un test simple et interactif pour confirmer leur légitimité.
Pour intégrer hCaptcha avec BunkerWeb, vous devez obtenir les informations d’identification nécessaires depuis le tableau de bord hCaptcha sur [hCaptcha](https://www.hcaptcha.com). Ces informations incluent une clé de site et une clé secrète.
**Paramètres :**
| Paramètre | Défaut | Contexte | Multiple | Description |
| -------------------------- | ------ | --------- | -------- | ------------------------------------------------------------------- |
| `USE_ANTIBOT` | `no` | multisite | non | Activer Antibot : définir sur `hcaptcha` pour activer ce mécanisme. |
| `ANTIBOT_HCAPTCHA_SITEKEY` | | multisite | non | Clé site hCaptcha. |
| `ANTIBOT_HCAPTCHA_SECRET` | | multisite | non | Clé secrète hCaptcha. |
Reportez‑vous aux [Paramètres communs](#paramètres-communs) pour les options supplémentaires.
=== "Turnstile"
Turnstile est un mécanisme de défi moderne et respectueux de la vie privée qui s’appuie sur la technologie de Cloudflare pour détecter et bloquer le trafic automatisé. Il valide les interactions des utilisateurs de manière transparente et en arrière-plan, réduisant les frictions pour les utilisateurs légitimes tout en décourageant efficacement les bots.
Pour intégrer Turnstile avec BunkerWeb, assurez-vous d’obtenir les informations d’identification nécessaires depuis [Cloudflare Turnstile](https://www.cloudflare.com/turnstile).
**Paramètres :**
| Paramètre | Défaut | Contexte | Multiple | Description |
| --------------------------- | ------ | --------- | -------- | -------------------------------------------------------------------- |
| `USE_ANTIBOT` | `no` | multisite | non | Activer Antibot : définir sur `turnstile` pour activer ce mécanisme. |
| `ANTIBOT_TURNSTILE_SITEKEY` | | multisite | non | Clé site Turnstile (Cloudflare). |
| `ANTIBOT_TURNSTILE_SECRET` | | multisite | non | Clé secrète Turnstile (Cloudflare). |
Reportez‑vous aux [Paramètres communs](#paramètres-communs) pour les options supplémentaires.
=== "mCaptcha"
mCaptcha est un mécanisme de défi CAPTCHA alternatif qui vérifie la légitimité des utilisateurs en présentant un test interactif similaire à d’autres solutions antibot. Lorsqu’il est activé, il met les utilisateurs au défi avec un CAPTCHA fourni par mCaptcha, s’assurant que seuls les utilisateurs authentiques contournent les contrôles de sécurité automatisés.
mCaptcha est conçu dans le respect de la vie privée. Il est entièrement conforme au RGPD, garantissant que toutes les données des utilisateurs impliquées dans le processus de défi respectent des normes strictes de protection des données. De plus, mCaptcha offre la flexibilité d’être auto-hébergé, permettant aux organisations de garder un contrôle total sur leurs données et leur infrastructure. Cette capacité d’auto-hébergement améliore non seulement la confidentialité, mais optimise également les performances et la personnalisation pour répondre aux besoins spécifiques de déploiement.
Pour intégrer mCaptcha avec BunkerWeb, vous devez obtenir les informations d’identification nécessaires depuis la plateforme [mCaptcha](https://mcaptcha.org/) ou votre propre fournisseur. Ces informations incluent une clé de site et une clé secrète pour la vérification.
**Paramètres :**
| Paramètre | Défaut | Contexte | Multiple | Description |
| -------------------------- | --------------------------- | --------- | -------- | ------------------------------------------------------------------- |
| `USE_ANTIBOT` | `no` | multisite | non | Activer Antibot : définir sur `mcaptcha` pour activer ce mécanisme. |
| `ANTIBOT_MCAPTCHA_SITEKEY` | | multisite | non | Clé site mCaptcha. |
| `ANTIBOT_MCAPTCHA_SECRET` | | multisite | non | Clé secrète mCaptcha. |
| `ANTIBOT_MCAPTCHA_URL` | `https://demo.mcaptcha.org` | multisite | non | Domaine à utiliser pour mCaptcha. |
Reportez‑vous aux [Paramètres communs](#paramètres-communs) pour les options supplémentaires.
=== "Cap.js"
[Cap.js](https://capjs.js.org/) est un CAPTCHA de preuve de travail auto-hébergé, open source et respectueux de la vie privée. Au lieu de déléguer la vérification à un service tiers, vous exécutez vous-même le serveur Cap.js et BunkerWeb vérifie les jetons auprès de ce serveur.
Utilisez l’URL frontend pour le point d’accès visible depuis le navigateur qui sert le widget. Si BunkerWeb peut joindre le serveur Cap.js via une adresse interne, définissez l’URL backend sur ce point d’accès interne ; sinon, laissez-la vide et BunkerWeb utilisera l’URL frontend pour `/siteverify`.
**Paramètres :**
| Paramètre | Défaut | Contexte | Multiple | Description |
| ---------------------------- | ------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `USE_ANTIBOT` | `no` | multisite | non | Activer Antibot : définir sur `capjs` pour activer ce mécanisme. |
| `ANTIBOT_CAPJS_FRONTEND_URL` | | multisite | non | URL accessible depuis le navigateur du serveur Cap.js qui sert le widget. |
| `ANTIBOT_CAPJS_BACKEND_URL` | | multisite | non | URL interne optionnelle que BunkerWeb utilise pour `/siteverify` ; si elle est vide, l’URL frontend est utilisée. |
| `ANTIBOT_CAPJS_SITEKEY` | | multisite | non | Clé site Cap.js. |
| `ANTIBOT_CAPJS_SECRET` | | multisite | non | Clé secrète Cap.js utilisée par BunkerWeb pour vérifier les jetons. |
!!! note "Exigences d’exploitation"
- Utilisez HTTPS pour `ANTIBOT_CAPJS_FRONTEND_URL` en production. Le worker du navigateur exige `crypto.subtle` dans un contexte sécurisé, et HTTPS empêche les modifications MITM du widget.
- Configurez CORS sur la clé de site Cap.js pour autoriser l’origine protégée.
- Définissez `ANTIBOT_CAPJS_FRONTEND_URL` et `ANTIBOT_CAPJS_BACKEND_URL` uniquement sur des origines : schéma, hôte et port optionnel, sans chemin.
- Utilisez le widget Cap.js **0.1.48 ou ultérieur**. BunkerWeb diffuse une CSP stricte basée sur un nonce ; les widgets antérieurs cassent les défis d’instrumentation parce que le `<script>` inline injecté dans l’iframe `srcdoc` isolée ne propage pas le nonce. Si vous auto-hébergez `tiago2/cap`, épinglez une version récente (par ex. `tiago2/cap:3.1.2` ou plus récente) ou définissez `WIDGET_VERSION` à `0.1.48` ou plus.
Reportez‑vous aux [Paramètres communs](#paramètres-communs) pour les options supplémentaires.
Exemples de configuration
=== "Défi Cookie"
```yaml
USE_ANTIBOT: "cookie"
ANTIBOT_URI: "/challenge"
ANTIBOT_TIME_RESOLVE: "60"
ANTIBOT_TIME_VALID: "86400"
```
=== "Défi JavaScript"
```yaml
USE_ANTIBOT: "javascript"
ANTIBOT_URI: "/challenge"
ANTIBOT_TIME_RESOLVE: "60"
ANTIBOT_TIME_VALID: "86400"
```
=== "Défi Captcha"
```yaml
USE_ANTIBOT: "captcha"
ANTIBOT_URI: "/challenge"
ANTIBOT_TIME_RESOLVE: "60"
ANTIBOT_TIME_VALID: "86400"
ANTIBOT_CAPTCHA_ALPHABET: "23456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
```
Remarque : l’exemple ci‑dessus utilise les chiffres 2‑9 et toutes les lettres, fréquemment utilisés pour les CAPTCHA. Vous pouvez personnaliser l’alphabet pour inclure des caractères spéciaux si nécessaire.
=== "Défi reCAPTCHA Classique"
Exemple de configuration pour le reCAPTCHA classique (clés site/secret) :
```yaml
USE_ANTIBOT: "recaptcha"
ANTIBOT_RECAPTCHA_CLASSIC: "yes"
ANTIBOT_RECAPTCHA_SITEKEY: "your-site-key"
ANTIBOT_RECAPTCHA_SECRET: "your-secret-key"
ANTIBOT_RECAPTCHA_SCORE: "0.7"
ANTIBOT_URI: "/challenge"
ANTIBOT_TIME_RESOLVE: "60"
ANTIBOT_TIME_VALID: "86400"
```
=== "Défi reCAPTCHA (nouveau)"
Exemple de configuration pour le nouveau reCAPTCHA basé sur Google Cloud (ID de projet + clé API) :
```yaml
USE_ANTIBOT: "recaptcha"
ANTIBOT_RECAPTCHA_CLASSIC: "no"
ANTIBOT_RECAPTCHA_SITEKEY: "your-site-key"
ANTIBOT_RECAPTCHA_PROJECT_ID: "your-gcp-project-id"
ANTIBOT_RECAPTCHA_API_KEY: "your-gcp-api-key"
# Empreintes optionnelles pour améliorer les évaluations Enterprise
# ANTIBOT_RECAPTCHA_JA3: "<empreinte-ja3>"
# ANTIBOT_RECAPTCHA_JA4: "<empreinte-ja4>"
ANTIBOT_RECAPTCHA_SCORE: "0.7"
ANTIBOT_URI: "/challenge"
ANTIBOT_TIME_RESOLVE: "60"
ANTIBOT_TIME_VALID: "86400"
```
=== "Défi hCaptcha"
```yaml
USE_ANTIBOT: "hcaptcha"
ANTIBOT_HCAPTCHA_SITEKEY: "your-site-key"
ANTIBOT_HCAPTCHA_SECRET: "your-secret-key"
ANTIBOT_URI: "/challenge"
ANTIBOT_TIME_RESOLVE: "60"
ANTIBOT_TIME_VALID: "86400"
```
=== "Défi Turnstile"
```yaml
USE_ANTIBOT: "turnstile"
ANTIBOT_TURNSTILE_SITEKEY: "your-site-key"
ANTIBOT_TURNSTILE_SECRET: "your-secret-key"
ANTIBOT_URI: "/challenge"
ANTIBOT_TIME_RESOLVE: "60"
ANTIBOT_TIME_VALID: "86400"
```
=== "Défi mCaptcha"
```yaml
USE_ANTIBOT: "mcaptcha"
ANTIBOT_MCAPTCHA_SITEKEY: "your-site-key"
ANTIBOT_MCAPTCHA_SECRET: "your-secret-key"
ANTIBOT_MCAPTCHA_URL: "https://demo.mcaptcha.org"
ANTIBOT_URI: "/challenge"
ANTIBOT_TIME_RESOLVE: "60"
ANTIBOT_TIME_VALID: "86400"
```
=== "Défi Cap.js"
```yaml
USE_ANTIBOT: "capjs"
ANTIBOT_CAPJS_FRONTEND_URL: "https://cap.example.com"
ANTIBOT_CAPJS_BACKEND_URL: "http://cap-server:3000"
ANTIBOT_CAPJS_SITEKEY: "your-site-key"
ANTIBOT_CAPJS_SECRET: "your-secret-key"
ANTIBOT_URI: "/challenge"
ANTIBOT_TIME_RESOLVE: "60"
ANTIBOT_TIME_VALID: "86400"
```
Auth basic
Prise en charge STREAM ❌
Le plugin Auth Basic fournit une authentification HTTP Basic pour protéger votre site ou certaines ressources. Les utilisateurs doivent saisir un identifiant et un mot de passe avant d’accéder au contenu protégé. Simple à mettre en place et largement supporté par les navigateurs.
Comment ça marche :
- Sur une zone protégée, le serveur envoie un défi d’authentification.
- Le navigateur affiche une boîte de connexion.
- L’utilisateur saisit ses identifiants, envoyés au serveur.
- Si les identifiants sont valides, l’accès au contenu demandé est accordé.
- Si les identifiants sont invalides, une erreur 401 Unauthorized est renvoyée.
Comment l’utiliser
- Activer : mettez le paramètre
USE_AUTH_BASICàyes. - Portée : configurez le paramètre
AUTH_BASIC_LOCATIONavecsitewide(tout le site) ou un chemin (ex./admin). - Identifiants : configurez les paramètres
AUTH_BASIC_USERetAUTH_BASIC_PASSWORD(plusieurs paires possibles). - Message : optionnel, ajustez
AUTH_BASIC_TEXT.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_AUTH_BASIC |
no |
multisite | non | Activer l’authentification Basic. |
AUTH_BASIC_LOCATION |
sitewide |
multisite | non | Portée : sitewide ou un chemin (ex. /admin). Vous pouvez également utiliser des modificateurs de style Nginx (=, ~, ~*, ^~). |
AUTH_BASIC_USER |
changeme |
multisite | oui | Nom d’utilisateur. Plusieurs paires peuvent être définies. |
AUTH_BASIC_PASSWORD |
changeme |
multisite | oui | Mot de passe. Les mots de passe sont hachés avec scrypt pour une sécurité maximale. |
AUTH_BASIC_TEXT |
Restricted area |
multisite | non | Message affiché dans l'invite d'authentification. |
!!! warning "Sécurité" Les identifiants sont encodés Base64, pas chiffrés. Utilisez toujours HTTPS avec l’authentification Basic.
!!! tip "Plusieurs comptes"
Vous pouvez configurer plusieurs paires identifiant/mot de passe pour l'accès. Chaque paramètre AUTH_BASIC_USER doit avoir un paramètre AUTH_BASIC_PASSWORD correspondant.
Exemples
=== "Tout le site"
```yaml
USE_AUTH_BASIC: "yes"
AUTH_BASIC_LOCATION: "sitewide"
AUTH_BASIC_USER: "admin"
AUTH_BASIC_PASSWORD: "secure_password"
AUTH_BASIC_TEXT: "Admin Access Only"
```
=== "Zone spécifique"
```yaml
USE_AUTH_BASIC: "yes"
AUTH_BASIC_LOCATION: "/admin/"
AUTH_BASIC_USER: "admin"
AUTH_BASIC_PASSWORD: "secure_password"
AUTH_BASIC_TEXT: "Admin Access Only"
```
=== "Utilisateurs multiples"
```yaml
USE_AUTH_BASIC: "yes"
AUTH_BASIC_LOCATION: "sitewide"
AUTH_BASIC_TEXT: "Staff Area"
# Premier utilisateur
AUTH_BASIC_USER: "admin"
AUTH_BASIC_PASSWORD: "admin_password"
# Deuxième utilisateur
AUTH_BASIC_USER_2: "editor"
AUTH_BASIC_PASSWORD_2: "editor_password"
# Troisième utilisateur
AUTH_BASIC_USER_3: "viewer"
AUTH_BASIC_PASSWORD_3: "viewer_password"
```
Backup
Prise en charge STREAM ✅
Le plugin Backup fournit une solution de sauvegarde automatisée pour protéger vos données BunkerWeb. Cette fonctionnalité assure la sécurité et la disponibilité de votre base de données importante en créant des sauvegardes régulières selon la planification choisie. Les sauvegardes sont stockées dans un emplacement dédié et peuvent être gérées facilement par des processus automatisés comme par des commandes manuelles.
Comment ça marche :
- Votre base de données est sauvegardée automatiquement selon la planification définie (quotidienne, hebdomadaire ou mensuelle).
- Les sauvegardes sont stockées dans un répertoire précis de votre système.
- Les anciennes sauvegardes sont automatiquement supprimées selon vos paramètres de rétention.
- Vous pouvez créer des sauvegardes, lister les sauvegardes existantes ou restaurer une sauvegarde manuellement à tout moment.
- Avant toute opération de restauration, l'état actuel est automatiquement sauvegardé par sécurité.
Comment l'utiliser
Suivez ces étapes pour configurer et utiliser la fonctionnalité Backup :
- Activer la fonctionnalité : La sauvegarde est activée par défaut. Si nécessaire, vous pouvez la contrôler avec le paramètre
USE_BACKUP. - Configurer la planification : Choisissez la fréquence des sauvegardes avec le paramètre
BACKUP_SCHEDULE. - Définir la politique de rétention : Indiquez le nombre de sauvegardes à conserver avec le paramètre
BACKUP_ROTATION. - Définir l'emplacement de stockage : Choisissez où les sauvegardes seront stockées avec le paramètre
BACKUP_DIRECTORY. - Utiliser les commandes CLI : Gérez les sauvegardes manuellement avec les commandes
bwcli plugin backuplorsque c'est nécessaire.
Paramètres de configuration
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_BACKUP |
yes |
global | non | Activer Backup : Mettre à yes pour activer les sauvegardes automatiques. |
BACKUP_SCHEDULE |
daily |
global | non | Fréquence de sauvegarde : Fréquence d'exécution des sauvegardes. Options : daily, weekly ou monthly. |
BACKUP_ROTATION |
7 |
global | non | Rétention des sauvegardes : Nombre de fichiers de sauvegarde à conserver. Les sauvegardes plus anciennes seront supprimées. |
BACKUP_DIRECTORY |
/var/lib/bunkerweb/backups |
global | non | Emplacement des sauvegardes : Répertoire dans lequel les fichiers de sauvegarde seront stockés. |
Interface en ligne de commande
Le plugin Backup fournit plusieurs commandes CLI pour gérer vos sauvegardes :
# Lister toutes les sauvegardes disponibles
bwcli plugin backup list
# Créer une sauvegarde manuelle
bwcli plugin backup save
# Créer une sauvegarde dans un emplacement personnalisé
bwcli plugin backup save --directory /path/to/custom/location
# Restaurer depuis la sauvegarde la plus récente
bwcli plugin backup restore
# Restaurer depuis un fichier de sauvegarde précis
bwcli plugin backup restore /path/to/backup/backup-sqlite-2023-08-15_12-34-56.zip
!!! tip "Priorité à la sécurité" Avant toute opération de restauration, le plugin Backup crée automatiquement une sauvegarde de l'état actuel de votre base de données dans un emplacement temporaire. Cela fournit une protection supplémentaire si vous devez annuler la restauration.
!!! warning "Compatibilité des bases de données" Le plugin Backup prend en charge les bases SQLite, MySQL/MariaDB et PostgreSQL. Les bases Oracle ne sont pas prises en charge actuellement pour les opérations de sauvegarde et de restauration.
Exemples de configuration
=== "Sauvegardes quotidiennes avec rétention de 7 jours"
Configuration par défaut qui crée des sauvegardes quotidiennes et conserve les 7 fichiers les plus récents :
```yaml
USE_BACKUP: "yes"
BACKUP_SCHEDULE: "daily"
BACKUP_ROTATION: "7"
BACKUP_DIRECTORY: "/var/lib/bunkerweb/backups"
```
=== "Sauvegardes hebdomadaires avec rétention étendue"
Configuration pour des sauvegardes moins fréquentes avec une rétention plus longue :
```yaml
USE_BACKUP: "yes"
BACKUP_SCHEDULE: "weekly"
BACKUP_ROTATION: "12"
BACKUP_DIRECTORY: "/var/lib/bunkerweb/backups"
```
=== "Sauvegardes mensuelles vers un emplacement personnalisé"
Configuration pour des sauvegardes mensuelles stockées dans un emplacement personnalisé :
```yaml
USE_BACKUP: "yes"
BACKUP_SCHEDULE: "monthly"
BACKUP_ROTATION: "24"
BACKUP_DIRECTORY: "/mnt/backup-drive/bunkerweb-backups"
```
Backup S3 (PRO)
Prise en charge STREAM ✅
Automatically backup your data to an S3 bucket
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_BACKUP_S3 |
no |
global | non | Enable or disable the S3 backup feature |
BACKUP_S3_SCHEDULE |
daily |
global | non | The frequency of the backup |
BACKUP_S3_ROTATION |
7 |
global | non | The number of backups to keep |
BACKUP_S3_ENDPOINT |
global | non | The S3 endpoint | |
BACKUP_S3_BUCKET |
global | non | The S3 bucket | |
BACKUP_S3_DIR |
global | non | The S3 directory | |
BACKUP_S3_REGION |
global | non | The S3 region | |
BACKUP_S3_ACCESS_KEY_ID |
global | non | The S3 access key ID | |
BACKUP_S3_ACCESS_KEY_SECRET |
global | non | The S3 access key secret | |
BACKUP_S3_COMP_LEVEL |
6 |
global | non | The compression level of the backup zip file |
Bad behavior
Prise en charge STREAM ✅
Le plugin Bad Behavior protège votre site en détectant et bannissant automatiquement les IP qui génèrent trop d’erreurs (codes HTTP « mauvais ») sur une période donnée. Utile contre la force brute, les scrapers, scanners et activités malveillantes.
Les attaquants déclenchent fréquemment des codes « suspects » lors de sondes ou d’exploitation — bien plus qu’un utilisateur normal sur une même période. En détectant ce comportement, BunkerWeb bannit l’IP fautive.
Comment ça marche :
- Le plugin surveille les réponses HTTP.
- À chaque code « mauvais » (400, 401, 403, 404, …), le compteur de l’IP augmente.
- Au‑delà du seuil et dans la fenêtre configurée, l’IP est bannie.
- Le bannissement peut être au niveau service (site) ou global (tous les sites).
- Les bans expirent après la durée configurée (ou sont permanents avec
0).
!!! success "Avantages clés"
1. **Protection automatique :** détecte et bloque les clients potentiellement malveillants sans intervention manuelle.
2. **Règles personnalisables :** adaptez ce qui constitue un « mauvais comportement » à vos besoins.
3. **Économie de ressources :** empêche les acteurs malveillants de consommer les ressources serveur avec des requêtes invalides répétées.
4. **Portée flexible :** choisissez si les bans s’appliquent seulement au service courant ou globalement à tous les services.
5. **Contrôle de durée :** configurez des bans temporaires qui expirent automatiquement ou des bans permanents jusqu’à suppression manuelle.
Comment l’utiliser
- Activation :
USE_BAD_BEHAVIOR(activé par défaut). - Codes à compter :
BAD_BEHAVIOR_STATUS_CODES. - Seuil :
BAD_BEHAVIOR_THRESHOLD. - Fenêtre et durée de ban :
BAD_BEHAVIOR_COUNT_TIME,BAD_BEHAVIOR_BAN_TIME. - Portée :
BAD_BEHAVIOR_BAN_SCOPE(serviceouglobal). Quand le trafic arrive sur le serveur par défaut (nom de serveur_), les bans sont toujours appliqués globalement pour bloquer l’IP partout.
!!! tip "Mode stream"
En mode stream, seul 444 est considéré comme « mauvais ».
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_BAD_BEHAVIOR |
yes |
multisite | non | Activer la détection et le bannissement. |
BAD_BEHAVIOR_STATUS_CODES |
400 401 403 404 405 429 444 |
multisite | non | Codes HTTP considérés « mauvais ». |
BAD_BEHAVIOR_THRESHOLD |
10 |
multisite | non | Seuil de réponses « mauvaises » avant bannissement. |
BAD_BEHAVIOR_COUNT_TIME |
60 |
multisite | non | Fenêtre de comptage (secondes). |
BAD_BEHAVIOR_BAN_TIME |
86400 |
multisite | non | Durée du ban en secondes (0 = permanent). |
BAD_BEHAVIOR_BAN_SCOPE |
service |
global | non | Portée du ban : site courant (service) ou global (global). Sur le serveur par défaut (_), les bans sont toujours globaux. |
!!! warning "Faux positifs" Un seuil/fenêtre trop bas peut bannir des utilisateurs légitimes. Démarrez conservateur et ajustez.
!!! tip "Ajuster votre configuration" Commencez avec des paramètres prudents (seuil plus élevé, durée de ban plus courte), puis adaptez-les selon vos besoins et vos modèles de trafic. Surveillez vos journaux pour vérifier que les utilisateurs légitimes ne sont pas bannis par erreur.
Exemples
=== "Défaut"
```yaml
USE_BAD_BEHAVIOR: "yes"
BAD_BEHAVIOR_STATUS_CODES: "400 401 403 404 405 429 444"
BAD_BEHAVIOR_THRESHOLD: "10"
BAD_BEHAVIOR_COUNT_TIME: "60"
BAD_BEHAVIOR_BAN_TIME: "86400"
BAD_BEHAVIOR_BAN_SCOPE: "service"
```
=== "Strict"
```yaml
USE_BAD_BEHAVIOR: "yes"
BAD_BEHAVIOR_STATUS_CODES: "400 401 403 404 405 429 444 500 502 503"
BAD_BEHAVIOR_THRESHOLD: "5"
BAD_BEHAVIOR_COUNT_TIME: "120"
BAD_BEHAVIOR_BAN_TIME: "604800"
BAD_BEHAVIOR_BAN_SCOPE: "global"
```
=== "Tolérant"
```yaml
USE_BAD_BEHAVIOR: "yes"
BAD_BEHAVIOR_STATUS_CODES: "401 403 429"
BAD_BEHAVIOR_THRESHOLD: "20"
BAD_BEHAVIOR_COUNT_TIME: "30"
BAD_BEHAVIOR_BAN_TIME: "3600"
BAD_BEHAVIOR_BAN_SCOPE: "service"
```
=== "Ban permanent"
```yaml
USE_BAD_BEHAVIOR: "yes"
BAD_BEHAVIOR_STATUS_CODES: "400 401 403 404 405 429 444"
BAD_BEHAVIOR_THRESHOLD: "10"
BAD_BEHAVIOR_COUNT_TIME: "60"
BAD_BEHAVIOR_BAN_TIME: "0"
BAD_BEHAVIOR_BAN_SCOPE: "global"
```
Blacklist
Prise en charge STREAM ⚠️
Le plugin Blacklist protège votre site en bloquant l’accès selon divers attributs client. Cette fonctionnalité défend contre les entités malveillantes connues, les scanners et les visiteurs suspects en refusant l’accès en fonction des adresses IP, des réseaux, des entrées DNS inversées (rDNS), des ASN, des user-agents et de motifs d’URI spécifiques.
Comment ça marche :
- Le plugin vérifie les requêtes entrantes par rapport à plusieurs critères de liste noire (adresses IP, réseaux, rDNS, ASN, User-Agent ou motifs d’URI).
- Les listes noires peuvent être spécifiées directement dans votre configuration ou chargées depuis des URL externes.
- Si un visiteur correspond à une règle de la liste noire (et ne correspond à aucune règle d’ignorance), l’accès est refusé.
- Les listes noires sont mises à jour automatiquement à intervalles réguliers à partir des URL configurées.
- Vous pouvez personnaliser précisément quels critères sont vérifiés et ignorés en fonction de vos besoins de sécurité spécifiques.
Comment l’utiliser
Suivez ces étapes pour configurer et utiliser la fonctionnalité Blacklist :
- Activer la fonctionnalité : La fonctionnalité Blacklist est activée par défaut. Si nécessaire, vous pouvez la contrôler avec le paramètre
USE_BLACKLIST. - Configurer les règles de blocage : Définissez quelles IP, quels réseaux, quels motifs rDNS, quels ASN, quels User-Agents ou quelles URI doivent être bloqués.
- Mettre en place des règles d’ignorance : Spécifiez les exceptions qui doivent contourner les vérifications de la liste noire.
- Ajouter des sources externes : Configurez des URL pour télécharger et mettre à jour automatiquement les données de la liste noire.
- Surveiller l’efficacité : Consultez l'interface web pour voir les statistiques sur les requêtes bloquées.
!!! info "Mode stream" En mode stream, seules les vérifications par IP, rDNS et ASN seront effectuées.
Paramètres de configuration
Général
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_BLACKLIST |
yes |
multisite | non | Activer la Blacklist : Mettre à yes pour activer la fonctionnalité de liste noire. |
BLACKLIST_COMMUNITY_LISTS |
ip:danmeuk-tor-exit ua:mitchellkrogza-bad-user-agents |
multisite | non | Listes noires communautaires : Sélectionnez des listes noires pré-configurées et maintenues par la communauté à inclure dans le blocage. |
=== "Listes noires communautaires" Ce que ça fait : Vous permet d’ajouter rapidement des listes noires bien entretenues et sourcées par la communauté sans avoir à configurer manuellement les URL.
Le paramètre `BLACKLIST_COMMUNITY_LISTS` vous permet de choisir parmi des sources de listes noires sélectionnées. Les options disponibles incluent :
| ID | Description | Source |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `ip:danmeuk-tor-exit` | Adresses IP des nœuds de sortie Tor (dan.me.uk) | `https://www.dan.me.uk/torlist/?exit` |
| `ua:mitchellkrogza-bad-user-agents` | Nginx Block Bad Bots, Spam Referrer Blocker, Vulnerability Scanners, User-Agents, Malware, Adware, Ransomware, Malicious Sites, avec anti-DDOS, Wordpress Theme Detector Blocking et Fail2Ban Jail for Repeat Offenders | `https://raw.githubusercontent.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker/master/_generator_lists/bad-user-agents.list` |
| `ip:laurent-minne-data-shield-aggressive` | Data-Shield IPv4 Blocklist - Laurent M. - Pour Web Apps, WordPress, VPS (Apache/Nginx) | `https://raw.githubusercontent.com/duggytuxy/Data-Shield_IPv4_Blocklist/refs/heads/main/prod_data-shield_ipv4_blocklist.txt` |
| `ip:laurent-minne-data-shield-critical` | Data-Shield IPv4 Blocklist - Laurent M. - Pour DMZs, SaaS, API & Actifs Critiques | `https://raw.githubusercontent.com/duggytuxy/Data-Shield_IPv4_Blocklist/refs/heads/main/prod_critical_data-shield_ipv4_blocklist.txt` |
**Configuration :** Spécifiez plusieurs listes séparées par des espaces. Par exemple :
```yaml
BLACKLIST_COMMUNITY_LISTS: "ip:danmeuk-tor-exit ua:mitchellkrogza-bad-user-agents"
```
!!! tip "Listes communautaires vs configuration manuelle"
Les listes noires communautaires offrent un moyen pratique de démarrer avec des sources de listes noires éprouvées. Vous pouvez les utiliser en parallèle de configurations manuelles d’URL pour une flexibilité maximale.
!!! note "Remerciements"
Merci à Laurent Minne d'avoir contribué aux [listes de blocage Data-Shield](https://duggytuxy.github.io/#) !
=== "Adresse IP" Ce que ça fait : Bloque les visiteurs en fonction de leur adresse IP ou de leur réseau.
| Paramètre | Défaut | Contexte | Multiple | Description |
| -------------------------- | ------------------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `BLACKLIST_IP` | | multisite | non | **Liste noire d’IP :** Liste d’adresses IP ou de réseaux (notation CIDR) à bloquer, séparés par des espaces. |
| `BLACKLIST_IGNORE_IP` | | multisite | non | **Liste d’ignorance d’IP :** Liste d’adresses IP ou de réseaux qui doivent contourner les vérifications de la liste noire d’IP. |
| `BLACKLIST_IP_URLS` | `https://www.dan.me.uk/torlist/?exit` | multisite | non | **URL de listes noires d’IP :** Liste d’URL contenant des adresses IP ou des réseaux à bloquer, séparés par des espaces. |
| `BLACKLIST_IGNORE_IP_URLS` | | multisite | non | **URL de listes d’ignorance d’IP :** Liste d’URL contenant des adresses IP ou des réseaux à ignorer. |
Le paramètre par défaut `BLACKLIST_IP_URLS` inclut une URL qui fournit une **liste des nœuds de sortie Tor connus**. C’est une source courante de trafic malveillant et un bon point de départ pour de nombreux sites.
=== "Reverse DNS" Ce que ça fait : Bloque les visiteurs en fonction de leur nom de domaine inversé. C’est utile pour bloquer les scanners et les crawlers connus en se basant sur les domaines de leur organisation.
| Paramètre | Défaut | Contexte | Multiple | Description |
| ---------------------------- | ----------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `BLACKLIST_RDNS` | `.shodan.io .censys.io` | multisite | non | **Liste noire rDNS :** Liste de suffixes de DNS inversé à bloquer, séparés par des espaces. |
| `BLACKLIST_RDNS_GLOBAL` | `yes` | multisite | non | **rDNS global uniquement :** N’effectue des vérifications rDNS que sur les adresses IP globales si mis à `yes`. |
| `BLACKLIST_IGNORE_RDNS` | | multisite | non | **Liste d’ignorance rDNS :** Liste de suffixes de DNS inversé qui doivent contourner les vérifications de la liste noire rDNS. |
| `BLACKLIST_RDNS_URLS` | | multisite | non | **URL de listes noires rDNS :** Liste d’URL contenant des suffixes de DNS inversé à bloquer. |
| `BLACKLIST_IGNORE_RDNS_URLS` | | multisite | non | **URL de listes d’ignorance rDNS :** Liste d’URL contenant des suffixes de DNS inversé à ignorer. |
Le paramètre par défaut `BLACKLIST_RDNS` inclut des domaines de scanners courants comme **Shodan** et **Censys**. Ils sont souvent utilisés par des chercheurs en sécurité et des scanners pour identifier des sites vulnérables.
=== "ASN" Ce que ça fait : Bloque les visiteurs provenant de fournisseurs de réseaux spécifiques. Les ASN sont comme des codes postaux pour Internet—ils identifient à quel fournisseur ou organisation une IP appartient.
| Paramètre | Défaut | Contexte | Multiple | Description |
| --------------------------- | ------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `BLACKLIST_ASN` | | multisite | non | **Liste noire d’ASN :** Liste de numéros de systèmes autonomes à bloquer, séparés par des espaces. |
| `BLACKLIST_IGNORE_ASN` | | multisite | non | **Liste d’ignorance d’ASN :** Liste d’ASN qui doivent contourner les vérifications de la liste noire d’ASN. |
| `BLACKLIST_ASN_URLS` | | multisite | non | **URL de listes noires d’ASN :** Liste d’URL contenant des ASN à bloquer. |
| `BLACKLIST_IGNORE_ASN_URLS` | | multisite | non | **URL de listes d’ignorance d’ASN :** Liste d’URL contenant des ASN à ignorer. |
=== "User-Agent" Ce que ça fait : Bloque les visiteurs en fonction du navigateur ou de l’outil qu’ils prétendent utiliser. C’est efficace contre les bots qui s’identifient honnêtement (comme "ScannerBot" ou "WebHarvestTool").
| Paramètre | Défaut | Contexte | Multiple | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `BLACKLIST_USER_AGENT` | | multisite | non | **Liste noire de User-Agent :** Liste de motifs de User-Agent (regex PCRE) à bloquer, séparés par des espaces. |
| `BLACKLIST_IGNORE_USER_AGENT` | | multisite | non | **Liste d’ignorance de User-Agent :** Liste de motifs de User-Agent qui doivent contourner les vérifications de la liste noire de User-Agent. |
| `BLACKLIST_USER_AGENT_URLS` | `https://raw.githubusercontent.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker/master/_generator_lists/bad-user-agents.list` | multisite | non | **URL de listes noires de User-Agent :** Liste d’URL contenant des motifs de User-Agent à bloquer. |
| `BLACKLIST_IGNORE_USER_AGENT_URLS` | | multisite | non | **URL de listes d’ignorance de User-Agent :** Liste d’URL contenant des motifs de User-Agent à ignorer. |
Le paramètre par défaut `BLACKLIST_USER_AGENT_URLS` inclut une URL qui fournit une **liste de user agents malveillants connus**. Ils sont souvent utilisés par des bots et des scanners malveillants pour identifier des sites vulnérables.
=== "URI" Ce que ça fait : Bloque les requêtes vers des URL spécifiques de votre site. C’est utile pour bloquer les tentatives d’accès aux pages d’administration, aux formulaires de connexion ou à d’autres zones sensibles qui pourraient être ciblées.
| Paramètre | Défaut | Contexte | Multiple | Description |
| --------------------------- | ------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `BLACKLIST_URI` | | multisite | non | **Liste noire d’URI :** Liste de motifs d’URI (regex PCRE) à bloquer, séparés par des espaces. |
| `BLACKLIST_IGNORE_URI` | | multisite | non | **Liste d’ignorance d’URI :** Liste de motifs d’URI qui doivent contourner les vérifications de la liste noire d’URI. |
| `BLACKLIST_URI_URLS` | | multisite | non | **URL de listes noires d’URI :** Liste d’URL contenant des motifs d’URI à bloquer. |
| `BLACKLIST_IGNORE_URI_URLS` | | multisite | non | **URL de listes d’ignorance d’URI :** Liste d’URL contenant des motifs d’URI à ignorer. |
!!! info "Support des formats d’URL"
Tous les paramètres *_URLS supportent les URL HTTP/HTTPS ainsi que les chemins de fichiers locaux en utilisant le préfixe file:///. L’authentification basique est supportée en utilisant le format http://user:pass@url.
!!! tip "Mises à jour régulières" Les listes noires provenant d’URL sont automatiquement téléchargées et mises à jour toutes les heures pour garantir que votre protection reste à jour contre les dernières menaces.
Exemples de configuration
=== "Protection de base par IP et User-Agent"
Une configuration simple qui bloque les nœuds de sortie Tor connus et les user agents malveillants courants en utilisant les listes noires communautaires :
```yaml
USE_BLACKLIST: "yes"
BLACKLIST_COMMUNITY_LISTS: "ip:danmeuk-tor-exit ua:mitchellkrogza-bad-user-agents"
```
Alternativement, vous pouvez utiliser une configuration manuelle par URL :
```yaml
USE_BLACKLIST: "yes"
BLACKLIST_IP_URLS: "https://www.dan.me.uk/torlist/?exit"
BLACKLIST_USER_AGENT_URLS: "https://raw.githubusercontent.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker/master/_generator_lists/bad-user-agents.list"
```
=== "Protection avancée avec des règles personnalisées"
Une configuration plus complète avec des entrées de liste noire personnalisées et des exceptions :
```yaml
USE_BLACKLIST: "yes"
# Entrées de liste noire personnalisées
BLACKLIST_IP: "192.168.1.100 203.0.113.0/24"
BLACKLIST_RDNS: ".shodan.io .censys.io .scanner.com"
BLACKLIST_ASN: "16509 14618" # ASN d'AWS et d'Amazon
BLACKLIST_USER_AGENT: "(?:\b)SemrushBot(?:\b) (?:\b)AhrefsBot(?:\b)"
BLACKLIST_URI: "^/wp-login\.php$ ^/administrator/"
# Règles d'ignorance personnalisées
BLACKLIST_IGNORE_IP: "192.168.1.200 203.0.113.42"
# Sources de listes noires externes
BLACKLIST_IP_URLS: "https://www.dan.me.uk/torlist/?exit https://www.spamhaus.org/drop/drop.txt"
BLACKLIST_USER_AGENT_URLS: "https://raw.githubusercontent.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker/master/_generator_lists/bad-user-agents.list"
```
=== "Utilisation de fichiers locaux"
Configuration utilisant des fichiers locaux pour les listes noires :
```yaml
USE_BLACKLIST: "yes"
BLACKLIST_IP_URLS: "file:///chemin/vers/ip-blacklist.txt"
BLACKLIST_RDNS_URLS: "file:///chemin/vers/rdns-blacklist.txt"
BLACKLIST_ASN_URLS: "file:///chemin/vers/asn-blacklist.txt"
BLACKLIST_USER_AGENT_URLS: "file:///chemin/vers/user-agent-blacklist.txt"
BLACKLIST_URI_URLS: "file:///chemin/vers/uri-blacklist.txt"
```
Travailler avec des fichiers de listes locaux
Les paramètres *_URLS fournis par les plugins Whitelist, Greylist et Blacklist utilisent le même téléchargeur. Lorsque vous référencez une URL file:/// :
- Le chemin est résolu dans le conteneur du scheduler (dans un déploiement Docker il s’agit généralement de
bunkerweb-scheduler). Montez-y vos fichiers et vérifiez que l’utilisateur scheduler possède un accès en lecture. - Chaque fichier est un texte encodé en UTF-8 avec une entrée par ligne. Les lignes vides sont ignorées et les commentaires doivent commencer par
#ou;. Les commentaires//ne sont pas pris en charge. - Valeur attendue selon le type de liste :
- Listes IP acceptent des adresses IPv4/IPv6 ou des réseaux CIDR (par exemple
192.0.2.10ou2001:db8::/48). - Listes rDNS attendent un suffixe sans espaces (par exemple
.search.msn.com). Les valeurs sont automatiquement converties en minuscules. - Listes ASN peuvent contenir uniquement le numéro (
32934) ou le numéro préfixé parAS(AS15169). - Listes User-Agent sont traitées comme des motifs PCRE et la ligne complète est conservée (espaces compris). Placez vos commentaires sur une ligne séparée pour éviter qu’ils ne soient interprétés comme motif.
- Listes URI doivent commencer par
/et peuvent utiliser des jetons PCRE tels que^ou$.
- Listes IP acceptent des adresses IPv4/IPv6 ou des réseaux CIDR (par exemple
Exemples de fichiers conformes :
# /etc/bunkerweb/lists/ip-blacklist.txt
192.0.2.10
198.51.100.0/24
# /etc/bunkerweb/lists/ua-blacklist.txt
(?:^|\s)FriendlyScanner(?:\s|$)
TrustedMonitor/\d+\.\d+
Brotli
Prise en charge STREAM ❌
Le plugin Brotli active la compression des réponses HTTP avec l’algorithme Brotli. Il réduit l’usage de bande passante et accélère le chargement en compressant le contenu avant l’envoi au navigateur.
Par rapport à gzip, Brotli atteint généralement de meilleurs taux de compression, pour des fichiers plus petits et une livraison plus rapide.
Comment ça marche :
- À la requête d’un client, BunkerWeb vérifie si le navigateur supporte Brotli.
- Si oui, la réponse est compressée au niveau configuré.
- Les en‑têtes appropriés indiquent la compression Brotli.
- Le navigateur décompresse avant affichage.
- Bande passante et temps de chargement diminuent.
Comment l’utiliser
- Activer : mettez le paramètre
USE_BROTLIàyes(désactivé par défaut). - Types MIME : définir les contenus à compresser via
BROTLI_TYPES. - Taille minimale :
BROTLI_MIN_LENGTHpour éviter de compresser les petites réponses. - Niveau de compression :
BROTLI_COMP_LEVELpour l’équilibre vitesse/ratio. - Laisser BunkerWeb faire le reste : une fois configurée, la compression s’applique automatiquement aux réponses éligibles.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_BROTLI |
no |
multisite | non | Activer la compression Brotli. |
BROTLI_TYPES |
application/atom+xml application/javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-opentype application/x-font-truetype application/x-font-ttf application/x-javascript application/xhtml+xml application/xml font/eot font/opentype font/otf font/truetype image/svg+xml image/vnd.microsoft.icon image/x-icon image/x-win-bitmap text/css text/javascript text/plain text/xml |
multisite | non | Types MIME compressés. |
BROTLI_MIN_LENGTH |
1000 |
multisite | non | Taille minimale (octets) pour appliquer la compression. |
BROTLI_COMP_LEVEL |
6 |
multisite | non | Niveau 0–11 : plus haut = meilleure compression mais plus de CPU. |
!!! tip "Niveau de compression"
6 offre un bon compromis. Pour du statique et CPU disponible : 9–11. Pour du dynamique ou CPU contraint : 4–5.
!!! info "Compatibilité navigateurs" Brotli est pris en charge par tous les navigateurs modernes. Les clients qui ne prennent pas en charge Brotli recevront des réponses non compressées ou un autre encodage disponible.
Exemples
=== "Basique"
```yaml
USE_BROTLI: "yes"
BROTLI_TYPES: "application/javascript application/json application/xml application/xhtml+xml text/css text/html text/javascript text/plain text/xml"
BROTLI_MIN_LENGTH: "1000"
BROTLI_COMP_LEVEL: "6"
```
=== "Compression maximale"
```yaml
USE_BROTLI: "yes"
BROTLI_TYPES: "application/atom+xml application/javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-opentype application/x-font-truetype application/x-font-ttf application/x-javascript application/xhtml+xml application/xml font/eot font/opentype font/otf font/truetype image/svg+xml image/vnd.microsoft.icon image/x-icon image/x-win-bitmap text/css text/javascript text/plain text/xml"
BROTLI_MIN_LENGTH: "500"
BROTLI_COMP_LEVEL: "11"
```
=== "Performance équilibrée"
```yaml
USE_BROTLI: "yes"
BROTLI_TYPES: "application/javascript application/json text/css text/html text/javascript text/plain"
BROTLI_MIN_LENGTH: "1000"
BROTLI_COMP_LEVEL: "4"
```
BunkerNet
Prise en charge STREAM ✅
Le plugin BunkerNet permet le partage collectif de renseignements sur les menaces entre instances BunkerWeb, créant un puissant réseau de protection contre les acteurs malveillants. En participant à BunkerNet, votre instance bénéficie d'une base mondiale de menaces connues et y contribue, ce qui renforce la sécurité de toute la communauté BunkerWeb.
Comment ça marche :
- Votre instance BunkerWeb s'enregistre automatiquement auprès de l'API BunkerNet afin de recevoir un identifiant unique.
- Lorsque votre instance détecte et bloque une adresse IP ou un comportement malveillant, elle signale anonymement la menace à BunkerNet.
- BunkerNet agrège les renseignements sur les menaces provenant de toutes les instances participantes et distribue la base consolidée.
- Votre instance télécharge régulièrement une base mise à jour des menaces connues depuis BunkerNet.
- Cette intelligence collective permet à votre instance de bloquer proactivement des adresses IP ayant eu un comportement malveillant sur d'autres instances BunkerWeb.
!!! success "Avantages clés" 1. Défense collective : Exploitez les détections de sécurité de milliers d'autres instances BunkerWeb dans le monde. 2. Protection proactive : Bloquez les acteurs malveillants avant qu'ils ne ciblent votre site, d'après leur comportement ailleurs. 3. Contribution communautaire : Aidez à protéger les autres utilisateurs BunkerWeb en partageant des données anonymisées sur les attaquants. 4. Zéro configuration : Fonctionne immédiatement avec des valeurs par défaut adaptées et très peu de configuration. 5. Respect de la vie privée : Ne partage que les informations de menace nécessaires, sans compromettre votre confidentialité ni celle de vos utilisateurs.
Comment l'utiliser
Suivez ces étapes pour configurer et utiliser la fonctionnalité BunkerNet :
- Activer la fonctionnalité : La fonctionnalité BunkerNet est activée par défaut. Si nécessaire, vous pouvez la contrôler avec le paramètre
USE_BUNKERNET. - Enregistrement initial : Au premier démarrage, votre instance s'enregistre automatiquement auprès de l'API BunkerNet et reçoit un identifiant unique.
- Mises à jour automatiques : Votre instance télécharge automatiquement la dernière base de menaces selon une planification régulière.
- Signalement automatique : Lorsque votre instance bloque une adresse IP malveillante, elle contribue automatiquement ces données à la communauté.
- Surveiller la protection : Consultez l'interface web pour voir les statistiques des menaces bloquées grâce aux renseignements BunkerNet.
Paramètres de configuration
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_BUNKERNET |
yes |
multisite | non | Activer BunkerNet : Mettre à yes pour activer le partage de renseignements BunkerNet. |
BUNKERNET_SERVER |
https://api.bunkerweb.io |
global | non | Serveur BunkerNet : Adresse du serveur API BunkerNet pour partager les renseignements sur les menaces. |
!!! tip "Protection réseau" Lorsque BunkerNet détecte qu'une adresse IP a été impliquée dans une activité malveillante sur plusieurs instances BunkerWeb, il ajoute cette IP à une blacklist collective. Cela fournit une couche de défense proactive, protégeant votre site contre les menaces avant qu'elles ne vous ciblent directement.
!!! info "Signalement anonyme" Lors du signalement d'informations de menace à BunkerNet, votre instance ne partage que les données nécessaires pour identifier la menace : l'adresse IP, la raison du blocage et un minimum de contexte. Aucune information personnelle sur vos utilisateurs ni aucun détail sensible sur votre site n'est partagé.
Exemples de configuration
=== "Configuration par défaut (recommandée)"
La configuration par défaut active BunkerNet avec le serveur API officiel de BunkerWeb :
```yaml
USE_BUNKERNET: "yes"
BUNKERNET_SERVER: "https://api.bunkerweb.io"
```
=== "Configuration désactivée"
Si vous préférez ne pas participer au réseau de renseignements BunkerNet :
```yaml
USE_BUNKERNET: "no"
```
=== "Configuration avec serveur personnalisé"
Pour les organisations exploitant leur propre serveur BunkerNet (peu courant) :
```yaml
USE_BUNKERNET: "yes"
BUNKERNET_SERVER: "https://bunkernet.example.com"
```
Intégration CrowdSec Console
Si vous ne connaissez pas encore l'intégration CrowdSec Console, CrowdSec utilise le renseignement participatif pour combattre les cybermenaces. Imaginez un "Waze de la cybersécurité" : lorsqu'un serveur est attaqué, d'autres systèmes dans le monde sont alertés et protégés contre les mêmes attaquants. Vous pouvez en savoir plus ici.
Grâce à notre partenariat avec CrowdSec, vous pouvez enrôler vos instances BunkerWeb dans votre CrowdSec Console. Les attaques bloquées par BunkerWeb seront visibles dans votre CrowdSec Console aux côtés des attaques bloquées par les CrowdSec Security Engines, ce qui vous donne une vue unifiée des menaces.
Important : CrowdSec n'a pas besoin d'être installé pour cette intégration, même si nous recommandons fortement de l'essayer avec le plugin CrowdSec pour BunkerWeb afin de renforcer davantage la sécurité de vos services web. Vous pouvez également enrôler vos CrowdSec Security Engines dans le même compte Console pour encore plus de synergie.
Étape n°1 : Créer votre compte CrowdSec Console
Rendez-vous sur la CrowdSec Console et inscrivez-vous si vous n'avez pas encore de compte. Une fois terminé, notez la clé d'enrôlement disponible dans "Security Engines" après avoir cliqué sur "Add Security Engine" :
Étape n°2 : Obtenir votre identifiant BunkerNet
L'activation de la fonctionnalité BunkerNet (activée par défaut) est obligatoire si vous souhaitez enrôler vos instances BunkerWeb dans votre CrowdSec Console. Activez-la en définissant USE_BUNKERNET à yes.
Pour Docker, obtenez votre identifiant BunkerNet avec :
docker exec my-bw-scheduler cat /var/cache/bunkerweb/bunkernet/instance.id
Pour Linux, utilisez :
cat /var/cache/bunkerweb/bunkernet/instance.id
Étape n°3 : Enrôler votre instance avec le Panel
Une fois votre identifiant BunkerNet et votre clé d'enrôlement CrowdSec Console obtenus, commandez le produit gratuit "BunkerNet / CrowdSec" sur le Panel. Vous pourrez être invité à créer un compte si ce n'est pas déjà fait.
Vous pouvez maintenant sélectionner le service "BunkerNet / CrowdSec" et remplir le formulaire en collant votre identifiant BunkerNet et votre clé d'enrôlement CrowdSec Console :
Étape n°4 : Accepter le nouveau security engine dans la Console
Retournez ensuite dans votre CrowdSec Console et acceptez le nouveau Security Engine :
Félicitations, votre instance BunkerWeb est maintenant enrôlée dans votre CrowdSec Console !
Astuce : Lorsque vous consultez vos alertes, cliquez sur l'option "columns" et cochez la case "context" pour accéder aux données spécifiques à BunkerWeb.
Cache (PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ❌
Provides caching functionality at the reverse proxy level.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
CACHE_PATH |
global | oui | Path and parameters for a cache. | |
CACHE_ZONE |
multisite | non | Name of cache zone to use (specified in a CACHE_PATH setting). | |
CACHE_HEADER |
X-Cache |
multisite | non | Add header about cache status. |
CACHE_BACKGROUND_UPDATE |
no |
multisite | non | Enable or disable background update of the cache. |
CACHE_BYPASS |
multisite | non | List of variables to determine if the cache should be bypassed or not. | |
CACHE_NO_CACHE |
$http_pragma$http_authorization |
multisite | non | Disable caching if variables are set. |
CACHE_KEY |
$scheme$proxy_host$request_uri |
multisite | non | Key used to identify cached elements. |
CACHE_CONVERT_HEAD_TO_GET |
yes |
multisite | non | Convert HEAD requests to GET when caching. |
CACHE_LOCK |
no |
multisite | non | Lock concurrent requests when populating the cache. |
CACHE_LOCK_AGE |
5s |
multisite | non | Pass request to upstream if cache is locked for that time (possible cache). |
CACHE_LOCK_TIMEOUT |
5s |
multisite | non | Pass request to upstream if cache is locked for that time (no cache). |
CACHE_METHODS |
GET HEAD |
multisite | non | Only cache response if corresponding method is present. |
CACHE_MIN_USES |
1 |
multisite | non | Number of requests before we put the corresponding response in cache. |
CACHE_REVALIDATE |
no |
multisite | non | Revalidate expired items using conditional requests to upstream. |
CACHE_USE_STALE |
off |
multisite | non | Determines the use of staled cache response (proxy_cache_use_stale directive). |
CACHE_VALID |
10m |
multisite | oui | Defines default caching with optional status code. |
Client cache
Prise en charge STREAM ❌
Le plugin Client Cache optimise les performances en contrôlant la mise en cache des contenus statiques par les navigateurs. Il réduit la bande passante, la charge serveur et accélère les temps de chargement en instruisant les navigateurs à conserver localement images, CSS, JS, etc., plutôt que de les retélécharger à chaque visite.
Comment ça marche :
- Une fois activé, BunkerWeb ajoute des en‑têtes Cache-Control aux réponses des fichiers statiques.
- Ces en‑têtes indiquent aux navigateurs pendant combien de temps conserver localement le contenu.
- Pour les extensions spécifiées (images, CSS, JS…), BunkerWeb applique la politique de cache configurée.
- Les ETags (optionnels) fournissent un mécanisme de validation supplémentaire.
- Lors des visites suivantes, le navigateur réutilise les fichiers en cache, accélérant le chargement.
Comment l’utiliser
- Activer : mettez
USE_CLIENT_CACHEàyes(désactivé par défaut). - Extensions : définissez
CLIENT_CACHE_EXTENSIONSpour les types de fichiers à mettre en cache. - Directives Cache-Control : personnalisez
CLIENT_CACHE_CONTROL. - ETag : activez ou non via
CLIENT_CACHE_ETAG. - Laisser BunkerWeb faire le reste : une fois configuré, les en-têtes de cache sont appliqués automatiquement aux réponses éligibles.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_CLIENT_CACHE |
no |
multisite | non | Activer la mise en cache côté client des fichiers statiques. |
CLIENT_CACHE_EXTENSIONS |
jpg|jpeg|png|bmp|ico|svg|tif|css|js|otf|ttf|eot|woff|woff2 |
global | non | Extensions mises en cache, séparées par des pipes. |
CLIENT_CACHE_CONTROL |
public, max-age=15552000 |
multisite | non | Valeur de l’en‑tête HTTP Cache-Control. |
CLIENT_CACHE_ETAG |
yes |
multisite | non | Envoi d’un ETag pour les ressources statiques. |
!!! tip "Optimiser le cache" Contenu fréquemment mis à jour : durée plus courte. Contenu versionné ou peu changeant : durée plus longue. La valeur par défaut (180 jours) convient souvent.
!!! info "Comportement des navigateurs" Les navigateurs respectent les en-têtes Cache-Control et ETag selon leurs propres règles de cache. Les utilisateurs peuvent toujours forcer un rechargement ou vider leur cache, ce qui déclenche un nouveau téléchargement.
Exemples
=== "Basique"
```yaml
USE_CLIENT_CACHE: "yes"
CLIENT_CACHE_EXTENSIONS: "jpg|jpeg|png|gif|css|js|svg|woff|woff2"
CLIENT_CACHE_CONTROL: "public, max-age=86400"
CLIENT_CACHE_ETAG: "yes"
```
=== "Agressif"
```yaml
USE_CLIENT_CACHE: "yes"
CLIENT_CACHE_EXTENSIONS: "jpg|jpeg|png|bmp|ico|svg|tif|gif|css|js|otf|ttf|eot|woff|woff2|pdf|xml|txt"
CLIENT_CACHE_CONTROL: "public, max-age=31536000, immutable"
CLIENT_CACHE_ETAG: "yes"
```
=== "Mixte"
```yaml
USE_CLIENT_CACHE: "yes"
CLIENT_CACHE_EXTENSIONS: "jpg|jpeg|png|bmp|ico|svg|tif|gif|css|js|otf|ttf|eot|woff|woff2"
CLIENT_CACHE_CONTROL: "public, max-age=604800"
CLIENT_CACHE_ETAG: "yes"
```
CORS
Prise en charge STREAM ❌
Le plugin CORS active le partage de ressources entre origines (Cross‑Origin Resource Sharing) de manière contrôlée. Il permet de partager vos ressources avec des domaines tiers de confiance en définissant précisément origines, méthodes et en‑têtes autorisés.
Comment ça marche :
- Pour une requête cross‑origin, le navigateur envoie d’abord une requête « preflight »
OPTIONS. - BunkerWeb vérifie si l’origine est autorisée.
- Si oui, il renvoie les en‑têtes CORS appropriés décrivant ce qui est permis.
- Sinon, la requête est refusée ou servie sans en‑têtes CORS selon la configuration.
- Des politiques supplémentaires, comme COEP, COOP et CORP, peuvent renforcer la sécurité.
Comment l’utiliser
- Activer : mettez le paramètre
USE_CORSàyes(désactivé par défaut). - Origines :
CORS_ALLOW_ORIGIN(regex PCRE,*tous,selfmême origine). - Méthodes :
CORS_ALLOW_METHODS. - En‑têtes :
CORS_ALLOW_HEADERS. - Identifiants :
CORS_ALLOW_CREDENTIALSpour autoriser cookies/auth.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_CORS |
no |
multisite | non | Activer CORS. |
CORS_ALLOW_ORIGIN |
self |
multisite | non | Origines autorisées (regex PCRE). * = toute origine, self = même origine. |
CORS_ALLOW_METHODS |
GET, POST, OPTIONS |
multisite | non | Méthodes autorisées. |
CORS_ALLOW_HEADERS |
DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range |
multisite | non | En‑têtes autorisés côté requête. |
CORS_ALLOW_CREDENTIALS |
no |
multisite | non | Autoriser les identifiants (cookies, auth HTTP). |
CORS_EXPOSE_HEADERS |
Content-Length,Content-Range |
multisite | non | En‑têtes exposés côté réponse. |
CROSS_ORIGIN_OPENER_POLICY |
same-origin |
multisite | non | Politique COOP. |
CROSS_ORIGIN_EMBEDDER_POLICY |
require-corp |
multisite | non | Politique COEP. |
CROSS_ORIGIN_RESOURCE_POLICY |
same-site |
multisite | non | Politique CORP. |
CORS_MAX_AGE |
86400 |
multisite | non | Durée de cache du preflight (secondes). |
CORS_DENY_REQUEST |
yes |
multisite | non | Refuser les origines non autorisées avec un code d’erreur. |
!!! tip "Optimiser le preflight"
Augmenter CORS_MAX_AGE réduit la fréquence des preflights (par défaut 24h).
!!! warning "Sécurité"
Soyez prudent avec le paramètre CORS_ALLOW_ORIGIN défini à * et/ou le paramètre CORS_ALLOW_CREDENTIALS défini à yes. Préférez lister explicitement les origines de confiance.
Exemples
Voici des exemples de valeurs possibles pour CORS_ALLOW_ORIGIN, avec leur comportement :
*: autorise les requêtes depuis n’importe quelle origine.self: autorise automatiquement les requêtes depuis la même origine que le serveur configuré.^https://www\.example\.com$: autorise uniquement les requêtes depuishttps://www.example.com.^https://.+\.example\.com$: autorise les requêtes depuis n’importe quel sous-domaine deexample.com.^https://(www\.example1\.com|www\.example2\.com)$: autorise les requêtes depuishttps://www.example1.comouhttps://www.example2.com.^https?://www\.example\.com$: autorise les requêtes depuishttp://www.example.comethttps://www.example.com.
=== "Configuration basique"
```yaml
USE_CORS: "yes"
CORS_ALLOW_ORIGIN: "self"
CORS_ALLOW_METHODS: "GET, POST, OPTIONS"
CORS_ALLOW_HEADERS: "Content-Type, Authorization"
CORS_ALLOW_CREDENTIALS: "no"
CORS_DENY_REQUEST: "yes"
```
=== "API publique"
```yaml
USE_CORS: "yes"
CORS_ALLOW_ORIGIN: "*"
CORS_ALLOW_METHODS: "GET, OPTIONS"
CORS_ALLOW_HEADERS: "Content-Type, X-API-Key"
CORS_ALLOW_CREDENTIALS: "no"
CORS_MAX_AGE: "3600"
CORS_DENY_REQUEST: "no"
```
=== "Plusieurs domaines de confiance"
```yaml
USE_CORS: "yes"
CORS_ALLOW_ORIGIN: "^https://(app|api|dashboard)\\.example\\.com$"
CORS_ALLOW_METHODS: "GET, POST, PUT, DELETE, OPTIONS"
CORS_ALLOW_HEADERS: "Content-Type, Authorization, X-Requested-With"
CORS_ALLOW_CREDENTIALS: "yes"
CORS_EXPOSE_HEADERS: "Content-Length, Content-Range, X-RateLimit-Remaining"
CORS_MAX_AGE: "86400"
CORS_DENY_REQUEST: "yes"
```
=== "Wildcard sous‑domaine"
```yaml
USE_CORS: "yes"
CORS_ALLOW_ORIGIN: "^https://.*\\.example\\.com$"
CORS_ALLOW_METHODS: "GET, POST, OPTIONS"
CORS_ALLOW_HEADERS: "Content-Type, Authorization"
CORS_ALLOW_CREDENTIALS: "no"
CORS_MAX_AGE: "86400"
CORS_DENY_REQUEST: "yes"
```
=== "Multiples motifs de domaine"
```yaml
USE_CORS: "yes"
CORS_ALLOW_ORIGIN: "^https://(.*\\.example\\.com|.*\\.trusted-partner\\.org|api\\.third-party\\.net)$"
CORS_ALLOW_METHODS: "GET, POST, PUT, OPTIONS"
CORS_ALLOW_HEADERS: "Content-Type, Authorization, X-Custom-Header"
CORS_ALLOW_CREDENTIALS: "no"
CORS_MAX_AGE: "86400"
CORS_DENY_REQUEST: "yes"
```
Country
Prise en charge STREAM ✅
Le plugin Country active le géo‑blocage et permet de restreindre l’accès selon la localisation géographique des visiteurs. Utile pour la conformité régionale, limiter la fraude associée à des zones à risque et appliquer des restrictions de contenu selon les frontières.
Comment ça marche :
- À chaque visite, BunkerWeb détermine le pays d’origine via l’adresse IP.
- Votre configuration définit une liste blanche (autorisés) ou noire (bloqués).
- En liste blanche : seuls les pays listés sont autorisés.
- En liste noire : les pays listés sont refusés.
- Le résultat est mis en cache pour les visites répétées.
Comment l’utiliser
- Stratégie : choisir liste blanche (peu de pays autorisés) ou liste noire (bloquer certains pays).
- Codes ou groupes : ajoutez des codes ISO 3166‑1 alpha‑2 (US, GB, FR) et/ou des tokens de groupe pris en charge (comme
@EU,@SCHENGEN) àWHITELIST_COUNTRYouBLACKLIST_COUNTRY. - Application : une fois configuré, la restriction s’applique à tous les visiteurs.
- Suivi : consultez la web UI pour les statistiques par pays.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
WHITELIST_COUNTRY |
multisite | non | Liste blanche : codes pays et/ou tokens de groupe, séparés par des espaces. Seuls ces pays sont autorisés. | |
BLACKLIST_COUNTRY |
multisite | non | Liste noire : codes pays et/ou tokens de groupe, séparés par des espaces. Ces pays sont bloqués. |
Groupes de pays pris en charge
Vous pouvez utiliser des tokens de groupe préfixés par @. Ils sont étendus côté serveur en pays membres :
@EU: États membres de l’Union européenne.@SCHENGEN: pays de l’espace Schengen.@EEA: Espace économique européen (@EU+ Islande, Liechtenstein, Norvège).@BENELUX: Belgique, Pays-Bas, Luxembourg.@DACH: zone germanophone de référence (Allemagne, Autriche, Suisse).@NORDICS: pays nordiques (Danemark, Finlande, Islande, Norvège, Suède).@USMCA: zone de l’accord USMCA (États-Unis, Canada, Mexique).@FIVE_EYES: pays de l’alliance de renseignement Five Eyes.@ASEAN: États membres de l’ASEAN en Asie du Sud-Est.@GCC: États membres du Conseil de coopération du Golfe.@G7: pays du Groupe des Sept.@LATAM: ensemble Amérique latine utilisé par ce plugin.
!!! tip "Liste blanche vs noire" Choisissez l’approche adaptée à vos besoins :
- Utilisez la liste blanche pour restreindre l’accès à un petit nombre de pays.
- Utilisez la liste noire pour bloquer des régions problématiques tout en autorisant le reste.
!!! warning "Priorité" Si une liste blanche et une liste noire sont définies, la liste blanche a priorité : si le pays n’y figure pas, l’accès est refusé.
!!! info "Détection du pays" BunkerWeb utilise la base mmdb db‑ip lite.
Exemples
=== "Liste blanche uniquement"
```yaml
WHITELIST_COUNTRY: "US CA GB"
```
=== "Liste noire uniquement"
```yaml
BLACKLIST_COUNTRY: "RU CN KP"
```
=== "UE uniquement"
```yaml
WHITELIST_COUNTRY: "@EU"
```
=== "Groupe + pays explicites"
```yaml
WHITELIST_COUNTRY: "@SCHENGEN GB"
```
=== "Blocage pays à risque"
```yaml
BLACKLIST_COUNTRY: "RU CN KP IR SY"
```
CrowdSec
Prise en charge STREAM ❌
Le plugin CrowdSec intègre BunkerWeb avec le moteur de sécurité CrowdSec, fournissant une couche de protection supplémentaire contre diverses cybermenaces. Ce plugin agit comme un bouncer CrowdSec, refusant les requêtes en fonction des décisions de l'API CrowdSec.
CrowdSec est un moteur de sécurité moderne et open-source qui détecte et bloque les adresses IP malveillantes en se basant sur l'analyse comportementale et l'intelligence collective de sa communauté. Vous pouvez également configurer des scénarios pour bannir automatiquement les adresses IP en fonction de comportements suspects, bénéficiant ainsi d'une liste noire participative.
Comment ça marche :
- Le moteur CrowdSec analyse les journaux et détecte les activités suspectes sur votre infrastructure.
- Lorsqu'une activité malveillante est détectée, CrowdSec crée une décision pour bloquer l'adresse IP incriminée.
- BunkerWeb, agissant comme un bouncer, interroge l'API locale de CrowdSec pour obtenir des décisions concernant les requêtes entrantes.
- Si l'adresse IP d'un client fait l'objet d'une décision de blocage active, BunkerWeb refuse l'accès aux services protégés.
- En option, le composant de sécurité applicative (Application Security Component) peut effectuer une inspection approfondie des requêtes pour une sécurité renforcée.
!!! success "Bénéfices clés"
1. **Sécurité communautaire :** Bénéficiez des renseignements sur les menaces partagés par la communauté des utilisateurs de CrowdSec.
2. **Analyse comportementale :** Détectez les attaques sophistiquées basées sur des modèles de comportement, et non uniquement sur des signatures.
3. **Intégration légère :** Impact minimal sur les performances de votre instance BunkerWeb.
4. **Protection multi-niveaux :** Combinez la défense périmétrique (blocage d'IP) avec la sécurité applicative pour une protection en profondeur.
Prérequis
- Une API locale CrowdSec accessible par BunkerWeb (généralement l’agent exécuté sur la même machine ou dans le même réseau Docker).
- L’accès aux journaux d’accès de BunkerWeb (
/var/log/bunkerweb/access.logpar défaut) pour que l’agent CrowdSec puisse analyser les requêtes. - L’accès à
csclisur l’hôte CrowdSec afin d’enregistrer la clé du bouncer BunkerWeb.
Parcours d’intégration
- Préparer l’agent CrowdSec pour ingérer les journaux BunkerWeb.
- Configurer BunkerWeb pour interroger l’API locale CrowdSec.
- Valider le lien via l’API
/crowdsec/pingou la carte CrowdSec dans l’interface d’administration.
Les sections suivantes détaillent chacune de ces étapes.
Étape 1 – Préparer CrowdSec à ingérer les journaux BunkerWeb
=== "Docker" Fichier d'acquisition
Vous devrez exécuter une instance de CrowdSec et la configurer pour analyser les journaux de BunkerWeb. Utilisez la valeur dédiée `bunkerweb` pour le paramètre `type` dans votre fichier d'acquisition (en supposant que les journaux de BunkerWeb sont stockés tels quels sans données supplémentaires) :
```yaml
filenames:
- /var/log/bunkerweb.log
labels:
type: bunkerweb
```
Si la collection n'apparaît pas dans le conteneur CrowdSec, exécutez `docker exec -it <crowdsec-container> cscli hub update`, puis redémarrez ce conteneur (`docker restart <crowdsec-container>`) afin que les nouveaux artefacts soient disponibles. Remplacez `<crowdsec-container>` par le nom de votre conteneur CrowdSec.
**Composant de sécurité applicative (*optionnel*)**
CrowdSec fournit également un [Composant de sécurité applicative](https://docs.crowdsec.net/docs/appsec/intro?utm_source=external-docs&utm_medium=cta&utm_campaign=bunker-web-docs) qui peut être utilisé pour protéger votre application contre les attaques. Si vous souhaitez l'utiliser, vous devez créer un autre fichier d'acquisition pour le composant AppSec :
```yaml
appsec_config: crowdsecurity/appsec-default
labels:
type: appsec
listen_addr: 0.0.0.0:7422
source: appsec
```
**Syslog**
Pour les intégrations basées sur des conteneurs, nous recommandons de rediriger les journaux du conteneur BunkerWeb vers un service syslog afin que CrowdSec puisse y accéder facilement. Voici un exemple de configuration pour syslog-ng qui stockera les journaux bruts provenant de BunkerWeb dans un fichier local `/var/log/bunkerweb.log` :
```syslog
@version: 4.10
source s_net {
udp(
ip("0.0.0.0")
);
};
template t_imp {
template("$MSG\n");
template_escape(no);
};
destination d_file {
file("/var/log/bunkerweb.log" template(t_imp) logrotate(enable(yes), size(100MB), rotations(7)));
};
log {
source(s_net);
destination(d_file);
};
```
**Docker Compose**
Voici le modèle docker-compose que vous pouvez utiliser (n'oubliez pas de mettre à jour la clé du bouncer) :
```yaml
x-bw-env: &bw-env
# Nous utilisons une ancre pour éviter de répéter les mêmes paramètres pour les deux services
API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24" # Assurez-vous de définir la bonne plage IP pour que le planificateur puisse envoyer la configuration à l'instance
services:
bunkerweb:
# C'est le nom qui sera utilisé pour identifier l'instance dans le planificateur
image: bunkerity/bunkerweb:1.6.11-rc1
ports:
- "80:8080/tcp"
- "443:8443/tcp"
- "443:8443/udp" # Pour le support QUIC / HTTP3
environment:
<<: *bw-env # Nous utilisons l'ancre pour éviter de répéter les mêmes paramètres pour tous les services
restart: "unless-stopped"
networks:
- bw-universe
- bw-services
logging:
driver: syslog # Envoyer les journaux à syslog
options:
syslog-address: "udp://10.20.30.254:514" # L'adresse IP du service syslog
bw-scheduler:
image: bunkerity/bunkerweb-scheduler:1.6.11-rc1
environment:
<<: *bw-env
BUNKERWEB_INSTANCES: "bunkerweb" # Assurez-vous de définir le nom correct de l'instance
DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db" # N'oubliez pas de définir un mot de passe plus fort pour la base de données
SERVER_NAME: ""
MULTISITE: "yes"
USE_CROWDSEC: "yes"
CROWDSEC_API: "http://crowdsec:8080" # C'est l'adresse de l'API du conteneur CrowdSec dans le même réseau
CROWDSEC_APPSEC_URL: "http://crowdsec:7422" # Commentez si vous ne voulez pas utiliser le composant AppSec
CROWDSEC_API_KEY: "s3cr3tb0unc3rk3y" # N'oubliez pas de définir une clé plus forte pour le bouncer
volumes:
- bw-storage:/data # Ceci est utilisé pour persister le cache et d'autres données comme les sauvegardes
restart: "unless-stopped"
networks:
- bw-universe
- bw-db
bw-db:
image: mariadb:11
# Nous définissons la taille maximale des paquets autorisés pour éviter les problèmes avec les grosses requêtes
command: --max-allowed-packet=67108864
environment:
MYSQL_RANDOM_ROOT_PASSWORD: "yes"
MYSQL_DATABASE: "db"
MYSQL_USER: "bunkerweb"
MYSQL_PASSWORD: "changeme" # N'oubliez pas de définir un mot de passe plus fort pour la base de données
volumes:
- bw-data:/var/lib/mysql
restart: "unless-stopped"
networks:
- bw-db
crowdsec:
image: crowdsecurity/crowdsec:v1.7.8 # Utilisez la dernière version mais épinglez toujours la version pour une meilleure stabilité/sécurité
volumes:
- cs-data:/var/lib/crowdsec/data # Pour persister les données de CrowdSec
- bw-logs:/var/log:ro # Les journaux de BunkerWeb à analyser par CrowdSec
- ./acquis.yaml:/etc/crowdsec/acquis.yaml # Le fichier d'acquisition pour les journaux de BunkerWeb
- ./appsec.yaml:/etc/crowdsec/acquis.d/appsec.yaml # Commentez si vous ne voulez pas utiliser le composant AppSec
environment:
BOUNCER_KEY_bunkerweb: "s3cr3tb0unc3rk3y" # N'oubliez pas de définir une clé plus forte pour le bouncer
COLLECTIONS: "bunkerity/bunkerweb crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules"
# COLLECTIONS: "bunkerity/bunkerweb" # Si vous ne voulez pas utiliser le composant AppSec, utilisez plutôt cette ligne
networks:
- bw-universe
syslog:
image: balabit/syslog-ng:4.10.2
cap_add:
- NET_BIND_SERVICE # Lier aux ports bas
- NET_BROADCAST # Envoyer des diffusions
- NET_RAW # Utiliser des sockets brutes
- DAC_READ_SEARCH # Lire les fichiers en contournant les autorisations
- DAC_OVERRIDE # Outrepasser les autorisations de fichiers
- CHOWN # Changer le propriétaire
- SYSLOG # Écrire dans les journaux système
volumes:
- bw-logs:/var/log/bunkerweb # C'est le volume utilisé pour stocker les journaux
- ./syslog-ng.conf:/etc/syslog-ng/syslog-ng.conf # C'est le fichier de configuration de syslog-ng
networks:
bw-universe:
ipv4_address: 10.20.30.254
volumes:
bw-data:
bw-storage:
bw-logs:
cs-data:
networks:
bw-universe:
name: bw-universe
ipam:
driver: default
config:
- subnet: 10.20.30.0/24 # Assurez-vous de définir la bonne plage IP pour que le planificateur puisse envoyer la configuration à l'instance
bw-services:
name: bw-services
bw-db:
name: bw-db
```
=== "Linux"
Vous devez installer CrowdSec et le configurer pour analyser les journaux de BunkerWeb. Suivez la [documentation officielle](https://doc.crowdsec.net/docs/getting_started/install_crowdsec?utm_source=external-docs&utm_medium=cta&utm_campaign=bunker-web-docs#scenarios).
Pour permettre à CrowdSec d'analyser les journaux de BunkerWeb, ajoutez les lignes suivantes à votre fichier d'acquisition situé à `/etc/crowdsec/acquis.yaml` :
```yaml
filenames:
- /var/log/bunkerweb/access.log
- /var/log/bunkerweb/error.log
- /var/log/bunkerweb/modsec_audit.log
labels:
type: bunkerweb
```
Mettez à jour le hub CrowdSec et installez la collection BunkerWeb :
```shell
sudo cscli hub update
sudo cscli collections install bunkerity/bunkerweb
```
Maintenant, ajoutez votre bouncer personnalisé à l'API CrowdSec en utilisant l'outil `cscli` :
```shell
sudo cscli bouncers add crowdsec-bunkerweb-bouncer/v1.6
```
!!! warning "Clé API"
Conservez la clé générée par la commande `cscli` ; vous en aurez besoin plus tard.
Ensuite, redémarrez le service CrowdSec :
```shell
sudo systemctl restart crowdsec
```
**Composant de sécurité applicative (*optionnel*)**
Si vous souhaitez utiliser le composant AppSec, vous devez créer un autre fichier d'acquisition pour celui-ci, situé à `/etc/crowdsec/acquis.d/appsec.yaml` :
```yaml
appsec_config: crowdsecurity/appsec-default
labels:
type: appsec
listen_addr: 127.0.0.1:7422
source: appsec
```
Vous devrez également installer les collections du composant AppSec :
```shell
sudo cscli collections install crowdsecurity/appsec-virtual-patching
sudo cscli collections install crowdsecurity/appsec-generic-rules
```
Enfin, redémarrez le service CrowdSec :
```shell
sudo systemctl restart crowdsec
```
**Paramètres**
Configurez le plugin en ajoutant les paramètres suivants à votre fichier de configuration BunkerWeb :
```env
USE_CROWDSEC=yes
CROWDSEC_API=http://127.0.0.1:8080
CROWDSEC_API_KEY=<La clé fournie par cscli>
# Commentez si vous ne voulez pas utiliser le composant AppSec
CROWDSEC_APPSEC_URL=http://127.0.0.1:7422
```
Enfin, rechargez le service BunkerWeb :
```shell
sudo systemctl reload bunkerweb
```
=== "All-in-one"
L'image Docker BunkerWeb All-In-One (AIO) est livrée avec CrowdSec entièrement intégré. Vous n'avez pas besoin de configurer une instance CrowdSec séparée ou de configurer manuellement les fichiers d'acquisition pour les journaux de BunkerWeb lorsque vous utilisez l'agent CrowdSec interne.
Référez-vous à la [documentation d'intégration de l'image All-In-One (AIO)](integrations.md#crowdsec-integration).
Étape 2 – Configurer les paramètres de BunkerWeb
Appliquez les variables d’environnement suivantes (ou leurs équivalents via le scheduler) pour permettre à votre instance BunkerWeb de communiquer avec l’API locale CrowdSec. Au minimum, USE_CROWDSEC, CROWDSEC_API et CROWDSEC_API_KEY avec une clé valide générée via cscli bouncers add sont nécessaires.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_CROWDSEC |
no |
multisite | no | Activer CrowdSec : Mettre à yes pour activer le bouncer CrowdSec. |
CROWDSEC_API |
http://crowdsec:8080 |
global | no | URL de l'API CrowdSec : L'adresse du service de l'API locale de CrowdSec. |
CROWDSEC_API_KEY |
global | no | Clé API CrowdSec : La clé API pour s'authentifier auprès de l'API CrowdSec, obtenue avec cscli bouncers add. |
|
CROWDSEC_MODE |
live |
global | no | Mode de fonctionnement : Soit live (interroge l'API pour chaque requête) ou stream (met en cache périodiquement toutes les décisions). |
CROWDSEC_ENABLE_INTERNAL |
no |
global | no | Trafic interne : Mettre à yes pour vérifier le trafic interne par rapport aux décisions de CrowdSec. |
CROWDSEC_REQUEST_TIMEOUT |
1000 |
global | no | Délai d'attente de la requête : Délai d'attente en millisecondes pour les requêtes HTTP vers l'API locale de CrowdSec en mode live. |
CROWDSEC_EXCLUDE_LOCATION |
global | no | Emplacements exclus : Liste d'emplacements (URI) séparés par des virgules à exclure des vérifications de CrowdSec. | |
CROWDSEC_CACHE_EXPIRATION |
1 |
global | no | Expiration du cache : Le temps d'expiration du cache en secondes pour les décisions IP en mode live. |
CROWDSEC_UPDATE_FREQUENCY |
10 |
global | no | Fréquence de mise à jour : À quelle fréquence (en secondes) récupérer les décisions nouvelles/expirées de l'API CrowdSec en mode stream. |
Paramètres du composant de sécurité applicative
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
CROWDSEC_APPSEC_URL |
global | no | URL AppSec : L'URL du composant de sécurité applicative de CrowdSec. Laisser vide pour désactiver AppSec. | |
CROWDSEC_APPSEC_FAILURE_ACTION |
passthrough |
global | no | Action en cas d'échec : Action à entreprendre lorsque AppSec renvoie une erreur. Peut être passthrough ou deny. |
CROWDSEC_APPSEC_CONNECT_TIMEOUT |
100 |
global | no | Délai de connexion : Le délai d'attente en millisecondes pour se connecter au composant AppSec. |
CROWDSEC_APPSEC_SEND_TIMEOUT |
100 |
global | no | Délai d'envoi : Le délai d'attente en millisecondes pour envoyer des données au composant AppSec. |
CROWDSEC_APPSEC_PROCESS_TIMEOUT |
500 |
global | no | Délai de traitement : Le délai d'attente en millisecondes pour traiter la requête dans le composant AppSec. |
CROWDSEC_ALWAYS_SEND_TO_APPSEC |
no |
global | no | Toujours envoyer : Mettre à yes pour toujours envoyer les requêtes à AppSec, même s'il y a une décision au niveau de l'IP. |
CROWDSEC_APPSEC_SSL_VERIFY |
no |
global | no | Vérification SSL : Mettre à yes pour vérifier le certificat SSL du composant AppSec. |
!!! info "À propos des modes de fonctionnement" - Le mode Live interroge l'API CrowdSec pour chaque requête entrante, offrant une protection en temps réel au prix d'une latence plus élevée. - Le mode Stream télécharge périodiquement toutes les décisions de l'API CrowdSec et les met en cache localement, réduisant la latence avec un léger retard dans l'application des nouvelles décisions.
Exemples de configurations
=== "Configuration de base"
C'est une configuration simple pour lorsque CrowdSec s'exécute sur le même hôte :
```yaml
USE_CROWDSEC: "yes"
CROWDSEC_API: "http://crowdsec:8080"
CROWDSEC_API_KEY: "your-api-key-here"
CROWDSEC_MODE: "live"
```
=== "Configuration avancée avec AppSec"
Une configuration plus complète incluant le composant de sécurité applicative :
```yaml
USE_CROWDSEC: "yes"
CROWDSEC_API: "http://crowdsec:8080"
CROWDSEC_API_KEY: "your-api-key-here"
CROWDSEC_MODE: "stream"
CROWDSEC_UPDATE_FREQUENCY: "30"
CROWDSEC_EXCLUDE_LOCATION: "/health,/metrics"
# Configuration AppSec
CROWDSEC_APPSEC_URL: "http://crowdsec:7422"
CROWDSEC_APPSEC_FAILURE_ACTION: "deny"
CROWDSEC_ALWAYS_SEND_TO_APPSEC: "yes"
CROWDSEC_APPSEC_SSL_VERIFY: "yes"
```
Étape 3 – Valider l’intégration
- Dans les journaux du planificateur, recherchez les entrées
CrowdSec configuration successfully generatedetCrowdSec bouncer denied requestafin de vérifier que le plugin est actif. - Côté CrowdSec, surveillez
cscli metrics showou la console CrowdSec pour vous assurer que les décisions BunkerWeb apparaissent comme prévu. - Dans l’interface BunkerWeb, ouvrez la page du plugin CrowdSec pour voir l’état de l’intégration.
Custom Pages (PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ❌
Tweak BunkerWeb error/antibot/default pages with custom HTML.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
CUSTOM_ERROR_PAGE |
multisite | non | Full path of the custom error page (must be readable by the scheduler) (Can be a lua template). | |
CUSTOM_DEFAULT_SERVER_PAGE |
global | non | Full path of the custom default server page (must be readable by the scheduler) (Can be a lua template). | |
CUSTOM_ANTIBOT_CAPTCHA_PAGE |
multisite | non | Full path of the custom antibot captcha page (must be readable by the scheduler) (Can be a lua template). | |
CUSTOM_ANTIBOT_JAVASCRIPT_PAGE |
multisite | non | Full path of the custom antibot javascript check page (must be readable by the scheduler) (Can be a lua template). | |
CUSTOM_ANTIBOT_RECAPTCHA_PAGE |
multisite | non | Full path of the custom antibot recaptcha page (must be readable by the scheduler) (Can be a lua template). | |
CUSTOM_ANTIBOT_HCAPTCHA_PAGE |
multisite | non | Full path of the custom antibot hcaptcha page (must be readable by the scheduler) (Can be a lua template). | |
CUSTOM_ANTIBOT_TURNSTILE_PAGE |
multisite | non | Full path of the custom antibot turnstile page (must be readable by the scheduler) (Can be a lua template). | |
CUSTOM_ANTIBOT_MCAPTCHA_PAGE |
multisite | non | Full path of the custom antibot mcaptcha page (must be readable by the scheduler) (Can be a lua template). | |
CUSTOM_ANTIBOT_CAPJS_PAGE |
multisite | non | Full path of the custom antibot Cap.js page (must be readable by the scheduler) (Can be a lua template). |
Custom SSL certificate
Prise en charge STREAM ✅
Le plugin Certificat SSL personnalisé permet d’utiliser vos propres certificats SSL/TLS avec BunkerWeb, au lieu de ceux générés automatiquement. Utile si vous possédez déjà des certificats d’une AC de confiance, avez des besoins spécifiques ou centralisez la gestion des certificats.
Comment ça marche :
- Vous fournissez le certificat et la clé privée (chemins de fichiers ou données en base64/PEM).
- BunkerWeb valide le format et l’utilisabilité des fichiers.
- Lors d’une connexion sécurisée, BunkerWeb sert votre certificat personnalisé.
- La validité est surveillée et des alertes sont émises avant expiration.
- Vous gardez le contrôle total sur le cycle de vie des certificats.
!!! info "Surveillance automatique"
Avec le paramètre USE_CUSTOM_SSL défini à yes, BunkerWeb surveille le certificat CUSTOM_SSL_CERT, détecte les changements et recharge NGINX si nécessaire.
Comment l’utiliser
- Activer : mettez le paramètre
USE_CUSTOM_SSLàyes. - Méthode : fichiers vs données, priorité via
CUSTOM_SSL_CERT_PRIORITY. - Fichiers : fournissez les chemins du certificat et de la clé privée.
- Données : fournissez les chaînes base64 ou PEM en clair.
- Laisser BunkerWeb faire le reste : une fois configuré, vos certificats personnalisés sont utilisés automatiquement pour les connexions HTTPS.
!!! tip "Mode stream"
En mode stream, configurez LISTEN_STREAM_PORT_SSL pour le port SSL/TLS.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_CUSTOM_SSL |
no |
multisite | non | Activer l’usage d’un certificat personnalisé. |
CUSTOM_SSL_CERT_PRIORITY |
file |
multisite | non | Priorité des sources : file (fichiers) ou data (données). |
CUSTOM_SSL_CERT |
multisite | non | Chemin complet vers le certificat (ou bundle). | |
CUSTOM_SSL_KEY |
multisite | non | Chemin complet vers la clé privée. | |
CUSTOM_SSL_CERT_DATA |
multisite | non | Données du certificat (base64 ou PEM en clair). | |
CUSTOM_SSL_KEY_DATA |
multisite | non | Données de la clé privée (base64 ou PEM en clair). |
!!! warning "Sécurité" Protégez la clé privée (droits adaptés, lisible par le scheduler BunkerWeb uniquement).
!!! tip "Format" Les certificats doivent être au format PEM. Convertissez si nécessaire.
!!! info "Chaînes de certification" Si une chaîne intermédiaire est nécessaire, fournissez le bundle complet dans l’ordre (certificat puis intermédiaires).
Exemples
=== "Fichiers"
```yaml
USE_CUSTOM_SSL: "yes"
CUSTOM_SSL_CERT_PRIORITY: "file"
CUSTOM_SSL_CERT: "/path/to/your/certificate.pem"
CUSTOM_SSL_KEY: "/path/to/your/private-key.pem"
```
=== "Données base64"
```yaml
USE_CUSTOM_SSL: "yes"
CUSTOM_SSL_CERT_PRIORITY: "data"
CUSTOM_SSL_CERT_DATA: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUR..."
CUSTOM_SSL_KEY_DATA: "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSEV..."
```
=== "PEM en clair"
```yaml
USE_CUSTOM_SSL: "yes"
CUSTOM_SSL_CERT_PRIORITY: "data"
CUSTOM_SSL_CERT_DATA: |
-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIUJH...certificate content...AAAA
-----END CERTIFICATE-----
CUSTOM_SSL_KEY_DATA: |
-----BEGIN PRIVATE KEY-----
MIIEvQIBADAN...key content...AAAA
-----END PRIVATE KEY-----
```
=== "Fallback"
```yaml
USE_CUSTOM_SSL: "yes"
CUSTOM_SSL_CERT_PRIORITY: "file"
CUSTOM_SSL_CERT: "/path/to/your/certificate.pem"
CUSTOM_SSL_KEY: "/path/to/your/private-key.pem"
CUSTOM_SSL_CERT_DATA: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUR..."
CUSTOM_SSL_KEY_DATA: "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSEV..."
```
Database
Prise en charge STREAM ✅
Le plugin Base de données fournit une intégration robuste pour BunkerWeb en permettant le stockage centralisé et la gestion des données de configuration, des journaux et d'autres informations essentielles.
Ce composant cœur prend en charge plusieurs moteurs : SQLite, PostgreSQL, MySQL/MariaDB et Oracle, afin de choisir la solution la mieux adaptée à votre environnement et à vos besoins.
Comment ça marche :
- BunkerWeb se connecte à la base configurée via une URI au format SQLAlchemy.
- Les données de configuration critiques, les informations d'exécution et les journaux des jobs sont stockés de manière sécurisée en base.
- Des tâches de maintenance automatiques optimisent la base en gérant la croissance et en purgeant les enregistrements excédentaires.
- Pour la haute disponibilité, vous pouvez configurer une URI en lecture seule servant de bascule et/ou pour délester les lectures.
- Les opérations base de données sont journalisées selon le niveau de log spécifié, offrant la visibilité adaptée.
Comment l'utiliser
Étapes pour configurer la base de données :
- Choisir un moteur : SQLite (par défaut), PostgreSQL, MySQL/MariaDB ou Oracle.
- Configurer l'URI : renseignez
DATABASE_URI(format SQLAlchemy) pour la base principale. - Optionnel :
DATABASE_URI_READONLYpour les opérations en lecture seule ou en secours.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
DATABASE_URI |
sqlite:////var/lib/bunkerweb/db.sqlite3 |
global | non | URI principale de connexion (format SQLAlchemy). |
DATABASE_URI_READONLY |
global | non | URI optionnelle en lecture seule (offload/HA). | |
DATABASE_LOG_LEVEL |
warning |
global | non | Niveau de verbosité des logs DB : debug, info, warn, warning, error. |
DATABASE_MAX_JOBS_RUNS |
10000 |
global | non | Nombre max d'entrées de runs de jobs conservées avant purge automatique. |
DATABASE_MAX_SESSION_AGE_DAYS |
14 |
global | non | Durée max de conservation des sessions UI (en jours) avant purge automatique. |
DATABASE_POOL_SIZE |
40 |
global | non | Taille du pool : Nombre de connexions maintenues dans le pool de connexions. |
DATABASE_POOL_MAX_OVERFLOW |
20 |
global | non | Dépassement max du pool : Nombre max de connexions supplémentaires au-delà de la taille du pool. -1 pour illimité. |
DATABASE_POOL_TIMEOUT |
5 |
global | non | Délai d'attente du pool : Nombre de secondes d'attente avant d'abandonner l'obtention d'une connexion du pool. |
DATABASE_POOL_RECYCLE |
1800 |
global | non | Recyclage du pool : Nombre de secondes avant le recyclage automatique d'une connexion. -1 pour désactiver. |
DATABASE_POOL_PRE_PING |
yes |
global | non | Pré-ping du pool : Tester la vivacité des connexions à chaque extraction du pool. |
DATABASE_POOL_RESET_ON_RETURN |
global | non | Réinitialisation au retour : Comment les connexions sont réinitialisées au retour dans le pool. Vide = auto (none pour MySQL/MariaDB, rollback sinon). Options : rollback, commit, none. |
|
DATABASE_RETRY_TIMEOUT |
60 |
global | non | Délai de reconnexion : Nombre max de secondes d'attente de disponibilité de la base au démarrage. |
DATABASE_REQUEST_RETRY_ATTEMPTS |
2 |
global | non | Tentatives de réessai : Nombre de tentatives en cas d'erreurs transitoires lors des opérations. |
DATABASE_REQUEST_RETRY_DELAY |
0.25 |
global | non | Délai entre réessais : Délai en secondes entre les tentatives de réessai en cas d'erreurs transitoires. |
!!! tip "Choix du moteur" - SQLite (défaut) : simple et fichier unique, idéal mono‑nœud/tests. - PostgreSQL : recommandé en production multi‑instances (robustesse, concurrence). - MySQL/MariaDB : alternative solide aux capacités proches de PostgreSQL. - Oracle : adapté aux environnements d'entreprise standardisés sur Oracle.
!!! info "Format SQLAlchemy" L'URI de base de données suit le format SQLAlchemy :
- SQLite : `sqlite:////chemin/vers/database.sqlite3`
- PostgreSQL : `postgresql://user:password@hôte:port/base`
- MySQL/MariaDB : `mysql://user:password@hôte:port/base` ou `mariadb://user:password@hôte:port/base`
- Oracle : `oracle://user:password@hôte:port/base`
!!! warning "Maintenance" Des tâches quotidiennes assurent la maintenance automatique :
- **Purge des runs de jobs excédentaires** : supprime l'historique au-delà de `DATABASE_MAX_JOBS_RUNS`.
- **Purge des sessions UI expirées** : enlève les sessions plus anciennes que `DATABASE_MAX_SESSION_AGE_DAYS`.
Ces jobs évitent la croissance illimitée tout en conservant un historique d'exploitation pertinent.
DNSBL
Prise en charge STREAM ✅
Le plugin DNSBL (Domain Name System Blacklist) protège contre les IP malveillantes connues en vérifiant l’adresse IP du client auprès de serveurs DNSBL externes. Cette fonctionnalité aide à se prémunir du spam, des botnets et de diverses menaces en s’appuyant on des listes communautaires d’IP problématiques.
Comment ça marche :
- Lorsqu’un client se connecte à votre site, BunkerWeb interroge les serveurs DNSBL que vous avez choisis via le protocole DNS.
- La vérification s’effectue en envoyant une requête DNS inversée à chaque serveur DNSBL avec l’IP du client.
- Si un serveur DNSBL confirme que l’IP du client est listée comme malveillante, BunkerWeb bannit automatiquement ce client, empêchant les menaces potentielles d’atteindre votre application.
- Les résultats sont mis en cache pour améliorer les performances pour les visites répétées depuis la même IP.
- Les recherches sont asynchrones pour minimiser l’impact sur le temps de chargement.
Comment l’utiliser
Suivez ces étapes pour configurer et utiliser la fonctionnalité DNSBL :
- Activer la fonction : La fonction DNSBL est désactivée par défaut. Passez
USE_DNSBLàyespour l'activer. - Configurer les serveurs DNSBL : Ajoutez les noms de domaine des services DNSBL que vous souhaitez utiliser dans le paramètre
DNSBL_LIST. - Appliquer les paramètres : Une fois configuré, BunkerWeb vérifiera automatiquement les connexions entrantes auprès des serveurs DNSBL spécifiés.
- Surveiller l'efficacité : Consultez la web UI pour voir les statistiques des requêtes bloquées par les vérifications DNSBL.
Paramètres de configuration
Général
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_DNSBL |
no |
multisite | non | Activer DNSBL : mettre à yes pour activer les vérifications DNSBL pour les connexions entrantes. |
DNSBL_LIST |
bl.blocklist.de sbl.spamhaus.org xbl.spamhaus.org |
global | non | Serveurs DNSBL : liste des domaines de serveurs DNSBL à vérifier, séparés par des espaces. |
Listes d’exception
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
DNSBL_IGNORE_IP |
`` | multisite | oui | IP/CIDR séparés par des espaces pour lesquels ignorer les vérifications DNSBL (liste blanche). |
DNSBL_IGNORE_IP_URLS |
`` | multisite | oui | URL séparées par des espaces fournissant des IP/CIDR à ignorer. Supporte http(s):// et file://. |
!!! tip "Choisir des serveurs DNSBL" Choisissez des fournisseurs DNSBL réputés pour minimiser les faux positifs. La liste par défaut inclut des services bien établis qui conviennent à la plupart des sites web :
- **bl.blocklist.de :** Liste les IP qui ont été détectées en train d'attaquer d'autres serveurs.
- **sbl.spamhaus.org :** Se concentre sur les sources de spam et autres activités malveillantes.
- **xbl.spamhaus.org :** Cible les systèmes infectés, tels que les machines compromises ou les proxys ouverts.
!!! info "Principe de fonctionnement de DNSBL" Les serveurs DNSBL fonctionnent en répondant à des requêtes DNS spécialement formatées. Lorsque BunkerWeb vérifie une adresse IP, il inverse l'IP et y ajoute le nom de domaine du DNSBL. Si la requête DNS résultante renvoie une réponse de « succès », l'IP est considérée comme étant sur la liste noire.
!!! warning "Considérations sur la performance" Bien que BunkerWeb optimise les recherches DNSBL pour la performance, l'ajout d'un grand nombre de serveurs DNSBL pourrait potentiellement impacter les temps de réponse. Commencez avec quelques serveurs DNSBL réputés et surveillez la performance avant d'en ajouter d'autres.
Exemples de configuration
=== "Configuration de base"
Une configuration simple utilisant les serveurs DNSBL par défaut :
```yaml
USE_DNSBL: "yes"
DNSBL_LIST: "bl.blocklist.de sbl.spamhaus.org xbl.spamhaus.org"
```
=== "Configuration minimale"
Une configuration minimale se concentrant sur les services DNSBL les plus fiables :
```yaml
USE_DNSBL: "yes"
DNSBL_LIST: "zen.spamhaus.org"
```
Cette configuration utilise uniquement :
- **zen.spamhaus.org** : La liste combinée de Spamhaus est souvent considérée comme suffisante en tant que solution autonome en raison de sa large couverture et de sa réputation de précision. Elle combine les listes SBL, XBL et PBL en une seule requête, la rendant efficace et complète.
=== "Exclure des IP de confiance"
Vous pouvez exclure certains clients des vérifications DNSBL via des valeurs statiques et/ou des fichiers distants :
- `DNSBL_IGNORE_IP` : Ajoutez des IP et des plages CIDR séparées par des espaces. Exemple : `192.0.2.10 203.0.113.0/24 2001:db8::/32`.
- `DNSBL_IGNORE_IP_URLS` : Fournissez des URL dont le contenu liste une IP/CIDR par ligne. Les commentaires commençant par `#` ou `;` sont ignorés. Les entrées en double sont dédupliquées.
Quand une IP cliente correspond à la liste d’exclusion, BunkerWeb saute les requêtes DNSBL et met en cache le résultat « ok » pour accélérer les requêtes suivantes.
=== "Utiliser des URL distantes"
La tâche `dnsbl-download` télécharge et met en cache les IP à ignorer toutes les heures :
- Protocoles : `https://`, `http://` et chemins locaux `file://`.
- Un cache par URL avec une somme de contrôle empêche les téléchargements redondants (délai de grâce d'1 heure).
- Fichier fusionné par service : `/var/cache/bunkerweb/dnsbl/<service>/IGNORE_IP.list`.
- Chargé au démarrage et fusionné avec `DNSBL_IGNORE_IP`.
Exemple combinant des sources statiques et des URL :
```yaml
USE_DNSBL: "yes"
DNSBL_LIST: "zen.spamhaus.org"
DNSBL_IGNORE_IP: "10.0.0.0/8 192.168.0.0/16 2001:db8::/32"
DNSBL_IGNORE_IP_URLS: "https://exemple.com/allow-cidrs.txt file:///etc/bunkerweb/dnsbl/ignore.txt"
```
=== "Utiliser des fichiers locaux"
Chargez des IP à ignorer depuis des fichiers locaux en utilisant des URL `file://` :
```yaml
USE_DNSBL: "yes"
DNSBL_LIST: "zen.spamhaus.org"
DNSBL_IGNORE_IP_URLS: "file:///etc/bunkerweb/dnsbl/ignore.txt file:///opt/data/allow-cidrs.txt"
```
Easy Resolve (PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ❌
Provides a simpler way to fix false positives in reports.
Errors
Prise en charge STREAM ❌
Le plugin Errors fournit une gestion personnalisable des erreurs HTTP, afin de définir l’apparence des réponses d’erreur pour vos utilisateurs. Vous pouvez ainsi afficher des pages d’erreur claires et cohérentes avec votre identité, plutôt que les pages techniques par défaut du serveur.
Comment ça marche :
- Quand une erreur HTTP survient (ex. 400, 404, 500), BunkerWeb intercepte la réponse.
- À la place de la page par défaut, BunkerWeb affiche une page personnalisée et soignée.
- Les pages d’erreur sont configurables : vous pouvez fournir un fichier HTML par code d’erreur. Les fichiers doivent être placés dans le répertoire défini par
ROOT_FOLDER(voir le plugin Misc).- Par défaut,
ROOT_FOLDERvaut/var/www/html/{server_name}. - En mode multisite, chaque site a son propre
ROOT_FOLDER; placez les pages d’erreur dans le dossier correspondant à chaque site.
- Par défaut,
- Les pages par défaut expliquent clairement le problème et suggèrent des actions possibles.
Comment l’utiliser
- Définir les pages personnalisées : utilisez
ERRORSpour associer des codes HTTP à des fichiers HTML (dansROOT_FOLDER). - Configurer vos pages : utilisez celles de BunkerWeb par défaut ou vos propres fichiers (placés dans le
ROOT_FOLDERapproprié). - Définir les codes interceptés : avec
INTERCEPTED_ERROR_CODES, choisissez les codes toujours gérés par BunkerWeb. - Laissez BunkerWeb faire le reste : la gestion d’erreurs sera appliquée automatiquement.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
ERRORS |
multisite | non | Pages d’erreur personnalisées : paires CODE=/chemin/page.html. |
|
INTERCEPTED_ERROR_CODES |
400 401 403 404 405 413 429 500 501 502 503 504 |
multisite | non | Codes interceptés : liste de codes gérés avec la page par défaut si aucune page personnalisée n’est définie. |
!!! tip "Conception des pages" Les pages d’erreur BunkerWeb par défaut sont informatives, conviviales et professionnelles. Elles incluent :
- Des descriptions d’erreur claires
- Des informations sur les causes possibles
- Des actions suggérées pour résoudre le problème
- Des repères visuels indiquant si le problème vient du client ou du serveur
!!! info "Types d’erreurs" Les codes d’erreur sont classés par type :
- **Erreurs 4xx (côté client) :** requêtes invalides, ressource inexistante, authentification manquante…
- **Erreurs 5xx (côté serveur) :** impossibilité de traiter une requête valide (erreur interne, indisponibilité temporaire…).
Exemples
=== "Gestion par défaut"
```yaml
INTERCEPTED_ERROR_CODES: "400 401 403 404 405 413 429 500 501 502 503 504"
```
=== "Pages personnalisées"
```yaml
ERRORS: "404=/custom/404.html 500=/custom/500.html"
INTERCEPTED_ERROR_CODES: "400 401 403 404 405 413 429 500 501 502 503 504"
```
=== "Gestion sélective"
```yaml
INTERCEPTED_ERROR_CODES: "404 500"
```
Greylist
Prise en charge STREAM ⚠️
Le plugin Greylist fournit une approche de sécurité flexible qui autorise l'accès des visiteurs tout en conservant les fonctionnalités de sécurité essentielles.
Contrairement aux approches classiques de blacklist/whitelist, qui bloquent ou autorisent complètement l'accès, la greylist crée un compromis en accordant l'accès à certains visiteurs tout en continuant à les soumettre aux contrôles de sécurité.
Comment ça marche :
- Vous définissez les critères des visiteurs à placer en greylist (adresses IP, réseaux, rDNS, ASN, User-Agent ou motifs d'URI).
- Lorsqu'un visiteur correspond à l'un de ces critères, l'accès à votre site lui est accordé, mais les autres fonctionnalités de sécurité restent actives.
- Si un visiteur ne correspond à aucun critère de greylist, son accès est refusé.
- Les données de greylist peuvent être automatiquement mises à jour depuis des sources externes selon une planification régulière.
Comment l'utiliser
Suivez ces étapes pour configurer et utiliser la fonctionnalité Greylist :
- Activer la fonctionnalité : La fonctionnalité Greylist est désactivée par défaut. Mettez le paramètre
USE_GREYLISTàyespour l'activer. - Configurer les règles de greylist : Définissez les IP, réseaux, motifs rDNS, ASN, User-Agents ou URI à placer en greylist.
- Ajouter des sources externes : Configurez éventuellement des URL pour télécharger et mettre à jour automatiquement les données de greylist.
- Surveiller l'accès : Consultez l'interface web pour voir quels visiteurs sont autorisés ou refusés.
!!! tip "Comportement du contrôle d'accès"
Lorsque la fonctionnalité greylist est activée avec le paramètre USE_GREYLIST défini à yes :
1. **Visiteurs en greylist :** Ils sont autorisés à accéder au site, mais restent soumis à tous les contrôles de sécurité.
2. **Visiteurs hors greylist :** Leur accès est entièrement refusé.
!!! info "mode stream" En mode stream, seuls les contrôles IP, rDNS et ASN sont effectués.
Paramètres de configuration
Général
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_GREYLIST |
no |
multisite | non | Activer Greylist : Mettre à yes pour activer la greylist. |
=== "Adresse IP" Ce que cela fait : Place les visiteurs en greylist selon leur adresse IP ou leur réseau. Ces visiteurs obtiennent l'accès, mais restent soumis aux contrôles de sécurité.
| Paramètre | Défaut | Contexte | Multiple | Description |
| ------------------ | ------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `GREYLIST_IP` | | multisite | non | **Greylist IP :** Liste d'adresses IP ou de réseaux (notation CIDR) à placer en greylist, séparés par des espaces. |
| `GREYLIST_IP_URLS` | | multisite | non | **URL de greylist IP :** Liste d'URL contenant des adresses IP ou des réseaux à placer en greylist, séparées par des espaces. |
=== "DNS inverse" Ce que cela fait : Place les visiteurs en greylist selon leur nom de domaine inversé. Utile pour autoriser conditionnellement l'accès aux visiteurs de certaines organisations ou de certains réseaux.
| Paramètre | Défaut | Contexte | Multiple | Description |
| ---------------------- | ------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `GREYLIST_RDNS` | | multisite | non | **Greylist rDNS :** Liste de suffixes DNS inversés à placer en greylist, séparés par des espaces. |
| `GREYLIST_RDNS_GLOBAL` | `yes` | multisite | non | **rDNS global seulement :** Effectue les contrôles de greylist rDNS uniquement sur les adresses IP globales lorsque défini à `yes`. |
| `GREYLIST_RDNS_URLS` | | multisite | non | **URL de greylist rDNS :** Liste d'URL contenant des suffixes DNS inversés à placer en greylist, séparées par des espaces. |
=== "ASN" Ce que cela fait : Place les visiteurs de fournisseurs réseau précis en greylist à l'aide des numéros de système autonome. Les ASN identifient le fournisseur ou l'organisation auquel appartient une IP.
| Paramètre | Défaut | Contexte | Multiple | Description |
| ------------------- | ------ | --------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `GREYLIST_ASN` | | multisite | non | **Greylist ASN :** Liste de numéros de système autonome à placer en greylist, séparés par des espaces. |
| `GREYLIST_ASN_URLS` | | multisite | non | **URL de greylist ASN :** Liste d'URL contenant des ASN à placer en greylist, séparées par des espaces. |
=== "User Agent" Ce que cela fait : Place les visiteurs en greylist selon le navigateur ou l'outil qu'ils déclarent utiliser. Cela permet un accès contrôlé pour des outils précis tout en conservant les contrôles de sécurité.
| Paramètre | Défaut | Contexte | Multiple | Description |
| -------------------------- | ------ | --------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `GREYLIST_USER_AGENT` | | multisite | non | **Greylist User-Agent :** Liste de motifs User-Agent (regex PCRE) à placer en greylist, séparés par des espaces. |
| `GREYLIST_USER_AGENT_URLS` | | multisite | non | **URL de greylist User-Agent :** Liste d'URL contenant des motifs User-Agent à placer en greylist. |
=== "URI" Ce que cela fait : Place en greylist les requêtes vers des URL précises de votre site. Cela permet un accès conditionnel à certains endpoints tout en conservant les contrôles de sécurité.
| Paramètre | Défaut | Contexte | Multiple | Description |
| ------------------- | ------ | --------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `GREYLIST_URI` | | multisite | non | **Greylist URI :** Liste de motifs d'URI (regex PCRE) à placer en greylist, séparés par des espaces. |
| `GREYLIST_URI_URLS` | | multisite | non | **URL de greylist URI :** Liste d'URL contenant des motifs d'URI à placer en greylist, séparées par des espaces. |
!!! info "Prise en charge du format d'URL"
Tous les paramètres *_URLS prennent en charge les URL HTTP/HTTPS ainsi que les chemins de fichiers locaux avec le préfixe file:///. L'authentification basique est prise en charge avec le format http://user:pass@url.
!!! tip "Mises à jour régulières" Les greylists provenant d'URL sont automatiquement téléchargées et mises à jour toutes les heures afin que votre protection reste à jour avec les dernières sources de confiance.
Exemples de configuration
=== "Configuration de base"
Configuration simple qui applique la greylist au réseau interne et au robot d'exploration d'une entreprise :
```yaml
USE_GREYLIST: "yes"
GREYLIST_IP: "192.168.1.0/24 10.0.0.0/8"
GREYLIST_USER_AGENT: "(?:\b)CompanyCrawler(?:\b)"
```
=== "Configuration avancée"
Configuration plus complète avec plusieurs critères de greylist :
```yaml
USE_GREYLIST: "yes"
# Ressources de l'entreprise et robots approuvés
GREYLIST_IP: "192.168.1.0/24 203.0.113.0/24"
GREYLIST_RDNS: ".company.com .partner-company.org"
GREYLIST_ASN: "12345 67890" # ASN de l'entreprise et du partenaire
GREYLIST_USER_AGENT: "(?:\b)GoodBot(?:\b) (?:\b)PartnerCrawler(?:\b)"
GREYLIST_URI: "^/api/v1/"
# Sources externes de confiance
GREYLIST_IP_URLS: "https://example.com/trusted-networks.txt"
GREYLIST_USER_AGENT_URLS: "https://example.com/trusted-crawlers.txt"
```
=== "Utilisation de fichiers locaux"
Configuration utilisant des fichiers locaux pour les greylists :
```yaml
USE_GREYLIST: "yes"
GREYLIST_IP_URLS: "file:///path/to/ip-greylist.txt"
GREYLIST_RDNS_URLS: "file:///path/to/rdns-greylist.txt"
GREYLIST_ASN_URLS: "file:///path/to/asn-greylist.txt"
GREYLIST_USER_AGENT_URLS: "file:///path/to/user-agent-greylist.txt"
GREYLIST_URI_URLS: "file:///path/to/uri-greylist.txt"
```
=== "Accès API sélectif"
Configuration autorisant l'accès à des endpoints d'API précis :
```yaml
USE_GREYLIST: "yes"
GREYLIST_URI: "^/api/v1/public/ ^/api/v1/status"
GREYLIST_IP: "203.0.113.0/24" # Réseau partenaire externe
```
Travailler avec des fichiers de listes locaux
Les paramètres *_URLS fournis par les plugins Whitelist, Greylist et Blacklist utilisent le même téléchargeur. Lorsque vous référencez une URL file:/// :
- Le chemin est résolu dans le conteneur du scheduler (dans un déploiement Docker il s'agit généralement de
bunkerweb-scheduler). Montez-y vos fichiers et vérifiez que l'utilisateur scheduler possède un accès en lecture. - Chaque fichier est un texte encodé en UTF-8 avec une entrée par ligne. Les lignes vides sont ignorées et les commentaires doivent commencer par
#ou;. Les commentaires//ne sont pas pris en charge. - Valeur attendue selon le type de liste :
- Listes IP acceptent des adresses IPv4/IPv6 ou des réseaux CIDR (par exemple
192.0.2.10ou2001:db8::/48). - Listes rDNS attendent un suffixe sans espaces (par exemple
.search.msn.com). Les valeurs sont automatiquement converties en minuscules. - Listes ASN peuvent contenir uniquement le numéro (
32934) ou le numéro préfixé parAS(AS15169). - Listes User-Agent sont traitées comme des motifs PCRE et la ligne complète est conservée (espaces compris). Placez vos commentaires sur une ligne séparée pour éviter qu'ils ne soient interprétés comme motif.
- Listes URI doivent commencer par
/et peuvent utiliser des jetons PCRE tels que^ou$.
- Listes IP acceptent des adresses IPv4/IPv6 ou des réseaux CIDR (par exemple
Exemples de fichiers conformes :
# /etc/bunkerweb/lists/ip-greylist.txt
192.0.2.10
198.51.100.0/24
# /etc/bunkerweb/lists/ua-greylist.txt
(?:^|\s)FriendlyScanner(?:\s|$)
TrustedMonitor/\d+\.\d+
gRPC
Prise en charge STREAM ❌
Le plugin gRPC permet à BunkerWeb de proxyfier des services gRPC via HTTP/2 avec grpc_pass. Il est conçu pour des environnements multisites où chaque hôte virtuel peut exposer un ou plusieurs backends gRPC sur des chemins spécifiques.
!!! example "Fonctionnalité expérimentale" Cette fonctionnalité n'est pas prête pour la production. N'hésitez pas à la tester et à nous signaler tout bug via les issues du dépôt GitHub.
Fonctionnement :
- Un client envoie une requête HTTP/2 à BunkerWeb.
- Le plugin gRPC fait correspondre une
locationconfigurée (GRPC_URL) et transmet la requête à l'upstream configuré (GRPC_HOST) avecgrpc_pass. - BunkerWeb ajoute des en-têtes de transfert et applique les paramètres de timeout/réessai upstream.
- Le serveur gRPC upstream répond et BunkerWeb relaie la réponse vers le client.
Utilisation
- Activer la fonctionnalité : Définissez
USE_GRPCsuryes. - Configurer le(s) upstream(s) : Définissez au minimum
GRPC_HOST(et éventuellementGRPC_HOST_2,GRPC_HOST_3, ...). - Associer les chemins : Définissez
GRPC_URLpour chaque upstream (avec les suffixes correspondants en cas d'entrées multiples). - Ajuster le comportement : Configurez si besoin les timeouts, les retries, les en-têtes et les options TLS SNI.
Paramètres de configuration
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_GRPC |
no |
multisite | non | Activer gRPC : Mettez yes pour activer le proxy gRPC. |
GRPC_HOST |
multisite | oui | Upstream gRPC : Valeur utilisée par grpc_pass (ex. grpc://service:50051 ou grpcs://...). |
|
GRPC_URL |
/ |
multisite | oui | URL de location : Chemin proxyfié vers l'upstream gRPC. |
GRPC_CUSTOM_HOST |
multisite | non | En-tête Host personnalisé : Remplace l'en-tête Host envoyé à l'upstream. |
|
GRPC_HEADERS |
multisite | oui | En-têtes upstream supplémentaires : Liste séparée par des ; pour grpc_set_header. |
|
GRPC_HIDE_HEADERS |
multisite | oui | En-têtes de réponse masqués : Liste séparée par des espaces pour grpc_hide_header. |
|
GRPC_INTERCEPT_ERRORS |
yes |
multisite | non | Intercepter les erreurs : Active/désactive grpc_intercept_errors. |
GRPC_CONNECT_TIMEOUT |
60s |
multisite | oui | Timeout de connexion : Délai pour établir la connexion vers l'upstream. |
GRPC_READ_TIMEOUT |
60s |
multisite | oui | Timeout de lecture : Délai de lecture depuis l'upstream. |
GRPC_SEND_TIMEOUT |
60s |
multisite | oui | Timeout d'envoi : Délai d'envoi vers l'upstream. |
GRPC_SOCKET_KEEPALIVE |
off |
multisite | oui | Keepalive socket : Active/désactive keepalive sur les sockets upstream. |
GRPC_SSL_SNI |
no |
multisite | non | SSL SNI : Active/désactive SNI pour les upstreams TLS. |
GRPC_SSL_SNI_NAME |
multisite | non | Nom SSL SNI : Nom SNI envoyé quand GRPC_SSL_SNI=yes. |
|
GRPC_NEXT_UPSTREAM |
multisite | oui | Conditions de next upstream : Valeur de grpc_next_upstream. |
|
GRPC_NEXT_UPSTREAM_TIMEOUT |
multisite | oui | Timeout de next upstream : Valeur de grpc_next_upstream_timeout. |
|
GRPC_NEXT_UPSTREAM_TRIES |
multisite | oui | Essais de next upstream : Valeur de grpc_next_upstream_tries. |
|
GRPC_INCLUDES |
multisite | oui | Includes additionnels : Fichiers include séparés par des espaces dans le bloc gRPC location. |
!!! warning "ModSecurity sur les locations gRPC"
ModSecurity est actuellement désactivé automatiquement dans les blocs gRPC location générés par ce plugin, car ModSecurity ne prend pas en charge de manière fiable les schémas de trafic gRPC.
!!! warning "Flux longue durée et timeouts du cœur"
Les RPC longue durée ou en streaming peuvent nécessiter des timeouts NGINX génériques plus élevés que les valeurs globales par défaut. Les réglages les plus courants sont CLIENT_BODY_TIMEOUT et CLIENT_HEADER_TIMEOUT dans les paramètres du plugin General.
!!! tip "Plusieurs backends gRPC"
Utilisez des paramètres suffixés pour plusieurs routes :
- GRPC_HOST, GRPC_URL
- GRPC_HOST_2, GRPC_URL_2
- GRPC_HOST_3, GRPC_URL_3
Exemples de configuration
=== "Proxy gRPC de base"
```yaml
USE_GRPC: "yes"
GRPC_HOST: "grpc://grpcbin:9000"
GRPC_URL: "/"
GRPC_CONNECT_TIMEOUT: "10s"
GRPC_READ_TIMEOUT: "300s"
GRPC_SEND_TIMEOUT: "300s"
```
=== "Upstream TLS (grpcs + SNI)"
```yaml
USE_GRPC: "yes"
GRPC_HOST: "grpcs://internal-grpc.example.net:443"
GRPC_URL: "/"
GRPC_SSL_SNI: "yes"
GRPC_SSL_SNI_NAME: "internal-grpc.example.net"
```
=== "Plusieurs chemins / backends"
```yaml
USE_GRPC: "yes"
GRPC_HOST: "grpc://user-service:50051"
GRPC_URL: "/users.UserService/"
GRPC_HOST_2: "grpc://billing-service:50052"
GRPC_URL_2: "/billing.BillingService/"
GRPC_HOST_3: "grpc://inventory-service:50053"
GRPC_URL_3: "/inventory.InventoryService/"
```
=== "En-têtes et politique de retry"
```yaml
USE_GRPC: "yes"
GRPC_HOST: "grpc://grpcbin:9000"
GRPC_URL: "/"
GRPC_HEADERS: "x-request-source bunkerweb;x-env production"
GRPC_NEXT_UPSTREAM: "error timeout unavailable"
GRPC_NEXT_UPSTREAM_TIMEOUT: "15s"
GRPC_NEXT_UPSTREAM_TRIES: "3"
```
Gzip
Prise en charge STREAM ❌
Le plugin GZIP compresse les réponses HTTP avec l’algorithme gzip pour réduire la bande passante et accélérer le chargement des pages.
Fonctionnement
- BunkerWeb détecte si le client supporte gzip.
- Si oui, la réponse est compressée au niveau configuré.
- Les en‑têtes indiquent l’usage de gzip.
- Le navigateur décompresse avant l’affichage.
- La bande passante et les temps de chargement diminuent, améliorant les performances globales du site.
Comment l’utiliser
- Activer : mettez le paramètre
USE_GZIPàyes(désactivé par défaut). - Types MIME : définir
GZIP_TYPES. - Taille minimale :
GZIP_MIN_LENGTHpour éviter les très petits fichiers. - Niveau de compression :
GZIP_COMP_LEVEL(1–9). - Contenu proxifié : ajuster
GZIP_PROXIED.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_GZIP |
no |
multisite | non | Activer la compression gzip. |
GZIP_TYPES |
application/atom+xml application/javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-opentype application/x-font-truetype application/x-font-ttf application/x-javascript application/xhtml+xml application/xml font/eot font/opentype font/otf font/truetype image/svg+xml image/vnd.microsoft.icon image/x-icon image/x-win-bitmap text/css text/javascript text/plain text/xml |
multisite | non | Types MIME compressés. |
GZIP_MIN_LENGTH |
1000 |
multisite | non | Taille minimale (octets) pour appliquer la compression. |
GZIP_COMP_LEVEL |
5 |
multisite | non | Niveau 1–9 : plus haut = meilleure compression mais plus de CPU. |
GZIP_PROXIED |
no-cache no-store private expired auth |
multisite | non | Précise quels contenus proxifiés doivent être compressés selon les en‑têtes de réponse. |
!!! tip "Niveau de compression"
5 est un bon compromis. Statique/CPU dispo : 7–9. Dynamique/CPU limité : 1–3.
!!! info "Compatibilité navigateurs" GZIP est pris en charge par tous les navigateurs modernes et constitue depuis longtemps la méthode de compression standard des réponses HTTP, avec une excellente compatibilité entre appareils et navigateurs.
!!! warning "Compression vs utilisation CPU" La compression GZIP réduit la bande passante et améliore les temps de chargement, mais les niveaux de compression élevés consomment plus de CPU. Pour les sites à fort trafic, trouvez le bon équilibre entre efficacité de compression et performance serveur.
Exemples
=== "Basique"
```yaml
USE_GZIP: "yes"
GZIP_TYPES: "application/javascript application/json application/xml text/css text/html text/javascript text/plain text/xml"
GZIP_MIN_LENGTH: "1000"
GZIP_COMP_LEVEL: "5"
```
=== "Compression maximale"
```yaml
USE_GZIP: "yes"
GZIP_TYPES: "application/atom+xml application/javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-opentype application/x-font-truetype application/x-font-ttf application/x-javascript application/xhtml+xml application/xml font/eot font/opentype font/otf font/truetype image/svg+xml image/vnd.microsoft.icon image/x-icon image/x-win-bitmap text/css text/javascript text/plain text/xml"
GZIP_MIN_LENGTH: "500"
GZIP_COMP_LEVEL: "9"
GZIP_PROXIED: "any"
```
=== "Performance équilibrée"
```yaml
USE_GZIP: "yes"
GZIP_TYPES: "application/javascript application/json text/css text/html text/javascript text/plain"
GZIP_MIN_LENGTH: "1000"
GZIP_COMP_LEVEL: "3"
GZIP_PROXIED: "no-cache no-store private expired"
```
=== "Contenu proxifié"
```yaml
USE_GZIP: "yes"
GZIP_TYPES: "application/javascript application/json text/css text/html text/javascript"
GZIP_MIN_LENGTH: "1000"
GZIP_COMP_LEVEL: "4"
GZIP_PROXIED: "any"
```
Headers
Prise en charge STREAM ❌
Les en-têtes HTTP jouent un rôle crucial dans la sécurité. Le plugin Headers offre une gestion robuste des en-têtes HTTP standards et personnalisés, améliorant ainsi la sécurité et les fonctionnalités. Il applique dynamiquement des mesures de sécurité, telles que HSTS, CSP (y compris un mode de rapport seul), et l'injection d'en-têtes personnalisés, tout en empêchant les fuites d'informations.
Comment ça marche
- Lorsqu'un client demande du contenu depuis votre site web, BunkerWeb traite les en-têtes de la réponse.
- Les en-têtes de sécurité sont appliqués conformément à votre configuration.
- Des en-têtes personnalisés peuvent être ajoutés pour fournir des informations ou des fonctionnalités supplémentaires aux clients.
- Les en-têtes indésirables qui pourraient révéler des informations sur le serveur sont automatiquement supprimés.
- Les cookies sont modifiés pour inclure les attributs de sécurité appropriés en fonction de vos paramètres.
- Les en-têtes des serveurs en amont peuvent être préservés de manière sélective lorsque cela est nécessaire.
Comment l’utiliser
Suivez ces étapes pour configurer et utiliser la fonctionnalité Headers :
- Configurer les en-têtes de sécurité : Définissez des valeurs pour les en-têtes courants.
- Ajouter des en-têtes personnalisés : Définissez les en-têtes personnalisés à l'aide du paramètre
CUSTOM_HEADER. - Supprimer les en-têtes indésirables : Utilisez
REMOVE_HEADERSpour vous assurer que les en-têtes qui pourraient exposer des détails sur le serveur sont supprimés. - Définir la sécurité des cookies : Activez une sécurité robuste des cookies en configurant
COOKIE_FLAGSet en réglantCOOKIE_AUTO_SECURE_FLAGsuryespour que l'attribut Secure soit automatiquement ajouté sur les connexions HTTPS. - Préserver les en-têtes en amont : Spécifiez les en-têtes en amont à conserver en utilisant
KEEP_UPSTREAM_HEADERS. - Tirer parti de l'application conditionnelle des en-têtes : Si vous souhaitez tester des politiques sans interruption, activez le mode CSP Report-Only via
CONTENT_SECURITY_POLICY_REPORT_ONLY.
Guide de configuration
=== "En-têtes de sécurité"
**Aperçu**
Les en-têtes de sécurité renforcent la communication sécurisée, restreignent le chargement des ressources et préviennent les attaques comme le clickjacking et l'injection. Des en-têtes correctement configurés créent une couche de défense robuste pour votre site web.
!!! success "Avantages des en-têtes de sécurité"
- **HSTS :** Assure que toutes les connexions sont chiffrées, protégeant contre les attaques de rétrogradation de protocole.
- **CSP :** Empêche l'exécution de scripts malveillants, réduisant le risque d'attaques XSS.
- **X-Frame-Options :** Bloque les tentatives de clickjacking en contrôlant l'intégration des iframes.
- **Referrer Policy :** Limite les fuites d'informations sensibles via les en-têtes referrer.
| Paramètre | Défaut | Contexte | Multiple | Description |
| ------------------------------------- | --------------------------------------------------------------------------------------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STRICT_TRANSPORT_SECURITY` | `max-age=63072000; includeSubDomains; preload` | multisite | non | **HSTS :** Force les connexions HTTPS sécurisées, réduisant les risques d'attaques de type "man-in-the-middle". |
| `CONTENT_SECURITY_POLICY` | `object-src 'none'; form-action 'self'; frame-ancestors 'self';` | multisite | non | **CSP :** Restreint le chargement des ressources aux sources de confiance, atténuant les attaques de type cross-site scripting et d'injection de données. |
| `CONTENT_SECURITY_POLICY_REPORT_ONLY` | `no` | multisite | non | **Mode rapport CSP :** Signale les violations sans bloquer le contenu, aidant à tester les politiques de sécurité tout en capturant les journaux. |
| `X_FRAME_OPTIONS` | `SAMEORIGIN` | multisite | non | **X-Frame-Options :** Empêche le clickjacking en contrôlant si votre site peut être intégré dans une frame. |
| `X_CONTENT_TYPE_OPTIONS` | `nosniff` | multisite | non | **X-Content-Type-Options :** Empêche les navigateurs de "MIME-sniffer", protégeant contre les attaques de type "drive-by download". |
| `X_DNS_PREFETCH_CONTROL` | `off` | multisite | non | **X-DNS-Prefetch-Control :** Régule le préchargement DNS pour réduire les requêtes réseau involontaires et améliorer la confidentialité. |
| `REFERRER_POLICY` | `strict-origin-when-cross-origin` | multisite | non | **Politique de Referrer :** Contrôle la quantité d'informations de référent envoyées, protégeant la vie privée de l'utilisateur. |
| `PERMISSIONS_POLICY` | `accelerometer=(), ambient-light-sensor=(), attribution-reporting=(), autoplay=(), battery=(), ...` | multisite | non | **Politique de permissions :** Restreint l'accès aux fonctionnalités du navigateur, réduisant les vecteurs d'attaque potentiels. |
| `KEEP_UPSTREAM_HEADERS` | `Content-Security-Policy Permissions-Policy X-Frame-Options` | multisite | non | **Conserver les en-têtes :** Préserve les en-têtes en amont sélectionnés, facilitant l'intégration héritée tout en maintenant la sécurité. |
!!! tip "Bonnes pratiques"
- Révisez et mettez à jour régulièrement vos en-têtes de sécurité pour vous conformer aux normes de sécurité en constante évolution.
- Utilisez des outils comme [Mozilla Observatory](https://observatory.mozilla.org/) pour valider la configuration de vos en-têtes.
- Testez la CSP en mode `Report-Only` avant de l'appliquer pour éviter de casser des fonctionnalités.
=== "Paramètres des cookies"
**Aperçu**
Des paramètres de cookies appropriés garantissent la sécurité des sessions utilisateur en empêchant le détournement, la fixation et le cross-site scripting. Les cookies sécurisés maintiennent l'intégrité de la session sur HTTPS et améliorent la protection globale des données des utilisateurs.
!!! success "Avantages des cookies sécurisés"
- **Attribut HttpOnly :** Empêche les scripts côté client d'accéder aux cookies, atténuant les risques XSS.
- **Attribut SameSite :** Réduit les attaques CSRF en restreignant l'utilisation des cookies inter-origines.
- **Attribut Secure :** Assure que les cookies ne sont transmis que sur des connexions HTTPS chiffrées.
| Paramètre | Défaut | Contexte | Multiple | Description |
| ------------------------- | ------------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COOKIE_FLAGS` | `* HttpOnly SameSite=Lax` | multisite | oui | **Attributs de cookie :** Ajoute automatiquement des attributs de sécurité tels que HttpOnly et SameSite, protégeant les cookies de l'accès par des scripts côté client et des attaques CSRF. |
| `COOKIE_AUTO_SECURE_FLAG` | `yes` | multisite | non | **Attribut Secure automatique :** Assure que les cookies ne sont envoyés que sur des connexions HTTPS sécurisées en ajoutant automatiquement l'attribut Secure. |
!!! tip "Bonnes pratiques"
- Utilisez `SameSite=Strict` pour les cookies sensibles afin d'empêcher l'accès inter-origines.
- Auditez régulièrement vos paramètres de cookies pour assurer la conformité avec les réglementations de sécurité et de confidentialité.
- Évitez de définir des cookies sans l'attribut Secure dans les environnements de production.
=== "En-têtes personnalisés"
**Aperçu**
Les en-têtes personnalisés vous permettent d'ajouter des en-têtes HTTP spécifiques pour répondre aux exigences de l'application ou de performance. Ils offrent de la flexibilité mais doivent être configurés avec soin pour éviter d'exposer des détails sensibles du serveur.
!!! success "Avantages des en-têtes personnalisés"
- Améliorez la sécurité en supprimant les en-têtes inutiles qui pourraient divulguer des détails sur le serveur.
- Ajoutez des en-têtes spécifiques à l'application pour améliorer la fonctionnalité ou le débogage.
| Paramètre | Défaut | Contexte | Multiple | Description |
| ---------------- | ------------------------------------------------------------------------------------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CUSTOM_HEADER` | | multisite | oui | **En-tête personnalisé :** Permet d'ajouter des en-têtes définis par l'utilisateur au format NomEnTete: ValeurEnTete pour des améliorations de sécurité ou de performance spécialisées. |
| `REMOVE_HEADERS` | `Server Expect-CT X-Powered-By X-AspNet-Version X-AspNetMvc-Version Public-Key-Pins` | multisite | non | **Supprimer les en-têtes :** Spécifie les en-têtes à supprimer, réduisant ainsi le risque d'exposer des détails internes du serveur et des vulnérabilités connues. |
!!! warning "Considérations de sécurité"
- Évitez d'exposer des informations sensibles via des en-têtes personnalisés.
- Révisez et mettez à jour régulièrement les en-têtes personnalisés pour les aligner sur les exigences de votre application.
!!! tip "Bonnes pratiques"
- Utilisez `REMOVE_HEADERS` pour supprimer les en-têtes comme `Server` et `X-Powered-By` afin de réduire les risques de prise d'empreintes.
- Testez les en-têtes personnalisés dans un environnement de pré-production avant de les déployer en production.
Exemples de configuration
=== "En-têtes de sécurité de base"
Une configuration standard avec les en-têtes de sécurité essentiels :
```yaml
STRICT_TRANSPORT_SECURITY: "max-age=63072000; includeSubDomains; preload"
CONTENT_SECURITY_POLICY: "default-src 'self'; script-src 'self'; object-src 'none'; frame-ancestors 'self'"
X_FRAME_OPTIONS: "SAMEORIGIN"
X_CONTENT_TYPE_OPTIONS: "nosniff"
REFERRER_POLICY: "strict-origin-when-cross-origin"
REMOVE_HEADERS: "Server X-Powered-By X-AspNet-Version"
```
=== "Sécurité des cookies renforcée"
Configuration avec des paramètres de sécurité des cookies robustes :
```yaml
COOKIE_FLAGS: "* HttpOnly SameSite=Strict"
COOKIE_FLAGS_2: "session_cookie Secure HttpOnly SameSite=Strict"
COOKIE_FLAGS_3: "auth_cookie Secure HttpOnly SameSite=Strict Max-Age=3600"
COOKIE_AUTO_SECURE_FLAG: "yes"
```
=== "En-têtes personnalisés pour API"
Configuration pour un service API avec des en-têtes personnalisés :
```yaml
CUSTOM_HEADER: "API-Version: 1.2.3"
CUSTOM_HEADER_2: "Access-Control-Max-Age: 86400"
CONTENT_SECURITY_POLICY: "default-src 'none'; frame-ancestors 'none'"
REMOVE_HEADERS: "Server X-Powered-By X-AspNet-Version X-Runtime"
```
=== "Content Security Policy - Mode rapport"
Configuration pour tester la CSP sans casser les fonctionnalités :
```yaml
CONTENT_SECURITY_POLICY: "default-src 'self'; script-src 'self' https://trusted-cdn.example.com; img-src 'self' data: https://*.example.com; style-src 'self' 'unsafe-inline' https://trusted-cdn.example.com; connect-src 'self' https://api.example.com; object-src 'none'; frame-ancestors 'self'; form-action 'self'; base-uri 'self'; report-uri https://example.com/csp-reports"
CONTENT_SECURITY_POLICY_REPORT_ONLY: "yes"
```
HTML injection
Prise en charge STREAM ❌
Le plugin d’injection HTML permet d’ajouter du code HTML personnalisé dans les pages de votre site juste avant </body> ou </head>. Idéal pour intégrer des scripts d’analytics, pixels de tracking, JS/CSS personnalisés ou des intégrations tierces sans modifier le code source de votre application.
Comment ça marche :
- À la livraison d’une page, BunkerWeb inspecte la réponse HTML.
- Si l’injection « body » est configurée, il insère votre HTML juste avant
</body>. - Si l’injection « head » est configurée, il insère votre HTML juste avant
</head>. - L’insertion s’applique automatiquement à toutes les pages HTML servies.
- Cela permet d’ajouter scripts, styles ou autres éléments sans modifier le code de votre application.
Comment l’utiliser
- Préparez votre HTML personnalisé.
- Choisissez l’emplacement :
<head>,<body>, ou les deux. - Renseignez
INJECT_HEADet/ouINJECT_BODYavec votre code. - Laissez BunkerWeb gérer le reste : une fois configuré, le HTML sera injecté automatiquement dans toutes les pages HTML servies.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
INJECT_HEAD |
multisite | non | Code HTML injecté avant </head>. |
|
INJECT_BODY |
multisite | non | Code HTML injecté avant </body>. |
!!! tip "Bonnes pratiques" - Placez de préférence les scripts JS en fin de body pour éviter de bloquer le rendu. - Mettez le CSS et le JS critique dans le head pour éviter le flash de contenu non stylé. - Attention au contenu injecté qui pourrait casser le site.
!!! info "Cas d’utilisation courants" - Ajouter des scripts d’analytics comme Google Analytics ou Matomo. - Intégrer des widgets de chat ou des outils de support client. - Inclure des pixels de suivi pour des campagnes marketing. - Ajouter des styles CSS personnalisés ou des fonctionnalités JavaScript. - Inclure des bibliothèques tierces sans modifier le code de votre application.
Exemples
=== "Google Analytics"
```yaml
INJECT_HEAD: ""
INJECT_BODY: '<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script><script>window.dataLayer = window.dataLayer || [];function gtag(){dataLayer.push(arguments);}gtag(''js'', new Date());gtag(''config'', ''G-XXXXXXXXXX'');</script>'
```
=== "Styles personnalisés"
```yaml
INJECT_HEAD: "<style>body { font-family: 'Arial', sans-serif; } .custom-element { color: blue; }</style>"
INJECT_BODY: ""
```
=== "Intégrations multiples"
```yaml
INJECT_HEAD: "<style>body { font-family: 'Arial', sans-serif; } .notification-banner { background: #f8f9fa; padding: 10px; text-align: center; }</style>"
INJECT_BODY: '<script src="https://cdn.example.com/js/widget.js"></script><script>initializeWidget(''your-api-key'');</script>'
```
=== "Bandeau cookies"
```yaml
INJECT_HEAD: "<style>.cookie-banner { position: fixed; bottom: 0; left: 0; right: 0; background: #f1f1f1; padding: 20px; text-align: center; z-index: 1000; } .cookie-banner button { background: #4CAF50; border: none; color: white; padding: 10px 20px; cursor: pointer; }</style>"
INJECT_BODY: '<div id="cookie-banner" class="cookie-banner">This website uses cookies to ensure you get the best experience. <button onclick="acceptCookies()">Accept</button></div><script>function acceptCookies() { document.getElementById(''cookie-banner'').style.display = ''none''; localStorage.setItem(''cookies-accepted'', ''true''); } if(localStorage.getItem(''cookies-accepted'') === ''true'') { document.getElementById(''cookie-banner'').style.display = ''none''; }</script>'
```
LDAP SSO (PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ❌
LDAP-based single sign-on plugin with session-backed authentication.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_LDAP |
no |
multisite | non | Enable or disable LDAP SSO authentication. |
LDAP_HOST |
multisite | non | LDAP server hostname or IP address. | |
LDAP_PORT |
389 |
multisite | non | LDAP server port (389 for LDAP/STARTTLS, 636 for LDAPS). |
LDAP_LDAPS |
no |
multisite | non | Use LDAPS (TLS from connection start). |
LDAP_STARTTLS |
no |
multisite | non | Use STARTTLS upgrade on LDAP connection. |
LDAP_SSL_VERIFY |
yes |
multisite | non | Verify server TLS certificate. |
LDAP_TIMEOUT |
10000 |
multisite | non | LDAP socket timeout in milliseconds. |
LDAP_KEEPALIVE_TIMEOUT |
60000 |
multisite | non | LDAP keepalive timeout in milliseconds. |
LDAP_KEEPALIVE_POOL_SIZE |
10 |
multisite | non | LDAP keepalive connection pool size. |
LDAP_KEEPALIVE_POOL_NAME |
multisite | non | Optional custom LDAP keepalive pool name. | |
LDAP_BIND_DN |
multisite | non | Optional service account DN used to perform LDAP user searches. | |
LDAP_BIND_PASSWORD |
multisite | non | Password for LDAP Bind DN service account. | |
LDAP_USER_SEARCH_BASE_DN |
multisite | non | Base DN for user discovery search (enables enterprise search mode when set). | |
LDAP_USER_SEARCH_FILTER |
(&(objectClass=person)(|(uid={username})(mail={username})(sAMAccountName={username})(userPrincipalName={username}))) |
multisite | non | LDAP user search filter template. Use {username} placeholder. |
LDAP_AUTHZ_FILTER |
multisite | non | Optional extra LDAP authorization filter (AND-ed with user search filter). | |
LDAP_USER_SEARCH_SCOPE |
subtree |
multisite | non | LDAP search scope for user lookup. |
LDAP_USER_SEARCH_DEREF_ALIASES |
always |
multisite | non | LDAP alias dereferencing mode during user lookup. |
LDAP_USER_SEARCH_SIZE_LIMIT |
10 |
multisite | non | Maximum number of LDAP entries returned by user search. |
LDAP_USER_SEARCH_TIME_LIMIT |
10 |
multisite | non | Maximum LDAP user search time in seconds. |
LDAP_USER_SEARCH_ATTRIBUTES |
dn |
multisite | non | Attributes requested during user search (space separated). |
LDAP_USER_SEARCH_DN_FIELD |
object_name |
multisite | non | Preferred field name in search response to extract user DN (e.g. object_name, dn). |
LDAP_USER_SEARCH_REQUIRE_UNIQUE |
yes |
multisite | non | Require exactly one search result before authenticating user. |
LDAP_USER_DN_TEMPLATE |
uid={username},ou=people,dc=example,dc=com |
multisite | non | User DN template used for direct bind fallback. Must include {username} when set. |
LDAP_USERNAME_REGEX |
^[A-Za-z0-9@._-]+$ |
multisite | non | PCRE regex used to validate submitted usernames. |
LDAP_LOGIN_PATH |
/ldap/login |
multisite | non | Login page path exposed by the LDAP plugin. |
LDAP_LOGOUT_PATH |
/ldap/logout |
multisite | non | Logout path exposed by the LDAP plugin. |
LDAP_SESSION_TTL |
3600 |
multisite | non | LDAP session validity duration in seconds. |
LDAP_REALM |
LDAP SSO |
multisite | non | Authentication realm displayed on LDAP login form. |
LDAP_USER_HEADER |
X-User |
multisite | non | Header to pass authenticated username to upstream (empty to disable). |
LDAP_REDIRECT_AFTER_LOGIN |
/ |
multisite | non | Fallback relative path after successful login when no redirect target is provided. |
LDAP_REDIRECT_AFTER_LOGOUT |
/ |
multisite | non | Relative path to redirect users to after logout. |
Let's Encrypt
Prise en charge STREAM ✅
Le plugin Let’s Encrypt simplifie la gestion des certificats SSL/TLS en automatisant la création, le renouvellement et la configuration de certificats gratuits de Let's Encrypt. Cette fonctionnalité active les connexions HTTPS sécurisées pour vos sites web sans la complexité de la gestion manuelle des certificats, réduisant ainsi les coûts et la charge administrative.
Comment ça marche :
- Une fois activé, BunkerWeb détecte automatiquement les domaines configurés pour votre site.
- BunkerWeb demande des certificats SSL/TLS gratuits à l'autorité de certification de Let's Encrypt.
- La propriété du domaine est vérifiée par des défis HTTP (prouvant que vous contrôlez le site) ou des défis DNS (prouvant que vous contrôlez le DNS de votre domaine).
- Les certificats sont automatiquement installés et configurés pour vos domaines.
- BunkerWeb gère les renouvellements de certificats en arrière-plan avant leur expiration, assurant une disponibilité HTTPS continue.
- L'ensemble du processus est entièrement automatisé, ne nécessitant qu'une intervention minimale après la configuration initiale.
!!! info "Prérequis" Pour utiliser cette fonctionnalité, assurez-vous que des enregistrements DNS A corrects sont configurés pour chaque domaine, pointant vers la ou les IP publiques où BunkerWeb est accessible. Sans une configuration DNS correcte, le processus de vérification de domaine échouera.
Comment l’utiliser
Suivez ces étapes pour configurer et utiliser la fonctionnalité Let's Encrypt :
- Activer la fonctionnalité : Mettez le paramètre
AUTO_LETS_ENCRYPTàyespour activer l'émission et le renouvellement automatiques des certificats. - Fournir un e-mail de contact (recommandé) : Saisissez votre adresse e-mail dans le paramètre
EMAIL_LETS_ENCRYPTpour que Let's Encrypt puisse vous prévenir avant l'expiration d'un certificat. Si vous laissez ce champ vide, BunkerWeb s'enregistrera sans adresse (option Certbot--register-unsafely-without-email) et vous ne recevrez aucun rappel ni e-mail de récupération. - Choisir l'autorité de certification : Définissez
LETS_ENCRYPT_SERVERsurletsencrypt(par défaut) ouzerossl. - Fournir les identifiants ZeroSSL (si nécessaire) : En utilisant
zerossl, renseignezEMAIL_LETS_ENCRYPTouLETS_ENCRYPT_ZEROSSL_API_KEYafin quezerossl-botpuisse récupérer les identifiants EAB. - Choisir le type de défi : Sélectionnez la vérification
httpoudnsavec le paramètreLETS_ENCRYPT_CHALLENGE. - Configurer le fournisseur DNS : Si vous utilisez les défis DNS, spécifiez votre fournisseur DNS et vos identifiants.
- Sélectionner un profil de certificat : Choisissez votre profil de certificat préféré avec le paramètre
LETS_ENCRYPT_PROFILE(classic, tlsserver ou shortlived). - Laissez BunkerWeb s'occuper du reste : Une fois configuré, les certificats sont automatiquement émis, installés et renouvelés selon les besoins.
!!! tip "Profils de certificat" Let's Encrypt propose différents profils de certificat pour différents cas d'usage :
- **classic** : Certificats à usage général avec une validité de 90 jours (par défaut)
- **tlsserver** : Optimisé pour l'authentification de serveur TLS avec une validité de 90 jours et une charge utile plus petite
- **shortlived** : Sécurité renforcée avec une validité de 7 jours pour les environnements automatisés
- **custom** : Si votre serveur ACME prend en charge un profil différent, définissez-le avec `LETS_ENCRYPT_CUSTOM_PROFILE`.
!!! info "Disponibilité des profils"
Notez que les profils tlsserver et shortlived peuvent ne pas être disponibles dans tous les environnements ou avec tous les clients ACME pour le moment. Le profil classic a la compatibilité la plus large et est recommandé pour la plupart des utilisateurs. Si un profil sélectionné n'est pas disponible, le système basculera automatiquement sur le profil classic.
Paramètres de configuration
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
AUTO_LETS_ENCRYPT |
no |
multisite | no | Activer Let's Encrypt : Mettre à yes pour activer l'émission et le renouvellement automatiques des certificats. |
LETS_ENCRYPT_PASSTHROUGH |
no |
multisite | no | Passer à travers Let's Encrypt : Mettre à yes pour passer les requêtes Let's Encrypt au serveur web. Utile si BunkerWeb est devant un autre reverse proxy gérant le SSL. |
EMAIL_LETS_ENCRYPT |
- |
multisite | no | E-mail de contact : Adresse e-mail utilisée pour les rappels Let's Encrypt. Ne laissez ce champ vide que si vous acceptez de ne recevoir aucun avertissement ni e-mail de récupération (Certbot s'enregistre avec --register-unsafely-without-email). |
LETS_ENCRYPT_SERVER |
letsencrypt |
multisite | no | Autorité de certification : Sélectionnez le serveur ACME utilisé pour l'émission. Options : letsencrypt ou zerossl. |
LETS_ENCRYPT_ZEROSSL_API_KEY |
multisite | no | Clé API ZeroSSL : Clé optionnelle utilisée par zerossl-bot lorsque LETS_ENCRYPT_SERVER=zerossl. Si elle est vide, EMAIL_LETS_ENCRYPT est utilisé pour récupérer les identifiants EAB. |
|
LETS_ENCRYPT_ZEROSSL_API_RETRY |
3 |
multisite | no | Tentatives API ZeroSSL : Nombre de tentatives pour les requêtes API ZeroSSL effectuées par zerossl-bot (0 désactive les tentatives). |
LETS_ENCRYPT_ZEROSSL_API_RETRY_DELAY |
2 |
multisite | no | Délai de tentative ZeroSSL : Délai en secondes entre les tentatives API ZeroSSL dans zerossl-bot. |
LETS_ENCRYPT_ZEROSSL_API_CONNECT_TIMEOUT |
5 |
multisite | no | Délai de connexion ZeroSSL : Délai de connexion en secondes pour les appels API ZeroSSL dans zerossl-bot. |
LETS_ENCRYPT_ZEROSSL_API_MAX_TIME |
20 |
multisite | no | Durée maximale de requête ZeroSSL : Durée totale maximale en secondes pour chaque appel API ZeroSSL dans zerossl-bot. |
LETS_ENCRYPT_CHALLENGE |
http |
multisite | no | Type de défi : Méthode utilisée pour vérifier la propriété du domaine. Options : http ou dns. |
LETS_ENCRYPT_DNS_PROVIDER |
multisite | no | Fournisseur DNS : Pour les défis DNS, le fournisseur à utiliser (ex. : cloudflare, route53, digitalocean). | |
LETS_ENCRYPT_DNS_PROPAGATION |
default |
multisite | no | Propagation DNS : Le temps d'attente en secondes pour la propagation DNS. Si aucune valeur n'est fournie, le temps par défaut du fournisseur est utilisé. |
LETS_ENCRYPT_DNS_CREDENTIAL_ITEM |
multisite | yes | Élément d'identification : Éléments de configuration pour l'authentification du fournisseur DNS (ex. : cloudflare_api_token 123456). Les valeurs peuvent être du texte brut, encodées en base64 ou un objet JSON. |
|
LETS_ENCRYPT_DNS_CREDENTIAL_DECODE_BASE64 |
yes |
multisite | no | Décoder les identifiants DNS Base64 : Décoder automatiquement les identifiants du fournisseur DNS encodés en base64 lorsqu'il est défini sur yes. Les valeurs au format base64 sont décodées avant utilisation (sauf pour le fournisseur rfc2136). Désactivez si vos identifiants sont intentionnellement en base64. |
USE_LETS_ENCRYPT_WILDCARD |
no |
multisite | no | Certificats Wildcard : Si mis à yes, crée des certificats wildcard pour tous les domaines. Uniquement disponible avec les défis DNS. |
USE_LETS_ENCRYPT_STAGING |
no |
multisite | no | Utiliser Staging : Si mis à yes, utilise l'environnement de staging de Let's Encrypt pour les tests. Les limites de débit y sont plus élevées mais les certificats ne sont pas fiables. |
LETS_ENCRYPT_CLEAR_OLD_CERTS |
no |
global | no | Effacer les anciens certificats : Si mis à yes, supprime les anciens certificats inutiles lors du renouvellement. |
LETS_ENCRYPT_CONCURRENT_REQUESTS |
no |
global | no | Requêtes concurrentes : Si mis à yes, certbot-new effectue les demandes de certificats en parallèle. À utiliser avec prudence pour éviter les limites de débit. |
LETS_ENCRYPT_PROFILE |
classic |
multisite | no | Profil de certificat : Sélectionnez le profil à utiliser. Options : classic (général), tlsserver (optimisé TLS), ou shortlived (7 jours). |
LETS_ENCRYPT_CUSTOM_PROFILE |
multisite | no | Profil de certificat personnalisé : Saisissez un profil personnalisé si votre serveur ACME le supporte. Remplace LETS_ENCRYPT_PROFILE s'il est défini. |
|
LETS_ENCRYPT_MAX_RETRIES |
3 |
multisite | no | Tentatives maximales : Nombre de tentatives de génération de certificat en cas d'échec. 0 pour désactiver. Utile pour les problèmes réseau temporaires. |
LETS_ENCRYPT_MAX_LOG_BACKUPS |
50 |
global | no | Nombre maximal de sauvegardes de logs Certbot : Nombre de sauvegardes rotatives de letsencrypt.log que Certbot conserve par job. La valeur par défaut de Certbot, 1000, s'accumule vite ; 50 est une limite raisonnable. Définissez 0 pour ne conserver que le log actif. |
!!! info "Information et comportement"
- Le paramètre LETS_ENCRYPT_DNS_CREDENTIAL_ITEM est un paramètre multiple et peut être utilisé pour définir plusieurs éléments pour le fournisseur DNS. Les éléments seront enregistrés dans un fichier de cache, et Certbot lira les informations d'identification à partir de celui-ci.
- Si aucun paramètre LETS_ENCRYPT_DNS_PROPAGATION n'est fourni, le temps de propagation par défaut du fournisseur est utilisé.
- L'automatisation complète de Let's Encrypt avec le défi http fonctionne en mode stream tant que vous ouvrez le port 80/tcp depuis l'extérieur. Utilisez le paramètre LISTEN_STREAM_PORT_SSL pour choisir votre port d'écoute SSL/TLS.
- Si LETS_ENCRYPT_PASSTHROUGH est mis à yes, BunkerWeb ne gérera pas les requêtes de défi ACME lui-même mais les transmettra au serveur web backend. Ceci est utile dans les scénarios où BunkerWeb agit comme un reverse proxy devant un autre serveur configuré pour gérer les défis Let's Encrypt.
!!! tip "Défis HTTP vs. DNS" Les défis HTTP sont plus simples à configurer et fonctionnent bien pour la plupart des sites web :
- Nécessite que votre site soit publiquement accessible sur le port 80
- Configuré automatiquement par BunkerWeb
- Ne peut pas être utilisé pour les certificats wildcard
**Les défis DNS** offrent plus de flexibilité et sont requis pour les certificats wildcard :
- Fonctionne même si votre site n'est pas publiquement accessible
- Nécessite les identifiants de l'API de votre fournisseur DNS
- Requis pour les certificats wildcard (ex. : *.example.com)
- Utile lorsque le port 80 est bloqué ou indisponible
!!! warning "Certificats wildcard"
Les certificats wildcard ne sont disponibles qu'avec les défis DNS. Si vous souhaitez les utiliser, vous devez mettre le paramètre USE_LETS_ENCRYPT_WILDCARD à yes et configurer correctement les identifiants de votre fournisseur DNS.
!!! warning "Limites de débit"
Let's Encrypt impose des limites de débit sur l'émission de certificats. Lors du test de configurations, utilisez l'environnement de staging en mettant USE_LETS_ENCRYPT_STAGING à yes pour éviter d'atteindre les limites de production. Les certificats de staging ne sont pas reconnus par les navigateurs mais sont utiles pour valider votre configuration.
Fournisseurs DNS supportés
Le plugin Let's Encrypt prend en charge un large éventail de fournisseurs DNS pour les défis DNS. Chaque fournisseur nécessite des informations d'identification spécifiques qui doivent être fournies via le paramètre LETS_ENCRYPT_DNS_CREDENTIAL_ITEM.
| Fournisseur | Description | Paramètres obligatoires | Paramètres optionnels | Documentation |
|---|---|---|---|---|
bunny |
bunny.net | api_key |
Documentation | |
cloudns |
ClouDNS | soit auth_id, sub_auth_id, ou sub_auth_useret auth_password |
Documentation | |
cloudflare |
Cloudflare | soit api_tokensoit email et api_key |
Documentation | |
desec |
deSEC | token |
Documentation | |
digitalocean |
DigitalOcean | token |
Documentation | |
domainoffensive |
Domain-Offensive | api_token |
Documentation | |
domeneshop |
Domeneshop | client_tokenclient_secret |
Documentation | |
dnsimple |
DNSimple | token |
Documentation | |
dnsmadeeasy |
DNS Made Easy | api_keysecret_key |
Documentation | |
duckdns |
DuckDNS | duckdns_token |
Documentation | |
dynu |
Dynu | auth_token |
Documentation | |
gandi |
Gandi | token |
sharing_id |
Documentation |
gehirn |
Gehirn DNS | api_tokenapi_secret |
Documentation | |
godaddy |
GoDaddy | keysecret |
ttl (défaut : 600) |
Documentation |
google |
Google Cloud | project_idprivate_key_idprivate_keyclient_emailclient_idclient_x509_cert_url |
type (défaut : service_account)auth_uri (défaut : https://accounts.google.com/o/oauth2/auth)token_uri (défaut : https://accounts.google.com/o/oauth2/token)auth_provider_x509_cert_url (défaut : https://www.googleapis.com/oauth2/v1/certs) |
Documentation |
hetzner |
Hetzner | api_token |
Documentation | |
infomaniak |
Infomaniak | token |
Documentation | |
ionos |
IONOS | prefixsecret |
endpoint (défaut : https://api.hosting.ionos.com) |
Documentation |
linode |
Linode | key |
Documentation | |
luadns |
LuaDNS | emailtoken |
Documentation | |
njalla |
Njalla | token |
Documentation | |
nsone |
NS1 | api_key |
Documentation | |
ovh |
OVH | application_keyapplication_secretconsumer_key |
endpoint (défaut : ovh-eu) |
Documentation |
pdns |
PowerDNS | endpointapi_keyserver_id (default: localhost)disable_notify (default: false) |
Documentation | |
rfc2136 |
RFC 2136 | servernamesecret |
port (défaut : 53)algorithm (défaut : HMAC-SHA512)sign_query (défaut : false) |
Documentation |
route53 |
Amazon Route 53 | access_key_idsecret_access_key |
Documentation | |
sakuracloud |
Sakura Cloud | api_tokenapi_secret |
Documentation | |
scaleway |
Scaleway | application_token |
Documentation | |
transip |
TransIP | key_fileusername |
Documentation |
Exemples de configuration
=== "Défi HTTP de base"
Configuration simple utilisant les défis HTTP pour un seul domaine :
```yaml
AUTO_LETS_ENCRYPT: "yes"
EMAIL_LETS_ENCRYPT: "admin@example.com"
LETS_ENCRYPT_CHALLENGE: "http"
```
=== "DNS Cloudflare avec Wildcard"
Configuration pour les certificats wildcard utilisant le DNS de Cloudflare :
```yaml
AUTO_LETS_ENCRYPT: "yes"
EMAIL_LETS_ENCRYPT: "admin@example.com"
LETS_ENCRYPT_CHALLENGE: "dns"
LETS_ENCRYPT_DNS_PROVIDER: "cloudflare"
LETS_ENCRYPT_DNS_CREDENTIAL_ITEM: "api_token VOTRE_JETON_API"
USE_LETS_ENCRYPT_WILDCARD: "yes"
```
=== "Configuration AWS Route53"
Configuration utilisant Amazon Route53 pour les défis DNS :
```yaml
AUTO_LETS_ENCRYPT: "yes"
EMAIL_LETS_ENCRYPT: "admin@example.com"
LETS_ENCRYPT_CHALLENGE: "dns"
LETS_ENCRYPT_DNS_PROVIDER: "route53"
LETS_ENCRYPT_DNS_CREDENTIAL_ITEM: "aws_access_key_id VOTRE_CLE_ACCES"
LETS_ENCRYPT_DNS_CREDENTIAL_ITEM_2: "aws_secret_access_key VOTRE_CLE_SECRETE"
```
=== "Test avec l'environnement de Staging et tentatives"
Configuration pour tester la configuration avec l'environnement de staging et des paramètres de tentatives améliorés :
```yaml
AUTO_LETS_ENCRYPT: "yes"
EMAIL_LETS_ENCRYPT: "admin@example.com"
LETS_ENCRYPT_CHALLENGE: "http"
USE_LETS_ENCRYPT_STAGING: "yes"
LETS_ENCRYPT_MAX_RETRIES: "5"
```
=== "DigitalOcean avec temps de propagation personnalisé"
Configuration utilisant le DNS de DigitalOcean avec un temps d'attente de propagation plus long :
```yaml
AUTO_LETS_ENCRYPT: "yes"
EMAIL_LETS_ENCRYPT: "admin@example.com"
LETS_ENCRYPT_CHALLENGE: "dns"
LETS_ENCRYPT_DNS_PROVIDER: "digitalocean"
LETS_ENCRYPT_DNS_CREDENTIAL_ITEM: "token VOTRE_JETON_API"
LETS_ENCRYPT_DNS_PROPAGATION: "120"
```
=== "Google Cloud DNS"
Configuration utilisant Google Cloud DNS avec les informations d'identification d'un compte de service :
```yaml
AUTO_LETS_ENCRYPT: "yes"
EMAIL_LETS_ENCRYPT: "admin@example.com"
LETS_ENCRYPT_CHALLENGE: "dns"
LETS_ENCRYPT_DNS_PROVIDER: "google"
LETS_ENCRYPT_DNS_CREDENTIAL_ITEM: "project_id votre-id-projet"
LETS_ENCRYPT_DNS_CREDENTIAL_ITEM_2: "private_key_id votre-id-cle-privee"
LETS_ENCRYPT_DNS_CREDENTIAL_ITEM_3: "private_key votre-cle-privee"
LETS_ENCRYPT_DNS_CREDENTIAL_ITEM_4: "client_email votre-email-compte-service"
LETS_ENCRYPT_DNS_CREDENTIAL_ITEM_5: "client_id votre-id-client"
LETS_ENCRYPT_DNS_CREDENTIAL_ITEM_6: "client_x509_cert_url votre-url-cert"
```
Limit
Prise en charge STREAM ⚠️
Le plugin Limit permet d’appliquer des politiques de limitation pour garantir un usage équitable et protéger vos ressources contre les abus, les attaques par déni de service (DoS) et la surconsommation. Ces politiques incluent :
- Le nombre de connexions simultanées par adresse IP (support STREAM ✅)
- Le nombre de requêtes par adresse IP et par URL sur une période donnée (support STREAM ❌)
Fonctionnement
- Limitation de débit : Suit le nombre de requêtes de chaque adresse IP cliente vers des URL spécifiques. Si un client dépasse la limite de débit configurée, les requêtes suivantes sont temporairement refusées.
- Limitation de connexions : Surveille et restreint le nombre de connexions simultanées de chaque adresse IP cliente. Différentes limites de connexion peuvent être appliquées en fonction du protocole utilisé (HTTP/1, HTTP/2, HTTP/3 ou stream).
- Dans les deux cas, les clients qui dépassent les limites définies reçoivent un code de statut HTTP « 429 - Too Many Requests », ce qui aide à prévenir la surcharge du serveur.
Utilisation
- Activer la limitation de débit de requêtes : Utilisez
USE_LIMIT_REQpour activer la limitation de débit de requêtes et définissez des motifs d'URL avec leurs limites correspondantes. - Activer la limitation de connexions : Utilisez
USE_LIMIT_CONNpour activer la limitation de connexions et définissez le nombre maximum de connexions simultanées pour différents protocoles. - Appliquer un contrôle granulaire : Créez plusieurs règles de limitation de débit pour différentes URL afin de fournir des niveaux de protection variés sur votre site.
- Suivre l'efficacité : Utilisez l'interface web pour consulter les statistiques sur les requêtes et les connexions limitées.
Paramètres
=== "Limitation de requêtes"
| Paramètre | Défaut | Contexte | Multiple | Description |
| ---------------- | ------ | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `USE_LIMIT_REQ` | `yes` | multisite | non | **Activer la limitation de requêtes :** Mettre à `yes` pour activer la fonctionnalité de limitation de débit par requêtes. |
| `LIMIT_REQ_URL` | `/` | multisite | oui | **Motif d’URL :** Motif d’URL (regex PCRE) auquel la limite de débit sera appliquée ; utilisez `/` pour l'appliquer à toutes les requêtes. |
| `LIMIT_REQ_RATE` | `2r/s` | multisite | oui | **Limite de débit :** Taux de requêtes maximal au format `Nr/t`, où N est le nombre de requêtes et t est l'unité de temps : s (seconde), m (minute), h (heure), ou d (jour). |
!!! tip "Format de la limitation de débit"
Le format de la limite de débit est spécifié comme `Nr/t` où :
- `N` est le nombre de requêtes autorisées
- `r` est la lettre littérale 'r' (pour 'requêtes')
- `/` est une barre oblique littérale
- `t` est l'unité de temps : `s` (seconde), `m` (minute), `h` (heure), ou `d` (jour)
Par exemple, `5r/m` signifie que 5 requêtes par minute sont autorisées pour chaque adresse IP.
=== "Limitation de connexions"
| Paramètre | Défaut | Contexte | Multiple | Description |
| ----------------------- | ------ | --------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `USE_LIMIT_CONN` | `yes` | multisite | non | **Activer la limitation de connexions :** Mettre à `yes` pour activer la limitation de connexions simultanées. |
| `LIMIT_CONN_MAX_HTTP1` | `10` | multisite | non | **Connexions HTTP/1.X :** Nombre maximal de connexions HTTP/1.X simultanées par adresse IP. |
| `LIMIT_CONN_MAX_HTTP2` | `100` | multisite | non | **Flux HTTP/2 :** Nombre maximal de flux HTTP/2 simultanés par adresse IP. |
| `LIMIT_CONN_MAX_HTTP3` | `100` | multisite | non | **Flux HTTP/3 :** Nombre maximal de flux HTTP/3 simultanés par adresse IP. |
| `LIMIT_CONN_MAX_STREAM` | `10` | multisite | non | **Connexions Stream :** Nombre maximal de connexions stream simultanées par adresse IP. |
!!! info "Limitation de connexions vs de requêtes" - La limitation de connexions restreint le nombre de connexions simultanées qu'une seule adresse IP peut maintenir. - La limitation de débit de requêtes restreint le nombre de requêtes qu'une adresse IP peut effectuer dans une période de temps définie.
L'utilisation des deux méthodes offre une protection complète contre divers types d'abus.
!!! warning "Réglages adaptés" Des limites trop strictes peuvent impacter des clients légitimes, notamment pour HTTP/2 et HTTP/3 où les navigateurs utilisent souvent plusieurs flux. Les valeurs par défaut sont équilibrées pour la plupart des cas d'utilisation, mais envisagez de les ajuster en fonction des besoins de votre application et du comportement des utilisateurs.
Exemples de configuration
=== "Protection de base"
Une configuration simple utilisant les paramètres par défaut pour protéger l'ensemble de votre site :
```yaml
USE_LIMIT_REQ: "yes"
LIMIT_REQ_URL: "/"
LIMIT_REQ_RATE: "2r/s"
USE_LIMIT_CONN: "yes"
LIMIT_CONN_MAX_HTTP1: "10"
LIMIT_CONN_MAX_HTTP2: "100"
LIMIT_CONN_MAX_HTTP3: "100"
LIMIT_CONN_MAX_STREAM: "10"
```
=== "Protection d'endpoints spécifiques"
Configuration avec différentes limites de débit pour divers endpoints :
```yaml
USE_LIMIT_REQ: "yes"
# Règle par défaut pour toutes les requêtes
LIMIT_REQ_URL: "/"
LIMIT_REQ_RATE: "10r/s"
# Limite plus stricte pour la page de connexion
LIMIT_REQ_URL_2: "^/login"
LIMIT_REQ_RATE_2: "1r/s"
# Limite plus stricte pour l'API
LIMIT_REQ_URL_3: "^/api/"
LIMIT_REQ_RATE_3: "5r/s"
USE_LIMIT_CONN: "yes"
LIMIT_CONN_MAX_HTTP1: "10"
LIMIT_CONN_MAX_HTTP2: "100"
LIMIT_CONN_MAX_HTTP3: "100"
LIMIT_CONN_MAX_STREAM: "10"
```
=== "Configuration pour site à fort trafic"
Configuration optimisée pour les sites à fort trafic avec des limites plus permissives :
```yaml
USE_LIMIT_REQ: "yes"
# Limite générale
LIMIT_REQ_URL: "/"
LIMIT_REQ_RATE: "30r/s"
# Protection de la zone d'administration
LIMIT_REQ_URL_2: "^/admin/"
LIMIT_REQ_RATE_2: "5r/s"
USE_LIMIT_CONN: "yes"
LIMIT_CONN_MAX_HTTP1: "50"
LIMIT_CONN_MAX_HTTP2: "200"
LIMIT_CONN_MAX_HTTP3: "200"
LIMIT_CONN_MAX_STREAM: "30"
```
=== "Configuration pour serveur d'API"
Configuration optimisée pour un serveur d'API avec des limites de débit exprimées en requêtes par minute :
```yaml
USE_LIMIT_REQ: "yes"
# Endpoints de l'API publique
LIMIT_REQ_URL: "^/api/public/"
LIMIT_REQ_RATE: "120r/m"
# Endpoints de l'API privée
LIMIT_REQ_URL_2: "^/api/private/"
LIMIT_REQ_RATE_2: "300r/m"
# Endpoint d'authentification
LIMIT_REQ_URL_3: "^/api/auth"
LIMIT_REQ_RATE_3: "10r/m"
USE_LIMIT_CONN: "yes"
LIMIT_CONN_MAX_HTTP1: "20"
LIMIT_CONN_MAX_HTTP2: "100"
LIMIT_CONN_MAX_HTTP3: "100"
LIMIT_CONN_MAX_STREAM: "20"
```
Load Balancer (PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ❌
Provides load balancing feature to group of upstreams with optional healthchecks.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
LOADBALANCER_HEALTHCHECK_DICT_SIZE |
10m |
global | non | Shared dict size (datastore for all healthchecks). |
LOADBALANCER_UPSTREAM_NAME |
global | oui | Name of the upstream (used in REVERSE_PROXY_HOST). | |
LOADBALANCER_UPSTREAM_SERVERS |
global | oui | List of servers/IPs in the server group. | |
LOADBALANCER_UPSTREAM_MODE |
round-robin |
global | oui | Load balancing mode (round-robin or sticky). |
LOADBALANCER_UPSTREAM_STICKY_METHOD |
ip |
global | oui | Sticky session method (ip or cookie). |
LOADBALANCER_UPSTREAM_RESOLVE |
no |
global | oui | Dynamically resolve upstream hostnames. |
LOADBALANCER_UPSTREAM_KEEPALIVE |
global | oui | Number of keepalive connections to cache per worker. | |
LOADBALANCER_UPSTREAM_KEEPALIVE_TIMEOUT |
60s |
global | oui | Keepalive timeout for upstream connections. |
LOADBALANCER_UPSTREAM_KEEPALIVE_TIME |
1h |
global | oui | Keepalive time for upstream connections. |
LOADBALANCER_HEALTHCHECK_URL |
/status |
global | oui | The healthcheck URL. |
LOADBALANCER_HEALTHCHECK_INTERVAL |
2000 |
global | oui | Healthcheck interval in milliseconds. |
LOADBALANCER_HEALTHCHECK_TIMEOUT |
1000 |
global | oui | Healthcheck timeout in milliseconds. |
LOADBALANCER_HEALTHCHECK_FALL |
3 |
global | oui | Number of failed healthchecks before marking the server as down. |
LOADBALANCER_HEALTHCHECK_RISE |
1 |
global | oui | Number of successful healthchecks before marking the server as up. |
LOADBALANCER_HEALTHCHECK_VALID_STATUSES |
200 |
global | oui | HTTP status considered valid in healthchecks. |
LOADBALANCER_HEALTHCHECK_CONCURRENCY |
10 |
global | oui | Maximum number of concurrent healthchecks. |
LOADBALANCER_HEALTHCHECK_TYPE |
http |
global | oui | Type of healthcheck (http or https). |
LOADBALANCER_HEALTHCHECK_SSL_VERIFY |
yes |
global | oui | Verify SSL certificate in healthchecks. |
LOADBALANCER_HEALTHCHECK_HOST |
global | oui | Host header for healthchecks (useful for HTTPS). |
Metrics
Prise en charge STREAM ⚠️
Le plugin Metrics fournit des capacités complètes de surveillance et de collecte de données pour votre instance BunkerWeb. Cette fonctionnalité vous permet de suivre divers indicateurs de performance, événements de sécurité et statistiques système, afin d'obtenir des informations précieuses sur le comportement et l'état de santé de vos sites et services protégés.
Comment ça marche :
- BunkerWeb collecte des métriques clés pendant le traitement des requêtes et des réponses.
- Ces métriques incluent des compteurs de requêtes bloquées, des mesures de performance et diverses statistiques liées à la sécurité.
- Les données sont stockées efficacement en mémoire, avec des limites configurables pour éviter une consommation excessive de ressources.
- Pour les déploiements multi-instances, Redis peut être utilisé pour centraliser et agréger les données de métriques.
- Les métriques collectées sont accessibles via l'API ou visualisables dans l'interface web.
- Ces informations vous aident à identifier les menaces de sécurité, à résoudre les problèmes et à optimiser votre configuration.
Implémentation technique
Le plugin Metrics fonctionne en :
- utilisant des dictionnaires partagés dans NGINX, où
metrics_datastoreest utilisé pour HTTP etmetrics_datastore_streampour le trafic TCP/UDP ; - s'appuyant sur un cache LRU pour un stockage efficace en mémoire ;
- synchronisant périodiquement les données entre les workers à l'aide de timers ;
- stockant des informations détaillées sur les requêtes bloquées, notamment l'adresse IP du client, le pays, l'horodatage, les détails de la requête et le motif du blocage ;
- prenant en charge des métriques spécifiques aux plugins via une interface commune de collecte de métriques ;
- fournissant des points d'accès API pour interroger les métriques collectées.
Utilisation
Suivez ces étapes pour configurer et utiliser la fonctionnalité Metrics :
- Activez la fonctionnalité : la collecte de métriques est activée par défaut. Vous pouvez la contrôler avec le paramètre
USE_METRICS. - Configurez l'allocation mémoire : définissez la quantité de mémoire allouée au stockage des métriques avec le paramètre
METRICS_MEMORY_SIZE. - Définissez les limites de stockage : indiquez combien de requêtes bloquées stocker par worker et dans Redis avec les paramètres correspondants.
- Accédez aux données : consultez les métriques collectées via l'interface web ou les points d'accès API.
- Analysez les informations : utilisez les données recueillies pour identifier des tendances, détecter des problèmes de sécurité et optimiser votre configuration.
Métriques collectées
Le plugin Metrics collecte les informations suivantes :
-
Requêtes bloquées : pour chaque requête bloquée, les données suivantes sont stockées :
- identifiant de requête et horodatage ;
- adresse IP du client et pays (si disponible) ;
- méthode HTTP et URL ;
- code d'état HTTP ;
- agent utilisateur ;
- motif du blocage et mode de sécurité ;
- nom du serveur ;
- données supplémentaires liées au motif du blocage.
-
Compteurs de plugins : divers compteurs spécifiques aux plugins qui suivent des activités et événements.
Accès API
Les données de métriques sont accessibles via les points d'accès API internes de BunkerWeb :
- Point d'accès :
/metrics/{filter} - Méthode : GET
- Description : récupère les données de métriques selon le filtre spécifié
- Format de réponse : objet JSON contenant les métriques demandées
Par exemple, /metrics/requests renvoie des informations sur les requêtes bloquées.
!!! info "Configuration de l'accès API" Pour accéder aux métriques via l'API, vous devez vous assurer que :
1. la fonctionnalité API est activée avec `USE_API: "yes"` (activée par défaut) ;
2. votre IP cliente est incluse dans le paramètre `API_WHITELIST_IP` (par défaut `127.0.0.0/8`) ;
3. vous accédez à l'API sur le port configuré (par défaut `5000` via le paramètre `API_HTTP_PORT`) ;
4. vous utilisez la bonne valeur `API_SERVER_NAME` dans l'en-tête Host (par défaut `bwapi`) ;
5. si `API_TOKEN` est configuré, vous incluez `Authorization: Bearer <token>` dans les en-têtes de la requête.
Requêtes typiques :
Sans jeton (lorsque `API_TOKEN` n'est pas défini) :
```bash
curl -H "Host: bwapi" \
http://votre-instance-bunkerweb:5000/metrics/requests
```
Avec jeton (lorsque `API_TOKEN` est défini) :
```bash
curl -H "Host: bwapi" \
-H "Authorization: Bearer $API_TOKEN" \
http://votre-instance-bunkerweb:5000/metrics/requests
```
Si vous avez personnalisé `API_SERVER_NAME` avec une valeur différente de `bwapi`, utilisez cette valeur dans l'en-tête Host.
Pour les environnements de production sécurisés, limitez l'accès à l'API à des IP de confiance et activez `API_TOKEN`.
Paramètres de configuration
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_METRICS |
yes |
multisite | non | Activer les métriques : mettez yes pour activer la collecte et la récupération des métriques. |
METRICS_MEMORY_SIZE |
16m |
global | non | Taille mémoire : taille du stockage interne des métriques (par exemple 8192, 16m, 32m). |
METRICS_MAX_BLOCKED_REQUESTS |
1k |
global | non | Maximum de requêtes bloquées : nombre maximal de requêtes bloquées à stocker par worker. Accepte la notation abrégée k/m. |
METRICS_MAX_BLOCKED_REQUESTS_REDIS |
10k |
global | non | Maximum Redis de requêtes bloquées : nombre maximal de requêtes bloquées à stocker dans Redis. Accepte la notation abrégée k/m. |
MAX_LRU_HISTORY |
1k |
global | non | Historique LRU maximal : nombre d'emplacements LRU par worker et limite du tableau d'historique des événements par clé (traces de blocage, traces d'authentification, etc.). Accepte la notation abrégée k/m. |
METRICS_SAVE_TO_REDIS |
yes |
global | non | Enregistrer les métriques dans Redis : mettez yes pour stocker les métriques (compteurs et tableaux) dans Redis pour l'agrégation. |
!!! tip "Dimensionner l'allocation mémoire"
Le paramètre METRICS_MEMORY_SIZE doit être ajusté selon votre volume de trafic et le nombre d'instances. Les valeurs brutes en octets et les suffixes k/m sont pris en charge. Pour les sites à fort trafic, envisagez d'augmenter cette valeur afin de garantir la capture de toutes les métriques sans perte de données.
!!! info "Intégration Redis" Lorsque BunkerWeb est configuré pour utiliser Redis, le plugin Metrics synchronise automatiquement les données de requêtes bloquées avec le serveur Redis. Cela fournit une vue centralisée des événements de sécurité sur plusieurs instances de BunkerWeb.
!!! warning "Considérations de performance"
Définir des valeurs très élevées pour METRICS_MAX_BLOCKED_REQUESTS ou METRICS_MAX_BLOCKED_REQUESTS_REDIS peut augmenter l'utilisation de la mémoire. Surveillez les ressources système et ajustez ces valeurs selon vos besoins réels et les ressources disponibles.
!!! note "Stockage spécifique aux workers" Chaque worker NGINX maintient ses propres métriques en mémoire. Lors de l'accès aux métriques via l'API, les données de tous les workers sont automatiquement agrégées pour fournir une vue complète.
Exemples de configuration
=== "Configuration de base"
Configuration par défaut adaptée à la plupart des déploiements :
```yaml
USE_METRICS: "yes"
METRICS_MEMORY_SIZE: "16m"
METRICS_MAX_BLOCKED_REQUESTS: "1k"
METRICS_MAX_BLOCKED_REQUESTS_REDIS: "10k"
MAX_LRU_HISTORY: "1k"
METRICS_SAVE_TO_REDIS: "yes"
```
=== "Environnement à faibles ressources"
Configuration optimisée pour les environnements disposant de ressources limitées :
```yaml
USE_METRICS: "yes"
METRICS_MEMORY_SIZE: "8m"
METRICS_MAX_BLOCKED_REQUESTS: "500"
METRICS_MAX_BLOCKED_REQUESTS_REDIS: "10000"
MAX_LRU_HISTORY: "500"
METRICS_SAVE_TO_REDIS: "no"
```
=== "Environnement à fort trafic"
Configuration pour des sites à fort trafic qui doivent suivre davantage d'événements de sécurité :
```yaml
USE_METRICS: "yes"
METRICS_MEMORY_SIZE: "64m"
METRICS_MAX_BLOCKED_REQUESTS: "5000"
METRICS_MAX_BLOCKED_REQUESTS_REDIS: "500000"
MAX_LRU_HISTORY: "5k"
METRICS_SAVE_TO_REDIS: "yes"
```
=== "Métriques désactivées"
Configuration avec la collecte de métriques désactivée :
```yaml
USE_METRICS: "no"
```
Migration (PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ✅
Migration of BunkerWeb configuration between instances made easy via the web UI
Miscellaneous
Prise en charge STREAM ⚠️
Le plugin Divers (Miscellaneous) fournit des paramètres de base essentiels qui aident à maintenir la sécurité et la fonctionnalité de votre site web. Ce composant central offre des contrôles complets pour :
- Le comportement du serveur - Configurez la manière dont votre serveur répond à diverses requêtes
- Les paramètres HTTP - Gérez les méthodes, la taille des requêtes et les options de protocole
- La gestion des fichiers - Contrôlez le service des fichiers statiques et optimisez leur livraison
- Le support des protocoles - Activez les protocoles HTTP modernes pour de meilleures performances
- Les configurations système - Étendez les fonctionnalités et améliorez la sécurité
Que vous ayez besoin de restreindre les méthodes HTTP, de gérer la taille des requêtes, d'optimiser la mise en cache des fichiers ou de contrôler la manière dont votre serveur répond à diverses requêtes, ce plugin vous donne les outils pour affiner le comportement de votre service web tout en optimisant à la fois la performance et la sécurité.
Fonctionnalités clés
| Catégorie de fonctionnalité | Description |
|---|---|
| Contrôle des méthodes HTTP | Définissez quelles méthodes HTTP sont acceptables pour votre application |
| Protection du serveur par défaut | Empêchez l'accès non autorisé par des noms d'hôte incorrects et forcez le SNI pour les connexions sécurisées |
| Gestion de la taille des requêtes | Définissez des limites pour le corps des requêtes client et les téléversements de fichiers |
| Service de fichiers statiques | Configurez et optimisez la livraison de contenu statique depuis des dossiers racine personnalisés |
| Mise en cache des fichiers | Améliorez les performances grâce à des mécanismes avancés de mise en cache des descripteurs de fichiers |
| Support des protocoles | Configurez les options des protocoles HTTP modernes (HTTP2/HTTP3) et les paramètres de port Alt-Svc |
| Rapport anonyme | Rapport de statistiques d'utilisation optionnel pour aider à améliorer BunkerWeb |
| Support des plugins externes | Étendez les fonctionnalités en intégrant des plugins externes via des URL |
| Contrôle du statut HTTP | Configurez la réponse de votre serveur lors du refus de requêtes (y compris la fermeture de connexion) |
Guide de configuration
=== "Sécurité du serveur par défaut"
**Contrôles du serveur par défaut**
En HTTP, l'en-tête `Host` spécifie le serveur cible, mais il peut être manquant ou inconnu, souvent à cause de bots recherchant des vulnérabilités.
Pour bloquer de telles requêtes :
- Mettez `DISABLE_DEFAULT_SERVER` à `yes` pour refuser silencieusement ces requêtes en utilisant le [code de statut `444` de NGINX](https://http.dev/444).
- Pour une sécurité plus stricte, activez `DISABLE_DEFAULT_SERVER_STRICT_SNI` pour rejeter les connexions SSL/TLS sans SNI valide.
!!! success "Avantages en matière de sécurité"
- Bloque la manipulation de l'en-tête Host et le scan des hôtes virtuels
- Atténue les risques de contrebande de requêtes HTTP (HTTP request smuggling)
- Supprime le serveur par défaut comme vecteur d'attaque
| Paramètre | Défaut | Contexte | Multiple | Description |
| ----------------------------------- | ------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `DISABLE_DEFAULT_SERVER` | `no` | global | no | **Serveur par défaut :** Mettre à `yes` pour désactiver le serveur par défaut lorsqu'aucun nom d'hôte ne correspond à la requête. |
| `DISABLE_DEFAULT_SERVER_STRICT_SNI` | `no` | global | no | **SNI Strict :** Si mis à `yes`, requiert le SNI pour les connexions HTTPS et rejette les connexions sans SNI valide. |
!!! warning "Application du SNI"
Activer la validation stricte du SNI offre une sécurité renforcée mais peut causer des problèmes si BunkerWeb est derrière un proxy inverse qui transmet les requêtes HTTPS sans préserver les informations SNI. Testez minutieusement avant d'activer en production.
=== "Statut HTTP en cas de refus"
**Contrôle du statut HTTP**
La première étape dans la gestion de l'accès refusé à un client est de définir l'action appropriée. Cela peut être configuré avec le paramètre `DENY_HTTP_STATUS`. Lorsque BunkerWeb refuse une requête, vous pouvez contrôler sa réponse. Par défaut, il renvoie un statut `403 Forbidden`, affichant une page web ou un contenu personnalisé.
Alternativement, le régler sur `444` ferme immédiatement la connexion sans envoyer de réponse. Ce [code de statut non standard](https://http.dev/444), spécifique à NGINX, est utile pour ignorer silencieusement les requêtes indésirables.
| Paramètre | Défaut | Contexte | Multiple | Description |
| ------------------ | ------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `DENY_HTTP_STATUS` | `403` | global | no | **Statut HTTP de refus :** Code de statut HTTP à envoyer quand une requête est refusée (403 ou 444). Le code 444 ferme la connexion. |
!!! warning "Considérations sur le code de statut 444"
Comme les clients ne reçoivent aucun retour, le dépannage peut être plus difficile. Régler sur `444` est recommandé uniquement si vous avez minutieusement traité les faux positifs, êtes expérimenté avec BunkerWeb et exigez un niveau de sécurité plus élevé.
!!! info "Mode stream"
En **mode stream**, ce paramètre est toujours appliqué comme `444`, ce qui signifie que la connexion sera fermée, quelle que soit la valeur configurée.
=== "Méthodes HTTP"
**Contrôle des méthodes HTTP**
Restreindre les méthodes HTTP à celles requises par votre application est une mesure de sécurité fondamentale qui respecte le principe du moindre privilège. En définissant explicitement les méthodes acceptables, vous minimisez le risque d'exploitation via des méthodes inutilisées ou dangereuses.
Cette fonctionnalité est configurée avec `ALLOWED_METHODS`, où les méthodes sont listées et séparées par un `|` (défaut : `GET|POST|HEAD`). Si un client tente une méthode non listée, le serveur répondra avec un statut **405 - Method Not Allowed**.
Pour la plupart des sites web, le défaut `GET|POST|HEAD` est suffisant. Si votre application utilise des API RESTful, vous devrez peut-être inclure `PUT` et `DELETE`. Les méthodes personnalisées en majuscules peuvent également contenir des underscores et des tirets pour la compatibilité avec des protocoles non standards (ex. `CCM_POST`, `M-SEARCH`).
!!! success "Avantages en matière de sécurité"
- Empêche l'exploitation de méthodes HTTP inutilisées ou inutiles
- Réduit la surface d'attaque en désactivant les méthodes potentiellement dangereuses
- Bloque les techniques d'énumération de méthodes HTTP utilisées par les attaquants
| Paramètre | Défaut | Contexte | Multiple | Description |
| ----------------- | ----------------- | --------- | -------- | --------------------------------------------------------------------------------------------- |
| `ALLOWED_METHODS` | `GET\|POST\|HEAD` | multisite | no | **Méthodes HTTP :** Liste des méthodes HTTP autorisées, séparées par des barres verticales (` | `). Les méthodes personnalisées en majuscules peuvent contenir des underscores et des tirets. |
!!! abstract "CORS et requêtes pre-flight"
Si votre application prend en charge le [Cross-Origin Resource Sharing (CORS)](#cors), vous devriez inclure la méthode `OPTIONS` dans `ALLOWED_METHODS` pour gérer les requêtes pre-flight. Cela garantit le bon fonctionnement pour les navigateurs effectuant des requêtes inter-origines.
!!! danger "Considérations de sécurité"
- **Évitez d'activer `TRACE` ou `CONNECT` :** Ces méthodes sont rarement nécessaires et peuvent introduire des risques de sécurité importants, comme le Cross-Site Tracing (XST) ou les attaques par tunnelisation.
- **Révisez régulièrement les méthodes autorisées :** Auditez périodiquement `ALLOWED_METHODS` pour vous assurer qu'il correspond aux besoins actuels de votre application.
- **Testez minutieusement avant le déploiement :** Les changements de restrictions de méthodes HTTP peuvent impacter la fonctionnalité de l'application. Validez votre configuration dans un environnement de pré-production.
=== "Limites de taille des requêtes"
**Limites de taille des requêtes**
La taille maximale du corps d'une requête peut être contrôlée avec `MAX_CLIENT_SIZE` (défaut : `10m`). Les valeurs acceptées suivent la syntaxe décrite [ici](https://nginx.org/en/docs/syntax.html).
!!! success "Avantages en matière de sécurité"
- Protège contre les attaques par déni de service causées par des charges utiles excessives
- Atténue les vulnérabilités de débordement de tampon (buffer overflow)
- Empêche les attaques par téléversement de fichiers
- Réduit le risque d'épuisement des ressources du serveur
| Paramètre | Défaut | Contexte | Multiple | Description |
| ----------------- | ------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `MAX_CLIENT_SIZE` | `10m` | multisite | no | **Taille maximale des requêtes :** La taille maximale autorisée pour le corps des requêtes client (ex. : téléversements). |
| `MAX_HEADERS` | `100` | global | no | **En-têtes maximum :** Nombre maximum de lignes d'en-tête par requête. Les requêtes dépassant cette limite sont rejetées avec `400 Bad Request`. |
!!! tip "Bonnes pratiques de configuration de la taille des requêtes"
Si vous devez autoriser un corps de requête de taille illimitée, vous pouvez mettre la valeur `MAX_CLIENT_SIZE` à `0`. Cependant, ce n'est **pas recommandé** en raison des risques potentiels de sécurité et de performance.
**Bonnes pratiques :**
- Configurez toujours `MAX_CLIENT_SIZE` à la plus petite valeur répondant aux besoins légitimes de votre application.
- Révisez et ajustez régulièrement ce paramètre pour l'aligner sur les besoins évolutifs de votre application.
- Évitez de mettre `0` sauf en cas de nécessité absolue, car cela peut exposer votre serveur à des attaques par déni de service et à l'épuisement des ressources.
En gérant soigneusement ce paramètre, vous pouvez garantir une sécurité et des performances optimales pour votre application.
=== "Support des protocoles"
**Paramètres des protocoles HTTP**
Les protocoles HTTP modernes comme HTTP/2 et HTTP/3 améliorent la performance et la sécurité. BunkerWeb permet une configuration facile de ces protocoles.
!!! success "Avantages en matière de sécurité et de performance"
- **Avantages de sécurité :** Les protocoles modernes comme HTTP/2 et HTTP/3 imposent TLS/HTTPS par défaut, réduisent la sensibilité à certaines attaques et améliorent la confidentialité grâce aux en-têtes chiffrés (HTTP/3).
- **Avantages de performance :** Des fonctionnalités comme le multiplexage, la compression des en-têtes, le server push et le transfert de données binaires améliorent la vitesse et l'efficacité.
| Paramètre | Défaut | Contexte | Multiple | Description |
| -------------------- | ------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `LISTEN_HTTP` | `yes` | multisite | no | **Écoute HTTP :** Répondre aux requêtes HTTP (non sécurisées) si mis à `yes`. Peut également être désactivé en laissant `HTTP_PORT` vide. |
| `HTTP2` | `yes` | multisite | no | **HTTP2 :** Supporte le protocole HTTP2 lorsque HTTPS est activé. |
| `HTTP3` | `yes` | multisite | no | **HTTP3 :** Supporte le protocole HTTP3 lorsque HTTPS est activé. |
| `HTTP3_ALT_SVC_PORT` | `443` | multisite | no | **Port Alt-Svc HTTP3 :** Port à utiliser dans l'en-tête Alt-Svc pour HTTP3. |
!!! example "À propos de HTTP/3"
HTTP/3, la dernière version du protocole Hypertext Transfer, utilise QUIC sur UDP au lieu de TCP, résolvant des problèmes comme le blocage en tête de ligne pour des connexions plus rapides et plus fiables.
NGINX a introduit un support expérimental pour HTTP/3 et QUIC à partir de la version 1.25.0. Cependant, cette fonctionnalité est encore expérimentale, et la prudence est de mise pour une utilisation en production. Pour plus de détails, consultez la [documentation officielle de NGINX](https://nginx.org/en/docs/quic.html).
Des tests approfondis sont recommandés avant d'activer HTTP/3 en production.
=== "Service de fichiers statiques"
**Configuration du service de fichiers**
BunkerWeb peut servir des fichiers statiques directement ou agir comme un proxy inverse vers un serveur d'application. Par défaut, les fichiers sont servis depuis `/var/www/html/{server_name}`.
| Paramètre | Défaut | Contexte | Multiple | Description |
| ------------- | ----------------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `SERVE_FILES` | `yes` | multisite | no | **Servir des fichiers :** Si `yes`, BunkerWeb servira les fichiers statiques depuis le dossier racine configuré. |
| `ROOT_FOLDER` | `/var/www/html/{server_name}` | multisite | no | **Dossier racine :** Le répertoire depuis lequel servir les fichiers statiques. Vide signifie utiliser l'emplacement par défaut. |
!!! tip "Bonnes pratiques pour le service de fichiers statiques"
- **Service direct :** Activez le service de fichiers (`SERVE_FILES=yes`) lorsque BunkerWeb est responsable de servir directement les fichiers statiques.
- **Proxy inverse :** Si BunkerWeb agit comme un proxy inverse, **désactivez le service de fichiers** (`SERVE_FILES=no`) pour réduire la surface d'attaque et éviter d'exposer des répertoires inutiles.
- **Permissions :** Assurez-vous que les permissions de fichiers et les configurations de chemin sont correctes pour empêcher tout accès non autorisé.
- **Sécurité :** Évitez d'exposer des répertoires ou des fichiers sensibles par des mauvaises configurations.
En gérant soigneusement le service de fichiers statiques, vous pouvez optimiser les performances tout en maintenant un environnement sécurisé.
=== "Paramètres système"
**Gestion des plugins et du système**
Ces paramètres gèrent l'interaction de BunkerWeb avec des systèmes externes et contribuent à l'amélioration du produit via des statistiques d'utilisation anonymes optionnelles.
**Rapport anonyme**
Le rapport anonyme fournit à l'équipe de BunkerWeb des informations sur la manière dont le logiciel est utilisé. Cela aide à identifier les domaines d'amélioration et à prioriser le développement de fonctionnalités. Les rapports sont strictement statistiques et n'incluent aucune information sensible ou personnellement identifiable. Ils couvrent :
- Les fonctionnalités activées
- Les schémas de configuration généraux
Vous pouvez désactiver cette fonctionnalité si vous le souhaitez en mettant `SEND_ANONYMOUS_REPORT` à `no`.
**Plugins externes**
Les plugins externes vous permettent d'étendre les fonctionnalités de BunkerWeb en intégrant des modules tiers. Cela permet une personnalisation supplémentaire et des cas d'utilisation avancés.
!!! danger "Sécurité des plugins externes"
**Les plugins externes peuvent introduire des risques de sécurité s'ils ne sont pas correctement vérifiés.** Suivez ces bonnes pratiques pour minimiser les menaces potentielles :
- N'utilisez que des plugins provenant de sources fiables.
- Vérifiez l'intégrité des plugins à l'aide de sommes de contrôle (checksums) lorsqu'elles sont disponibles.
- Révisez et mettez à jour régulièrement les plugins pour garantir la sécurité et la compatibilité.
Pour plus de détails, consultez la [documentation des Plugins](plugins.md).
| Paramètre | Défaut | Contexte | Multiple | Description |
| ----------------------- | ------ | -------- | -------- | ------------------------------------------------------------------------------------------------- |
| `SEND_ANONYMOUS_REPORT` | `yes` | global | no | **Rapports anonymes :** Envoyer des rapports d'utilisation anonymes aux mainteneurs de BunkerWeb. |
| `EXTERNAL_PLUGIN_URLS` | | global | no | **Plugins externes :** URL pour télécharger des plugins externes (séparées par des espaces). |
=== "Mise en cache des fichiers"
**Optimisation du cache de fichiers**
Le cache de fichiers ouverts améliore les performances en stockant les descripteurs de fichiers et les métadonnées en mémoire, réduisant ainsi le besoin d'opérations répétées sur le système de fichiers.
!!! success "Avantages de la mise en cache de fichiers"
- **Performance :** Réduit les E/S du système de fichiers, diminue la latence et abaisse l'utilisation du CPU pour les opérations sur les fichiers.
- **Sécurité :** Atténue les attaques par synchronisation (timing attacks) en mettant en cache les réponses d'erreur et réduit l'impact des attaques DoS ciblant le système de fichiers.
| Paramètre | Défaut | Contexte | Multiple | Description |
| -------------------------- | ----------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `USE_OPEN_FILE_CACHE` | `no` | multisite | no | **Activer le cache :** Activer la mise en cache des descripteurs de fichiers et des métadonnées pour améliorer les performances. |
| `OPEN_FILE_CACHE` | `max=1000 inactive=20s` | multisite | no | **Configuration du cache :** Configurez le cache de fichiers ouverts (ex. : nombre max d'entrées et délai d'inactivité). |
| `OPEN_FILE_CACHE_ERRORS` | `yes` | multisite | no | **Mettre en cache les erreurs :** Met en cache les erreurs de recherche de descripteurs de fichiers ainsi que les recherches réussies. |
| `OPEN_FILE_CACHE_MIN_USES` | `2` | multisite | no | **Utilisations minimales :** Nombre minimum d'accès pendant la période d'inactivité pour qu'un fichier reste en cache. |
| `OPEN_FILE_CACHE_VALID` | `30s` | multisite | no | **Validité du cache :** Temps après lequel les éléments mis en cache sont revalidés. |
**Guide de configuration**
Pour activer et configurer la mise en cache des fichiers :
1. Mettez `USE_OPEN_FILE_CACHE` à `yes`.
2. Ajustez les paramètres `OPEN_FILE_CACHE` pour définir le nombre maximum d'entrées et leur délai d'inactivité.
3. Utilisez `OPEN_FILE_CACHE_ERRORS` pour mettre en cache les recherches réussies et échouées.
4. Réglez `OPEN_FILE_CACHE_MIN_USES` pour spécifier le nombre d'accès requis pour qu'un fichier reste en cache.
5. Définissez la période de validité du cache avec `OPEN_FILE_CACHE_VALID`.
!!! tip "Bonnes pratiques"
- Activez la mise en cache pour les sites web avec de nombreux fichiers statiques pour améliorer les performances.
- Révisez et affinez régulièrement les paramètres de cache pour équilibrer performance et utilisation des ressources.
- Dans les environnements dynamiques où les fichiers changent fréquemment, envisagez de réduire la période de validité du cache ou de désactiver la fonctionnalité pour garantir la fraîcheur du contenu.
Exemples de configuration
=== "Sécurité du serveur par défaut"
Exemple pour désactiver le serveur par défaut et forcer le SNI strict :
```yaml
DISABLE_DEFAULT_SERVER: "yes"
DISABLE_DEFAULT_SERVER_STRICT_SNI: "yes"
```
=== "Statut HTTP en cas de refus"
Exemple pour ignorer silencieusement les requêtes indésirables :
```yaml
DENY_HTTP_STATUS: "444"
```
=== "Méthodes HTTP"
Exemple pour restreindre les méthodes HTTP à celles requises par une API RESTful :
```yaml
ALLOWED_METHODS: "GET|POST|PUT|DELETE"
```
=== "Limites de taille des requêtes"
Exemple pour limiter la taille maximale du corps d'une requête :
```yaml
MAX_CLIENT_SIZE: "5m"
```
=== "Support des protocoles"
Exemple pour activer HTTP/2 et HTTP/3 avec un port Alt-Svc personnalisé :
```yaml
HTTP2: "yes"
HTTP3: "yes"
HTTP3_ALT_SVC_PORT: "443"
```
=== "Service de fichiers statiques"
Exemple pour servir des fichiers statiques depuis un dossier racine personnalisé :
```yaml
SERVE_FILES: "yes"
ROOT_FOLDER: "/var/www/custom-folder"
```
=== "Mise en cache des fichiers"
Exemple pour activer et optimiser la mise en cache des fichiers :
```yaml
USE_OPEN_FILE_CACHE: "yes"
OPEN_FILE_CACHE: "max=2000 inactive=30s"
OPEN_FILE_CACHE_ERRORS: "yes"
OPEN_FILE_CACHE_MIN_USES: "3"
OPEN_FILE_CACHE_VALID: "60s"
```
ModSecurity
Prise en charge STREAM ❌
Le plugin ModSecurity intègre le puissant pare-feu applicatif web (WAF) ModSecurity dans BunkerWeb. Cette intégration offre une protection robuste contre un large éventail d'attaques web en s'appuyant sur le Jeu de Règles de Base OWASP (CRS) pour détecter et bloquer des menaces telles que l'injection SQL, le cross-site scripting (XSS), l'inclusion de fichiers locaux, et bien plus encore.
Comment ça marche :
- Lorsqu'une requête est reçue, ModSecurity l'évalue par rapport au jeu de règles actif.
- Le Jeu de Règles de Base OWASP inspecte les en-têtes, les cookies, les paramètres d'URL et le contenu du corps de la requête.
- Chaque violation détectée contribue à un score d'anomalie global.
- Si ce score dépasse le seuil configuré, la requête est bloquée.
- Des journaux détaillés sont créés pour aider à diagnostiquer quelles règles ont été déclenchées et pourquoi.
!!! success "Bénéfices clés"
1. **Protection standard de l'industrie :** Utilise le pare-feu open-source ModSecurity largement répandu.
2. **Jeu de Règles de Base OWASP :** Emploie des règles maintenues par la communauté couvrant le Top Dix de l'OWASP et plus encore.
3. **Niveaux de sécurité configurables :** Ajustez les niveaux de paranoïa pour équilibrer la sécurité avec les faux positifs potentiels.
4. **Journalisation détaillée :** Fournit des journaux d'audit complets pour l'analyse des attaques.
5. **Support des plugins :** Étendez la protection avec des plugins CRS optionnels adaptés à vos applications.
Comment l’utiliser
Suivez ces étapes pour configurer et utiliser ModSecurity :
- Activer la fonctionnalité : ModSecurity est activé par défaut. Cela peut être contrôlé via le paramètre
USE_MODSECURITY. - Sélectionner une version du CRS : Choisissez une version du Jeu de Règles de Base OWASP (v3 ou v4).
- Ajouter des plugins : Activez optionnellement des plugins CRS pour améliorer la couverture des règles.
- Surveiller et ajuster : Utilisez les journaux et l'interface web pour identifier les faux positifs et ajuster les paramètres.
Paramètres de configuration
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_MODSECURITY |
yes |
multisite | no | Activer ModSecurity : Active la protection du pare-feu applicatif web ModSecurity. |
USE_MODSECURITY_CRS |
yes |
multisite | no | Utiliser le Core Rule Set : Active le Jeu de Règles de Base OWASP pour ModSecurity. |
MODSECURITY_CRS_VERSION |
4 |
multisite | no | Version du CRS : La version du Jeu de Règles de Base OWASP à utiliser. Options : 3 ou 4. Note : nightly est obsolète et utilise v4 par défaut. |
MODSECURITY_SEC_RULE_ENGINE |
On |
multisite | no | Moteur de règles : Contrôle si les règles sont appliquées. Options : On, DetectionOnly, ou Off. |
MODSECURITY_SEC_AUDIT_ENGINE |
RelevantOnly |
multisite | no | Moteur d'audit : Contrôle le fonctionnement de la journalisation d'audit. Options : On, Off, ou RelevantOnly. |
MODSECURITY_SEC_AUDIT_LOG_PARTS |
ABIJDEFHZ |
multisite | no | Parties du journal d'audit : Quelles parties des requêtes/réponses inclure dans les journaux d'audit. |
MODSECURITY_REQ_BODY_NO_FILES_LIMIT |
131072 |
multisite | no | Limite du corps de requête (sans fichiers) : Taille maximale pour les corps de requête sans téléversement de fichiers. Accepte les octets bruts ou un suffixe lisible (k, m, g). |
USE_MODSECURITY_CRS_PLUGINS |
yes |
multisite | no | Activer les plugins CRS : Active des jeux de règles de plugins supplémentaires pour le Core Rule Set. |
MODSECURITY_CRS_PLUGINS |
multisite | no | Liste des plugins CRS : Liste de plugins séparés par des espaces à télécharger et installer (nom-plugin[/tag] ou URL). |
|
USE_MODSECURITY_GLOBAL_CRS |
no |
global | no | CRS Global : Si activé, applique les règles CRS globalement au niveau HTTP plutôt que par serveur. |
!!! warning "ModSecurity et le Jeu de Règles de Base OWASP" Nous recommandons vivement de garder ModSecurity et le Jeu de Règles de Base OWASP (CRS) activés pour fournir une protection robuste contre les vulnérabilités web courantes. Bien que des faux positifs occasionnels puissent se produire, ils peuvent être résolus avec un peu d'effort en affinant les règles ou en utilisant des exclusions prédéfinies.
L'équipe du CRS maintient activement une liste d'exclusions pour des applications populaires telles que WordPress, Nextcloud, Drupal et Cpanel, facilitant ainsi l'intégration sans impacter la fonctionnalité. Les avantages en matière de sécurité l'emportent de loin sur l'effort de configuration minimal requis pour traiter les faux positifs.
!!! warning "Recommandation de sécurité pour les gros téléversements"
ModSecurity met en mémoire tampon le corps complet de la requête et ne peut pas le plafonner pour les téléversements de plusieurs Go, ce qui peut provoquer un OOM du worker. Si — et seulement si — une URL de reverse proxy est utilisée exclusivement pour les téléversements de fichiers (par exemple un point de terminaison /upload dédié), définissez REVERSE_PROXY_MODSECURITY_N: "no" sur cette URL afin d'émettre modsecurity off; dans son bloc location. Ne le désactivez pas sur des URL à usage mixte : vous perdriez la couverture WAF sur tout ce qui est servi par cette location.
Pour conserver une protection des téléversements après le contournement de ModSecurity, associez cela à un plugin d'analyse de fichiers comme [ClamAV](https://github.com/bunkerity/bunkerweb-plugins/tree/main/clamav) ou [VirusTotal](https://github.com/bunkerity/bunkerweb-plugins/tree/main/virustotal) — ils inspectent le fichier téléversé lui-même plutôt que le corps brut de la requête.
Versions du CRS disponibles
Sélectionnez une version du CRS pour répondre au mieux à vos besoins de sécurité :
!!! warning "Version de nuit obsolète"
L'option nightly pour MODSECURITY_CRS_VERSION est obsolète car le projet OWASP Core Rule Set a arrêté les versions de nuit. Si votre configuration utilise encore nightly, CRS v4 sera utilisé à la place. Veuillez mettre à jour votre configuration pour utiliser MODSECURITY_CRS_VERSION=4.
!!! tip "Niveaux de paranoïa" Le Jeu de Règles de Base OWASP utilise des "niveaux de paranoïa" (PL) pour contrôler la rigueur des règles :
- **PL1 (défaut) :** Protection de base avec un minimum de faux positifs
- **PL2 :** Sécurité renforcée avec une correspondance de motifs plus stricte
- **PL3 :** Sécurité améliorée avec une validation plus stricte
- **PL4 :** Sécurité maximale avec des règles très strictes (peut causer de nombreux faux positifs)
Vous pouvez définir le niveau de paranoïa en ajoutant un fichier de configuration personnalisé dans `/etc/bunkerweb/configs/modsec-crs/`.
Configurations personnalisées
L'ajustement de ModSecurity et du Jeu de Règles de Base OWASP (CRS) peut être réalisé grâce à des configurations personnalisées. Celles-ci vous permettent de personnaliser le comportement à des étapes spécifiques du traitement des règles de sécurité :
modsec-crs: Appliqué avant le chargement du Jeu de Règles de Base OWASP.modsec: Appliqué après le chargement du Jeu de Règles de Base OWASP. Également utilisé si le CRS n'est pas chargé du tout.crs-plugins-before: Appliqué avant le chargement des plugins CRS.crs-plugins-after: Appliqué après le chargement des plugins CRS.
Cette structure offre une grande flexibilité, vous permettant d'affiner les paramètres de ModSecurity et du CRS pour répondre aux besoins spécifiques de votre application tout en maintenant un flux de configuration clair.
Ajout d'exclusions CRS avec modsec-crs
Vous pouvez utiliser une configuration personnalisée de type modsec-crs pour ajouter des exclusions pour des cas d'usage spécifiques, comme l'activation d'exclusions prédéfinies pour WordPress :
SecAction \
"id:900130,\
phase:1,\
nolog,\
pass,\
t:none,\
setvar:tx.crs_exclusions_wordpress=1"
Dans cet exemple :
- L'action est exécutée en Phase 1 (tôt dans le cycle de vie de la requête).
- Elle active les exclusions spécifiques à WordPress du CRS en définissant la variable
tx.crs_exclusions_wordpress.
Mise à jour des règles CRS avec modsec
Pour affiner les règles CRS chargées, vous pouvez utiliser une configuration personnalisée de type modsec. Par exemple, vous pouvez supprimer des règles ou des balises spécifiques pour certains chemins de requête :
SecRule REQUEST_FILENAME "/wp-admin/admin-ajax.php" "id:1,ctl:ruleRemoveByTag=attack-xss,ctl:ruleRemoveByTag=attack-rce"
SecRule REQUEST_FILENAME "/wp-admin/options.php" "id:2,ctl:ruleRemoveByTag=attack-xss"
SecRule REQUEST_FILENAME "^/wp-json/yoast" "id:3,ctl:ruleRemoveById=930120"
Dans cet exemple :
- Règle 1 : Supprime les règles avec les balises
attack-xssetattack-rcepour les requêtes vers/wp-admin/admin-ajax.php. - Règle 2 : Supprime les règles avec la balise
attack-xsspour les requêtes vers/wp-admin/options.php. - Règle 3 : Supprime une règle spécifique (ID
930120) pour les requêtes correspondant à/wp-json/yoast.
!!! info "Ordre d'exécution" L'ordre d'exécution pour ModSecurity dans BunkerWeb est le suivant, assurant une progression claire et logique de l'application des règles :
1. **Configuration OWASP CRS** : Configuration de base pour le Jeu de Règles de Base OWASP.
2. **Configuration des plugins personnalisés (`crs-plugins-before`)** : Paramètres spécifiques aux plugins, appliqués avant toute règle CRS.
3. **Règles des plugins personnalisés (avant les règles CRS) (`crs-plugins-before`)** : Règles personnalisées pour les plugins exécutées avant les règles CRS.
4. **Configuration des plugins téléchargés** : Configuration pour les plugins téléchargés en externe.
5. **Règles des plugins téléchargés (avant les règles CRS)** : Règles pour les plugins téléchargés exécutées avant les règles CRS.
6. **Règles CRS personnalisées (`modsec-crs`)** : Règles définies par l'utilisateur appliquées avant le chargement des règles CRS.
7. **Règles OWASP CRS** : Le jeu de règles de sécurité de base fourni par l'OWASP.
8. **Règles des plugins personnalisés (après les règles CRS) (`crs-plugins-after`)** : Règles de plugins personnalisés exécutées après les règles CRS.
9. **Règles des plugins téléchargés (après les règles CRS)** : Règles pour les plugins téléchargés exécutées après les règles CRS.
10. **Règles personnalisées (`modsec`)** : Règles définies par l'utilisateur appliquées après toutes les règles CRS et de plugins.
**Notes clés** :
- Les personnalisations **pré-CRS** (`crs-plugins-before`, `modsec-crs`) vous permettent de définir des exceptions ou des règles préparatoires avant le chargement des règles CRS de base.
- Les personnalisations **post-CRS** (`crs-plugins-after`, `modsec`) sont idéales pour outrepasser ou étendre des règles après l'application des règles CRS et de plugins.
- Cette structure offre une flexibilité maximale, permettant un contrôle précis de l'exécution et de la personnalisation des règles tout en maintenant une base de sécurité solide.
Plugins OWASP CRS
Le Jeu de Règles de Base OWASP prend également en charge une gamme de plugins conçus pour étendre ses fonctionnalités et améliorer la compatibilité avec des applications ou des environnements spécifiques. Ces plugins peuvent aider à affiner le CRS pour une utilisation avec des plateformes populaires telles que WordPress, Nextcloud et Drupal, ou même des configurations personnalisées. Pour plus d'informations et une liste des plugins disponibles, consultez le registre des plugins OWASP CRS.
!!! tip "Téléchargement de plugins"
Le paramètre MODSECURITY_CRS_PLUGINS vous permet de télécharger et d'installer des plugins pour étendre les fonctionnalités du Jeu de Règles de Base OWASP (CRS). Ce paramètre accepte une liste de noms de plugins avec des balises ou des URL optionnelles, facilitant l'intégration de fonctionnalités de sécurité supplémentaires adaptées à vos besoins spécifiques.
Voici une liste non exhaustive des valeurs acceptées pour le paramètre `MODSECURITY_CRS_PLUGINS` :
* `fake-bot` - Télécharge la dernière version du plugin.
* `wordpress-rule-exclusions/v1.0.0` - Télécharge la version 1.0.0 du plugin.
* `https://github.com/coreruleset/dos-protection-plugin-modsecurity/archive/refs/heads/main.zip` - Télécharge le plugin directement depuis l'URL.
!!! warning "Faux positifs" Des paramètres de sécurité plus élevés peuvent bloquer le trafic légitime. Commencez avec les paramètres par défaut et surveillez les journaux avant d'augmenter les niveaux de sécurité. Soyez prêt à ajouter des règles d'exclusion pour les besoins spécifiques de votre application.
Exemples de configuration
=== "Configuration de base"
Une configuration standard avec ModSecurity et CRS v4 activés :
```yaml
USE_MODSECURITY: "yes"
USE_MODSECURITY_CRS: "yes"
MODSECURITY_CRS_VERSION: "4"
MODSECURITY_SEC_RULE_ENGINE: "On"
```
=== "Mode détection uniquement"
Configuration pour surveiller les menaces potentielles sans bloquer :
```yaml
USE_MODSECURITY: "yes"
USE_MODSECURITY_CRS: "yes"
MODSECURITY_CRS_VERSION: "4"
MODSECURITY_SEC_RULE_ENGINE: "DetectionOnly"
MODSECURITY_SEC_AUDIT_ENGINE: "On"
MODSECURITY_SEC_AUDIT_LOG_PARTS: "ABIJDEFHZ"
```
=== "Configuration avancée avec plugins"
Configuration avec CRS v4 et des plugins activés pour une protection supplémentaire :
```yaml
USE_MODSECURITY: "yes"
USE_MODSECURITY_CRS: "yes"
MODSECURITY_CRS_VERSION: "4"
MODSECURITY_SEC_RULE_ENGINE: "On"
USE_MODSECURITY_CRS_PLUGINS: "yes"
MODSECURITY_CRS_PLUGINS: "wordpress-rule-exclusions fake-bot"
MODSECURITY_REQ_BODY_NO_FILES_LIMIT: "262144"
```
=== "Configuration héritée"
Configuration utilisant CRS v3 pour la compatibilité avec des installations plus anciennes :
```yaml
USE_MODSECURITY: "yes"
USE_MODSECURITY_CRS: "yes"
MODSECURITY_CRS_VERSION: "3"
MODSECURITY_SEC_RULE_ENGINE: "On"
```
=== "ModSecurity Global"
Configuration appliquant ModSecurity globalement à toutes les connexions HTTP :
```yaml
USE_MODSECURITY: "yes"
USE_MODSECURITY_CRS: "yes"
MODSECURITY_CRS_VERSION: "4"
USE_MODSECURITY_GLOBAL_CRS: "yes"
```
!!! note "Valeurs de taille lisibles"
Pour les paramètres de taille comme MODSECURITY_REQ_BODY_NO_FILES_LIMIT, les suffixes k, m, et g (insensibles à la casse) sont pris en charge et représentent les kibioctets, mébioctets et gibioctets (multiples de 1024). Exemples : 256k = 262144, 1m = 1048576, 2g = 2147483648.
Monitoring (PRO)
Prise en charge STREAM ❌
BunkerWeb monitoring pro system. This plugin is a prerequisite for some other plugins.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_MONITORING |
yes |
global | non | Enable monitoring of BunkerWeb. |
MONITORING_METRICS_DICT_SIZE |
10M |
global | non | Size of the dict to store monitoring metrics. |
MONITORING_IGNORE_URLS |
global | non | List of URLs to ignore when monitoring separated with spaces (e.g. /health) | |
MONITORING_TOP_N_DECAY_HOURS |
6 |
global | non | How often (in hours) to halve attacker top-N counters and prune cold entries. Lower = top-N reflects more recent traffic; higher = old attackers persist longer. |
MONITORING_TOP_N_TRACK_MAX |
5000 |
global | non | Maximum tracked attacker IPs and URIs per prefix in the bounded top-N sketch. Caps memory under distributed attack via Space-Saving admission. |
Mutual TLS
Prise en charge STREAM ✅
Le plugin Mutual TLS (mTLS) protège vos applications sensibles en exigeant que les clients présentent des certificats délivrés par des autorités que vous maîtrisez. Une fois activé, BunkerWeb authentifie les appelants avant que leurs requêtes n’atteignent vos services, ce qui sécurise vos outils internes et intégrations partenaires.
BunkerWeb évalue chaque poignée de main TLS en fonction du bundle d’AC et de la politique que vous définissez. Les clients qui ne répondent pas aux règles sont bloqués, tandis que les connexions conformes peuvent transmettre les détails du certificat aux applications amont pour une autorisation affinée.
Fonctionnement :
- Le plugin surveille les échanges HTTPS du site sélectionné.
- Pendant l’échange TLS, BunkerWeb inspecte le certificat client et vérifie sa chaîne par rapport à votre magasin de confiance.
- Le mode de vérification détermine si les clients non authentifiés sont rejetés, acceptés avec tolérance ou autorisés pour des diagnostics.
- (Optionnel) BunkerWeb expose le résultat via les en-têtes
X-SSL-Client-*afin que vos applications puissent appliquer leur propre logique d’accès.
!!! success "Avantages clés"
1. **Contrôle renforcé :** limitez l’accès aux machines et utilisateurs authentifiés.
2. **Politiques souples :** combinez modes stricts et optionnels pour accompagner vos workflows.
3. **Visibilité applicative :** transférez empreintes et identités de certificats pour l’audit.
4. **Défense en profondeur :** associez mTLS aux autres plugins BunkerWeb pour multiplier les protections.
Mise en œuvre
Suivez ces étapes pour déployer le mutual TLS sereinement :
- Activer la fonctionnalité : positionnez
USE_MTLSàyessur les sites qui nécessitent l’authentification par certificat. - Fournir le bundle d’AC : stockez vos autorités de confiance dans un fichier PEM et renseignez
MTLS_CA_CERTIFICATEavec son chemin absolu. - Choisir le mode de vérification : sélectionnez
onpour rendre les certificats obligatoires,optionalpour offrir un repli ouoptional_no_capour un diagnostic temporaire. - Ajuster la profondeur de chaîne : adaptez
MTLS_VERIFY_DEPTHsi votre organisation utilise plusieurs intermédiaires. - Transmettre le résultat (optionnel) : laissez
MTLS_FORWARD_CLIENT_HEADERSàyessi vos services amont doivent inspecter le certificat présenté. - Maintenir la révocation : si vous publiez une CRL, renseignez
MTLS_CRLpour que BunkerWeb refuse les certificats révoqués.
Paramètres de configuration
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_MTLS |
no |
multisite | non | Activer le mutual TLS : active l’authentification par certificat client pour le site courant. |
MTLS_CA_CERTIFICATE |
multisite | non | Bundle d’AC client : chemin absolu vers le bundle d’AC clients (PEM). Requis lorsque MTLS_VERIFY_CLIENT vaut on ou optional; doit être lisible. |
|
MTLS_VERIFY_CLIENT |
on |
multisite | non | Mode de vérification : choisissez si les certificats sont requis (on), optionnels (optional) ou acceptés sans validation d’AC (optional_no_ca). |
MTLS_VERIFY_DEPTH |
2 |
multisite | non | Profondeur de vérification : profondeur maximale de chaîne acceptée pour les certificats clients. |
MTLS_FORWARD_CLIENT_HEADERS |
yes |
multisite | non | Transmettre les en-têtes client : propage les résultats de vérification (X-SSL-Client-* avec statut, DN, émetteur, numéro de série, empreinte, validité). |
MTLS_CRL |
multisite | non | Chemin de la CRL client : chemin optionnel vers une liste de révocation de certificats encodée en PEM. Appliqué uniquement si le bundle d’AC est chargé avec succès. |
!!! tip "Maintenez les certificats à jour" Stockez bundles d’AC et listes de révocation dans un volume monté accessible par le Scheduler pour que chaque redémarrage récupère les ancrages de confiance récents.
!!! warning "Bundle d’AC obligatoire en mode strict"
Lorsque MTLS_VERIFY_CLIENT vaut on ou optional, le fichier d’AC doit être présent à l’exécution. S’il manque, BunkerWeb ignore les directives mTLS pour éviter un démarrage sur un chemin invalide. Réservez optional_no_ca au diagnostic, car ce mode affaiblit l’authentification.
!!! info "Certificat approuvé vs. vérification" BunkerWeb réutilise le même bundle d’AC pour vérifier les clients et bâtir la chaîne de confiance, garantissant une cohérence OCSP/CRL et durant le handshake.
Exemples de configuration
=== "Contrôle d’accès strict"
Exigez des certificats clients valides émis par votre AC privée et transmettez les informations de vérification au backend :
```yaml
USE_MTLS: "yes"
MTLS_CA_CERTIFICATE: "/etc/bunkerweb/mtls/engineering-ca.pem"
MTLS_VERIFY_CLIENT: "on"
MTLS_VERIFY_DEPTH: "2"
MTLS_FORWARD_CLIENT_HEADERS: "yes"
```
=== "Authentification client optionnelle"
Autorisez les utilisateurs anonymes mais transmettez les détails du certificat lorsqu’un client en présente un :
```yaml
USE_MTLS: "yes"
MTLS_CA_CERTIFICATE: "/etc/bunkerweb/mtls/partner-ca.pem"
MTLS_VERIFY_CLIENT: "optional"
MTLS_FORWARD_CLIENT_HEADERS: "yes"
```
=== "Diagnostic sans AC"
Autorisez les connexions à aboutir même si un certificat ne peut pas être rattaché à un bundle d’AC de confiance. Utile uniquement pour le dépannage :
```yaml
USE_MTLS: "yes"
MTLS_VERIFY_CLIENT: "optional_no_ca"
MTLS_FORWARD_CLIENT_HEADERS: "no"
```
OpenAPI Validator (PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ❌
Validates incoming HTTP requests against an OpenAPI / Swagger specification.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_OPENAPI_VALIDATOR |
no |
multisite | non | Enable OpenAPI route validation for this site. |
OPENAPI_SPEC |
multisite | non | Absolute path or HTTP(S) URL to the OpenAPI (swagger) document in JSON/YAML format. | |
OPENAPI_BASE_PATH |
multisite | non | Optional base path prefix to prepend to every path in the spec (overrides servers[*].url path). | |
OPENAPI_ALLOW_UNSPECIFIED |
no |
multisite | non | Allow requests to paths not listed in the specification (otherwise they are denied). |
OPENAPI_ALLOW_INSECURE_URL |
no |
multisite | non | Allow fetching the OpenAPI spec over plain HTTP (not recommended). |
OPENAPI_IGNORE_URLS |
^/docs$ ^/redoc$ ^/openapi\.json$ |
multisite | non | List of URL regexes to bypass OpenAPI validation (space separated). |
OPENAPI_MAX_SPEC_SIZE |
2M |
global | non | Maximum allowed size of the OpenAPI document (accepts suffix k/M/G). |
OPENAPI_VALIDATE_PARAMS |
yes |
multisite | non | Validate query, header, cookie, and path parameters against the OpenAPI specification. |
OpenID Connect (PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ❌
OpenID Connect authentication plugin providing SSO capabilities with identity providers.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_OPENIDC |
no |
multisite | non | Enable or disable OpenID Connect authentication. |
OPENIDC_DISCOVERY |
multisite | non | OpenID Connect discovery URL (e.g. https://idp.example.com/.well-known/openid-configuration). | |
OPENIDC_CLIENT_ID |
multisite | non | OAuth 2.0 client identifier registered with the IdP. | |
OPENIDC_CLIENT_SECRET |
multisite | non | OAuth 2.0 client secret registered with the IdP. | |
OPENIDC_TOKEN_ENDPOINT_AUTH_METHOD |
basic |
multisite | non | Token endpoint auth method: basic (recommended, HTTP Basic), post (POST body), secret_jwt (JWT with client secret), private_key_jwt (JWT with RSA key). |
OPENIDC_CLIENT_RSA_PRIVATE_KEY |
multisite | non | PEM-encoded RSA private key for private_key_jwt authentication. | |
OPENIDC_CLIENT_RSA_PRIVATE_KEY_ID |
multisite | non | Optional key ID (kid) for private_key_jwt authentication. | |
OPENIDC_CLIENT_JWT_ASSERTION_EXPIRES_IN |
multisite | non | JWT assertion lifetime in seconds (empty to use library default). | |
OPENIDC_REDIRECT_URI |
/callback |
multisite | non | URI path where the IdP redirects after authentication. |
OPENIDC_SCOPE |
openid email profile |
multisite | non | Space-separated list of OAuth 2.0 scopes to request. |
OPENIDC_AUTHORIZATION_PARAMS |
multisite | non | Additional authorization params as comma-separated key=value pairs (e.g. audience=api,resource=xyz). URL-encode values if needed. | |
OPENIDC_USE_NONCE |
yes |
multisite | non | Use nonce in authentication requests to prevent replay attacks. |
OPENIDC_USE_PKCE |
no |
multisite | non | Use PKCE (Proof Key for Code Exchange) for authorization code flow. |
OPENIDC_FORCE_REAUTHORIZE |
no |
multisite | non | Force re-authorization on every request (not recommended for production). |
OPENIDC_REFRESH_SESSION_INTERVAL |
multisite | non | Interval in seconds to silently re-authenticate (empty to disable). | |
OPENIDC_IAT_SLACK |
120 |
multisite | non | Allowed clock skew in seconds for token validation. |
OPENIDC_ACCESS_TOKEN_EXPIRES_IN |
3600 |
multisite | non | Default access token lifetime (seconds) if not provided by IdP. |
OPENIDC_RENEW_ACCESS_TOKEN_ON_EXPIRY |
yes |
multisite | non | Automatically renew access token using refresh token when expired. |
OPENIDC_ACCEPT_UNSUPPORTED_ALG |
no |
multisite | non | Accept tokens signed with unsupported algorithms (not recommended). |
OPENIDC_LOGOUT_PATH |
/logout |
multisite | non | URI path for logout requests. |
OPENIDC_REVOKE_TOKENS_ON_LOGOUT |
no |
multisite | non | Revoke tokens at the IdP when logging out. |
OPENIDC_REDIRECT_AFTER_LOGOUT_URI |
multisite | non | URI to redirect after logout (leave empty for IdP default). | |
OPENIDC_POST_LOGOUT_REDIRECT_URI |
multisite | non | URI to redirect after IdP logout is complete. | |
OPENIDC_TIMEOUT_CONNECT |
10000 |
multisite | non | Connection timeout in milliseconds for IdP requests. |
OPENIDC_TIMEOUT_SEND |
10000 |
multisite | non | Send timeout in milliseconds for IdP requests. |
OPENIDC_TIMEOUT_READ |
10000 |
multisite | non | Read timeout in milliseconds for IdP requests. |
OPENIDC_SSL_VERIFY |
yes |
multisite | non | Verify SSL certificates when communicating with the IdP. |
OPENIDC_KEEPALIVE |
yes |
multisite | non | Enable HTTP keepalive for connections to the IdP. |
OPENIDC_HTTP_PROXY |
multisite | non | HTTP proxy URL for IdP connections (e.g. http://proxy:8080). | |
OPENIDC_HTTPS_PROXY |
multisite | non | HTTPS proxy URL for IdP connections (e.g. http://proxy:8080). | |
OPENIDC_USER_HEADER |
X-User |
multisite | non | Header to pass user info to upstream (empty to disable). |
OPENIDC_USER_HEADER_CLAIM |
sub |
multisite | non | ID token claim to use for the user header (e.g. sub, email, preferred_username). |
OPENIDC_DISPLAY_CLAIM |
preferred_username |
multisite | non | Claim to use for display in logs and metrics (e.g. preferred_username, name, email). Falls back to User Header Claim if not found. |
OPENIDC_DISCOVERY_DICT_SIZE |
1m |
global | non | Size of the shared dictionary to cache discovery data. |
OPENIDC_JWKS_DICT_SIZE |
1m |
global | non | Size of the shared dictionary to cache JWKS data. |
OPENIDC_USE_ACL |
no |
multisite | non | Enable claim-based access control (ACL) after OIDC authentication. When enabled, only users whose claims match the configured rules will be granted access. |
OPENIDC_ACL_MATCH_MODE |
all |
multisite | non | How multiple ACL rules are evaluated. 'all' means every rule must pass (AND logic). 'any' means at least one rule must pass (OR logic). |
OPENIDC_ACL_DENIED_URL |
multisite | non | URL to redirect to when access is denied by ACL. If empty, returns a 403 Forbidden response. | |
OPENIDC_ACL_CLAIM |
multisite | oui | Name of the OIDC claim to check (e.g. groups, email, sub, preferred_username). | |
OPENIDC_ACL_CLAIM_VALUE |
multisite | oui | Expected value for the claim. For array claims (e.g. groups), checks if this value is a member. For string claims, checks strict equality. |
PHP
Prise en charge STREAM ❌
Le plugin PHP fournit l’intégration PHP‑FPM avec BunkerWeb pour exécuter du PHP dynamiquement. Il prend en charge des instances locales (même machine) et distantes, offrant de la flexibilité dans l’architecture.
Comment ça marche :
- À la demande d’un fichier PHP, BunkerWeb route la requête vers l’instance PHP‑FPM configurée.
- En local, la communication se fait via un socket Unix.
- À distance, la communication utilise FastCGI vers l’hôte et le port indiqués.
- PHP‑FPM exécute le script et renvoie la réponse à BunkerWeb qui la livre au client.
- La réécriture d’URL est automatiquement configurée pour les frameworks/applications qui utilisent des « pretty URLs ».
Comment l’utiliser
- Choisissez local vs distant.
- Connexion : chemin du socket (local) ou hôte+port (distant).
- Racine de documents : pointez vers le dossier contenant vos fichiers PHP.
- Laisser BunkerWeb faire le reste : une fois configuré, BunkerWeb route automatiquement les requêtes PHP vers votre instance PHP-FPM.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
REMOTE_PHP |
multisite | non | Hôte PHP‑FPM distant. Laissez vide pour utiliser le local. | |
REMOTE_PHP_PATH |
multisite | non | Chemin racine des fichiers côté PHP‑FPM distant. | |
REMOTE_PHP_PORT |
9000 |
multisite | non | Port PHP‑FPM distant. |
LOCAL_PHP |
multisite | non | Chemin du socket PHP‑FPM local. Laissez vide pour utiliser un PHP‑FPM distant. | |
LOCAL_PHP_PATH |
multisite | non | Chemin racine des fichiers côté PHP‑FPM local. |
!!! tip "Local vs distant" Choisissez la configuration adaptée à votre infrastructure :
- **PHP-FPM local** offre de meilleures performances grâce à la communication par socket et convient lorsque PHP s’exécute sur la même machine que BunkerWeb.
- **PHP-FPM distant** apporte davantage de flexibilité et de scalabilité en déportant le traitement PHP sur des serveurs séparés.
!!! warning "Chemins"
REMOTE_PHP_PATH/LOCAL_PHP_PATH doivent correspondre au chemin réel des fichiers sous peine d’erreurs « File not found ».
!!! info "Réécriture d’URL"
Le plugin configure automatiquement la réécriture pour diriger les requêtes vers index.php si le fichier demandé n’existe pas.
Exemples
=== "PHP‑FPM local"
```yaml
LOCAL_PHP: "/var/run/php/php8.1-fpm.sock"
LOCAL_PHP_PATH: "/var/www/html"
```
=== "PHP‑FPM distant"
```yaml
REMOTE_PHP: "php-server.example.com"
REMOTE_PHP_PORT: "9000"
REMOTE_PHP_PATH: "/var/www/html"
```
=== "Port personnalisé"
```yaml
REMOTE_PHP: "php-server.example.com"
REMOTE_PHP_PORT: "9001"
REMOTE_PHP_PATH: "/var/www/html"
```
=== "WordPress"
```yaml
LOCAL_PHP: "/var/run/php/php8.1-fpm.sock"
LOCAL_PHP_PATH: "/var/www/html/wordpress"
```
Pro
Prise en charge STREAM ❌
Le plugin Pro regroupe des fonctionnalités avancées pour les déploiements entreprise de BunkerWeb. Il déverrouille des capacités supplémentaires, des plugins premium et des extensions qui complètent la plateforme BunkerWeb, pour plus de sécurité, de performance et d’options de gestion.
Comment ça marche :
- Avec une clé de licence Pro valide, BunkerWeb contacte l’API Pro pour valider votre abonnement.
- Une fois authentifié, le plugin télécharge et installe automatiquement les plugins et extensions exclusifs Pro.
- Le statut Pro est vérifié périodiquement afin d’assurer l’accès continu aux fonctionnalités premium.
- Les plugins premium s’intègrent de façon transparente à votre configuration existante.
- Les fonctionnalités Pro complètent le cœur open‑source, elles ne le remplacent pas.
!!! success "Bénéfices clés"
1. Extensions premium : accès à des plugins et fonctions exclusives.
2. Performances accrues : configurations optimisées et mécanismes avancés de cache.
3. Support entreprise : assistance prioritaire et canaux dédiés.
4. Intégration fluide : cohabite avec l’édition communautaire sans conflits.
5. Mises à jour automatiques : plugins premium téléchargés et tenus à jour automatiquement.
Comment l’utiliser
- Obtenir une licence : achetez une licence Pro depuis le BunkerWeb Panel.
- Configurer la licence : définissez
PRO_LICENSE_KEYavec votre clé. - Laissez BunkerWeb faire le reste : les plugins Pro sont téléchargés et activés automatiquement.
- Surveiller le statut Pro : vérifiez les indicateurs de santé dans l’interface web UI.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
PRO_LICENSE_KEY |
global | non | Clé de licence BunkerWeb Pro (authentification). |
!!! tip "Gestion de licence" La licence est liée à votre environnement de déploiement. Pour un transfert ou une question d’abonnement, contactez le support via le BunkerWeb Panel.
!!! info "Fonctionnalités Pro" Le périmètre des fonctionnalités peut évoluer. Le plugin Pro gère automatiquement l’installation et la configuration des capacités disponibles.
!!! warning "Accès réseau"
Le plugin Pro requiert un accès Internet sortant pour contacter l’API BunkerWeb (vérification de licence) et télécharger les plugins premium. Autorisez les connexions HTTPS vers api.bunkerweb.io:443.
FAQ
Q : Que se passe‑t‑il si ma licence Pro expire ?
R : L’accès aux fonctionnalités premium est désactivé, mais votre installation continue de fonctionner avec l’édition communautaire. Pour réactiver les fonctionnalités Pro, renouvelez la licence.
Q : Les fonctionnalités Pro peuvent‑elles perturber ma configuration existante ?
R : Non. Elles sont conçues pour s’intégrer sans modifier votre configuration actuelle.
Q : Puis‑je essayer Pro avant achat ?
R : Oui. Deux offres existent :
- BunkerWeb PRO Standard : accès complet, sans support technique.
- BunkerWeb PRO Enterprise : accès complet, avec support dédié.
Un essai gratuit d’1 mois est disponible avec le code freetrial. Rendez‑vous sur le BunkerWeb Panel pour l’activer.
Prometheus exporter (PRO)
Prise en charge STREAM ❌
Prometheus exporter for BunkerWeb internal metrics.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_PROMETHEUS_EXPORTER |
no |
global | non | Enable the Prometheus export. |
PROMETHEUS_EXPORTER_IP |
0.0.0.0 |
global | non | Listening IP of the Prometheus exporter. |
PROMETHEUS_EXPORTER_PORT |
9113 |
global | non | Listening port of the Prometheus exporter. |
PROMETHEUS_EXPORTER_URL |
/metrics |
global | non | HTTP URL of the Prometheus exporter. |
PROMETHEUS_EXPORTER_ALLOW_IP |
127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 |
global | non | List of IP/networks allowed to contact the Prometheus exporter endpoint. |
Real IP
Prise en charge STREAM ⚠️
Le plugin Real IP garantit que BunkerWeb identifie correctement l’adresse IP du client même derrière des proxys. Indispensable pour appliquer les règles de sécurité, la limitation de débit et des logs fiables : sinon toutes les requêtes sembleraient venir de l’IP du proxy.
Comment ça marche :
- Activé, BunkerWeb inspecte les en‑têtes (ex.
X-Forwarded-For) contenant l’IP d’origine. - Il vérifie que l’IP source figure dans
REAL_IP_FROM(liste de proxys de confiance) pour n’accepter que les proxys légitimes. - L’IP client est extraite de l’en‑tête
REAL_IP_HEADERet utilisée pour l’évaluation sécurité et la journalisation. - En chaînes d’IPs, une recherche récursive peut déterminer l’IP d’origine.
- Le support du PROXY protocol peut être activé pour recevoir l’IP client directement depuis des proxys compatibles (ex. HAProxy).
- Les listes d’IP de proxys de confiance peuvent être téléchargées automatiquement via des URLs.
Comment l’utiliser
- Activer : mettez le paramètre
USE_REAL_IPàyes. - Proxys de confiance : renseignez IP/plages dans
REAL_IP_FROM. - En‑tête : indiquez lequel porte l’IP réelle via
REAL_IP_HEADER. - Récursif : activez
REAL_IP_RECURSIVEsi nécessaire. - Sources URL : utilisez
REAL_IP_FROM_URLSpour télécharger des listes. - PROXY protocol : activez
USE_PROXY_PROTOCOLsi l’amont le supporte.
!!! danger "Avertissement PROXY protocol"
Activer USE_PROXY_PROTOCOL sans un amont correctement configuré pour l’émettre cassera votre application. Assurez‑vous de l’avoir configuré avant activation.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_REAL_IP |
no |
multisite | non | Activer la récupération de l’IP réelle depuis les en‑têtes ou le PROXY protocol. |
REAL_IP_FROM |
192.168.0.0/16 172.16.0.0/12 10.0.0.0/8 |
multisite | non | Proxys de confiance : liste d’IP/réseaux séparés par des espaces. |
REAL_IP_HEADER |
X-Forwarded-For |
multisite | non | En‑tête porteur de l’IP réelle ou valeur spéciale proxy_protocol. |
REAL_IP_RECURSIVE |
yes |
multisite | non | Recherche récursive dans un en‑tête contenant plusieurs IPs. |
REAL_IP_FROM_URLS |
multisite | non | URLs fournissant des IPs/réseaux de proxys de confiance (supporte file://). |
|
USE_PROXY_PROTOCOL |
no |
global | non | Activer le support PROXY protocol pour la communication directe proxy→BunkerWeb. |
!!! tip "Fournisseurs cloud"
Ajoutez les IP de vos load balancers (AWS/GCP/Azure…) à REAL_IP_FROM pour une identification correcte.
!!! danger "Considérations sécurité" N’ajoutez que des sources de confiance, sinon risque d’usurpation d’IP via en‑têtes manipulés.
!!! info "Multiples adresses"
Avec REAL_IP_RECURSIVE, si l’en‑tête contient plusieurs IPs, la première non listée comme proxy de confiance est retenue comme IP client.
Exemples
=== "Basique (derrière reverse proxy)"
Configuration simple pour un site derrière un reverse proxy :
```yaml
USE_REAL_IP: "yes"
REAL_IP_FROM: "192.168.1.0/24 10.0.0.5"
REAL_IP_HEADER: "X-Forwarded-For"
REAL_IP_RECURSIVE: "yes"
```
=== "Load balancer cloud"
Configuration pour un site derrière un load balancer cloud :
```yaml
USE_REAL_IP: "yes"
REAL_IP_FROM: "192.168.0.0/16 172.16.0.0/12 10.0.0.0/8"
REAL_IP_HEADER: "X-Forwarded-For"
REAL_IP_RECURSIVE: "yes"
```
=== "PROXY Protocol"
Configuration utilisant le PROXY protocol avec un load balancer compatible :
```yaml
USE_REAL_IP: "yes"
REAL_IP_FROM: "192.168.1.0/24"
REAL_IP_HEADER: "proxy_protocol"
USE_PROXY_PROTOCOL: "yes"
```
=== "Sources de proxys multiples avec URL"
Configuration avancée avec des listes d'IP de proxys mises à jour automatiquement :
```yaml
USE_REAL_IP: "yes"
REAL_IP_FROM: "192.168.0.0/16 172.16.0.0/12 10.0.0.0/8"
REAL_IP_HEADER: "X-Real-IP"
REAL_IP_RECURSIVE: "yes"
REAL_IP_FROM_URLS: "https://example.com/proxy-ips.txt file:///etc/bunkerweb/custom-proxies.txt"
```
=== "Configuration CDN"
Configuration pour un site web derrière un CDN :
```yaml
USE_REAL_IP: "yes"
REAL_IP_FROM: "192.168.0.0/16 172.16.0.0/12 10.0.0.0/8"
REAL_IP_FROM_URLS: "https://cdn-provider.com/ip-ranges.txt"
REAL_IP_HEADER: "CF-Connecting-IP" # Exemple pour Cloudflare
REAL_IP_RECURSIVE: "no" # Inutile avec les en-têtes à IP unique
```
=== "Derrière Cloudflare"
Configuration pour un site web derrière Cloudflare :
```yaml
USE_REAL_IP: "yes"
REAL_IP_FROM: "" # Nous faisons uniquement confiance aux IP Cloudflare
REAL_IP_FROM_URLS: "https://www.cloudflare.com/ips-v4/ https://www.cloudflare.com/ips-v6/" # Télécharge automatiquement les IP Cloudflare
REAL_IP_HEADER: "CF-Connecting-IP" # En-tête Cloudflare pour l'IP client
REAL_IP_RECURSIVE: "yes"
```
Redirect
Prise en charge STREAM ❌
Le plugin Redirect fournit des redirections HTTP simples et efficaces. Il permet de rediriger des visiteurs d’une URL à une autre, pour un domaine entier, des chemins précis, avec ou sans conservation du chemin d’origine.
Comment ça marche :
- À l’accès d’un visiteur, BunkerWeb vérifie si une redirection est définie.
- Si activée, il redirige vers l’URL de destination.
- Vous pouvez préserver le chemin d’origine en activant l’option correspondante.
- Le code HTTP peut être
301(permanent) ou302(temporaire). - Idéal pour migrations, canonicals, URLs obsolètes.
Comment l’utiliser
- Source :
REDIRECT_FROM(ex./,/old-page). - Destination :
REDIRECT_TO. - Type :
REDIRECT_TO_REQUEST_URIpour conserver le chemin. - Code :
REDIRECT_TO_STATUS_CODE(301ou302). - Laisser BunkerWeb faire le reste : une fois configurées, les redirections sont appliquées automatiquement à vos visiteurs.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
REDIRECT_FROM |
/ |
multisite | oui | Chemin source à rediriger. |
REDIRECT_TO |
multisite | oui | URL de destination. Laisser vide pour désactiver. | |
REDIRECT_TO_REQUEST_URI |
no |
multisite | oui | Conserver le chemin d'origine en l'ajoutant à l'URL de destination. |
REDIRECT_TO_STATUS_CODE |
301 |
multisite | oui | Code HTTP : 301, 302, 303, 307 ou 308. |
!!! tip "Choisir le bon code"
- 301 (Moved Permanently) : Redirection permanente, mise en cache par les navigateurs. Peut changer POST en GET. Idéal pour migrations de domaine.
- 302 (Found) : Redirection temporaire. Peut changer POST en GET.
- 303 (See Other) : Redirige toujours en GET. Utile après soumission de formulaire.
- 307 (Temporary Redirect) : Redirection temporaire qui préserve la méthode HTTP. Idéal pour les APIs.
- 308 (Permanent Redirect) : Redirection permanente qui préserve la méthode HTTP. Pour migrations d'API permanentes.
!!! info "Conservation du chemin"
Avec le paramètre REDIRECT_TO_REQUEST_URI défini à yes, /blog/post-1 vers https://new.com devient https://new.com/blog/post-1.
Exemples
=== "Multiples chemins"
```yaml
REDIRECT_FROM: "/blog/"
REDIRECT_TO: "https://blog.example.com/"
REDIRECT_TO_REQUEST_URI: "yes"
REDIRECT_TO_STATUS_CODE: "301"
REDIRECT_FROM_2: "/shop/"
REDIRECT_TO_2: "https://shop.example.com/"
REDIRECT_TO_REQUEST_URI_2: "no"
REDIRECT_TO_STATUS_CODE_2: "301"
REDIRECT_FROM_3: "/"
REDIRECT_TO_3: "https://new-domain.com"
REDIRECT_TO_REQUEST_URI_3: "no"
REDIRECT_TO_STATUS_CODE_3: "301"
```
=== "Domaine entier"
```yaml
REDIRECT_TO: "https://new-domain.com"
REDIRECT_TO_REQUEST_URI: "no"
REDIRECT_TO_STATUS_CODE: "301"
```
=== "Conserver le chemin"
```yaml
REDIRECT_TO: "https://new-domain.com"
REDIRECT_TO_REQUEST_URI: "yes"
REDIRECT_TO_STATUS_CODE: "301"
```
=== "Temporaire"
```yaml
REDIRECT_TO: "https://maintenance.example.com"
REDIRECT_TO_REQUEST_URI: "no"
REDIRECT_TO_STATUS_CODE: "302"
```
=== "Sous‑domaine → chemin"
```yaml
REDIRECT_TO: "https://example.com/support"
REDIRECT_TO_REQUEST_URI: "yes"
REDIRECT_TO_STATUS_CODE: "301"
```
=== "Migration API"
```yaml
REDIRECT_FROM: "/api/v1/"
REDIRECT_TO: "https://api.example.com/v2/"
REDIRECT_TO_REQUEST_URI: "yes"
REDIRECT_TO_STATUS_CODE: "308"
```
=== "Après soumission de formulaire"
```yaml
REDIRECT_TO: "https://example.com/merci"
REDIRECT_TO_REQUEST_URI: "no"
REDIRECT_TO_STATUS_CODE: "303"
```
Redis
Prise en charge STREAM ✅
Le plugin Redis intègre Redis ou Valkey à BunkerWeb pour la mise en cache et l’accès rapide aux données. Essentiel en haute disponibilité pour partager sessions, métriques et autres informations entre plusieurs nœuds.
Comment ça marche :
- Activé, BunkerWeb se connecte au serveur Redis/Valkey configuré.
- Les données critiques (sessions, métriques, sécurité) y sont stockées.
- Plusieurs instances partagent ces données pour un clustering fluide.
- Prend en charge déploiements standalone, auth par mot de passe, SSL/TLS et Redis Sentinel.
- Reconnexion automatique et timeouts configurables pour la robustesse.
Comment l’utiliser
- Activer : mettez le paramètre
USE_REDISàyes. - Connexion : hôte/IP et port.
- Sécurité : identifiants si requis.
- Avancé : base, SSL et timeouts.
- Haute dispo : configurez Sentinel si utilisé.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_REDIS |
no |
global | non | Activer l’intégration Redis/Valkey (mode cluster). |
REDIS_HOST |
global | non | Hôte/IP du serveur Redis/Valkey. | |
REDIS_PORT |
6379 |
global | non | Port Redis/Valkey. |
REDIS_DATABASE |
0 |
global | non | Numéro de base (0–15). |
REDIS_SSL |
no |
global | non | Activer SSL/TLS. |
REDIS_SSL_VERIFY |
yes |
global | non | Vérifier le certificat SSL du serveur. |
REDIS_TIMEOUT |
5 |
global | non | Timeout (secondes). |
REDIS_USERNAME |
global | non | Nom d’utilisateur (Redis ≥ 6.0). | |
REDIS_PASSWORD |
global | non | Mot de passe. | |
REDIS_SENTINEL_HOSTS |
global | non | Hôtes Sentinel (séparés par espaces, hôte:port). |
|
REDIS_SENTINEL_USERNAME |
global | non | Utilisateur Sentinel. | |
REDIS_SENTINEL_PASSWORD |
global | non | Mot de passe Sentinel. | |
REDIS_SENTINEL_MASTER |
mymaster |
global | non | Nom du master Sentinel. |
REDIS_KEEPALIVE_IDLE |
300 |
global | non | Intervalle keepalive TCP (secondes) pour connexions inactives. |
REDIS_KEEPALIVE_POOL |
3 |
global | non | Nb max de connexions conservées dans le pool. |
!!! tip "Haute disponibilité" Configurez Redis Sentinel pour un failover automatique en production.
!!! warning "Sécurité" - Mots de passe forts pour Redis et Sentinel - Envisagez SSL/TLS - Ne pas exposer Redis sur Internet - Restreignez l’accès au port Redis (pare‑feu, segmentation)
!!! info "Prérequis pour le clustering" Lors du déploiement de BunkerWeb en cluster :
- Toutes les instances BunkerWeb doivent se connecter au même serveur Redis/Valkey ou cluster Sentinel
- Configurez le même numéro de base de données sur toutes les instances
- Assurez-vous de la connectivité réseau entre toutes les instances BunkerWeb et les serveurs Redis/Valkey
Exemples
=== "Configuration basique"
Une configuration simple pour se connecter à un serveur Redis ou Valkey sur la machine locale :
```yaml
USE_REDIS: "yes"
REDIS_HOST: "localhost"
REDIS_PORT: "6379"
```
=== "Configuration sécurisée"
Configuration avec authentification par mot de passe et SSL activé :
```yaml
USE_REDIS: "yes"
REDIS_HOST: "redis.example.com"
REDIS_PORT: "6379"
REDIS_PASSWORD: "your-strong-password"
REDIS_SSL: "yes"
REDIS_SSL_VERIFY: "yes"
```
=== "Redis Sentinel"
Configuration pour la haute disponibilité utilisant Redis Sentinel :
```yaml
USE_REDIS: "yes"
REDIS_SENTINEL_HOSTS: "sentinel1:26379 sentinel2:26379 sentinel3:26379"
REDIS_SENTINEL_MASTER: "mymaster"
REDIS_SENTINEL_PASSWORD: "sentinel-password"
REDIS_PASSWORD: "redis-password"
```
=== "Tuning avancé"
Configuration avec des paramètres de connexion avancés pour l'optimisation des performances :
```yaml
USE_REDIS: "yes"
REDIS_HOST: "redis.example.com"
REDIS_PORT: "6379"
REDIS_PASSWORD: "your-strong-password"
REDIS_DATABASE: "3"
REDIS_TIMEOUT: "3"
REDIS_KEEPALIVE_IDLE: "60"
REDIS_KEEPALIVE_POOL: "5"
```
Bonnes pratiques Redis
Lorsque vous utilisez Redis ou Valkey avec BunkerWeb, prenez en compte ces bonnes pratiques pour garantir des performances, une sécurité et une fiabilité optimales :
Gestion de la mémoire
- Surveillez l'utilisation de la mémoire : Configurez Redis avec des paramètres
maxmemoryappropriés pour éviter les erreurs de mémoire insuffisante - Définissez une politique d'éviction : Utilisez une
maxmemory-policy(par exemple,volatile-lrupour un usage général ouallkeys-lrupour les charges de travail à forte composante cache) adaptée à votre cas d'utilisation - Valeurs par défaut de l'all-in-one : L'image Docker AIO livre Redis avec
maxmemory=256mbetmaxmemory-policy=volatile-lru; remplacez ces valeurs via les variables d'environnementREDIS_MAXMEMORYetREDIS_MAXMEMORY_POLICY. Avecvolatile-lru, les compteurs transitoires (rate-limit, bad-behavior) sont évincés avant les clés dont la TTL est importante pour les sessions et les bannissements temporaires, et les clés sans expiration (bannissements permanents) restent intactes. La même politique est recommandée pour les serveurs Redis ou Valkey externes utilisés par BunkerWeb. - Évitez les clés volumineuses : Assurez-vous que les clés Redis individuelles restent d'une taille raisonnable pour éviter la dégradation des performances
Persistance des données
- Activez les instantanés RDB : Configurez des instantanés périodiques pour la persistance des données sans impact significatif sur les performances
- Envisagez AOF : Pour les données critiques, activez la persistance AOF (Append-Only File) avec une politique fsync appropriée
- Stratégie de sauvegarde : Mettez en œuvre des sauvegardes régulières de Redis dans le cadre de votre plan de reprise après sinistre
Optimisation des performances
- Pooling de connexions : BunkerWeb l'implémente déjà, mais assurez-vous que les autres applications suivent cette pratique
- Pipelining : Lorsque c'est possible, utilisez le pipelining pour les opérations en masse afin de réduire la surcharge réseau
- Évitez les opérations coûteuses : Soyez prudent avec les commandes comme KEYS dans les environnements de production
- Testez votre charge de travail : Utilisez redis-benchmark pour tester vos modèles de charge de travail spécifiques
Ressources supplémentaires
Reporting (PRO)
Prise en charge STREAM ❌
Regular reporting of important data from BunkerWeb (global, attacks, bans, requests, reasons, AS...). Monitoring pro plugin needed to work.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_REPORTING_SMTP |
no |
global | non | Enable sending the report via email. |
USE_REPORTING_WEBHOOK |
no |
global | non | Enable sending the report via webhook. |
REPORTING_SCHEDULE |
weekly |
global | non | The frequency at which reports are sent. |
REPORTING_TOP_N |
3 |
global | non | Number of entries shown in 'Top' tables (IPs, AS, reasons, countries, URIs and offenders). Range: 1-50. Values are clamped at runtime; the upstream metric caps at rank 50 per server. |
REPORTING_WEBHOOK_URLS |
global | non | List of webhook URLs to receive the report in Markdown (separated by spaces). | |
REPORTING_SMTP_EMAILS |
global | non | List of email addresses to receive the report in HTML format (separated by spaces). | |
REPORTING_SMTP_HOST |
global | non | The host server used for SMTP sending. | |
REPORTING_SMTP_PORT |
465 |
global | non | The port used for SMTP. Please note that there are different standards depending on the type of connection (SSL = 465, TLS = 587). |
REPORTING_SMTP_FROM_EMAIL |
global | non | The email address used as the sender. Note that 2FA must be disabled for this email address. | |
REPORTING_SMTP_FROM_USER |
global | non | The user authentication value for sending via the from email address. | |
REPORTING_SMTP_FROM_PASSWORD |
global | non | The password authentication value for sending via the from email address. | |
REPORTING_SMTP_SSL |
SSL |
global | non | Determine whether or not to use a secure connection for SMTP. |
REPORTING_SMTP_SUBJECT |
BunkerWeb Report |
global | non | The subject line of the email. |
Reverse proxy
Prise en charge STREAM ⚠️
Le plugin Reverse Proxy offre des capacités de proxy transparentes pour BunkerWeb, vous permettant de router les requêtes vers des serveurs et services backend. Cette fonctionnalité permet à BunkerWeb d'agir comme une façade sécurisée pour vos applications tout en offrant des avantages supplémentaires tels que la terminaison SSL et le filtrage de sécurité.
Comment ça marche :
- Lorsqu'un client envoie une requête à BunkerWeb, le plugin Reverse Proxy la transmet à votre serveur backend configuré.
- BunkerWeb ajoute des en-têtes de sécurité, applique des règles WAF et effectue d'autres contrôles de sécurité avant de transmettre les requêtes à votre application.
- Le serveur backend traite la requête et renvoie une réponse à BunkerWeb.
- BunkerWeb applique des mesures de sécurité supplémentaires à la réponse avant de la renvoyer au client.
- Le plugin prend en charge le proxying de flux HTTP et TCP/UDP, permettant un large éventail d'applications, y compris les WebSockets et d'autres protocoles non-HTTP.
Comment l’utiliser
Suivez ces étapes pour configurer et utiliser la fonctionnalité Reverse Proxy :
- Activer la fonctionnalité : Mettez le paramètre
USE_REVERSE_PROXYàyespour activer la fonctionnalité de reverse proxy. - Configurer vos serveurs backend : Spécifiez les serveurs en amont à l'aide du paramètre
REVERSE_PROXY_HOST. - Ajuster les paramètres du proxy : Affinez le comportement avec des paramètres optionnels pour les délais d'attente, les tailles de tampon, et d'autres paramètres.
- Configurer les options spécifiques au protocole : Pour les WebSockets ou des exigences HTTP spéciales, ajustez les paramètres correspondants.
- Mettre en place la mise en cache (optionnel) : Activez et configurez la mise en cache du proxy pour améliorer les performances pour le contenu fréquemment accédé.
Guide de configuration
=== "Configuration de base"
**Paramètres principaux**
Les paramètres de configuration essentiels activent et contrôlent la fonctionnalité de base du reverse proxy.
!!! success "Bénéfices du Reverse Proxy"
- **Amélioration de la sécurité :** Tout le trafic passe par les couches de sécurité de BunkerWeb avant d'atteindre vos applications
- **Terminaison SSL :** Gérez les certificats SSL/TLS de manière centralisée tandis que les services backend peuvent utiliser des connexions non chiffrées
- **Gestion des protocoles :** Prise en charge de HTTP, HTTPS, WebSockets, et d'autres protocoles
- **Interception des erreurs :** Personnalisez les pages d'erreur pour une expérience utilisateur cohérente
| Paramètre | Défaut | Contexte | Multiple | Description |
| --------------------------------- | ------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `USE_REVERSE_PROXY` | `no` | multisite | no | **Activer le Reverse Proxy :** Mettre à `yes` pour activer la fonctionnalité de reverse proxy. |
| `REVERSE_PROXY_HOST` | | multisite | yes | **Hôte Backend :** URL complète de la ressource proxifiée (proxy_pass). |
| `REVERSE_PROXY_URL` | `/` | multisite | yes | **URL d'emplacement :** Chemin qui sera proxifié vers le serveur backend. |
| `REVERSE_PROXY_BUFFERING` | `yes` | multisite | yes | **Mise en tampon de la réponse :** Active ou désactive la mise en tampon des réponses de la ressource proxifiée. |
| `REVERSE_PROXY_REQUEST_BUFFERING` | `yes` | multisite | yes | **Mise en tampon des requêtes :** Active ou désactive la mise en tampon des requêtes vers la ressource proxifiée. |
| `REVERSE_PROXY_KEEPALIVE` | `no` | multisite | yes | **Keep-Alive :** Active ou désactive les connexions keepalive avec la ressource proxifiée. |
| `REVERSE_PROXY_HTTP_VERSION` | `1.1` | multisite | yes | **Version HTTP :** Version du protocole HTTP utilisée pour communiquer avec l'amont (`1.0`, `1.1` ou `2`). Définissez à `2` pour activer le multiplexage HTTP/2 sur le lien amont. Les emplacements WebSocket sont fixés à 1.1 quoi qu'il arrive. |
| `REVERSE_PROXY_CUSTOM_HOST` | | multisite | no | **Hôte personnalisé :** Remplace l'en-tête Host envoyé au serveur en amont. |
| `REVERSE_PROXY_INTERCEPT_ERRORS` | `yes` | multisite | no | **Intercepter les erreurs :** Intercepte et réécrit les réponses d'erreur du backend. |
!!! tip "Bonnes pratiques"
- Spécifiez toujours l'URL complète dans `REVERSE_PROXY_HOST`, y compris le protocole (http:// ou https://)
- Utilisez `REVERSE_PROXY_INTERCEPT_ERRORS` pour fournir des pages d'erreur cohérentes sur tous vos services
- Lors de la configuration de plusieurs backends, utilisez le format de suffixe numéroté (par exemple, `REVERSE_PROXY_HOST_2`, `REVERSE_PROXY_URL_2`)
!!! warning "Comportement de la mise en tampon des requêtes"
La désactivation de `REVERSE_PROXY_REQUEST_BUFFERING` n'a d'effet que lorsque ModSecurity est désactivé, car la mise en tampon des requêtes est autrement imposée.
=== "Paramètres de connexion"
**Configuration des connexions et des délais d'attente**
Ces paramètres contrôlent le comportement des connexions, la mise en tampon et les valeurs de délai d'attente pour les connexions proxifiées.
!!! success "Bénéfices"
- **Performance optimisée :** Ajustez les tailles de tampon et les paramètres de connexion en fonction des besoins de votre application
- **Gestion des ressources :** Contrôlez l'utilisation de la mémoire grâce à des configurations de tampon appropriées
- **Fiabilité :** Configurez des délais d'attente appropriés pour gérer les connexions lentes ou les problèmes de backend
| Paramètre | Défaut | Contexte | Multiple | Description |
| ------------------------------- | ------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `REVERSE_PROXY_CONNECT_TIMEOUT` | `60s` | multisite | yes | **Délai de connexion :** Temps maximum pour établir une connexion avec le serveur backend. |
| `REVERSE_PROXY_READ_TIMEOUT` | `60s` | multisite | yes | **Délai de lecture :** Temps maximum entre les transmissions de deux paquets successifs depuis le serveur backend. |
| `REVERSE_PROXY_SEND_TIMEOUT` | `60s` | multisite | yes | **Délai d'envoi :** Temps maximum entre les transmissions de deux paquets successifs vers le serveur backend. |
| `PROXY_BUFFERS` | | multisite | no | **Tampons :** Nombre et taille des tampons pour lire la réponse du serveur backend. |
| `PROXY_BUFFER_SIZE` | | multisite | no | **Taille du tampon :** Taille du tampon pour lire la première partie de la réponse du serveur backend. |
| `PROXY_BUSY_BUFFERS_SIZE` | | multisite | no | **Taille des tampons occupés :** Taille des tampons qui peuvent être occupés à envoyer une réponse au client. |
!!! warning "Considérations sur les délais d'attente"
- Des délais trop courts peuvent interrompre des connexions légitimes mais lentes
- Des délais trop longs peuvent laisser des connexions ouvertes inutilement, épuisant potentiellement les ressources
- Pour les applications WebSocket, augmentez considérablement les délais de lecture et d'envoi (300s ou plus recommandé)
=== "Configuration SSL/TLS"
**Paramètres SSL/TLS pour les connexions Backend**
Ces paramètres contrôlent la manière dont BunkerWeb établit des connexions sécurisées avec les serveurs backend.
!!! success "Bénéfices"
- **Chiffrement de bout en bout :** Maintenez des connexions chiffrées du client au backend
- **Validation des certificats :** Contrôlez la validation des certificats des serveurs backend
- **Support SNI :** Spécifiez l'indication du nom du serveur (SNI) pour les backends hébergeant plusieurs sites
| Paramètre | Défaut | Contexte | Multiple | Description |
| ---------------------------- | ------ | --------- | -------- | ---------------------------------------------------------------------------------------------- |
| `REVERSE_PROXY_SSL_SNI` | `no` | multisite | no | **SSL SNI :** Active ou désactive l'envoi du SNI (Server Name Indication) à l'amont. |
| `REVERSE_PROXY_SSL_SNI_NAME` | | multisite | no | **Nom SSL SNI :** Définit le nom d'hôte SNI à envoyer à l'amont lorsque le SSL SNI est activé. |
!!! info "Explication du SNI"
L'Indication du Nom du Serveur (SNI) est une extension TLS qui permet à un client de spécifier le nom d'hôte auquel il tente de se connecter pendant la négociation. Cela permet aux serveurs de présenter plusieurs certificats sur la même adresse IP et le même port, permettant ainsi de servir plusieurs sites web sécurisés (HTTPS) à partir d'une seule adresse IP sans que tous ces sites n'utilisent le même certificat.
=== "Support des protocoles"
**Configuration spécifique aux protocoles**
Configurez la gestion de protocoles spéciaux, notamment pour les WebSockets et autres protocoles non-HTTP.
!!! success "Bénéfices"
- **Flexibilité des protocoles :** Le support des WebSockets permet des applications en temps réel
- **Applications web modernes :** Activez des fonctionnalités interactives nécessitant une communication bidirectionnelle
| Paramètre | Défaut | Contexte | Multiple | Description |
| ------------------ | ------ | --------- | -------- | ----------------------------------------------------------------------- |
| `REVERSE_PROXY_WS` | `no` | multisite | yes | **Support WebSocket :** Active le protocole WebSocket sur la ressource. |
!!! tip "Configuration WebSocket"
- Lors de l'activation des WebSockets avec `REVERSE_PROXY_WS: "yes"`, envisagez d'augmenter les valeurs des délais d'attente
- Les connexions WebSocket restent ouvertes plus longtemps que les connexions HTTP typiques
- Pour les applications WebSocket, une configuration recommandée est :
```yaml
REVERSE_PROXY_WS: "yes"
REVERSE_PROXY_READ_TIMEOUT: "300s"
REVERSE_PROXY_SEND_TIMEOUT: "300s"
```
=== "Gestion des en-têtes"
**Configuration des en-têtes HTTP**
Contrôlez quels en-têtes sont envoyés aux serveurs backend et aux clients, vous permettant d'ajouter, de modifier ou de préserver des en-têtes HTTP.
!!! success "Bénéfices"
- **Contrôle de l'information :** Gérez précisément les informations partagées entre les clients et les backends
- **Amélioration de la sécurité :** Ajoutez des en-têtes liés à la sécurité ou supprimez ceux qui pourraient divulguer des informations sensibles
- **Support d'intégration :** Fournissez les en-têtes nécessaires à l'authentification et au bon fonctionnement du backend
| Paramètre | Défaut | Contexte | Multiple | Description |
| -------------------------------------- | --------- | --------- | -------- | ------------------------------------------------------------------------------------------------- |
| `REVERSE_PROXY_HEADERS` | | multisite | yes | **En-têtes personnalisés :** En-têtes HTTP à envoyer au backend, séparés par des points-virgules. |
| `REVERSE_PROXY_HIDE_HEADERS` | `Upgrade` | multisite | yes | **Cacher les en-têtes :** En-têtes HTTP à cacher aux clients lorsqu'ils sont reçus du backend. |
| `REVERSE_PROXY_HEADERS_CLIENT` | | multisite | yes | **En-têtes client :** En-têtes HTTP à envoyer au client, séparés par des points-virgules. |
| `REVERSE_PROXY_UNDERSCORES_IN_HEADERS` | `no` | multisite | no | **Underscores dans les en-têtes :** Active ou désactive la directive `underscores_in_headers`. |
!!! warning "Considérations de sécurité"
Lors de l'utilisation de la fonctionnalité de reverse proxy, soyez prudent quant aux en-têtes que vous transmettez à vos applications backend. Certains en-têtes peuvent exposer des informations sensibles sur votre infrastructure ou contourner les contrôles de sécurité.
!!! example "Exemples de format d'en-tête"
En-têtes personnalisés vers les serveurs backend :
```
REVERSE_PROXY_HEADERS: "X-Real-IP $remote_addr;X-Forwarded-For $proxy_add_x_forwarded_for;X-Forwarded-Proto $scheme"
```
En-têtes personnalisés vers les clients :
```
REVERSE_PROXY_HEADERS_CLIENT: "X-Powered-By BunkerWeb;X-Frame-Options SAMEORIGIN"
```
=== "Authentification"
**Configuration de l'authentification externe**
Intégrez avec des systèmes d'authentification externes pour centraliser la logique d'autorisation à travers vos applications.
!!! success "Bénéfices"
- **Authentification centralisée :** Mettez en œuvre un point d'authentification unique pour plusieurs applications
- **Sécurité cohérente :** Appliquez des politiques d'authentification uniformes sur différents services
- **Contrôle amélioré :** Transmettez les détails d'authentification aux applications backend via des en-têtes ou des variables
| Paramètre | Défaut | Contexte | Multiple | Description |
| --------------------------------------- | ------ | --------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `REVERSE_PROXY_AUTH_REQUEST` | | multisite | yes | **Requête d'authentification :** Active l'authentification via un fournisseur externe. |
| `REVERSE_PROXY_AUTH_REQUEST_SIGNIN_URL` | | multisite | yes | **URL de connexion :** Redirige les clients vers l'URL de connexion en cas d'échec de l'authentification. |
| `REVERSE_PROXY_AUTH_REQUEST_SET` | | multisite | yes | **Variables d'authentification :** Variables à définir à partir du fournisseur d'authentification. |
!!! tip "Intégration de l'authentification"
- La fonctionnalité de requête d'authentification permet la mise en œuvre de microservices d'authentification centralisés
- Votre service d'authentification doit renvoyer un code de statut 200 pour une authentification réussie ou 401/403 en cas d'échec
- Utilisez la directive auth_request_set pour extraire et transmettre des informations du service d'authentification
=== "Configuration avancée"
**Options de configuration supplémentaires**
Ces paramètres offrent une personnalisation plus poussée du comportement du reverse proxy pour des scénarios spécialisés.
!!! success "Bénéfices"
- **Personnalisation :** Incluez des extraits de configuration supplémentaires pour des exigences complexes
- **Optimisation des performances :** Affinez la gestion des requêtes pour des cas d'usage spécifiques
- **Flexibilité :** Adaptez-vous aux exigences uniques de l'application avec des configurations spécialisées
| Paramètre | Défaut | Contexte | Multiple | Description |
| --------------------------------- | ------ | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `REVERSE_PROXY_INCLUDES` | | multisite | yes | **Configurations supplémentaires :** Incluez des configurations additionnelles dans le bloc location. |
| `REVERSE_PROXY_PASS_REQUEST_BODY` | `yes` | multisite | yes | **Passer le corps de la requête :** Active ou désactive la transmission du corps de la requête. |
| `REVERSE_PROXY_MODSECURITY` | `yes` | multisite | yes | **ModSecurity (par location) :** Mettez à `no` pour émettre `modsecurity off;` dans cette location — contourne le WAF sur les points de terminaison de gros téléversements afin d'éviter un OOM (voir la note ci-dessous). |
!!! warning "Considérations de sécurité"
Soyez prudent lorsque vous incluez des extraits de configuration personnalisés car ils peuvent outrepasser les paramètres de sécurité de BunkerWeb ou introduire des vulnérabilités s'ils ne sont pas correctement configurés.
!!! warning "Recommandation de sécurité pour les gros téléversements"
ModSecurity met en mémoire tampon le corps complet de la requête et ne peut pas le plafonner pour les téléversements de plusieurs Go, ce qui peut provoquer un OOM du worker. Si — **et seulement si** — une URL de reverse proxy est utilisée *exclusivement* pour les téléversements de fichiers (par exemple un point de terminaison `/upload` dédié), définissez `REVERSE_PROXY_MODSECURITY_N: "no"` sur cette URL. Ne le désactivez pas sur des URL à usage mixte : vous perdriez la couverture WAF sur tout ce qui est servi par cette location.
Pour conserver une protection des téléversements après le contournement de ModSecurity, associez cela à un plugin d'analyse de fichiers comme [ClamAV](https://github.com/bunkerity/bunkerweb-plugins/tree/main/clamav) ou [VirusTotal](https://github.com/bunkerity/bunkerweb-plugins/tree/main/virustotal) — ils inspectent le fichier téléversé lui-même plutôt que le corps brut de la requête.
=== "Configuration du cache"
**Paramètres de mise en cache des réponses**
Améliorez les performances en mettant en cache les réponses des serveurs backend, réduisant ainsi la charge et améliorant les temps de réponse.
!!! success "Bénéfices"
- **Performance :** Réduisez la charge sur les serveurs backend en servant du contenu mis en cache
- **Latence réduite :** Temps de réponse plus rapides pour le contenu fréquemment demandé
- **Économies de bande passante :** Minimisez le trafic réseau interne en mettant en cache les réponses
- **Personnalisation :** Configurez exactement quoi, quand et comment le contenu est mis en cache
| Paramètre | Défaut | Contexte | Multiple | Description |
| ---------------------------- | ---------------------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `USE_PROXY_CACHE` | `no` | multisite | no | **Activer le cache :** Mettre à `yes` pour activer la mise en cache des réponses du backend. |
| `PROXY_CACHE_PATH_LEVELS` | `1:2` | global | no | **Niveaux de chemin du cache :** Comment structurer la hiérarchie du répertoire de cache. |
| `PROXY_CACHE_PATH_ZONE_SIZE` | `10m` | global | no | **Taille de la zone de cache :** Taille de la zone de mémoire partagée utilisée pour les métadonnées du cache. |
| `PROXY_CACHE_PATH_PARAMS` | `max_size=100m` | global | no | **Paramètres du chemin de cache :** Paramètres supplémentaires pour le chemin de cache. |
| `PROXY_CACHE_METHODS` | `GET HEAD` | multisite | no | **Méthodes de cache :** Méthodes HTTP qui peuvent être mises en cache. |
| `PROXY_CACHE_MIN_USES` | `2` | multisite | no | **Utilisations min. pour cache :** Nombre minimum de requêtes avant qu'une réponse ne soit mise en cache. |
| `PROXY_CACHE_KEY` | `$scheme$host$request_uri` | multisite | no | **Clé de cache :** La clé utilisée pour identifier de manière unique une réponse mise en cache. |
| `PROXY_CACHE_VALID` | `200=24h 301=1h 302=24h` | multisite | no | **Validité du cache :** Durée de mise en cache pour des codes de réponse spécifiques. |
| `PROXY_NO_CACHE` | `$http_pragma $http_authorization` | multisite | no | **Pas de cache :** Conditions pour ne pas mettre en cache les réponses même si elles sont normalement cachables. |
| `PROXY_CACHE_BYPASS` | `0` | multisite | no | **Contournement du cache :** Conditions sous lesquelles contourner le cache. |
!!! tip "Bonnes pratiques de mise en cache"
- Ne mettez en cache que le contenu qui ne change pas fréquemment ou qui n'est pas personnalisé
- Utilisez des durées de cache appropriées en fonction du type de contenu (les ressources statiques peuvent être mises en cache plus longtemps)
- Configurez `PROXY_NO_CACHE` pour éviter de mettre en cache du contenu sensible ou personnalisé
- Surveillez les taux de réussite du cache et ajustez les paramètres en conséquence
!!! danger "Utilisateurs de Docker Compose - Variables NGINX"
Lorsque vous utilisez Docker Compose avec des variables NGINX dans vos configurations, vous devez échapper le signe dollar ($) en utilisant des doubles signes dollar ($$). Cela s'applique à tous les paramètres contenant des variables NGINX comme $remote_addr, $proxy_add_x_forwarded_for, etc.
Sans cet échappement, Docker Compose essaiera de substituer ces variables par des variables d'environnement, qui n'existent généralement pas, ce qui entraînera des valeurs vides dans votre configuration NGINX.
Exemples de configuration
=== "Proxy HTTP de base"
Une configuration simple pour proxifier les requêtes HTTP vers un serveur d'application backend :
```yaml
USE_REVERSE_PROXY: "yes"
REVERSE_PROXY_HOST: "http://application:8080"
REVERSE_PROXY_URL: "/"
REVERSE_PROXY_CONNECT_TIMEOUT: "10s"
REVERSE_PROXY_SEND_TIMEOUT: "60s"
REVERSE_PROXY_READ_TIMEOUT: "60s"
```
=== "Application WebSocket"
Configuration optimisée pour une application WebSocket avec des délais d'attente plus longs :
```yaml
USE_REVERSE_PROXY: "yes"
REVERSE_PROXY_HOST: "http://websocket-app:8080"
REVERSE_PROXY_URL: "/"
REVERSE_PROXY_WS: "yes"
REVERSE_PROXY_CONNECT_TIMEOUT: "10s"
REVERSE_PROXY_SEND_TIMEOUT: "300s"
REVERSE_PROXY_READ_TIMEOUT: "300s"
```
=== "Emplacements multiples"
Configuration pour router différents chemins vers différents services backend :
```yaml
USE_REVERSE_PROXY: "yes"
# Backend API
REVERSE_PROXY_HOST: "http://api-server:8080"
REVERSE_PROXY_URL: "/api/"
# Backend Admin
REVERSE_PROXY_HOST_2: "http://admin-server:8080"
REVERSE_PROXY_URL_2: "/admin/"
# Application Frontend
REVERSE_PROXY_HOST_3: "http://frontend:3000"
REVERSE_PROXY_URL_3: "/"
```
=== "Configuration du cache"
Configuration avec mise en cache du proxy activée pour de meilleures performances :
```yaml
USE_REVERSE_PROXY: "yes"
REVERSE_PROXY_HOST: "http://application:8080"
REVERSE_PROXY_URL: "/"
USE_PROXY_CACHE: "yes"
PROXY_CACHE_VALID: "200=24h 301=1h 302=24h"
PROXY_CACHE_METHODS: "GET HEAD"
PROXY_NO_CACHE: "$http_authorization"
```
=== "Gestion avancée des en-têtes"
Configuration avec manipulation personnalisée des en-têtes :
```yaml
USE_REVERSE_PROXY: "yes"
REVERSE_PROXY_HOST: "http://application:8080"
REVERSE_PROXY_URL: "/"
# En-têtes personnalisés vers le backend
REVERSE_PROXY_HEADERS: "X-Real-IP $remote_addr;X-Forwarded-For $proxy_add_x_forwarded_for;X-Forwarded-Proto $scheme"
# En-têtes personnalisés vers le client
REVERSE_PROXY_HEADERS_CLIENT: "X-Powered-By BunkerWeb;X-Frame-Options SAMEORIGIN"
```
=== "Intégration de l'authentification"
Configuration avec authentification externe :
```yaml
USE_REVERSE_PROXY: "yes"
REVERSE_PROXY_HOST: "http://application:8080"
REVERSE_PROXY_URL: "/"
# Configuration de l'authentification
REVERSE_PROXY_AUTH_REQUEST: "/auth"
REVERSE_PROXY_AUTH_REQUEST_SIGNIN_URL: "https://login.example.com"
REVERSE_PROXY_AUTH_REQUEST_SET: "$auth_user $upstream_http_x_user;$auth_role $upstream_http_x_role"
# Backend du service d'authentification
REVERSE_PROXY_HOST_2: "http://auth-service:8080"
REVERSE_PROXY_URL_2: "/auth"
```
Reverse scan
Prise en charge STREAM ✅
Le plugin Reverse Scan protège contre les tentatives de contournement via proxy en scannant certains ports côté client pour détecter des proxys/serveurs ouverts. Il aide à identifier et bloquer les clients qui tentent de masquer leur identité ou leur origine.
Comment ça marche :
- À la connexion d’un client, BunkerWeb tente de scanner des ports spécifiques sur l’IP du client.
- Les ports de proxy courants (80, 443, 8080, etc.) sont vérifiés.
- Si des ports ouverts sont détectés (signe d’un proxy), la connexion est refusée.
- Cela ajoute une couche contre bots/outils automatisés et utilisateurs malveillants.
!!! success "Avantages clés"
1. **Détection de proxy :** identifie les clients qui exposent des ports de proxy courants.
2. **Protection contre le contournement :** limite les tentatives de masquage d’origine via proxys ouverts.
3. **Configuration flexible :** personnalisez les ports et délais selon votre modèle de menace.
4. **Défense automatisée :** bloque les clients suspects sans vérification manuelle.
5. **Intégration transparente :** fonctionne avec vos couches de sécurité existantes.
Comment l’utiliser
- Activer : mettez le paramètre
USE_REVERSE_SCANàyes. - Ports : personnalisez
REVERSE_SCAN_PORTS. - Timeout : ajustez
REVERSE_SCAN_TIMEOUTpour l’équilibre sécurité/performance. - Suivi : consultez les logs et la web UI.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_REVERSE_SCAN |
no |
multisite | non | Activer l’analyse des ports côté client. |
REVERSE_SCAN_PORTS |
22 80 443 3128 8000 8080 |
multisite | non | Ports à vérifier (séparés par des espaces). |
REVERSE_SCAN_TIMEOUT |
500 |
multisite | non | Délai max par port en millisecondes. |
!!! warning "Performance" Scanner de nombreux ports ajoute de la latence. Limitez la liste et adaptez le timeout.
!!! info "Ports de proxy courants" La configuration par défaut inclut 80, 443, 8080, 3128 et SSH (22). Adaptez selon votre modèle de menace.
Exemples
=== "Basique"
```yaml
USE_REVERSE_SCAN: "yes"
REVERSE_SCAN_TIMEOUT: "500"
REVERSE_SCAN_PORTS: "80 443 8080"
```
=== "Approfondi"
```yaml
USE_REVERSE_SCAN: "yes"
REVERSE_SCAN_TIMEOUT: "1000"
REVERSE_SCAN_PORTS: "22 80 443 3128 8080 8000 8888 1080 3333 8081"
```
=== "Optimisé performance"
```yaml
USE_REVERSE_SCAN: "yes"
REVERSE_SCAN_TIMEOUT: "250"
REVERSE_SCAN_PORTS: "80 443 8080"
```
=== "Haute sécurité"
```yaml
USE_REVERSE_SCAN: "yes"
REVERSE_SCAN_TIMEOUT: "1500"
REVERSE_SCAN_PORTS: "22 25 80 443 1080 3128 3333 4444 5555 6588 6666 7777 8000 8080 8081 8800 8888 9999"
```
Robots.txt
Prise en charge STREAM ✅
Le plugin Robots.txt gère le fichier robots.txt de votre site, indiquant aux robots les zones autorisées/interdites.
Comment ça marche :
Activé, BunkerWeb génère dynamiquement /robots.txt à la racine. Les règles sont agrégées dans l’ordre :
- DarkVisitors (si
ROBOTSTXT_DARKVISITORS_TOKEN) : bloque des bots/IA connus selon les types d’agents et chemins interdits configurés. - Listes communautaires (
ROBOTSTXT_COMMUNITY_LISTS). - URLs personnalisées (
ROBOTSTXT_URLS). - Règles manuelles définies via les variables
ROBOTSTXT_RULE.
Ensuite, les règles à ignorer (ROBOTSTXT_IGNORE_RULE[_N], PCRE) sont filtrées. S’il ne reste rien, un User-agent: * + Disallow: / par défaut est appliqué. Des sitemaps (ROBOTSTXT_SITEMAP[_N]) peuvent être ajoutés.
Contournement dynamique des bots avec l’API DarkVisitors
DarkVisitors fournit un robots.txt dynamique pour bloquer des bots/IA. Inscrivez‑vous sur darkvisitors.com et obtenez un bearer token.
Comment l’utiliser
- Activer : mettez le paramètre
USE_ROBOTSTXTàyes. - Règles : choisissez une ou plusieurs méthodes pour définir vos règles
robots.txt:- API DarkVisitors : fournissez
ROBOTSTXT_DARKVISITORS_TOKENet, si nécessaire,ROBOTSTXT_DARKVISITORS_AGENT_TYPESetROBOTSTXT_DARKVISITORS_DISALLOW. - Listes communautaires : indiquez
ROBOTSTXT_COMMUNITY_LISTS(IDs séparés par des espaces). - URLs personnalisées : fournissez
ROBOTSTXT_URLS(URLs séparées par des espaces). - Règles manuelles : utilisez
ROBOTSTXT_RULEpour une règle individuelle (plusieurs règles peuvent être précisées avecROBOTSTXT_RULE_N).
- API DarkVisitors : fournissez
- Filtrer (optionnel) : utilisez
ROBOTSTXT_IGNORE_RULE(ouROBOTSTXT_IGNORE_RULE_N) pour ignorer des règles selon un motif PCRE. - Sitemaps (optionnel) : utilisez
ROBOTSTXT_SITEMAP(ouROBOTSTXT_SITEMAP_N) pour ajouter des URLs de sitemap. - Accès :
http(s)://votre-domaine/robots.txt.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_ROBOTSTXT |
no |
multisite | non | Active/désactive la fonctionnalité. |
ROBOTSTXT_DARKVISITORS_TOKEN |
multisite | non | Jeton Bearer pour l’API DarkVisitors. | |
ROBOTSTXT_DARKVISITORS_AGENT_TYPES |
multisite | non | Types d’agents (séparés par virgules) à inclure depuis DarkVisitors. | |
ROBOTSTXT_DARKVISITORS_DISALLOW |
/ |
multisite | non | Valeur du champ Disallow envoyée à l’API DarkVisitors. |
ROBOTSTXT_COMMUNITY_LISTS |
multisite | non | IDs de listes communautaires (séparés par espaces). | |
ROBOTSTXT_URLS |
multisite | non | URLs supplémentaires (supporte file:// et auth basique). |
|
ROBOTSTXT_RULE |
multisite | oui | Règle individuelle robots.txt. |
|
ROBOTSTXT_HEADER |
multisite | oui | En‑tête (peut être encodé Base64). | |
ROBOTSTXT_FOOTER |
multisite | oui | Pied de page (peut être encodé Base64). | |
ROBOTSTXT_IGNORE_RULE |
multisite | oui | Motif PCRE d’ignorance de règles. | |
ROBOTSTXT_SITEMAP |
multisite | oui | URL de sitemap. |
Exemples
Basique (manuel)
USE_ROBOTSTXT: "yes"
ROBOTSTXT_RULE: "User-agent: *"
ROBOTSTXT_RULE_1: "Disallow: /private"
ROBOTSTXT_SITEMAP: "https://example.com/sitemap.xml"
Sources dynamiques (DarkVisitors + liste)
USE_ROBOTSTXT: "yes"
ROBOTSTXT_DARKVISITORS_TOKEN: "your-darkvisitors-token-here"
ROBOTSTXT_DARKVISITORS_AGENT_TYPES: "AI Data Scraper"
ROBOTSTXT_COMMUNITY_LISTS: "robots-disallowed"
ROBOTSTXT_IGNORE_RULE: "User-agent: Googlebot-Image"
Combiné
USE_ROBOTSTXT: "yes"
ROBOTSTXT_DARKVISITORS_TOKEN: "your-darkvisitors-token-here"
ROBOTSTXT_COMMUNITY_LISTS: "ai-robots-txt"
ROBOTSTXT_URLS: "https://example.com/my-custom-rules.txt"
ROBOTSTXT_RULE: "User-agent: MyOwnBot"
ROBOTSTXT_RULE_1: "Disallow: /admin"
ROBOTSTXT_IGNORE_RULE: "User-agent: Googlebot-Image"
ROBOTSTXT_SITEMAP: "https://example.com/sitemap.xml"
En‑tête/Pied de page
USE_ROBOTSTXT: "yes"
ROBOTSTXT_HEADER: "# This is a custom header"
ROBOTSTXT_RULE: "User-agent: *"
ROBOTSTXT_RULE_1: "Disallow: /private"
ROBOTSTXT_FOOTER: "# This is a custom footer"
ROBOTSTXT_SITEMAP: "https://example.com/sitemap.xml"
Pour en savoir plus : documentation robots.txt.
Security.txt
Prise en charge STREAM ✅
Le plugin Security.txt met en œuvre le standard Security.txt (RFC 9116) sur votre site. Il facilite l’accès aux politiques de sécurité et fournit un moyen standardisé de signaler des vulnérabilités.
Comment ça marche :
- Une fois activé, BunkerWeb expose
/.well-known/security.txtà la racine du site. - Le fichier contient vos politiques, contacts et informations pertinentes.
- Les chercheurs en sécurité et outils automatisés le trouvent à l’emplacement standard.
- Le contenu est défini via des paramètres simples (contacts, clés de chiffrement, politiques, remerciements…).
- BunkerWeb formate automatiquement selon la RFC 9116.
Comment l’utiliser
- Activer : mettez le paramètre
USE_SECURITYTXTàyes. - Contacts : précisez au moins un moyen de contact via
SECURITYTXT_CONTACT. - Informations additionnelles : configurez expiration, chiffrement, remerciements, URL de politique…
- Laisser BunkerWeb faire le reste : une fois configuré, BunkerWeb crée et sert automatiquement le fichier security.txt à l’emplacement standard.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_SECURITYTXT |
no |
multisite | non | Activer le fichier security.txt. |
SECURITYTXT_URI |
/.well-known/security.txt |
multisite | non | URI d’accès au fichier. |
SECURITYTXT_CONTACT |
multisite | oui | Moyens de contact (ex. mailto:security@example.com). |
|
SECURITYTXT_EXPIRES |
multisite | non | Date d’expiration (format ISO 8601). | |
SECURITYTXT_ENCRYPTION |
multisite | oui | URL de clés de chiffrement pour échanges sécurisés. | |
SECURITYTXT_ACKNOWLEDGEMENTS |
multisite | oui | URL de remerciements pour les chercheurs. | |
SECURITYTXT_POLICY |
multisite | oui | URL de la politique de sécurité (procédure de signalement). | |
SECURITYTXT_HIRING |
multisite | oui | URL d’offres d’emploi sécurité. | |
SECURITYTXT_CANONICAL |
multisite | oui | URL canonique du fichier security.txt. | |
SECURITYTXT_PREFERRED_LANG |
en |
multisite | non | Langue préférée (code ISO 639‑1). |
SECURITYTXT_CSAF |
multisite | oui | Lien vers le provider-metadata.json du fournisseur CSAF. |
!!! warning "Expiration requise"
Le champ Expires est obligatoire. Si SECURITYTXT_EXPIRES est absent, BunkerWeb définit par défaut une expiration à un an.
!!! info "Contacts essentiels" Fournissez au moins un moyen de contact : email, formulaire, téléphone, etc.
!!! warning "HTTPS obligatoire"
Toutes les URLs (sauf mailto: et tel:) DOIVENT utiliser HTTPS. BunkerWeb convertit les URL non‑HTTPS pour la conformité.
Exemples
=== "Basique"
```yaml
USE_SECURITYTXT: "yes"
SECURITYTXT_CONTACT: "mailto:security@example.com"
SECURITYTXT_POLICY: "https://example.com/security-policy"
```
=== "Complet"
```yaml
USE_SECURITYTXT: "yes"
SECURITYTXT_CONTACT: "mailto:security@example.com"
SECURITYTXT_CONTACT_2: "https://example.com/security-contact-form"
SECURITYTXT_EXPIRES: "2023-12-31T23:59:59+00:00"
SECURITYTXT_ENCRYPTION: "https://example.com/pgp-key.txt"
SECURITYTXT_ACKNOWLEDGEMENTS: "https://example.com/hall-of-fame"
SECURITYTXT_POLICY: "https://example.com/security-policy"
SECURITYTXT_HIRING: "https://example.com/jobs/security"
SECURITYTXT_CANONICAL: "https://example.com/.well-known/security.txt"
SECURITYTXT_PREFERRED_LANG: "en"
SECURITYTXT_CSAF: "https://example.com/provider-metadata.json"
```
=== "Contacts multiples"
```yaml
USE_SECURITYTXT: "yes"
SECURITYTXT_CONTACT: "mailto:security@example.com"
SECURITYTXT_CONTACT_2: "tel:+1-201-555-0123"
SECURITYTXT_CONTACT_3: "https://example.com/security-form"
SECURITYTXT_POLICY: "https://example.com/security-policy"
SECURITYTXT_EXPIRES: "2024-06-30T23:59:59+00:00"
```
Self-signed certificate
Prise en charge STREAM ✅
Le plugin Certificat auto‑signé génère et gère automatiquement des certificats SSL/TLS directement dans BunkerWeb, pour activer HTTPS sans autorité de certification externe. Idéal en développement, réseaux internes ou déploiements rapides d’HTTPS.
Comment ça marche :
- Une fois activé, BunkerWeb génère un certificat auto‑signé pour vos domaines configurés.
- Le certificat inclut tous les noms de serveurs définis, assurant une validation correcte.
- Les certificats sont stockés de façon sécurisée et chiffrent tout le trafic HTTPS.
- Le renouvellement est automatique avant expiration.
!!! warning "Avertissements navigateurs" Les navigateurs afficheront des alertes de sécurité car un certificat auto‑signé n’est pas émis par une AC de confiance. En production, préférez Let’s Encrypt.
Comment l’utiliser
- Activer : mettez le paramètre
GENERATE_SELF_SIGNED_SSLàyes. - Algorithme : choisissez via
SELF_SIGNED_SSL_ALGORITHM. - Validité : durée en jours via
SELF_SIGNED_SSL_EXPIRY. - Sujet : champ subject via
SELF_SIGNED_SSL_SUBJ. - Laisser BunkerWeb faire le reste : une fois configurés, les certificats sont générés et appliqués automatiquement à vos domaines.
!!! tip "Mode stream"
En mode stream, configurez LISTEN_STREAM_PORT_SSL pour définir le port d’écoute SSL/TLS.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
GENERATE_SELF_SIGNED_SSL |
no |
multisite | non | Activer la génération automatique de certificats auto‑signés. |
SELF_SIGNED_SSL_ALGORITHM |
ec-prime256v1 |
multisite | non | Algorithme : ec-prime256v1, ec-secp384r1, rsa-2048, rsa-4096. |
SELF_SIGNED_SSL_EXPIRY |
365 |
multisite | non | Validité (jours). |
SELF_SIGNED_SSL_SUBJ |
/CN=www.example.com/ |
multisite | non | Sujet du certificat (identifiant le domaine). |
!!! tip "Environnements de développement" Les certificats auto-signés conviennent aux environnements de développement et de test où vous pouvez contrôler les certificats de confiance des clients. En production publique, utilisez plutôt une autorité de certification reconnue.
!!! info "Informations du certificat" Le certificat généré inclut les noms de serveur configurés et utilise l’algorithme configuré. Ajustez le sujet du certificat pour refléter le domaine principal.
Exemples
=== "Basique"
```yaml
GENERATE_SELF_SIGNED_SSL: "yes"
SELF_SIGNED_SSL_ALGORITHM: "ec-prime256v1"
SELF_SIGNED_SSL_EXPIRY: "365"
SELF_SIGNED_SSL_SUBJ: "/CN=mysite.local/"
```
=== "Certificats courte durée"
```yaml
GENERATE_SELF_SIGNED_SSL: "yes"
SELF_SIGNED_SSL_ALGORITHM: "ec-prime256v1"
SELF_SIGNED_SSL_EXPIRY: "90"
SELF_SIGNED_SSL_SUBJ: "/CN=dev.example.com/"
```
=== "Test en RSA"
```yaml
SERVER_NAME: "test.example.com"
GENERATE_SELF_SIGNED_SSL: "yes"
SELF_SIGNED_SSL_ALGORITHM: "rsa-4096"
SELF_SIGNED_SSL_EXPIRY: "365"
SELF_SIGNED_SSL_SUBJ: "/CN=test.example.com/"
```
Sessions
Prise en charge STREAM ✅
Le plugin Sessions fournit une gestion robuste des sessions HTTP dans BunkerWeb pour suivre de manière sécurisée et fiable les sessions utilisateur entre les requêtes. Cette fonctionnalité centrale est essentielle pour maintenir l’état utilisateur, la persistance d’authentification et les autres fonctions qui nécessitent une continuité d’identité, comme la protection antibot et les systèmes d’authentification utilisateur.
Comment ça marche :
- Lorsqu’un utilisateur interagit pour la première fois avec votre site, BunkerWeb crée un identifiant de session unique.
- Cet identifiant est stocké de manière sécurisée dans un cookie du navigateur de l’utilisateur.
- Lors des requêtes suivantes, BunkerWeb récupère l’identifiant de session depuis le cookie et l’utilise pour accéder aux données de session de l’utilisateur.
- Les données de session peuvent être stockées localement ou dans Redis pour les environnements distribués comportant plusieurs instances BunkerWeb.
- Les sessions sont gérées automatiquement avec des délais configurables, ce qui garantit la sécurité tout en conservant une bonne ergonomie.
- La sécurité cryptographique des sessions est assurée par une clé secrète utilisée pour signer les cookies de session.
Comment l’utiliser
Suivez ces étapes pour configurer et utiliser la fonctionnalité Sessions :
- Configurer la sécurité des sessions : définissez un
SESSIONS_SECRETfort et unique pour empêcher la falsification des cookies de session. (La valeur par défaut est "random", ce qui amène BunkerWeb à générer une clé secrète aléatoire.) - Choisir un nom de session : personnalisez éventuellement
SESSIONS_NAMEpour définir le nom du cookie de session dans le navigateur. (La valeur par défaut est "random", ce qui amène BunkerWeb à générer un nom aléatoire.) - Définir les délais d’expiration : configurez la durée de validité des sessions avec les paramètres (
SESSIONS_IDLING_TIMEOUT,SESSIONS_ROLLING_TIMEOUT,SESSIONS_ABSOLUTE_TIMEOUT). - Partager le cookie entre sous-domaines (optionnel, par serveur) : par défaut, le cookie de session est limité à l’hôte. Si un serveur donné héberge plusieurs sous-domaines d’un même domaine enregistrable (par exemple
a.example.cometb.example.com) et que vous voulez partager l’état antibot/défi, définissezSESSIONS_DOMAINsur le domaine parent (example.com) sur ce serveur uniquement.SESSIONS_DOMAINest un paramètre multisite : configurez-le par serveur afin que des tenants non liés sur une même instance BunkerWeb ne reçoivent jamais un attributDomainpartagé entre tenants. - Configurer l’intégration Redis : pour les environnements distribués, définissez
USE_REDISsur "yes" et configurez votre connexion Redis afin de partager les données de session entre plusieurs nœuds BunkerWeb. - Laisser BunkerWeb gérer le reste : une fois configurée, la gestion des sessions est assurée automatiquement pour votre site.
Paramètres de configuration
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
SESSIONS_SECRET |
random |
global | non | Secret de session : clé cryptographique utilisée pour signer les cookies de session. Elle doit être une chaîne forte, aléatoire et propre à votre site. |
SESSIONS_NAME |
random |
global | non | Nom du cookie : nom du cookie qui stockera l’identifiant de session. |
SESSIONS_DOMAIN |
multisite | non | Domaine du cookie : attribut Domain optionnel appliqué au cookie de session (par exemple example.com). Laissez vide pour conserver un cookie limité à l’hôte. Définissez-le par serveur pour partager l’état de session entre sous-domaines frères d’un même domaine enregistrable. |
|
SESSIONS_IDLING_TIMEOUT |
1800 |
global | non | Délai d’inactivité : durée maximale (en secondes) d’inactivité avant invalidation de la session. |
SESSIONS_ROLLING_TIMEOUT |
3600 |
global | non | Délai glissant : durée maximale (en secondes) avant qu’une session doive être renouvelée. |
SESSIONS_ABSOLUTE_TIMEOUT |
86400 |
global | non | Délai absolu : durée maximale (en secondes) avant qu’une session soit détruite quelle que soit l’activité. |
SESSIONS_CHECK_IP |
yes |
global | non | Vérification IP : lorsqu’il vaut yes, détruit la session si l’adresse IP du client change. |
SESSIONS_CHECK_USER_AGENT |
yes |
global | non | Vérification User-Agent : lorsqu’il vaut yes, détruit la session si le User-Agent du client change. |
!!! warning "Considérations de sécurité"
Le paramètre SESSIONS_SECRET est critique pour la sécurité. En production :
1. Utilisez une valeur forte et aléatoire (au moins 32 caractères)
2. Gardez cette valeur confidentielle
3. Utilisez exactement la même valeur sur toutes les instances BunkerWeb d’un cluster
4. Envisagez des variables d’environnement ou un gestionnaire de secrets pour éviter de stocker cette valeur en clair
!!! tip "Environnements en cluster" Si vous exécutez plusieurs instances BunkerWeb derrière un répartiteur de charge :
1. Définissez `USE_REDIS` sur `yes` et configurez votre connexion Redis
2. Assurez-vous que toutes les instances utilisent exactement le même `SESSIONS_SECRET` et `SESSIONS_NAME`
3. Cela garantit que les utilisateurs conservent leur session quelle que soit l’instance BunkerWeb qui traite leurs requêtes
Exemples de configuration
=== "Configuration de base"
Une configuration simple pour une instance BunkerWeb unique :
```yaml
SESSIONS_SECRET: "your-strong-random-secret-key-here"
SESSIONS_NAME: "myappsession"
SESSIONS_IDLING_TIMEOUT: "1800"
SESSIONS_ROLLING_TIMEOUT: "3600"
SESSIONS_ABSOLUTE_TIMEOUT: "86400"
```
=== "Sécurité renforcée"
Configuration avec des réglages de sécurité renforcés :
```yaml
SESSIONS_SECRET: "your-very-strong-random-secret-key-here"
SESSIONS_NAME: "securesession"
SESSIONS_IDLING_TIMEOUT: "900" # 15 minutes
SESSIONS_ROLLING_TIMEOUT: "1800" # 30 minutes
SESSIONS_ABSOLUTE_TIMEOUT: "43200" # 12 heures
SESSIONS_CHECK_IP: "yes"
SESSIONS_CHECK_USER_AGENT: "yes"
```
=== "Environnement en cluster avec Redis"
Configuration pour plusieurs instances BunkerWeb partageant les données de session :
```yaml
SESSIONS_SECRET: "your-strong-random-secret-key-here"
SESSIONS_NAME: "clustersession"
SESSIONS_IDLING_TIMEOUT: "1800"
SESSIONS_ROLLING_TIMEOUT: "3600"
SESSIONS_ABSOLUTE_TIMEOUT: "86400"
USE_REDIS: "yes"
# Assurez-vous que la connexion Redis est correctement configurée
```
=== "Sessions longue durée"
Configuration pour les applications nécessitant une persistance de session étendue :
```yaml
SESSIONS_SECRET: "your-strong-random-secret-key-here"
SESSIONS_NAME: "persistentsession"
SESSIONS_IDLING_TIMEOUT: "86400" # 1 jour
SESSIONS_ROLLING_TIMEOUT: "172800" # 2 jours
SESSIONS_ABSOLUTE_TIMEOUT: "604800" # 7 jours
```
=== "Sessions inter-sous-domaines (tenant unique)"
Partagez le cookie de session entre tous les sous-domaines de `example.com` afin que l’état antibot/défi ne doive être résolu qu’une seule fois pour tout le site :
```yaml
SERVER_NAME: "app.example.com api.example.com shop.example.com"
SESSIONS_SECRET: "your-strong-random-secret-key-here"
SESSIONS_NAME: "crossdomainsession"
# SESSIONS_DOMAIN est un paramètre multisite : préfixez-le avec le nom du serveur pour qu’il ne s’applique qu’aux hôtes correspondants
app.example.com_SESSIONS_DOMAIN: "example.com"
api.example.com_SESSIONS_DOMAIN: "example.com"
shop.example.com_SESSIONS_DOMAIN: "example.com"
USE_ANTIBOT: "turnstile"
```
=== "Sessions inter-sous-domaines (tenants mixtes)"
Lorsque la même instance BunkerWeb héberge plusieurs domaines enregistrables non liés, limitez `SESSIONS_DOMAIN` aux seuls serveurs qui doivent partager le cookie. Les serveurs non configurés conservent le cookie limité à l’hôte par défaut, de sorte que les tenants restent isolés :
```yaml
SERVER_NAME: "app.example.com api.example.com billing.acme.org www.unrelated.io"
SESSIONS_SECRET: "your-strong-random-secret-key-here"
SESSIONS_NAME: "tenantsession"
# Partagez le cookie uniquement entre les sous-domaines example.com
app.example.com_SESSIONS_DOMAIN: "example.com"
api.example.com_SESSIONS_DOMAIN: "example.com"
# billing.acme.org et www.unrelated.io restent volontairement limités à l’hôte
USE_ANTIBOT: "turnstile"
```
!!! note
`SESSIONS_DOMAIN` doit toujours être un domaine parent du serveur auquel il s’applique. Par exemple, `example.com` est valide à la fois pour `example.com` et pour n’importe quel hôte `*.example.com`, et un point initial (`.example.com`) reste toléré pour compatibilité historique. Le définir sur un domaine enregistrable non lié fera rejeter le cookie par les navigateurs.
SSL
Prise en charge STREAM ✅
Le plugin SSL fournit un chiffrement SSL/TLS robuste pour vos sites protégés par BunkerWeb. Il permet des connexions HTTPS sécurisées en configurant protocoles, suites cryptographiques et paramètres associés.
Comment ça marche :
- Lors d’une connexion HTTPS, BunkerWeb gère la négociation SSL/TLS selon vos réglages.
- Le plugin impose des protocoles modernes et des suites fortes, et désactive les options vulnérables.
- Des paramètres de session optimisés améliorent les performances sans sacrifier la sécurité.
- La présentation des certificats suit les bonnes pratiques pour compatibilité et sécurité.
!!! success "Avantages de sécurité" - Protection des données : chiffre les données en transit et empêche l’écoute ou les attaques de l’homme du milieu. - Authentification : vérifie l’identité de votre serveur auprès des clients. - Intégrité : garantit que les données n’ont pas été altérées pendant la transmission. - Standards modernes : configuration alignée sur les bonnes pratiques et standards de sécurité du secteur.
Comment l’utiliser
- Protocoles : choisissez les versions via
SSL_PROTOCOLS. - Suites : sélectionnez un niveau via
SSL_CIPHERS_LEVELou des suites personnalisées viaSSL_CIPHERS_CUSTOM. - Redirections : configurez la redirection HTTP→HTTPS avec
AUTO_REDIRECT_HTTP_TO_HTTPSet/ouREDIRECT_HTTP_TO_HTTPS.
Paramètres
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
REDIRECT_HTTP_TO_HTTPS |
no |
multisite | non | Rediriger tout HTTP vers HTTPS. |
AUTO_REDIRECT_HTTP_TO_HTTPS |
yes |
multisite | non | Redirection auto si HTTPS détecté. |
SSL_PROTOCOLS |
TLSv1.2 TLSv1.3 |
multisite | non | Protocoles SSL/TLS supportés (séparés par des espaces). |
SSL_CIPHERS_LEVEL |
modern |
multisite | non | Niveau de sécurité des suites (modern, intermediate, old). |
SSL_CIPHERS_CUSTOM |
multisite | non | Suites personnalisées (liste séparée par :) qui remplacent le niveau. |
|
SSL_ECDH_CURVE |
auto |
multisite | non | Courbes ECDH SSL : Liste séparée par : des courbes ECDH (groupes TLS) ou auto pour une sélection intelligente (PQC avec OpenSSL 3.5+). |
SSL_SESSION_CACHE_SIZE |
10m |
multisite | non | Taille du cache de session SSL (ex. 10m, 512k). Définir à off ou none pour désactiver. |
!!! tip "Test SSL Labs" Testez votre configuration via Qualys SSL Labs. Une configuration BunkerWeb bien réglée atteint généralement A+.
!!! warning "Protocoles anciens" SSLv3, TLSv1.0 et TLSv1.1 sont désactivés par défaut (vulnérabilités connues). Activez‑les uniquement si nécessaire pour clients hérités.
Exemples
=== "Sécurité moderne (défaut)"
```yaml
LISTEN_HTTPS: "yes"
SSL_PROTOCOLS: "TLSv1.2 TLSv1.3"
SSL_CIPHERS_LEVEL: "modern"
AUTO_REDIRECT_HTTP_TO_HTTPS: "yes"
REDIRECT_HTTP_TO_HTTPS: "no"
```
=== "Sécurité maximale"
```yaml
LISTEN_HTTPS: "yes"
SSL_PROTOCOLS: "TLSv1.3"
SSL_CIPHERS_LEVEL: "modern"
AUTO_REDIRECT_HTTP_TO_HTTPS: "yes"
REDIRECT_HTTP_TO_HTTPS: "yes"
```
=== "Compatibilité héritée"
```yaml
LISTEN_HTTPS: "yes"
SSL_PROTOCOLS: "TLSv1.2 TLSv1.3"
SSL_CIPHERS_LEVEL: "old"
AUTO_REDIRECT_HTTP_TO_HTTPS: "no"
```
=== "Suites personnalisées"
```yaml
LISTEN_HTTPS: "yes"
SSL_PROTOCOLS: "TLSv1.2 TLSv1.3"
SSL_CIPHERS_CUSTOM: "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
AUTO_REDIRECT_HTTP_TO_HTTPS: "yes"
```
UI
Prise en charge STREAM ❌
Integrate easily the BunkerWeb UI.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_UI |
no |
multisite | non | Use UI |
UI_HOST |
global | non | Address of the web UI used for initial setup |
UI Single Sign-On (PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ❌
Enable SSO authentication for the BunkerWeb web interface by reading headers set by upstream authentication proxies (Authentik, Authelia, Keycloak, Traefik Forward Auth, etc.)
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_UI_SSO |
no |
global | non | Enable or disable UI Single Sign-On authentication for the web interface |
UI_SSO_PROVIDER |
custom |
global | non | Select your SSO provider to auto-configure headers and group parsing. Use 'Custom' for manual header configuration. |
UI_SSO_HEADER_USERNAME |
X-User |
global | non | HTTP header containing the authenticated username |
UI_SSO_HEADER_EMAIL |
X-Email |
global | non | HTTP header containing the user's email address |
UI_SSO_HEADER_GROUPS |
X-Groups |
global | non | HTTP header containing the user's groups (comma or space separated) |
UI_SSO_HEADER_NAME |
X-Name |
global | non | HTTP header containing the user's display name |
UI_SSO_TRUSTED_IPS |
127.0.0.1,::1 |
global | non | Comma-separated list of trusted IP addresses or CIDR ranges that are allowed to send SSO headers |
UI_SSO_AUTO_CREATE_USERS |
yes |
global | non | Automatically create new users when they authenticate via SSO for the first time |
UI_SSO_DEFAULT_ROLE |
reader |
global | non | Default role assigned to new SSO users when no group mapping matches |
UI_SSO_GROUP_ADMIN |
global | non | Group name that grants admin role (highest priority) | |
UI_SSO_GROUP_WRITER |
global | non | Group name that grants writer role | |
UI_SSO_GROUP_READER |
global | non | Group name that grants reader role | |
UI_SSO_FALLBACK_TO_LOGIN |
yes |
global | non | Allow users to fall back to normal login when SSO headers are not present |
UI_SSO_UPDATE_USER_ON_LOGIN |
yes |
global | non | Update user information (email) from SSO headers on each login |
UI_SSO_SYNC_ROLES |
no |
global | non | Synchronize user roles from SSO group mappings on each login when the groups header is present and at least one group mapping is configured |
UI_SSO_SYNC_ROLES_PROTECT_ADMIN |
yes |
global | non | Prevent SSO role sync from downgrading users who currently have the admin role |
UI_SSO_ACCOUNT_LINKING |
username_or_email |
global | non | How to match incoming SSO users to local accounts |
UI_SSO_LOGOUT_REDIRECT_URL |
global | non | URL to redirect users to after logout (e.g., SSO provider logout endpoint) |
User Manager (PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ❌
Add the possibility to manage users on the web interface
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USERS_REQUIRE_2FA |
no |
global | non | Require two-factor authentication for all users |
Whitelist
Prise en charge STREAM ⚠️
Le plugin Whitelist vous permet de définir une liste d'adresses IP de confiance qui contournent les autres filtres de sécurité. Pour bloquer plutôt des clients indésirables, consultez le plugin Blacklist.
Le plugin Whitelist fournit une approche complète pour autoriser explicitement l'accès à votre site web selon différents attributs client. Cette fonctionnalité agit comme un mécanisme de sécurité : les visiteurs correspondant à des critères précis obtiennent un accès immédiat, tandis que tous les autres doivent passer les contrôles de sécurité habituels.
Comment ça marche :
- Vous définissez les critères des visiteurs à placer en "whitelist" (adresses IP, réseaux, rDNS, ASN, User-Agent ou motifs d'URI).
- Lorsqu'un visiteur tente d'accéder à votre site, BunkerWeb vérifie s'il correspond à l'un de ces critères de whitelist.
- Si un visiteur correspond à une règle de whitelist (et ne correspond à aucune règle d'ignore), l'accès à votre site lui est accordé et il contourne tous les autres contrôles de sécurité.
- Si un visiteur ne correspond à aucun critère de whitelist, il passe normalement par tous les contrôles de sécurité habituels.
- Les whitelists peuvent être automatiquement mises à jour depuis des sources externes selon une planification régulière.
Comment l'utiliser
Suivez ces étapes pour configurer et utiliser la fonctionnalité Whitelist :
- Activer la fonctionnalité : La fonctionnalité Whitelist est désactivée par défaut. Mettez le paramètre
USE_WHITELISTàyespour l'activer. - Configurer les règles d'autorisation : Définissez les IP, réseaux, motifs rDNS, ASN, User-Agents ou URI à placer en whitelist.
- Définir les règles d'ignore : Indiquez les exceptions qui doivent contourner les contrôles de whitelist.
- Ajouter des sources externes : Configurez des URL pour télécharger et mettre à jour automatiquement les données de whitelist.
- Surveiller l'accès : Consultez l'interface web pour voir quels visiteurs sont autorisés ou refusés.
!!! info "mode stream" En mode stream, seuls les contrôles IP, rDNS et ASN sont effectués.
Paramètres de configuration
Général
| Paramètre | Défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_WHITELIST |
no |
multisite | non | Activer Whitelist : Mettre à yes pour activer la fonctionnalité whitelist. |
=== "Adresse IP" Ce que cela fait : Place les visiteurs en whitelist selon leur adresse IP ou leur réseau. Ces visiteurs contourneront tous les contrôles de sécurité.
| Paramètre | Défaut | Contexte | Multiple | Description |
| -------------------------- | ------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `WHITELIST_IP` | | multisite | non | **Whitelist IP :** Liste d'adresses IP ou de réseaux (notation CIDR) à autoriser, séparés par des espaces. |
| `WHITELIST_IGNORE_IP` | | multisite | non | **Liste d'ignore IP :** Liste d'adresses IP ou de réseaux qui doivent contourner les contrôles de whitelist IP. |
| `WHITELIST_IP_URLS` | | multisite | non | **URL de whitelist IP :** Liste d'URL contenant des adresses IP ou réseaux à placer en whitelist, séparées par des espaces. |
| `WHITELIST_IGNORE_IP_URLS` | | multisite | non | **URL de liste d'ignore IP :** Liste d'URL contenant des adresses IP ou réseaux à ignorer. |
=== "DNS inverse" Ce que cela fait : Place les visiteurs en whitelist selon leur nom de domaine inversé. C'est utile pour autoriser l'accès à des visiteurs de certaines organisations ou de certains réseaux via leur domaine.
| Paramètre | Défaut | Contexte | Multiple | Description |
| ---------------------------- | ------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `WHITELIST_RDNS` | | multisite | non | **Whitelist rDNS :** Liste de suffixes DNS inversés à autoriser, séparés par des espaces. |
| `WHITELIST_RDNS_GLOBAL` | `yes` | multisite | non | **rDNS global seulement :** Effectue les contrôles de whitelist rDNS uniquement sur les adresses IP globales lorsque défini à `yes`. |
| `WHITELIST_IGNORE_RDNS` | | multisite | non | **Liste d'ignore rDNS :** Liste de suffixes DNS inversés qui doivent contourner les contrôles de whitelist rDNS. |
| `WHITELIST_RDNS_URLS` | | multisite | non | **URL de whitelist rDNS :** Liste d'URL contenant des suffixes DNS inversés à placer en whitelist, séparées par des espaces. |
| `WHITELIST_IGNORE_RDNS_URLS` | | multisite | non | **URL de liste d'ignore rDNS :** Liste d'URL contenant des suffixes DNS inversés à ignorer. |
=== "ASN" Ce que cela fait : Place les visiteurs de fournisseurs réseau précis en whitelist à l'aide des numéros de système autonome. Les ASN identifient le fournisseur ou l'organisation auquel appartient une IP.
| Paramètre | Défaut | Contexte | Multiple | Description |
| --------------------------- | ------ | --------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `WHITELIST_ASN` | | multisite | non | **Whitelist ASN :** Liste de numéros de système autonome à autoriser, séparés par des espaces. |
| `WHITELIST_IGNORE_ASN` | | multisite | non | **Liste d'ignore ASN :** Liste d'ASN qui doivent contourner les contrôles de whitelist ASN. |
| `WHITELIST_ASN_URLS` | | multisite | non | **URL de whitelist ASN :** Liste d'URL contenant des ASN à placer en whitelist, séparées par des espaces. |
| `WHITELIST_IGNORE_ASN_URLS` | | multisite | non | **URL de liste d'ignore ASN :** Liste d'URL contenant des ASN à ignorer. |
=== "User Agent" Ce que cela fait : Place les visiteurs en whitelist selon le navigateur ou l'outil qu'ils déclarent utiliser. C'est efficace pour autoriser l'accès à des outils ou services connus précis.
| Paramètre | Défaut | Contexte | Multiple | Description |
| ---------------------------------- | ------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `WHITELIST_USER_AGENT` | | multisite | non | **Whitelist User-Agent :** Liste de motifs User-Agent (regex PCRE) à autoriser, séparés par des espaces. |
| `WHITELIST_IGNORE_USER_AGENT` | | multisite | non | **Liste d'ignore User-Agent :** Liste de motifs User-Agent qui doivent contourner les contrôles de whitelist User-Agent. |
| `WHITELIST_USER_AGENT_URLS` | | multisite | non | **URL de whitelist User-Agent :** Liste d'URL contenant des motifs User-Agent à placer en whitelist. |
| `WHITELIST_IGNORE_USER_AGENT_URLS` | | multisite | non | **URL de liste d'ignore User-Agent :** Liste d'URL contenant des motifs User-Agent à ignorer. |
=== "URI" Ce que cela fait : Place en whitelist les requêtes vers des URL précises de votre site. C'est utile pour autoriser l'accès à certains endpoints indépendamment des autres facteurs.
| Paramètre | Défaut | Contexte | Multiple | Description |
| --------------------------- | ------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `WHITELIST_URI` | | multisite | non | **Whitelist URI :** Liste de motifs d'URI (regex PCRE) à autoriser, séparés par des espaces. |
| `WHITELIST_IGNORE_URI` | | multisite | non | **Liste d'ignore URI :** Liste de motifs d'URI qui doivent contourner les contrôles de whitelist URI. |
| `WHITELIST_URI_URLS` | | multisite | non | **URL de whitelist URI :** Liste d'URL contenant des motifs d'URI à placer en whitelist, séparées par des espaces. |
| `WHITELIST_IGNORE_URI_URLS` | | multisite | non | **URL de liste d'ignore URI :** Liste d'URL contenant des motifs d'URI à ignorer. |
!!! info "Prise en charge du format d'URL"
Tous les paramètres *_URLS prennent en charge les URL HTTP/HTTPS ainsi que les chemins de fichiers locaux avec le préfixe file:///. L'authentification basique est prise en charge avec le format http://user:pass@url.
!!! tip "Mises à jour régulières" Les whitelists provenant d'URL sont automatiquement téléchargées et mises à jour toutes les heures afin que votre protection reste à jour avec les dernières sources de confiance.
!!! warning "Contournement de sécurité" Les visiteurs en whitelist contourneront complètement tous les autres contrôles de sécurité de BunkerWeb, y compris les règles WAF, la limitation de débit, la détection des mauvais bots et tout autre mécanisme de sécurité. Utilisez la whitelist uniquement pour des sources de confiance dont vous êtes absolument certain.
Exemples de configuration
=== "Accès d'organisation de base"
Configuration simple qui place en whitelist les IP des bureaux de l'entreprise :
```yaml
USE_WHITELIST: "yes"
WHITELIST_IP: "192.168.1.0/24 10.0.0.0/8 203.0.113.42"
```
=== "Configuration avancée"
Configuration plus complète avec plusieurs critères de whitelist :
```yaml
USE_WHITELIST: "yes"
# Ressources de l'entreprise et des partenaires de confiance
WHITELIST_IP: "192.168.1.0/24 203.0.113.0/24"
WHITELIST_RDNS: ".company.com .partner-company.org"
WHITELIST_ASN: "12345 67890" # ASN de l'entreprise et du partenaire
WHITELIST_USER_AGENT: "(?:\b)CompanyBot(?:\b) (?:\b)PartnerCrawler(?:\b)"
# Sources externes de confiance
WHITELIST_IP_URLS: "https://example.com/trusted-networks.txt"
WHITELIST_USER_AGENT_URLS: "https://example.com/trusted-crawlers.txt"
```
=== "Utilisation de fichiers locaux"
Configuration utilisant des fichiers locaux pour les whitelists :
```yaml
USE_WHITELIST: "yes"
WHITELIST_IP_URLS: "file:///path/to/ip-whitelist.txt"
WHITELIST_RDNS_URLS: "file:///path/to/rdns-whitelist.txt"
WHITELIST_ASN_URLS: "file:///path/to/asn-whitelist.txt"
WHITELIST_USER_AGENT_URLS: "file:///path/to/user-agent-whitelist.txt"
WHITELIST_URI_URLS: "file:///path/to/uri-whitelist.txt"
```
=== "Motif d'accès API"
Configuration centrée sur l'autorisation d'accès à certains endpoints d'API uniquement :
```yaml
USE_WHITELIST: "yes"
WHITELIST_URI: "^/api/v1/public/ ^/api/v1/status"
WHITELIST_IP: "192.168.1.0/24" # Réseau interne pour tous les endpoints
```
=== "Robots d'exploration connus"
Configuration qui place en whitelist les robots d'exploration courants des moteurs de recherche et réseaux sociaux :
```yaml
USE_WHITELIST: "yes"
# Vérification par DNS inverse pour plus de sécurité
WHITELIST_RDNS: ".googlebot.com .search.msn.com .crawl.yahoo.net .yandex.com .baidu.com .facebook.com"
WHITELIST_RDNS_GLOBAL: "yes" # Vérifier uniquement les IP globales
```
Cette configuration permet aux robots d'exploration légitimes d'indexer votre site sans être soumis à la limitation de débit ou à d'autres mesures de sécurité susceptibles de les bloquer. Les contrôles rDNS aident à vérifier que les robots proviennent bien des entreprises qu'ils déclarent.
Travailler avec des fichiers de listes locaux
Les paramètres *_URLS fournis par les plugins Whitelist, Greylist et Blacklist utilisent le même téléchargeur. Lorsque vous référencez une URL file:/// :
- Le chemin est résolu dans le conteneur du scheduler (dans un déploiement Docker il s'agit généralement de
bunkerweb-scheduler). Montez-y vos fichiers et vérifiez que l'utilisateur scheduler possède un accès en lecture. - Chaque fichier est un texte encodé en UTF-8 avec une entrée par ligne. Les lignes vides sont ignorées et les commentaires doivent commencer par
#ou;. Les commentaires//ne sont pas pris en charge. - Valeur attendue selon le type de liste :
- Listes IP acceptent des adresses IPv4/IPv6 ou des réseaux CIDR (par exemple
192.0.2.10ou2001:db8::/48). - Listes rDNS attendent un suffixe sans espaces (par exemple
.search.msn.com). Les valeurs sont automatiquement converties en minuscules. - Listes ASN peuvent contenir uniquement le numéro (
32934) ou le numéro préfixé parAS(AS15169). - Listes User-Agent sont traitées comme des motifs PCRE et la ligne complète est conservée (espaces compris). Placez vos commentaires sur une ligne séparée pour éviter qu'ils ne soient interprétés comme motif.
- Listes URI doivent commencer par
/et peuvent utiliser des jetons PCRE tels que^ou$.
- Listes IP acceptent des adresses IPv4/IPv6 ou des réseaux CIDR (par exemple
Exemples de fichiers conformes :
# /etc/bunkerweb/lists/ip-whitelist.txt
192.0.2.10
198.51.100.0/24
# /etc/bunkerweb/lists/ua-whitelist.txt
(?:^|\s)FriendlyScanner(?:\s|$)
TrustedMonitor/\d+\.\d+
Wildcard (PRO)
Pour un guide plus détaillé, consultez la documentation des utilisations avancées.
Prise en charge STREAM ❌
Adds wildcard server_name support (*.domain) for services.
| Paramètre | Valeur par défaut | Contexte | Multiple | Description |
|---|---|---|---|---|
USE_WILDCARD |
no |
multisite | non | Enable wildcard server_name for this service (adds *.domain for the first domain in SERVER_NAME). |