bunkerweb

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 :

1. Au démarrage de BunkerWeb, le plugin General charge et applique vos paramètres de configuration principaux.
2. Les modes de sécurité sont définis globalement ou par site, déterminant le niveau de protection appliqué.
3. Les paramètres par défaut du serveur établissent des valeurs de repli pour toute configuration multisite non spécifiée.
4. Les paramètres de journalisation contrôlent les informations enregistrées et leur format.
5. Ces paramètres constituent la base sur laquelle s’appuient tous les autres plugins et fonctionnalités de BunkerWeb.

Mode multisite {#multisite-mode}

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=captcha active le CAPTCHA pour www.example.com.
• myapp.example.com_USE_GZIP=yes active la compression GZIP pour myapp.example.com.

Cette approche garantit que les paramètres sont appliqués au bon site dans un environnement multisite.

Paramètres multiples {#multiple-settings}

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=/subdir et REVERSE_PROXY_HOST_1=http://myhost1 définissent le premier reverse proxy.
• REVERSE_PROXY_URL_2=/anotherdir et REVERSE_PROXY_HOST_2=http://myhost2 dé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 {#plugin-order}

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é {#security-modes}

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) :