Saltar a contenido

API

Descripci贸n general

La API de BunkerWeb es el plano de control utilizado para gestionar las instancias de BunkerWeb de forma program谩tica: listar y gestionar instancias, recargar/detener, manejar baneos, plugins, trabajos, configuraciones y m谩s. Expone una aplicaci贸n FastAPI documentada con autenticaci贸n fuerte, autorizaci贸n y limitaci贸n de velocidad.

Abre la documentaci贸n interactiva en /docs (o <root_path>/docs si estableciste API_ROOT_PATH). El esquema OpenAPI est谩 disponible en /openapi.json.

Seguridad

La API es un plano de control privilegiado. No la expongas en la Internet p煤blica sin protecciones adicionales.

Como m铆nimo, restringe las IP de origen (API_WHITELIST_IPS), habilita la autenticaci贸n (API_TOKEN o usuarios de API + Biscuit), y considera ponerla detr谩s de BunkerWeb con una ruta dif铆cil de adivinar y controles de acceso adicionales.

Requisitos previos

El servicio de la API requiere acceso a la base de datos de BunkerWeb (DATABASE_URI). Generalmente se despliega junto con el Programador y opcionalmente la Interfaz de Usuario Web. La configuraci贸n recomendada es ejecutar BunkerWeb al frente como un proxy inverso y aislar la API en una red interna.

Consulta el asistente de inicio r谩pido y la gu铆a de arquitectura en la gu铆a de inicio r谩pido.

Puntos destacados

  • Consciente de las instancias: transmite acciones operativas a las instancias descubiertas.
  • Autenticaci贸n fuerte: B谩sica para administradores, anulaci贸n de administrador con Bearer, o ACL de Biscuit para permisos detallados.
  • Lista blanca de IP y limitaci贸n de velocidad flexible por ruta.
  • Se帽ales est谩ndar de salud/disponibilidad y comprobaciones de seguridad al inicio.

Plantillas de Compose

Haz un proxy inverso de la API bajo /api con BunkerWeb.

x-bw-env: &bw-env
  # Lista blanca compartida del plano de control de instancias para 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"  # Coincide con el nombre del servicio de la instancia
      SERVER_NAME: "www.example.com"
      MULTISITE: "yes"
      DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db"
      DISABLE_DEFAULT_SERVER: "yes"
      # Proxy inverso de la API en /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"  # Usa una contrase帽a fuerte
      API_WHITELIST_IPS: "127.0.0.0/8 10.20.30.0/24"                      # Lista blanca de la API
      API_TOKEN: "secret"                                                 # Token de anulaci贸n de administrador opcional
      API_ROOT_PATH: "/api"                                               # Coincide con la ruta del proxy inverso
    restart: unless-stopped
    networks:
      - bw-universe
      - bw-db

  bw-db:
    image: mariadb:11
    # Evita problemas con consultas grandes
    command: --max-allowed-packet=67108864
    environment:
      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
      MYSQL_DATABASE: "db"
      MYSQL_USER: "bunkerweb"
      MYSQL_PASSWORD: "changeme"  # Usa una contrase帽a fuerte
    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

Lo mismo que arriba pero aprovechando el servicio Autoconf para descubrir y configurar servicios autom谩ticamente. La API se expone bajo /api usando etiquetas en el contenedor de la API.

x-api-env: &api-env
  AUTOCONF_MODE: "yes"
  DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db"  # Usa una contrase帽a fuerte

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: ""    # Descubierto por Autoconf
      SERVER_NAME: ""            # Rellenado a trav茅s de etiquetas
      MULTISITE: "yes"           # Obligatorio con 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

Ruta del proxy inverso

Mant茅n la ruta de la API dif铆cil de adivinar y comb铆nala con la lista blanca de la API y la autenticaci贸n.

Si ya expones otra aplicaci贸n en el mismo nombre de servidor con una plantilla (p. ej., USE_TEMPLATE), prefiere un nombre de host separado para la API para evitar conflictos.

Todo en Uno

Si utilizas la imagen Todo en Uno, la API se puede habilitar estableciendo 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

Autenticaci贸n

Formas admitidas para autenticar solicitudes:

  • Administrador B谩sico: Cuando las credenciales pertenecen a un usuario de API administrador, los puntos finales protegidos aceptan Authorization: Basic <base64(nombredeusuario:contrase帽a)>.
  • Anulaci贸n de Administrador con Bearer: Si se configura API_TOKEN, Authorization: Bearer <API_TOKEN> otorga acceso completo.
  • Token Biscuit (recomendado): Obt茅n un token desde POST /auth utilizando credenciales B谩sicas o un cuerpo JSON/formulario que contenga username y password. Utiliza el token devuelto como Authorization: Bearer <token> en llamadas posteriores.

Ejemplo: obtener un Biscuit, listar instancias y luego recargar todas las instancias.

# 1) Obtener un token Biscuit con credenciales de administrador
TOKEN=$(curl -s -X POST -u admin:changeme http://api.example.com/auth | jq -r .token)

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

# 3) Recargar la configuraci贸n en todas las instancias (sin prueba)
curl -X POST -H "Authorization: Bearer $TOKEN" \
     "http://api.example.com/instances/reload?test=no"

Hechos y comprobaciones de Biscuit

Los tokens incorporan hechos como user(<username>), client_ip(<ip>), domain(<host>), y un rol general role("api_user", ["read", "write"]) derivado de los permisos de la base de datos. Los administradores incluyen admin(true) mientras que los no administradores llevan hechos detallados como api_perm(<resource_type>, <resource_id|*>, <permission>).

La autorizaci贸n mapea la ruta/m茅todo a los permisos requeridos; admin(true) siempre pasa. Cuando los hechos detallados est谩n ausentes, la guarda recurre al rol general: GET/HEAD/OPTIONS requieren read; los verbos de escritura requieren write.

Las claves se almacenan en /var/lib/bunkerweb/.api_biscuit_private_key y /var/lib/bunkerweb/.api_biscuit_public_key. Tambi茅n puedes proporcionar BISCUIT_PUBLIC_KEY/BISCUIT_PRIVATE_KEY a trav茅s de variables de entorno; si no se establecen ni archivos ni variables de entorno, la API genera un par de claves al inicio y lo persiste de forma segura.

Permisos (ACL)

Esta API soporta dos capas de autorizaci贸n:

  • Rol general: Los tokens llevan role("api_user", ["read"[, "write"]]) para los puntos finales sin un mapeo detallado. Lectura se mapea a GET/HEAD/OPTIONS; escritura se mapea a POST/PUT/PATCH/DELETE.
  • ACL detallada: Los tokens incorporan api_perm(<resource_type>, <resource_id|*>, <permission>) y las rutas declaran lo que requieren. admin(true) omite todas las comprobaciones.

Tipos de recursos admitidos: instances, global_config, services, configs, plugins, cache, bans, jobs.

Nombres de permisos por tipo de recurso:

  • 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 recursos: Para comprobaciones detalladas, el segundo segmento de la ruta se trata como resource_id cuando tiene sentido. Ejemplos: /services/{service} -> {service}; /configs/{service}/... -> {service}. Usa "*" (u omite) para otorgar globalmente para un tipo de recurso.

Configuraci贸n de usuario y ACL:

  • Usuario administrador: Establece API_USERNAME y API_PASSWORD para crear el primer administrador al inicio. Para rotar las credenciales m谩s tarde, establece OVERRIDE_API_CREDS=yes (o aseg煤rate de que el administrador fue creado con el m茅todo manual). Solo existe un administrador; los intentos adicionales recurren a la creaci贸n de no administradores.
  • Usuarios no administradores y concesiones: Proporciona API_ACL_BOOTSTRAP_FILE apuntando a un archivo JSON, o monta /var/lib/bunkerweb/api_acl_bootstrap.json. La API lo lee al inicio para crear/actualizar usuarios y permisos.
  • Archivo de cach茅 de ACL: Se escribe un resumen de solo lectura en /var/lib/bunkerweb/api_acl.json al inicio para introspecci贸n; la autorizaci贸n eval煤a las concesiones respaldadas por la base de datos incorporadas en el token Biscuit.

Ejemplos de JSON de arranque (se admiten ambas formas):

{
  "users": {
    "ci": {
      "admin": false,
      "password": "Str0ng&P@ss!",
      "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$...bcrypt-hash...",
      "permissions": {
        "instances": { "*": { "instances_execute": true } },
        "jobs": { "*": { "job_run": true } }
      }
    }
  }
}

O en formato de lista:

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

Notas:

  • Las contrase帽as pueden ser texto plano (password) o bcrypt (password_hash / password_bcrypt). Las contrase帽as de texto plano d茅biles son rechazadas en compilaciones que no son de depuraci贸n; si faltan, se genera una aleatoria y se registra una advertencia.
  • resource_id: "*" (o nulo/vac铆o) otorga globalmente sobre ese tipo de recurso.
  • Las contrase帽as de los usuarios existentes pueden actualizarse y se pueden aplicar concesiones adicionales a trav茅s del arranque.

Referencia de caracter铆sticas

La API est谩 organizada por enrutadores centrados en recursos. Utiliza las secciones a continuaci贸n como un mapa de capacidades; el esquema interactivo en /docs documenta los modelos de solicitud/respuesta en detalle.

N煤cleo y autenticaci贸n

  • GET /ping, GET /health: sondas de actividad ligeras para el propio servicio de la API.
  • POST /auth: intercambia credenciales B谩sicas (o el token de anulaci贸n de administrador) por un Biscuit. Acepta JSON, formulario o cabeceras Authorization. Los administradores tambi茅n pueden continuar usando HTTP Basic directamente en rutas protegidas cuando lo deseen.

Plano de control de instancias

  • GET /instances: lista las instancias registradas, incluyendo marcas de tiempo de creaci贸n/煤ltima vez visto, m茅todo de registro y metadatos.
  • POST /instances: registra una nueva instancia gestionada por la API (nombre de host, puerto opcional, nombre de servidor, nombre amigable, m茅todo).
  • GET /instances/{hostname} / PATCH /instances/{hostname} / DELETE /instances/{hostname}: inspecciona, actualiza campos mutables o elimina instancias gestionadas por la API.
  • DELETE /instances: eliminaci贸n masiva; omite las instancias que no son de la API y las informa en skipped.
  • GET /instances/ping y GET /instances/{hostname}/ping: comprobaciones de salud en todas o en instancias individuales.
  • POST /instances/reload?test=yes|no, POST /instances/{hostname}/reload: activa la recarga de la configuraci贸n (el modo de prueba realiza una validaci贸n de ejecuci贸n en seco).
  • POST /instances/stop, POST /instances/{hostname}/stop: retransmite comandos de detenci贸n a las instancias.

Configuraci贸n global

  • GET /global_config: obtiene configuraciones no predeterminadas (usa full=true para la configuraci贸n completa, methods=true para incluir la procedencia).
  • PATCH /global_config: actualiza o inserta configuraciones globales propiedad de la API (method="api"); los errores de validaci贸n se帽alan claves desconocidas o de solo lectura.

Ciclo de vida del servicio

  • GET /services: enumera los servicios con metadatos, incluido el estado de borrador y las marcas de tiempo.
  • GET /services/{service}: recupera las superposiciones no predeterminadas (full=false) o la instant谩nea completa de la configuraci贸n (full=true) para un servicio.
  • POST /services: crea servicios, opcionalmente como borrador, y siembra variables con prefijo ({service}_{KEY}). Actualiza la lista SERVER_NAME at贸micamente.
  • PATCH /services/{service}: renombra servicios, cambia los indicadores de borrador y actualiza las variables con prefijo. Ignora las ediciones directas a SERVER_NAME dentro de variables por seguridad.
  • DELETE /services/{service}: elimina un servicio y sus claves de configuraci贸n derivadas.
  • POST /services/{service}/convert?convert_to=online|draft: cambia r谩pidamente el estado borrador/en l铆nea sin alterar otras variables.

Fragmentos de configuraci贸n personalizados

  • GET /configs: lista fragmentos de configuraci贸n personalizados (HTTP/servidor/stream/ModSecurity/ganchos CRS) para un servicio (service=global por defecto). with_data=true incrusta contenido UTF-8 cuando es imprimible.
  • POST /configs y POST /configs/upload: crea nuevos fragmentos a partir de cargas 煤tiles JSON o archivos subidos. Los tipos aceptados incluyen http, server_http, default_server_http, modsec, modsec_crs, stream, server_stream, y ganchos de plugins CRS. Los nombres deben coincidir con ^[\w_-]{1,64}$.
  • GET /configs/{service}/{type}/{name}: recupera un fragmento con contenido opcional (with_data=true).
  • PATCH /configs/{service}/{type}/{name} y PATCH .../upload: actualiza o mueve fragmentos gestionados por la API; las entradas gestionadas por plantilla o archivo permanecen de solo lectura.
  • DELETE /configs y DELETE /configs/{service}/{type}/{name}: elimina fragmentos gestionados por la API conservando los gestionados por plantilla, devolviendo una lista skipped para las entradas ignoradas.

Orquestaci贸n de baneos

  • GET /bans: agrega los baneos activos informados por todas las instancias.
  • POST /bans o POST /bans/ban: aplica uno o varios baneos. Las cargas 煤tiles pueden ser objetos JSON, matrices o JSON en formato de cadena. service es opcional; cuando se omite, el baneo es global.
  • POST /bans/unban o DELETE /bans: elimina baneos globalmente o por servicio utilizando las mismas cargas 煤tiles flexibles.

Gesti贸n de plugins

  • GET /plugins?type=all|external|ui|pro: lista plugins con metadatos; with_data=true incluye los bytes empaquetados cuando est谩n disponibles.
  • POST /plugins/upload: instala plugins de UI desde archivos .zip, .tar.gz o .tar.xz. Los archivos pueden agrupar m煤ltiples plugins siempre que cada uno contenga un plugin.json.
  • DELETE /plugins/{id}: elimina un plugin de UI por ID (^[\w.-]{4,64}$).

Cach茅 y ejecuci贸n de trabajos

  • GET /cache: lista los artefactos en cach茅 producidos por los trabajos del programador, filtrados por servicio, ID de plugin o nombre de trabajo. with_data=true incluye contenido de archivo imprimible.
  • GET /cache/{service}/{plugin}/{job}/{file}: obtiene un archivo de cach茅 espec铆fico (download=true transmite un archivo adjunto).
  • DELETE /cache o DELETE /cache/{service}/{plugin}/{job}/{file}: elimina archivos de cach茅 y notifica al programador sobre los plugins afectados.
  • GET /jobs: inspecciona trabajos conocidos, sus metadatos de programaci贸n y res煤menes de cach茅.
  • POST /jobs/run: solicita la ejecuci贸n de un trabajo marcando el(los) plugin(s) asociado(s) como cambiado(s).

Notas operativas

  • Los puntos finales de escritura persisten en la base de datos compartida; las instancias recogen los cambios a trav茅s de la sincronizaci贸n del programador o despu茅s de un /instances/reload.
  • Los errores se normalizan a { "status": "error", "message": "..." } con los c贸digos de estado HTTP apropiados (422 validaci贸n, 404 no encontrado, 403 ACL, 5xx fallos de origen).

Limitaci贸n de velocidad

La limitaci贸n de velocidad por cliente es manejada por SlowAPI. Habil铆tala/deshabil铆tala y configura los l铆mites a trav茅s de variables de entorno o /etc/bunkerweb/api.yml.

  • API_RATE_LIMIT_ENABLED (predeterminado: yes)
  • L铆mite predeterminado: API_RATE_LIMIT_TIMES por API_RATE_LIMIT_SECONDS (p. ej., 100 por 60)
  • API_RATE_LIMIT_RULES: JSON/CSV en l铆nea, o una ruta a un archivo YAML/JSON con reglas por ruta
  • Backend de almacenamiento: en memoria o Redis/Valkey cuando USE_REDIS=yes y se proporcionan las variables REDIS_* (compatible con Sentinel)
  • Cabeceras: API_RATE_LIMIT_HEADERS_ENABLED (predeterminado: yes)

Ejemplo de YAML (montado en /etc/bunkerweb/api.yml):

yaml 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

Configuraci贸n

Puedes configurar la API a trav茅s de variables de entorno, secretos de Docker y los archivos opcionales /etc/bunkerweb/api.yml o /etc/bunkerweb/api.env. Configuraciones clave:

  • Documentaci贸n y esquema: API_DOCS_URL, API_REDOC_URL, API_OPENAPI_URL, API_ROOT_PATH.
  • Autenticaci贸n b谩sica: API_TOKEN (Bearer de anulaci贸n de administrador), API_USERNAME/API_PASSWORD (crear/actualizar administrador), OVERRIDE_API_CREDS.
  • ACL y usuarios: API_ACL_BOOTSTRAP_FILE (ruta JSON).
  • Pol铆tica de Biscuit: API_BISCUIT_TTL_SECONDS (0/desactivado deshabilita el TTL), CHECK_PRIVATE_IP (vincula el token a la IP del cliente a menos que sea privada).
  • Lista blanca de IP: API_WHITELIST_ENABLED, API_WHITELIST_IPS.
  • Limitaci贸n de velocidad (n煤cleo): API_RATE_LIMIT_ENABLED, API_RATE_LIMIT_TIMES, API_RATE_LIMIT_SECONDS, API_RATE_LIMIT_HEADERS_ENABLED.
  • Limitaci贸n de velocidad (avanzado): 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.
  • Almacenamiento de limitaci贸n de velocidad: en memoria o Redis/Valkey cuando USE_REDIS=yes y se establecen configuraciones de Redis como REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_DATABASE, REDIS_SSL, o variables de Sentinel. Consulta la tabla de configuraciones de Redis en docs/features.md.
  • Red/TLS: API_LISTEN_ADDR, API_LISTEN_PORT, API_FORWARDED_ALLOW_IPS, API_SSL_ENABLED, API_SSL_CERTFILE, API_SSL_KEYFILE, API_SSL_CA_CERTS.

C贸mo se carga la configuraci贸n

Precedencia de mayor a menor:

  • Variables de entorno (p. ej., environment: del contenedor o variables de shell exportadas)
  • Archivos de secretos en /run/secrets (secretos de Docker/K8s; los nombres de archivo coinciden con los nombres de las variables)
  • Archivo YAML en /etc/bunkerweb/api.yml
  • Archivo de entorno en /etc/bunkerweb/api.env (l铆neas clave=valor)
  • Valores predeterminados incorporados

Notas:

  • YAML admite la inserci贸n de archivos de secretos con <file:relative/path>; la ruta se resuelve contra /run/secrets.
  • Establece las URL de la documentaci贸n en off/disabled/none para deshabilitar los puntos finales (p. ej., API_DOCS_URL=off).
  • Si API_SSL_ENABLED=yes, tambi茅n debes establecer API_SSL_CERTFILE y API_SSL_KEYFILE.
  • Si Redis est谩 habilitado (USE_REDIS=yes), proporciona los detalles de Redis; consulta la secci贸n de Redis en docs/features.md.

Autenticaci贸n y usuarios

  • Arranque de administrador: establece API_USERNAME y API_PASSWORD para crear el primer administrador. Para volver a aplicar m谩s tarde, establece OVERRIDE_API_CREDS=yes.
  • No administradores y permisos: proporciona API_ACL_BOOTSTRAP_FILE con una ruta JSON (o monta en /var/lib/bunkerweb/api_acl_bootstrap.json). El archivo puede listar usuarios y concesiones detalladas.
  • Claves de Biscuit: establece BISCUIT_PUBLIC_KEY/BISCUIT_PRIVATE_KEY o monta archivos en /var/lib/bunkerweb/.api_biscuit_public_key y /var/lib/bunkerweb/.api_biscuit_private_key. Si no se proporciona ninguno, la API genera y persiste un par de claves al inicio.

TLS y redes

  • Direcci贸n/puerto de enlace: API_LISTEN_ADDR (predeterminado 0.0.0.0), API_LISTEN_PORT (predeterminado 8888).
  • Proxies inversos: establece API_FORWARDED_ALLOW_IPS en las IP del proxy para que Gunicorn conf铆e en las cabeceras X-Forwarded-*.
  • Terminaci贸n de TLS en la API: API_SSL_ENABLED=yes m谩s API_SSL_CERTFILE y API_SSL_KEYFILE; opcional API_SSL_CA_CERTS

Recetas r谩pidas de limitaci贸n de velocidad

  • Deshabilitar globalmente: API_RATE_LIMIT_ENABLED=no
  • Establecer un l铆mite global simple: API_RATE_LIMIT_TIMES=100, API_RATE_LIMIT_SECONDS=60
  • Reglas por ruta: establece API_RATE_LIMIT_RULES en una ruta de archivo JSON/YAML o YAML en l铆nea en /etc/bunkerweb/api.yml.

Seguridad de inicio

La API se cierra si no hay una ruta de autenticaci贸n configurada (sin claves Biscuit, sin usuario administrador y sin API_TOKEN). Aseg煤rate de que al menos un m茅todo est茅 configurado antes de iniciar.

Seguridad de inicio: La API se cierra si no hay una ruta de autenticaci贸n disponible (sin claves Biscuit, sin usuario de API administrador y sin API_TOKEN). Aseg煤rate de que al menos una est茅 configurada.

Ruta ra铆z y proxies

Si despliegas la API detr谩s de BunkerWeb en una subruta, establece API_ROOT_PATH en esa ruta para que /docs y las rutas relativas funcionen correctamente cuando se usan con un proxy.

Operaciones

  • Salud: GET /health devuelve {"status":"ok"} cuando el servicio est谩 activo.
  • Servicio de Linux: se empaqueta una unidad systemd llamada bunkerweb-api.service. Personaliza a trav茅s de /etc/bunkerweb/api.env y gestiona con systemctl.
  • Seguridad de inicio: la API falla r谩pidamente cuando no hay una ruta de autenticaci贸n disponible (sin claves Biscuit, sin usuario administrador, sin API_TOKEN). Los errores se escriben en /var/tmp/bunkerweb/api.error.