Aller au contenu

API

Aperçu

L'API de BunkerWeb est le plan de contrôle utilisé pour gérer les instances BunkerWeb de manière programmatique : lister et gérer les instances, les recharger/arrêter, gérer les bannissements, les plugins, les tâches, les configurations, et plus encore. Elle expose une application FastAPI documentée avec une authentification forte, une gestion des autorisations et une limitation de débit.

Ouvrez la documentation interactive sur /docs (ou <root_path>/docs si vous avez défini API_ROOT_PATH). Le schéma OpenAPI est disponible sur /openapi.json.

Sécurité

L'API est un plan de contrôle privilégié. Ne l'exposez pas sur l'Internet public sans protections supplémentaires.

Au minimum, restreignez les adresses IP sources (API_WHITELIST_IPS), activez l'authentification (API_TOKEN ou des utilisateurs API + Biscuit), et envisagez de la placer derrière BunkerWeb avec une URL difficile à deviner et des contrôles d'accès supplémentaires.

Prérequis

Le service API nécessite un accès à la base de données de BunkerWeb (DATABASE_URI). Il est généralement déployé aux côtés du Planificateur (Scheduler) et, optionnellement, de l'Interface Web (Web UI). La configuration recommandée est d'exécuter BunkerWeb en tant que reverse proxy en amont et d'isoler l'API sur un réseau interne.

Consultez l'assistant et les conseils d'architecture dans le guide de démarrage rapide.

Points clés

  • Gestion des instances : diffuse les actions opĂ©rationnelles aux instances dĂ©couvertes.
  • Authentification forte : Basic pour les administrateurs, jeton Bearer pour un accès admin complet, ou jeton Biscuit pour des permissions granulaires.
  • Liste blanche d'IP et limitation de dĂ©bit flexible par route.
  • Signaux standards de santĂ©/disponibilitĂ© (health/readiness) et vĂ©rifications de sĂ©curitĂ© au dĂ©marrage.

Modèles de configuration Docker Compose

Exposer l'API en reverse proxy sous /api avec BunkerWeb.

x-bw-env: &bw-env
  # Liste blanche commune pour le plan de contrĂ´le des instances (BunkerWeb/Scheduler)
  API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24"

services:
  bunkerweb:
    image: bunkerity/bunkerweb:testing
    ports:
      - "80:8080/tcp"
      - "443:8443/tcp"
      - "443:8443/udp"  # QUIC
    environment:
      <<: *bw-env
    restart: unless-stopped
    networks:
      - bw-universe
      - bw-services

  bw-scheduler:
    image: bunkerity/bunkerweb-scheduler:testing
    environment:
      <<: *bw-env
      BUNKERWEB_INSTANCES: "bunkerweb"  # Doit correspondre au nom de service de l'instance
      SERVER_NAME: "www.example.com"
      MULTISITE: "yes"
      DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db"
      DISABLE_DEFAULT_SERVER: "yes"
      # Reverse proxy pour l'API sur /api
      www.example.com_USE_REVERSE_PROXY: "yes"
      www.example.com_REVERSE_PROXY_URL: "/api"
      www.example.com_REVERSE_PROXY_HOST: "http://bw-api:8888"
    volumes:
      - bw-storage:/data
    restart: unless-stopped
    networks:
      - bw-universe
      - bw-db

  bw-api:
    image: bunkerity/bunkerweb-api:testing
    environment:
      DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db"  # Utilisez un mot de passe robuste
      API_WHITELIST_IPS: "127.0.0.0/8 10.20.30.0/24"                      # Liste blanche de l'API
      API_TOKEN: "secret"                                                 # Jeton optionnel pour accès admin complet
      API_ROOT_PATH: "/api"                                               # Doit correspondre au chemin du reverse proxy
    restart: unless-stopped
    networks:
      - bw-universe
      - bw-db

  bw-db:
    image: mariadb:11
    # Évite les problèmes avec les requêtes volumineuses
    command: --max-allowed-packet=67108864
    environment:
      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
      MYSQL_DATABASE: "db"
      MYSQL_USER: "bunkerweb"
      MYSQL_PASSWORD: "changeme"  # Utilisez un mot de passe robuste
    volumes:
      - bw-data:/var/lib/mysql
    restart: unless-stopped
    networks:
      - bw-db

volumes:
  bw-data:
  bw-storage:

networks:
  bw-universe:
    name: bw-universe
    ipam:
      driver: default
      config:
        - subnet: 10.20.30.0/24
  bw-services:
    name: bw-services
  bw-db:
    name: bw-db

Identique à ci-dessus, mais en utilisant le service Autoconf pour découvrir et configurer automatiquement les services. L'API est exposée sous /api grâce aux labels sur le conteneur de l'API.

x-api-env: &api-env
  AUTOCONF_MODE: "yes"
  DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db"  # Utilisez un mot de passe robuste

services:
  bunkerweb:
    image: bunkerity/bunkerweb:testing
    ports:
      - "80:8080/tcp"
      - "443:8443/tcp"
      - "443:8443/udp"  # QUIC
    environment:
      AUTOCONF_MODE: "yes"
      API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24"
    restart: unless-stopped
    networks:
      - bw-universe
      - bw-services

  bw-scheduler:
    image: bunkerity/bunkerweb-scheduler:testing
    environment:
      <<: *api-env
      BUNKERWEB_INSTANCES: ""    # DĂ©couvert par Autoconf
      SERVER_NAME: ""            # Rempli via les labels
      MULTISITE: "yes"           # Obligatoire avec Autoconf
      API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24"
    volumes:
      - bw-storage:/data
    restart: unless-stopped
    networks:
      - bw-universe
      - bw-db

  bw-autoconf:
    image: bunkerity/bunkerweb-autoconf:testing
    depends_on:
      - bunkerweb
      - bw-docker
    environment:
      <<: *api-env
      DOCKER_HOST: "tcp://bw-docker:2375"
    restart: unless-stopped
    networks:
      - bw-universe
      - bw-docker
      - bw-db

  bw-api:
    image: bunkerity/bunkerweb-api:testing
    environment:
      <<: *api-env
      API_WHITELIST_IPS: "127.0.0.0/8 10.20.30.0/24"
      API_TOKEN: "secret"
      API_ROOT_PATH: "/api"
    labels:
      - "bunkerweb.SERVER_NAME=www.example.com"
      - "bunkerweb.USE_REVERSE_PROXY=yes"
      - "bunkerweb.REVERSE_PROXY_URL=/api"
      - "bunkerweb.REVERSE_PROXY_HOST=http://bw-api:8888"
    restart: unless-stopped
    networks:
      - bw-universe
      - bw-db

  bw-db:
    image: mariadb:11
    command: --max-allowed-packet=67108864
    environment:
      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
      MYSQL_DATABASE: "db"
      MYSQL_USER: "bunkerweb"
      MYSQL_PASSWORD: "changeme"
    volumes:
      - bw-data:/var/lib/mysql
    restart: unless-stopped
    networks:
      - bw-db

  bw-docker:
    image: tecnativa/docker-socket-proxy:nightly
    environment:
      CONTAINERS: "1"
      LOG_LEVEL: "warning"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped
    networks:
      - bw-docker

volumes:
  bw-data:
  bw-storage:

networks:
  bw-universe:
    name: bw-universe
    ipam:
      driver: default
      config:
        - subnet: 10.20.30.0/24
  bw-services:
    name: bw-services
  bw-db:
    name: bw-db
  bw-docker:
    name: bw-docker

Chemin du reverse proxy

Gardez le chemin de l'API difficile Ă  deviner et combinez-le avec la liste blanche et l'authentification de l'API.

Si vous exposez déjà une autre application sur le même nom de serveur avec un modèle (par ex. USE_TEMPLATE), préférez un nom d'hôte distinct pour l'API afin d'éviter les conflits.

All-In-One

Si vous utilisez l'image All-In-One, l'API peut être activée en définissant SERVICE_API=yes:

docker run -d \
  --name bunkerweb-aio \
  -e SERVICE_API=yes \
  -e API_WHITELIST_IPS="127.0.0.0/8" \
  -p 80:8080/tcp -p 443:8443/tcp -p 443:8443/udp \
  bunkerity/bunkerweb-all-in-one:testing

Authentification

Méthodes supportées pour authentifier les requêtes :

  • Basic admin : Lorsque les identifiants appartiennent Ă  un utilisateur admin de l'API, les points d'accès protĂ©gĂ©s acceptent Authorization: Basic <base64(username:password)>.
  • Bearer admin (jeton global) : Si API_TOKEN est configurĂ©, Authorization: Bearer <API_TOKEN> accorde un accès complet.
  • Jeton Biscuit (recommandĂ©) : Obtenez un jeton depuis POST /auth en utilisant des identifiants Basic ou un corps de requĂŞte JSON/formulaire contenant username et password. Utilisez le jeton retournĂ© comme Authorization: Bearer <token> pour les appels suivants.

Exemple : obtenir un jeton Biscuit, lister les instances, puis les recharger toutes.

# 1) Obtenir un jeton Biscuit avec des identifiants admin
TOKEN=$(curl -s -X POST -u admin:changeme http://api.example.com/auth | jq -r .token)

# 2) Lister les instances
curl -H "Authorization: Bearer $TOKEN" http://api.example.com/instances

# 3) Recharger la configuration sur toutes les instances (sans test)
curl -X POST -H "Authorization: Bearer $TOKEN" \
     "http://api.example.com/instances/reload?test=no"

Jetons Biscuit : fonctionnement et vérifications

Les jetons intègrent des "faits" (facts) comme user(<username>), client_ip(<ip>), domain(<host>), et un rôle général role("api_user", ["read", "write"]) dérivé des permissions de la base de données. Les administrateurs incluent admin(true) tandis que les non-administrateurs ont des faits granulaires comme api_perm(<resource_type>, <resource_id|*>, <permission>).

L'autorisation fait correspondre la route/méthode aux permissions requises ; admin(true) est toujours accepté. En l'absence de faits granulaires, le système se base sur le rôle général : GET/HEAD/OPTIONS nécessitent read ; les verbes d'écriture nécessitent write.

Les clés sont stockées dans /var/lib/bunkerweb/.api_biscuit_private_key et /var/lib/bunkerweb/.api_biscuit_public_key. Vous pouvez aussi fournir BISCUIT_PUBLIC_KEY/BISCUIT_PRIVATE_KEY via des variables d'environnement ; si ni les fichiers ni les variables ne sont définis, l'API génère et sauvegarde une paire de clés au démarrage.

Permissions (ACL)

Cette API supporte deux niveaux d'autorisation :

  • RĂ´le gĂ©nĂ©ral : Les jetons contiennent role("api_user", ["read"[, "write"]]) pour les points d'accès sans correspondance granulaire. read correspond Ă  GET/HEAD/OPTIONS ; write correspond Ă  POST/PUT/PATCH/DELETE.
  • ACL granulaire : Les jetons intègrent api_perm(<resource_type>, <resource_id|*>, <permission>) et les routes dĂ©clarent ce qu'elles exigent. admin(true) contourne toutes les vĂ©rifications.

Types de ressources supportés : instances, global_config, services, configs, plugins, cache, bans, jobs.

Noms des permissions par type de ressource :

  • instances: instances_read, instances_update, instances_delete, instances_create, instances_execute
  • global_config: global_config_read, global_config_update
  • services: service_read, service_create, service_update, service_delete, service_convert, service_export
  • configs: configs_read, config_read, config_create, config_update, config_delete
  • plugins: plugin_read, plugin_create, plugin_delete
  • cache: cache_read, cache_delete
  • bans: ban_read, ban_update, ban_delete, ban_created
  • jobs: job_read, job_run

ID de ressource : Pour les vérifications granulaires, le deuxième segment de l'URL est traité comme resource_id lorsque c'est pertinent. Exemples : /services/{service} -> {service} ; /configs/{service}/... -> {service}. Utilisez "*" (ou omettez) pour accorder la permission globalement pour un type de ressource.

Configuration des utilisateurs et des ACL :

  • Utilisateur admin : DĂ©finissez API_USERNAME et API_PASSWORD pour crĂ©er le premier administrateur au dĂ©marrage. Pour renouveler les identifiants plus tard, dĂ©finissez OVERRIDE_API_CREDS=yes (ou assurez-vous que l'admin a Ă©tĂ© crĂ©Ă© avec la mĂ©thode manual). Il n'y a qu'un seul admin ; les tentatives supplĂ©mentaires de crĂ©ation basculent vers la crĂ©ation d'un utilisateur non-admin.
  • Utilisateurs non-admin et permissions : Fournissez API_ACL_BOOTSTRAP_FILE pointant vers un fichier JSON, ou montez-le sur /var/lib/bunkerweb/api_acl_bootstrap.json. L'API le lit au dĂ©marrage pour crĂ©er/mettre Ă  jour les utilisateurs et les permissions.
  • Fichier cache ACL : Un rĂ©sumĂ© en lecture seule est Ă©crit dans /var/lib/bunkerweb/api_acl.json au dĂ©marrage pour introspection ; l'autorisation Ă©value les permissions stockĂ©es en base de donnĂ©es et intĂ©grĂ©es dans le jeton Biscuit.

Exemples de JSON de bootstrap (les deux formats sont supportés) :

{
  "users": {
    "ci": {
      "admin": false,
      "password": "M0tDeP@sseF0rt!",
      "permissions": {
        "services": {
          "*": { "service_read": true },
          "app-frontend": { "service_update": true, "service_delete": false }
        },
        "configs": {
          "app-frontend": { "config_read": true, "config_update": true }
        }
      }
    },
    "ops": {
      "admin": false,
      "password_hash": "$2b$13$...hash-bcrypt...",
      "permissions": {
        "instances": { "*": { "instances_execute": true } },
        "jobs": { "*": { "job_run": true } }
      }
    }
  }
}

Ou en format liste :

{
  "users": [
    {
      "username": "ci",
      "password": "M0tDeP@sseF0rt!",
      "permissions": [
        { "resource_type": "services", "resource_id": "*", "permission": "service_read" },
        { "resource_type": "services", "resource_id": "app-frontend", "permission": "service_update" }
      ]
    }
  ]
}

Notes : - Les mots de passe peuvent être en clair (password) ou bcrypt (password_hash / password_bcrypt). Les mots de passe en clair trop faibles sont rejetés en dehors des builds de débogage ; si manquant, un mot de passe aléatoire est généré et un avertissement est journalisé. - resource_id: "*" (ou null/vide) accorde la permission globalement pour ce type de ressource. - Les mots de passe des utilisateurs existants peuvent être mis à jour et des permissions supplémentaires peuvent être appliquées via le bootstrap.

Référence des fonctionnalités

L'API est organisée par routeurs thématiques. Utilisez les sections ci-dessous comme un aperçu des capacités ; le schéma interactif sur /docs documente en détail les modèles de requête/réponse.

CĹ“ur et authentification

  • GET /ping, GET /health : sondes de vivacitĂ© lĂ©gères pour le service API lui-mĂŞme.
  • POST /auth : Ă©changez des identifiants Basic (ou le jeton admin global) contre un jeton Biscuit. Accepte JSON, formulaire, ou les en-tĂŞtes Authorization. Les admins peuvent aussi continuer Ă  utiliser l'authentification HTTP Basic sur les routes protĂ©gĂ©es.

Plan de contrĂ´le des instances

  • GET /instances : liste les instances enregistrĂ©es, avec horodatages, mĂ©thode d'enregistrement et mĂ©tadonnĂ©es.
  • POST /instances : enregistre une nouvelle instance gĂ©rĂ©e par l'API (nom d'hĂ´te, port optionnel, nom de serveur, nom descriptif, mĂ©thode).
  • GET /instances/{hostname}, PATCH /instances/{hostname}, DELETE /instances/{hostname} : inspecte, met Ă  jour les champs modifiables, ou supprime les instances gĂ©rĂ©es par l'API.
  • DELETE /instances : suppression en masse ; ignore les instances non gĂ©rĂ©es par l'API et les signale dans skipped.
  • GET /instances/ping et GET /instances/{hostname}/ping : vĂ©rifications de santĂ© sur toutes les instances ou une seule.
  • POST /instances/reload?test=yes|no, POST /instances/{hostname}/reload : dĂ©clenche le rechargement de la configuration (le mode test effectue une validation Ă  blanc).
  • POST /instances/stop, POST /instances/{hostname}/stop : relaie les commandes d'arrĂŞt aux instances.

Configuration globale

  • GET /global_config : rĂ©cupère les paramètres non-dĂ©faut (utilisez full=true pour la configuration complète, methods=true pour inclure la provenance).
  • PATCH /global_config : crĂ©e ou met Ă  jour les paramètres globaux gĂ©rĂ©s par l'API (method="api") ; les erreurs de validation signalent les clĂ©s inconnues ou en lecture seule.

Cycle de vie des services

  • GET /services : Ă©numère les services avec leurs mĂ©tadonnĂ©es, y compris le statut de brouillon et les horodatages.
  • GET /services/{service} : rĂ©cupère les surcharges non-dĂ©faut (full=false) ou la configuration complète (full=true) pour un service.
  • POST /services : crĂ©e des services, optionnellement en tant que brouillon, et initialise des variables prĂ©fixĂ©es ({service}_{KEY}). Met Ă  jour la liste SERVER_NAME de manière atomique.
  • PATCH /services/{service} : renomme les services, bascule le statut brouillon/en ligne, et met Ă  jour les variables prĂ©fixĂ©es. Ignore les modifications directes de SERVER_NAME dans variables par sĂ©curitĂ©.
  • DELETE /services/{service} : supprime un service et ses clĂ©s de configuration dĂ©rivĂ©es.
  • POST /services/{service}/convert?convert_to=online|draft : bascule rapidement entre les Ă©tats brouillon/en ligne sans modifier d'autres variables.

Extraits de configuration personnalisés

  • GET /configs : liste les fragments de configuration personnalisĂ©s (hooks HTTP/server/stream/ModSecurity/CRS) pour un service (service=global par dĂ©faut). with_data=true intègre le contenu UTF-8 s'il est affichable.
  • POST /configs et POST /configs/upload : crĂ©e de nouveaux extraits depuis des donnĂ©es JSON ou des fichiers tĂ©lĂ©versĂ©s. Types acceptĂ©s : http, server_http, default_server_http, modsec, modsec_crs, stream, server_stream, et les hooks de plugins CRS. Les noms doivent correspondre Ă  ^[\w_-]{1,64}$.
  • GET /configs/{service}/{type}/{name} : rĂ©cupère un extrait avec son contenu optionnel (with_data=true).
  • PATCH /configs/{service}/{type}/{name} et PATCH .../upload : met Ă  jour ou dĂ©place les extraits gĂ©rĂ©s par l'API ; les entrĂ©es gĂ©rĂ©es par modèle ou fichier restent en lecture seule.
  • DELETE /configs et DELETE /configs/{service}/{type}/{name} : supprime les extraits gĂ©rĂ©s par l'API tout en prĂ©servant ceux gĂ©rĂ©s par modèle, retournant une liste skipped pour les entrĂ©es ignorĂ©es.

Orchestration des bannissements

  • GET /bans : agrège les bannissements actifs signalĂ©s par toutes les instances.
  • POST /bans ou POST /bans/ban : applique un ou plusieurs bannissements. Les donnĂ©es peuvent ĂŞtre des objets JSON, des tableaux, ou du JSON sous forme de chaĂ®ne. service est optionnel ; si omis, le bannissement est global.
  • POST /bans/unban ou DELETE /bans : supprime des bannissements globalement ou par service en utilisant les mĂŞmes formats de donnĂ©es flexibles.

Gestion des plugins

  • GET /plugins?type=all|external|ui|pro : liste les plugins avec leurs mĂ©tadonnĂ©es ; with_data=true inclut les octets du paquet si disponibles.
  • POST /plugins/upload : installe des plugins UI depuis des archives .zip, .tar.gz, ou .tar.xz. Les archives peuvent contenir plusieurs plugins si chacun a un plugin.json.
  • DELETE /plugins/{id} : supprime un plugin UI par son ID (^[\w.-]{4,64}$).

Cache et exécution des tâches

  • GET /cache : liste les artefacts en cache produits par les tâches du planificateur, filtrĂ©s par service, ID de plugin, ou nom de tâche. with_data=true inclut le contenu des fichiers s'il est affichable.
  • GET /cache/{service}/{plugin}/{job}/{file} : rĂ©cupère un fichier de cache spĂ©cifique (download=true le tĂ©lĂ©charge en pièce jointe).
  • DELETE /cache ou DELETE /cache/{service}/{plugin}/{job}/{file} : supprime des fichiers de cache et notifie le planificateur des plugins affectĂ©s.
  • GET /jobs : inspecte les tâches connues, les mĂ©tadonnĂ©es de leur planification, et les rĂ©sumĂ©s du cache.
  • POST /jobs/run : demande l'exĂ©cution d'une tâche en marquant le ou les plugins associĂ©s comme modifiĂ©s.

Notes opérationnelles

  • Les points d'accès en Ă©criture persistent dans la base de donnĂ©es partagĂ©e ; les instances rĂ©cupèrent les changements via la synchronisation du planificateur ou après un /instances/reload.
  • Les erreurs sont normalisĂ©es en { "status": "error", "message": "..." } avec des codes de statut HTTP appropriĂ©s (422 validation, 404 non trouvĂ©, 403 ACL, 5xx erreurs en amont).

Limitation de débit

La limitation de débit par client est gérée par SlowAPI. Activez/désactivez et configurez les limites via des variables d'environnement ou /etc/bunkerweb/api.yml.

  • API_RATE_LIMIT_ENABLED (dĂ©faut : yes)
  • Limite par dĂ©faut : API_RATE_LIMIT_TIMES par API_RATE_LIMIT_SECONDS (ex. 100 par 60)
  • API_RATE_LIMIT_RULES : JSON/CSV en ligne, ou un chemin vers un fichier YAML/JSON avec des règles par route
  • Stockage : en mĂ©moire ou Redis/Valkey lorsque USE_REDIS=yes et les variables REDIS_* sont fournies (Sentinel supportĂ©)
  • En-tĂŞtes : API_RATE_LIMIT_HEADERS_ENABLED (dĂ©faut : yes)

Exemple de YAML (monté dans /etc/bunkerweb/api.yml) :

API_RATE_LIMIT_ENABLED: yes
API_RATE_LIMIT_DEFAULTS: ["200/minute"]
API_RATE_LIMIT_RULES:
  - path: "/auth"
    methods: "POST"
    times: 10
    seconds: 60
  - path: "/instances*"
    methods: "GET|POST"
    times: 100
    seconds: 60

Configuration

Vous pouvez configurer l'API via des variables d'environnement, des secrets Docker, et les fichiers optionnels /etc/bunkerweb/api.yml ou /etc/bunkerweb/api.env. Paramètres clés :

  • Docs & schĂ©ma : API_DOCS_URL, API_REDOC_URL, API_OPENAPI_URL, API_ROOT_PATH.
  • Authentification de base : API_TOKEN (jeton Bearer admin), API_USERNAME/API_PASSWORD (crĂ©er/mettre Ă  jour l'admin), OVERRIDE_API_CREDS.
  • ACL et utilisateurs : API_ACL_BOOTSTRAP_FILE (chemin JSON).
  • Politique Biscuit : API_BISCUIT_TTL_SECONDS (0/dĂ©sactivĂ© dĂ©sactive la durĂ©e de vie), CHECK_PRIVATE_IP (lie le jeton Ă  l'IP du client sauf si privĂ©e).
  • Liste blanche IP : API_WHITELIST_ENABLED, API_WHITELIST_IPS.
  • Limitation de dĂ©bit (cĹ“ur) : API_RATE_LIMIT_ENABLED, API_RATE_LIMIT_TIMES, API_RATE_LIMIT_SECONDS, API_RATE_LIMIT_HEADERS_ENABLED.
  • Limitation de dĂ©bit (avancĂ©) : API_RATE_LIMIT_AUTH_TIMES, API_RATE_LIMIT_AUTH_SECONDS, API_RATE_LIMIT_RULES, API_RATE_LIMIT_DEFAULTS, API_RATE_LIMIT_APPLICATION_LIMITS, API_RATE_LIMIT_STRATEGY, API_RATE_LIMIT_KEY, API_RATE_LIMIT_EXEMPT_IPS, API_RATE_LIMIT_STORAGE_OPTIONS.
  • Stockage de la limitation de dĂ©bit : en mĂ©moire ou Redis/Valkey lorsque USE_REDIS=yes et les paramètres Redis comme REDIS_HOST, REDIS_PORT, etc., sont dĂ©finis. Voir la table des paramètres Redis dans docs/features.md.
  • RĂ©seau/TLS : API_LISTEN_ADDR, API_LISTEN_PORT, API_FORWARDED_ALLOW_IPS, API_SSL_ENABLED, API_SSL_CERTFILE, API_SSL_KEYFILE, API_SSL_CA_CERTS.

Comment la configuration est chargée

Priorité du plus élevé au plus bas :

  1. Variables d'environnement (ex. environment: du conteneur ou variables shell exportées)
  2. Fichiers secrets sous /run/secrets (secrets Docker/K8s ; les noms de fichiers correspondent aux noms de variables)
  3. Fichier YAML Ă  l'adresse /etc/bunkerweb/api.yml
  4. Fichier d'environnement à l'adresse /etc/bunkerweb/api.env (lignes clé=valeur)
  5. Valeurs par défaut intégrées

Notes : - Le YAML supporte l'inclusion de fichiers secrets avec <file:chemin/relatif>; le chemin est résolu par rapport à /run/secrets. - Mettez les URL de la documentation à off/disabled/none pour désactiver les points d'accès (ex. API_DOCS_URL=off). - Si API_SSL_ENABLED=yes, vous devez aussi définir API_SSL_CERTFILE et API_SSL_KEYFILE. - Si Redis est activé (USE_REDIS=yes), fournissez les détails de connexion ; voir la section Redis dans docs/features.md.

Authentification et utilisateurs

  • Bootstrap admin : dĂ©finissez API_USERNAME et API_PASSWORD pour crĂ©er le premier admin. Pour rĂ©appliquer plus tard, dĂ©finissez OVERRIDE_API_CREDS=yes.
  • Non-admins et permissions : fournissez API_ACL_BOOTSTRAP_FILE avec un chemin JSON (ou montez-le sur /var/lib/bunkerweb/api_acl_bootstrap.json). Le fichier peut lister des utilisateurs et des permissions granulaires.
  • ClĂ©s Biscuit : dĂ©finissez BISCUIT_PUBLIC_KEY/BISCUIT_PRIVATE_KEY ou montez des fichiers sur /var/lib/bunkerweb/.api_biscuit_public_key et /var/lib/bunkerweb/.api_biscuit_private_key. Si rien n'est fourni, l'API gĂ©nère et sauvegarde une paire de clĂ©s au dĂ©marrage.

TLS et réseau

  • Adresse/port d'Ă©coute : API_LISTEN_ADDR (dĂ©faut 0.0.0.0), API_LISTEN_PORT (dĂ©faut 8888).
  • Reverse proxies : dĂ©finissez API_FORWARDED_ALLOW_IPS avec les IPs des proxys pour que Gunicorn fasse confiance aux en-tĂŞtes X-Forwarded-*.
  • Terminaison TLS dans l'API : API_SSL_ENABLED=yes plus API_SSL_CERTFILE et API_SSL_KEYFILE ; optionnellement API_SSL_CA_CERTS.

Limitation de débit : configurations rapides

  • DĂ©sactiver globalement : API_RATE_LIMIT_ENABLED=no
  • DĂ©finir une limite globale simple : API_RATE_LIMIT_TIMES=100, API_RATE_LIMIT_SECONDS=60
  • Règles par route : dĂ©finissez API_RATE_LIMIT_RULES sur un chemin de fichier JSON/YAML ou du YAML en ligne dans /etc/bunkerweb/api.yml.

Sécurité au démarrage

L'API se termine si aucun chemin d'authentification n'est configuré (pas de clés Biscuit, pas d'utilisateur admin, et pas de API_TOKEN). Assurez-vous qu'au moins une méthode est définie avant de démarrer.

Chemin racine et proxys

Si vous déployez l'API derrière BunkerWeb sur une sous-URL, définissez API_ROOT_PATH sur ce chemin pour que /docs et les routes relatives fonctionnent correctement.

Opérations

  • SantĂ© : GET /health renvoie {"status":"ok"} lorsque le service est dĂ©marrĂ©.
  • Service Linux : une unitĂ© systemd nommĂ©e bunkerweb-api.service est fournie. Personnalisez via /etc/bunkerweb/api.env et gĂ©rez avec systemctl.
  • SĂ©curitĂ© au dĂ©marrage : l'API Ă©choue rapidement si aucun chemin d'authentification n'est disponible (pas de clĂ©s Biscuit, pas d'utilisateur admin, pas de API_TOKEN). Les erreurs sont Ă©crites dans /var/tmp/bunkerweb/api.error.