Saltar a contenido

Usos avanzados

Muchos ejemplos de casos de uso del mundo real están disponibles en la carpeta examples del repositorio de GitHub.

También proporcionamos numerosos boilerplates, como archivos YAML para diversas integraciones y tipos de bases de datos. Estos están disponibles en la carpeta misc/integrations.

Esta sección solo se enfoca en usos avanzados y ajustes de seguridad, consulta la sección de características de la documentación para ver todas las configuraciones disponibles.

Pruebas

Para realizar pruebas rápidas cuando el modo multisitio está habilitado (y si no tienes las entradas DNS adecuadas configuradas para los dominios) puedes usar curl con la cabecera HTTP Host de tu elección: 

curl -H "Host: app1.example.com" http://ip-o-fqdn-del-servidor

Si estás usando HTTPS, necesitarás jugar con SNI: 

curl -H "Host: app1.example.com" --resolve example.com:443:ip-del-servidor https://example.com

Detrás de un balanceador de carga o proxy inverso

IP real

Cuando BunkerWeb está a su vez detrás de un balanceador de carga o un proxy inverso, necesitas configurarlo para que pueda obtener la dirección IP real de los clientes. Si no lo haces, las características de seguridad bloquearán la dirección IP del balanceador de carga o del proxy inverso en lugar de la del cliente.

BunkerWeb admite dos métodos para recuperar la dirección IP real del cliente:

  • Usando el protocolo PROXY
  • Usando una cabecera HTTP como X-Forwarded-For

Se pueden usar las siguientes configuraciones:

  • USE_REAL_IP: habilitar/deshabilitar la recuperación de la IP real
  • USE_PROXY_PROTOCOL: habilitar/deshabilitar el soporte del protocolo PROXY.
  • REAL_IP_FROM: lista de direcciones IP/red de confianza permitidas para enviarnos la "IP real"
  • REAL_IP_HEADER: la cabecera HTTP que contiene la IP real o el valor especial proxy_protocol cuando se usa el protocolo PROXY

Encontrarás más configuraciones sobre la IP real en la sección de características de la documentación.

Asumiremos lo siguiente con respecto a los balanceadores de carga o proxies inversos (necesitarás actualizar la configuración dependiendo de tu configuración):

  • Usan la cabecera X-Forwarded-For para establecer la IP real
  • Tienen IPs en las redes 1.2.3.0/24 y 100.64.0.0/10

Navega a la página de Configuración Global, selecciona el plugin Real IP y completa las siguientes configuraciones:

Configuración de IP real (cabecera) usando la interfaz de usuario web
Configuración de IP real (cabecera) usando la interfaz de usuario web

Ten en cuenta que se recomienda reiniciar BunkerWeb cuando cambies la configuración relacionada con la IP real.

Necesitarás agregar la configuración al archivo /etc/bunkerweb/variables.env:

...
USE_REAL_IP=yes
REAL_IP_FROM=1.2.3.0/24 100.64.0.0/16
REAL_IP_HEADER=X-Forwarded-For
...

Ten en cuenta que se recomienda emitir un reinicio en lugar de una recarga al configurar ajustes relacionados con la IP real:

sudo systemctl restart bunkerweb && \
sudo systemctl restart bunkerweb-scheduler

Necesitarás agregar la configuración a las variables de entorno al ejecutar el contenedor Todo en uno:

docker run -d \
    --name bunkerweb-aio \
    -v bw-storage:/data \
    -e USE_REAL_IP="yes" \
    -e REAL_IP_FROM="1.2.3.0/24 100.64.0.0/10" \
    -e REAL_IP_HEADER="X-Forwarded-For" \
    -p 80:8080/tcp \
    -p 443:8443/tcp \
    -p 443:8443/udp \
    bunkerity/bunkerweb-all-in-one:1.6.18-rc1

Ten en cuenta que si tu contenedor ya está creado, necesitarás eliminarlo y recrearlo para que se actualicen las nuevas variables de entorno.

Necesitarás agregar la configuración a las variables de entorno de los contenedores de BunkerWeb y del programador:

bunkerweb:
  image: bunkerity/bunkerweb:1.6.18-rc1
  ...
  environment:
    USE_REAL_IP: "yes"
    REAL_IP_FROM: "1.2.3.0/24 100.64.0.0/10"
    REAL_IP_HEADER: "X-Forwarded-For"
  ...
bw-scheduler:
  image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
  ...
  environment:
    USE_REAL_IP: "yes"
    REAL_IP_FROM: "1.2.3.0/24 100.64.0.0/10"
    REAL_IP_HEADER: "X-Forwarded-For"
  ...

Ten en cuenta que si tu contenedor ya está creado, necesitarás eliminarlo y recrearlo para que se actualicen las nuevas variables de entorno.

Necesitarás agregar la configuración a las variables de entorno de los contenedores de BunkerWeb y del programador:

bunkerweb:
  image: bunkerity/bunkerweb:1.6.18-rc1
  ...
  environment:
    USE_REAL_IP: "yes"
    REAL_IP_FROM: "1.2.3.0/24 100.64.0.0/10"
    REAL_IP_HEADER: "X-Forwarded-For"
  ...
bw-scheduler:
  image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
  ...
  environment:
    USE_REAL_IP: "yes"
    REAL_IP_FROM: "1.2.3.0/24 100.64.0.0/10"
    REAL_IP_HEADER: "X-Forwarded-For"
  ...

Ten en cuenta que si tu contenedor ya está creado, necesitarás eliminarlo y recrearlo para que se actualicen las nuevas variables de entorno.

Necesitarás agregar la configuración a las variables de entorno de los pods de BunkerWeb y del programador.

Aquí está la parte correspondiente de tu archivo values.yaml que puedes usar:

bunkerweb:
  extraEnvs:
    - name: USE_REAL_IP
      value: "yes"
    - name: REAL_IP_FROM
      value: "1.2.3.0/24 100.64.0.0/10"
    - name: REAL_IP_HEADER
      value: "X-Forwarded-For"
scheduler:
  extraEnvs:
    - name: USE_REAL_IP
      value: "yes"
    - name: REAL_IP_FROM
      value: "1.2.3.0/24 100.64.0.0/10"
    - name: REAL_IP_HEADER
      value: "X-Forwarded-For"

Obsoleto

La integración de Swarm está obsoleta y se eliminará en una futura versión. Por favor, considera usar la integración de Kubernetes en su lugar.

Puedes encontrar más información en la documentación de la integración de Swarm.

Necesitarás agregar la configuración a las variables de entorno de los servicios de BunkerWeb y del programador:

bunkerweb:
  image: bunkerity/bunkerweb:1.6.18-rc1
  ...
  environment:
    USE_REAL_IP: "yes"
    REAL_IP_FROM: "1.2.3.0/24 100.64.0.0/10"
    REAL_IP_HEADER: "X-Forwarded-For"
  ...
bw-scheduler:
  image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
  ...
  environment:
    USE_REAL_IP: "yes"
    REAL_IP_FROM: "1.2.3.0/24 100.64.0.0/10"
    REAL_IP_HEADER: "X-Forwarded-For"
  ...

Ten en cuenta que si tu servicio ya está creado, necesitarás eliminarlo y recrearlo para que se actualicen las nuevas variables de entorno.

Lee con atención

Solo usa el protocolo PROXY si estás seguro de que tu balanceador de carga o proxy inverso lo está enviando. Si lo habilitas y no se está usando, obtendrás errores.

Asumiremos lo siguiente con respecto a los balanceadores de carga o proxies inversos (necesitarás actualizar la configuración dependiendo de tu configuración):

  • Usan el protocolo PROXY v1 o v2 para establecer la IP real
  • Tienen IPs en las redes 1.2.3.0/24 y 100.64.0.0/10

Navega a la página de Configuración Global, selecciona el plugin Real IP y completa las siguientes configuraciones:

Configuración de IP real (protocolo PROXY) usando la interfaz de usuario web
Configuración de IP real (protocolo PROXY) usando la interfaz de usuario web

Ten en cuenta que se recomienda reiniciar BunkerWeb cuando cambies la configuración relacionada con la IP real.

Necesitarás agregar la configuración al archivo /etc/bunkerweb/variables.env:

...
USE_REAL_IP=yes
USE_PROXY_PROTOCOL=yes
REAL_IP_FROM=1.2.3.0/24 100.64.0.0/16
REAL_IP_HEADER=proxy_protocol
...

Ten en cuenta que se recomienda emitir un reinicio en lugar de una recarga al configurar ajustes relacionados con los protocolos proxy:

sudo systemctl restart bunkerweb && \
sudo systemctl restart bunkerweb-scheduler

Necesitarás agregar la configuración a las variables de entorno al ejecutar el contenedor Todo en uno:

docker run -d \
    --name bunkerweb-aio \
    -v bw-storage:/data \
    -e USE_REAL_IP="yes" \
    -e USE_PROXY_PROTOCOL="yes" \
    -e REAL_IP_FROM="1.2.3.0/24 100.64.0.0/10" \
    -e REAL_IP_HEADER="proxy_protocol" \
    -p 80:8080/tcp \
    -p 443:8443/tcp \
    -p 443:8443/udp \
    bunkerity/bunkerweb-all-in-one:1.6.18-rc1

Ten en cuenta que si tu contenedor ya está creado, necesitarás eliminarlo y recrearlo para que se actualicen las nuevas variables de entorno.

Necesitarás agregar la configuración a las variables de entorno de los contenedores de BunkerWeb y del programador:

bunkerweb:
  image: bunkerity/bunkerweb:1.6.18-rc1
  ...
  environment:
    USE_REAL_IP: "yes"
    USE_PROXY_PROTOCOL: "yes"
    REAL_IP_FROM: "1.2.3.0/24 100.64.0.0/10"
    REAL_IP_HEADER: "proxy_protocol"
  ...
...
bw-scheduler:
  image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
  ...
  environment:
    USE_REAL_IP: "yes"
    USE_PROXY_PROTOCOL: "yes"
    REAL_IP_FROM: "1.2.3.0/24 100.64.0.0/10"
    REAL_IP_HEADER: "proxy_protocol"
  ...

Ten en cuenta que si tu contenedor ya está creado, necesitarás eliminarlo y recrearlo para que se actualicen las nuevas variables de entorno.

Necesitarás agregar la configuración a las variables de entorno de los contenedores de BunkerWeb y del programador:

bunkerweb:
  image: bunkerity/bunkerweb:1.6.18-rc1
  ...
  environment:
    USE_REAL_IP: "yes"
    USE_PROXY_PROTOCOL: "yes"
    REAL_IP_FROM: "1.2.3.0/24 100.64.0.0/10"
    REAL_IP_HEADER: "proxy_protocol"
  ...
...
bw-scheduler:
  image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
  ...
  environment:
    USE_REAL_IP: "yes"
    USE_PROXY_PROTOCOL: "yes"
    REAL_IP_FROM: "1.2.3.0/24 100.64.0.0/10"
    REAL_IP_HEADER: "proxy_protocol"
  ...

Ten en cuenta que si tu contenedor ya está creado, necesitarás eliminarlo y recrearlo para que se actualicen las nuevas variables de entorno.

Necesitarás agregar la configuración a las variables de entorno de los pods de BunkerWeb y del programador.

Aquí está la parte correspondiente de tu archivo values.yaml que puedes usar:

bunkerweb:
  extraEnvs:
    - name: USE_REAL_IP
      value: "yes"
    - name: USE_PROXY_PROTOCOL
      value: "yes"
    - name: REAL_IP_FROM
      value: "1.2.3.0/24 100.64.0.0/10"
    - name: REAL_IP_HEADER
      value: "proxy_protocol"
scheduler:
  extraEnvs:
    - name: USE_REAL_IP
      value: "yes"
    - name: USE_PROXY_PROTOCOL
      value: "yes"
    - name: REAL_IP_FROM
      value: "1.2.3.0/24 100.64.0.0/10"
    - name: REAL_IP_HEADER
      value: "proxy_protocol"

Obsoleto

La integración de Swarm está obsoleta y se eliminará en una futura versión. Por favor, considera usar la integración de Kubernetes en su lugar.

Puedes encontrar más información en la documentación de la integración de Swarm.

Necesitarás agregar la configuración a las variables de entorno de los servicios de BunkerWeb y del programador.

bunkerweb:
  image: bunkerity/bunkerweb:1.6.18-rc1
  ...
  environment:
    USE_REAL_IP: "yes"
    USE_PROXY_PROTOCOL: "yes"
    REAL_IP_FROM: "1.2.3.0/24 100.64.0.0/10"
    REAL_IP_HEADER: "proxy_protocol"
  ...
...
bw-scheduler:
  image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
  ...
  environment:
    USE_REAL_IP: "yes"
    USE_PROXY_PROTOCOL: "yes"
    REAL_IP_FROM: "1.2.3.0/24 100.64.0.0/10"
    REAL_IP_HEADER: "proxy_protocol"
  ...

Ten en cuenta que si tu servicio ya está creado, necesitarás eliminarlo y recrearlo para que se actualicen las nuevas variables de entorno.

Alta disponibilidad y balanceo de carga

Para que tus aplicaciones sigan disponibles incluso si un servidor falla, puedes desplegar BunkerWeb en un clúster de Alta Disponibilidad (HA). Esta arquitectura incluye un Manager (Scheduler) que orquesta la configuración y varios Workers (instancias BunkerWeb) que manejan el tráfico.

flowchart LR

  %% ================ Styles =================
  classDef manager     fill:#eef2ff,stroke:#4c1d95,stroke-width:1px,rx:6px,ry:6px;
  classDef component     fill:#f9fafb,stroke:#6b7280,stroke-width:1px,rx:4px,ry:4px;
  classDef lb            fill:#e0f2fe,stroke:#0369a1,stroke-width:1px,rx:6px,ry:6px;
  classDef database fill:#d1fae5,stroke:#059669,stroke-width:1px,rx:4px,ry:4px;
  classDef datastore     fill:#fee2e2,stroke:#b91c1c,stroke-width:1px,rx:4px,ry:4px;
  classDef backend       fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,rx:4px,ry:4px;
  classDef client        fill:#e5e7eb,stroke:#4b5563,stroke-width:1px,rx:4px,ry:4px;

  %% Container styles
  style CLUSTER fill:#f3f4f6,stroke:#d1d5db,stroke-width:1px,stroke-dasharray:6 3;
  style WORKERS fill:none,stroke:#9ca3af,stroke-width:1px,stroke-dasharray:4 2;

  %% ============== Outside left =============
  Client["Cliente"]:::client
  LB["Load Balancer"]:::lb

  %% ============== Cluster ==================
  subgraph CLUSTER[" "]
    direction TB

    %% ---- Top row: Manager + Redis ----
    subgraph TOP["Manager & Data Stores"]
      direction LR
      Manager["Manager<br/>(Scheduler)"]:::manager
      BDD["BDD"]:::database
      Redis["Redis/Valkey"]:::datastore
      UI["Interfaz Web"]:::manager
    end

    %% ---- Middle: Workers ----
    subgraph WORKERS["Workers (BunkerWeb)"]
      direction TB
      Worker1["Worker 1"]:::component
      WorkerN["Worker N"]:::component
    end

    %% ---- Bottom: App ----
    App["App"]:::backend
  end

  %% ============ Outside right ============
  Admin["Admin"]:::client

  %% ============ Traffic & control ===========
  %% Manager / control plane
  Manager -->|API 5000| Worker1
  Manager -->|API 5000| WorkerN
  Manager -->|bwcli| Redis
  Manager -->|Config| BDD

  %% User interface (UI)
  UI -->|Config| BDD
  UI -->|Reports / Bans| Redis
  BDD --- UI
  Redis --- UI
  linkStyle 6 stroke-width:0px;
  linkStyle 7 stroke-width:0px;

  %% Workers <-> Redis
  Worker1 -->|Caché compartida| Redis
  WorkerN -->|Caché compartida| Redis

  %% Workers -> App
  Worker1 -->|Tráfico legítimo| App
  WorkerN -->|Tráfico legítimo| App

  %% Client (right side) -> Load balancer -> Workers -> App
  Client -->|Petición| LB
  LB -->|HTTP/TCP| Worker1
  LB -->|HTTP/TCP| WorkerN

  %% Admin -> UI
  UI --- Admin
  Admin -->|HTTP| UI
  linkStyle 15 stroke-width:0px;

Cómo funcionan las API de BunkerWeb

BunkerWeb maneja dos conceptos distintos de API:

  • Una API interna que conecta automáticamente managers y workers para la orquestación. Siempre está habilitada y no requiere configuración manual.
  • Un servicio API opcional (bunkerweb-api) que expone una interfaz REST pública para herramientas de automatización (bwcli, CI/CD, etc.). Está deshabilitada por defecto en instalaciones Linux y es independiente de las comunicaciones internas manager↔worker.

Requisitos previos

Antes de configurar un clúster, asegúrate de contar con:

  • 2 o más hosts Linux con acceso root/sudo.
  • Conectividad de red entre los hosts (especialmente en el puerto TCP 5000 para la API interna).
  • IP o hostname de la aplicación a proteger.
  • (Opcional) Load Balancer (p. ej. HAProxy) para repartir el tráfico entre los workers.

1. Instalar el Manager

El Manager es el cerebro del clúster. Ejecuta el Scheduler, la base de datos y, opcionalmente, la interfaz web.

Seguridad de la interfaz web

La interfaz web escucha en un puerto dedicado (7000 por defecto) y solo debería ser accesible por administradores. Si piensas exponerla a internet, recomendamos encarecidamente protegerla con una instancia de BunkerWeb delante.

  1. Descarga y ejecuta el instalador en el host del manager:

    # Descargar script y checksum
curl -fsSL -O https://github.com/bunkerity/bunkerweb/releases/download/v1.6.18-rc1/install-bunkerweb.sh
curl -fsSL -O https://github.com/bunkerity/bunkerweb/releases/download/v1.6.18-rc1/install-bunkerweb.sh.sha256

# Verificar checksum
sha256sum -c install-bunkerweb.sh.sha256

# Ejecutar instalador
chmod +x install-bunkerweb.sh
sudo ./install-bunkerweb.sh

    Aviso de seguridad

    Comprueba siempre la integridad del script con el checksum proporcionado antes de ejecutarlo.

  2. Selecciona Manager en el menú de tipo de instalación (usa ↑/↓ y luego Enter), y sigue las indicaciones:

    Pregunta Acción
    Instancias BunkerWeb Introduce las IP de tus nodos worker separadas por espacios (ej.: 192.168.10.11 192.168.10.12).
    Whitelist IP Acepta la IP detectada o introduce un subnet (ej.: 192.168.10.0/24) para permitir el acceso a la API.
    Resolutores DNS Elige No para mantener los valores predeterminados, o indica los tuyos.
    HTTPS para la API interna Recomendado: elige Sí para generar certificados y asegurar la comunicación manager-worker.
    Servicio Web UI Elige Sí para activar la interfaz web (muy recomendado).
    Servicio API Elige No salvo que necesites la API REST pública para herramientas externas.

    Interfaz de indicaciones

    El instalador usa la TUI gum. En la primera ejecución interactiva descarga el binario gum oficial desde la release de GitHub (SHA256 fijado), lo ejecuta desde un directorio temporal y elimina ese directorio al salir — no se instala ningún paquete del sistema. Usa las flechas + Enter para responder. Pasa --no-tui si prefieres indicaciones de texto plano.

Asegurar y exponer la UI

Si activaste la interfaz web, debes asegurarla. Puedes alojarla en el Manager o en una máquina separada.

  1. Edita /etc/bunkerweb/ui.env y define credenciales fuertes:
# OVERRIDE_ADMIN_CREDS=no
ADMIN_USERNAME=admin
ADMIN_PASSWORD=changeme
# FLASK_SECRET=changeme
# TOTP_ENCRYPTION_KEYS=changeme
LISTEN_ADDR=0.0.0.0
# LISTEN_PORT=7000
FORWARDED_ALLOW_IPS=127.0.0.1,::1
# ENABLE_HEALTHCHECK=no

Cambia las credenciales por defecto

Sustituye admin y changeme por credenciales robustas antes de arrancar el servicio UI en producción.

  1. Reinicia la UI:
sudo systemctl restart bunkerweb-ui

Para más aislamiento, instala la UI en un nodo independiente.

  1. Ejecuta el instalador y selecciona el tipo de instalación Web UI Only.

  2. Edita /etc/bunkerweb/ui.env para apuntar a la base de datos del Manager:

    # Configuración de base de datos (debe coincidir con la del Manager)
DATABASE_URI=mariadb+pymysql://bunkerweb:changeme@db-host:3306/bunkerweb
# Para PostgreSQL: postgresql://bunkerweb:changeme@db-host:5432/bunkerweb
# Para MySQL: mysql+pymysql://bunkerweb:changeme@db-host:3306/bunkerweb

# Configuración de Redis (si usas Redis/Valkey para persistencia)
# Si no se proporciona, se toma automáticamente de la base de datos
# REDIS_HOST=redis-host

# Credenciales de seguridad
ADMIN_USERNAME=admin
ADMIN_PASSWORD=changeme

# Ajustes de red
LISTEN_ADDR=0.0.0.0
# LISTEN_PORT=7000

  3. Reinicia el servicio:

    sudo systemctl restart bunkerweb-ui

Configuración de firewall

Asegúrate de que el host de la UI pueda llegar a los puertos de base de datos y Redis. Puede que debas ajustar las reglas de firewall tanto en el host de la UI como en los hosts de la base/Redis.

Crea un archivo docker-compose.yml en el host del manager:

docker-compose.yml
x-ui-env: &bw-ui-env
  # Anclamos las variables de entorno para evitar duplicaciones
  DATABASE_URI: \"mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db\" # Usa una contraseña más fuerte

services:
  bw-scheduler:
    image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
    environment:
      <<: *bw-ui-env
      BUNKERWEB_INSTANCES: \"192.168.1.11 192.168.1.12\" # Sustituye por las IP de tus workers
      API_WHITELIST_IP: \"127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16\" # Permitir redes locales
      # API_LISTEN_HTTPS: \"yes\" # Recomendado para asegurar la API interna
      # API_TOKEN: \"my_secure_token\" # Opcional: token adicional
      SERVER_NAME: \"\"
      MULTISITE: \"yes\"
      USE_REDIS: \"yes\"
      REDIS_HOST: \"redis\"
    volumes:
      - bw-storage:/data # Persistencia del caché y backups
    restart: \"unless-stopped\"
    networks:
      - bw-db
      - bw-redis

  bw-ui:
    image: bunkerity/bunkerweb-ui:1.6.18-rc1
    ports:
      - \"7000:7000\" # Exponer el puerto de la UI
    environment:
      <<: *bw-ui-env
      ADMIN_USERNAME: \"changeme\"
      ADMIN_PASSWORD: \"changeme\" # Usa una contraseña más fuerte
      # TOTP_ENCRYPTION_KEYS: \"changeme\" # Opcional: se genera en el volumen bw-ui-data si no se define; una clave tiene 43 caracteres
    volumes:
      - bw-ui-data:/data # Se usa para conservar los secretos de la interfaz web (secreto Flask, claves de cifrado TOTP, claves Biscuit)
    restart: \"unless-stopped\"
    networks:
      - bw-db
      - bw-redis

  bw-db:
    image: mariadb:11
    # Establecemos el tamaño máximo de paquete para evitar 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 más fuerte
    volumes:
      - bw-data:/var/lib/mysql
    restart: \"unless-stopped\"
    networks:
      - bw-db

  redis: # Redis para la persistencia de informes/prohibiciones/estadísticas
    image: redis:8-alpine
    command: >
      redis-server
      --maxmemory 256mb
      --maxmemory-policy volatile-lru
      --save 60 1000
      --appendonly yes
    volumes:
      - redis-data:/data
    restart: \"unless-stopped\"
    networks:
      - bw-redis

volumes:
  bw-data:
  bw-storage:
  redis-data:
  bw-ui-data:

networks:
  bw-db:
    name: bw-db
  bw-redis:
    name: bw-redis

Arranca el stack del manager:

docker compose up -d

2. Instalar los Workers

Los workers son los nodos que procesan el tráfico entrante.

  1. Ejecuta el instalador en cada nodo worker (mismos comandos que para el Manager).

  2. Selecciona la opción 3) Worker y configura:

    Pregunta Acción
    IP del Manager Introduce la IP de tu Manager (ej.: 192.168.10.10).
    HTTPS para la API interna Debe coincidir con el ajuste del Manager (Y o N).

El worker se registrará automáticamente en el Manager.

Crea un archivo docker-compose.yml en cada worker:

docker-compose.yml
services:
  bunkerweb:
    image: bunkerity/bunkerweb:1.6.18-rc1
    ports:
      - \"80:8080/tcp\"
      - \"443:8443/tcp\"
      - \"443:8443/udp\" # Compatibilidad QUIC / HTTP3
      - \"5000:5000/tcp\" # Puerto de la API interna
    environment:
      API_WHITELIST_IP: \"127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16\"
      # API_LISTEN_HTTPS: \"yes\" # Recomendado para asegurar la API interna (debe coincidir con el Manager)
      # API_TOKEN: \"my_secure_token\" # Opcional: token adicional (debe coincidir con el Manager)
    restart: \"unless-stopped\"

Inicia el worker:

docker compose up -d

3. Gestionar los Workers

Puedes añadir más workers más adelante usando la interfaz web o la CLI.

  1. Ve a la pestaña Instances.
  2. Haz clic en Add instance.
  3. Introduce la IP/hostname del worker y guarda.

<div class=\"grid grid-2\" markdown style=\"display:grid; align-items:center;\"> <figure markdown style=\"display:flex; flex-direction:column; justify-content:center; align-items:center; height:100%;\"> BunkerWeb UI - Crear instancia

BunkerWeb UI - Crear instancia
<figure markdown style=\"display:flex; flex-direction:column; justify-content:center; align-items:center; height:100%;\"> BunkerWeb UI - Formulario de instancia
BunkerWeb UI - Formulario de instancia

=== \"Vía configuración\"

=== \"Linux\"

    1. **Edita** `/etc/bunkerweb/variables.env` en el Manager:

        ```bash
        BUNKERWEB_INSTANCES=192.168.10.11 192.168.10.12 192.168.10.13
        ```

    2. **Reinicia el Scheduler**:

        ```bash
        sudo systemctl restart bunkerweb-scheduler
        ```

=== \"Docker\"

    1. **Edita** el archivo `docker-compose.yml` en el Manager para actualizar `BUNKERWEB_INSTANCES`.

    2. **Recrea el contenedor del Scheduler**:

        ```bash
        docker compose up -d bw-scheduler
        ```

4. Verificar la instalación

  1. Comprobar estado: accede a la UI (http://<ip-manager>:7000) y abre la pestaña Instances. Todos los workers deben aparecer Up.
  2. Probar conmutación: detén BunkerWeb en un worker (sudo systemctl stop bunkerweb) y verifica que el tráfico sigue fluyendo.
  1. Comprobar estado: accede a la UI (http://<ip-manager>:7000) y abre la pestaña Instances. Todos los workers deben aparecer Up.
  2. Probar conmutación: detén BunkerWeb en un worker (docker compose stop bunkerweb) y verifica que el tráfico sigue fluyendo.

5. Balanceo de carga

Para repartir el tráfico entre tus workers, utiliza un Load Balancer. Recomendamos uno de capa 4 (TCP) que soporte PROXY protocol para preservar la IP del cliente.

Ejemplo de configuración HAProxy que pasa el tráfico (modo TCP) manteniendo la IP cliente mediante PROXY protocol.

```cfg title=\"haproxy.cfg\" defaults timeout connect 5s timeout client 5s timeout server 5s

frontend http_front mode tcp bind *:80 default_backend http_back

frontend https_front mode tcp bind *:443 default_backend https_back

backend http_back mode tcp balance roundrobin server worker01 192.168.10.11:80 check send-proxy-v2 server worker02 192.168.10.12:80 check send-proxy-v2

backend https_back mode tcp balance roundrobin server worker01 192.168.10.11:443 check send-proxy-v2 server worker02 192.168.10.12:443 check send-proxy-v2 ```

Ejemplo de configuración HAProxy para balanceo en capa 7 (HTTP). Añade la cabecera X-Forwarded-For para que BunkerWeb obtenga la IP del cliente.

```cfg title=\"haproxy.cfg\" defaults timeout connect 5s timeout client 5s timeout server 5s

frontend http_front mode http bind *:80 default_backend http_back

frontend https_front mode http bind *:443 default_backend https_back

backend http_back mode http balance roundrobin option forwardfor server worker01 192.168.10.11:80 check server worker02 192.168.10.12:80 check

backend https_back mode http balance roundrobin option forwardfor server worker01 192.168.10.11:443 check server worker02 192.168.10.12:443 check ```

Reinicia HAProxy una vez guardada la configuración:

sudo systemctl restart haproxy

Para más información, consulta la documentación oficial de HAProxy.

Configurar IP real

No olvides configurar BunkerWeb para recibir la IP real del cliente (usando PROXY protocol o la cabecera X-Forwarded-For).

Consulta la sección Detrás de un balanceador de carga o proxy inverso para asegurarte de que recibes la IP correcta del cliente.

Revisa /var/log/bunkerweb/access.log en cada worker para confirmar que las solicitudes llegan desde la red del PROXY protocol y que los dos workers comparten la carga. Tu clúster BunkerWeb ya está listo para proteger cargas de producción con alta disponibilidad.

6. IP flotante con keepalived (sin Load Balancer)

Si no tienes un Load Balancer, puedes ejecutar los workers en modo activo/pasivo con keepalived. Una IP virtual (VIP) se desplaza entre los workers mediante VRRP, el DNS apunta a la VIP y solo el worker que la posee atiende el tráfico. Es una alternativa a la sección 5: el tráfico no se reparte entre los workers, pero un worker que falla es sustituido en unos segundos.

Los ejemplos usan la VIP 192.168.10.100, worker01 (192.168.10.11, master) y worker02 (192.168.10.12, backup).

Instala keepalived en cada worker:

# Debian / Ubuntu
sudo apt install keepalived
# RHEL / Fedora
sudo dnf install keepalived

El script de comprobación de salud de BunkerWeb, llamado con el argumento ok, sale con código 0 cuando la instancia responde ok en http://127.0.0.1:6000/healthz. ok significa que NGINX está en ejecución y la instancia ha recibido su configuración, incluso mientras aplica una nueva y sigue sirviendo la anterior (desde la versión 1.6.16). El script sale con código 1 mientras la instancia siga en estado loading o NGINX esté detenido. Si se llama sin argumentos, el script también acepta loading; no uses esa forma aquí, porque un worker recién iniciado tomaría la VIP y mostraría la página «Generating...».

/usr/share/bunkerweb/helpers/healthcheck.sh ok

/usr/bin/docker compose -f /path/to/docker-compose.yml exec -T bunkerweb /usr/share/bunkerweb/helpers/healthcheck.sh ok

Configura keepalived. Crea /etc/keepalived/keepalived.conf en cada worker. Ajusta interface a la interfaz de red (consulta ip addr) y usa los mismos valores de virtual_router_id y auth_pass en ambos workers. En la pestaña Docker, sustituye la línea script por el comando docker compose anterior (keepalived avisa si el binario no se indica con su ruta completa).

/etc/keepalived/keepalived.conf
global_defs {
    enable_script_security
    script_user root
}

vrrp_script chk_bunkerweb {
    script "/usr/share/bunkerweb/helpers/healthcheck.sh ok"
    interval 2
    fall 2
    rise 2
}

vrrp_instance VI_BUNKERWEB {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 110
    advert_int 1
    authentication {
        auth_type PASS
        auth_pass changeme
    }
    virtual_ipaddress {
        192.168.10.100/24
    }
    track_script {
        chk_bunkerweb
    }
}
/etc/keepalived/keepalived.conf
global_defs {
    enable_script_security
    script_user root
}

vrrp_script chk_bunkerweb {
    script "/usr/share/bunkerweb/helpers/healthcheck.sh ok"
    interval 2
    fall 2
    rise 2
}

vrrp_instance VI_BUNKERWEB {
    state BACKUP
    interface eth0
    virtual_router_id 51
    priority 100
    advert_int 1
    authentication {
        auth_type PASS
        auth_pass changeme
    }
    virtual_ipaddress {
        192.168.10.100/24
    }
    track_script {
        chk_bunkerweb
    }
}

La comprobación no tiene weight, así que dos fallos consecutivos (unos 4 segundos) ponen el nodo en estado FAULT y liberan la VIP. script_user root es necesario para ejecutar docker compose exec. enable_script_security acepta el script porque otros usuarios no pueden modificar los archivos de BunkerWeb. La contraseña auth_pass de VRRP se transmite en texto claro y solo protege frente a errores de configuración; mantén los workers en una red de confianza.

BunkerWeb 1.6.15

En la versión 1.6.15, /healthz responde loading en todos los workers durante unos 5 segundos con cada recarga. Usa fall 4 y interval 2 en lugar de fall 2 para que una recarga no ponga ambos workers en estado FAULT.

Inicia keepalived en ambos workers:

sudo systemctl enable --now keepalived

Cortafuegos

VRRP usa el protocolo IP 112 (no es un puerto TCP ni UDP). Permítelo entre los workers, junto con los puertos 80 y 443 hacia los clientes.

IP real

Los clientes se conectan directamente a la VIP, por lo que no hace falta configurar PROXY protocol ni X-Forwarded-For. BunkerWeb ve la IP real del cliente de forma predeterminada.

Verifica la conmutación por error:

  1. En worker01, ejecuta ip addr show eth0. Debe aparecer la VIP 192.168.10.100.
  2. Detén BunkerWeb en worker01: sudo systemctl stop bunkerweb (Linux) o docker compose stop bunkerweb (Docker).
  3. Tras unos segundos, la VIP desaparece de worker01 y aparece en worker02. En nuestras pruebas, los clientes recuperaron el servicio en unos 4 segundos al detener el contenedor y en unos 7 segundos cuando solo falló la comprobación de salud.
  4. Inicia BunkerWeb de nuevo. worker01 solo recupera la VIP cuando la comprobación pasa, por lo que nunca atiende tráfico mientras está cargando.
  5. Sigue los cambios de estado con sudo journalctl -u keepalived -f.

Consideraciones

  • Sidecar de Docker. Si keepalived se ejecuta en un contenedor con network_mode: "service:bunkerweb", pierde su interfaz de red cuando se reinicia el contenedor de BunkerWeb y no vuelve a obtener la VIP. Añadir depends_on: { bunkerweb: { condition: service_started, restart: true } } al servicio keepalived solo cubre los reinicios hechos mediante Compose (docker compose restart o up). No cubre un reinicio automático por la política de reinicio de Docker (fallo, falta de memoria) ni un docker restart normal. En esos casos, reinicia juntos los contenedores de keepalived y BunkerWeb, o ejecuta keepalived en el host como en la pestaña Docker anterior.
  • Manager no disponible. Los workers que ya tienen su configuración siguen respondiendo ok y conservan la VIP. Un worker que se reinicia mientras el manager está caído permanece en estado loading y no obtiene la VIP. Si ambos se reinician, ningún worker puede asumirla y el servicio queda inactivo hasta que vuelva el manager.
  • Configuración. El manager envía la configuración a ambos workers sin importar el estado de la VIP, así que el worker de reserva ya tiene los últimos ajustes cuando toma el relevo.
  • Estado compartido. Los bloqueos, los contadores y las sesiones residen en cada worker. Un cliente bloqueado en worker01 no queda bloqueado en worker02 tras un fallo. Activa Redis (USE_REDIS=yes, consulta los ajustes de Redis/Valkey) y usa la misma instancia Redis en ambos workers para compartir bloqueos y contadores. Redis por sí solo no mantiene las sesiones válidas entre workers: SESSIONS_SECRET y SESSIONS_NAME tienen el valor random de forma predeterminada y se generan por instancia. Define valores fijos e idénticos para ambos en el manager (son ajustes globales que se envían a los dos workers).
  • Let's Encrypt. El token del desafío HTTP se envía a todas las instancias registradas en el manager, por lo que ambos workers pueden responder.

Usando mecanismos de resolución DNS personalizados

La configuración de NGINX de BunkerWeb se puede personalizar para usar diferentes resolutores de DNS según tus necesidades. Esto puede ser particularmente útil en varios escenarios:

  1. Para respetar las entradas en tu archivo local /etc/hosts
  2. Cuando necesitas usar servidores DNS personalizados para ciertos dominios
  3. Para integrarse con soluciones locales de caché de DNS

Usando systemd-resolved

Muchos sistemas Linux modernos usan systemd-resolved para la resolución de DNS. Si quieres que BunkerWeb respete el contenido de tu archivo /etc/hosts y use el mecanismo de resolución de DNS del sistema, puedes configurarlo para que use el servicio DNS local de systemd-resolved.

Para verificar que systemd-resolved se está ejecutando en tu sistema, puedes usar:

systemctl status systemd-resolved

Para habilitar systemd-resolved como tu resolutor de DNS en BunkerWeb, establece la configuración DNS_RESOLVERS a 127.0.0.53, que es la dirección de escucha predeterminada para systemd-resolved:

Navega a la página de Configuración Global y establece los resolutores de DNS en 127.0.0.53

Configuración de resolutores de DNS usando la interfaz de usuario web
Configuración de resolutores de DNS usando la interfaz de usuario web

Necesitarás modificar el archivo /etc/bunkerweb/variables.env:

...
DNS_RESOLVERS=127.0.0.53
...

Después de hacer este cambio, recarga el Programador para aplicar la configuración:

sudo systemctl reload bunkerweb-scheduler

Usando dnsmasq

dnsmasq es un servidor ligero de DNS, DHCP y TFTP que se usa comúnmente para el almacenamiento en caché y la personalización de DNS local. Es particularmente útil cuando necesitas más control sobre tu resolución de DNS del que proporciona systemd-resolved.

Primero, instala y configura dnsmasq en tu sistema Linux:

# Instalar dnsmasq
sudo apt-get update && sudo apt-get install dnsmasq

# Configurar dnsmasq para escuchar solo en localhost
echo "listen-address=127.0.0.1" | sudo tee -a /etc/dnsmasq.conf
echo "bind-interfaces" | sudo tee -a /etc/dnsmasq.conf

# Agregar entradas DNS personalizadas si es necesario
echo "address=/custom.example.com/192.168.1.10" | sudo tee -a /etc/dnsmasq.conf

# Reiniciar dnsmasq
sudo systemctl restart dnsmasq
sudo systemctl enable dnsmasq

# Instalar dnsmasq
sudo dnf install dnsmasq

# Configurar dnsmasq para escuchar solo en localhost
echo "listen-address=127.0.0.1" | sudo tee -a /etc/dnsmasq.conf
echo "bind-interfaces" | sudo tee -a /etc/dnsmasq.conf

# Agregar entradas DNS personalizadas si es necesario
echo "address=/custom.example.com/192.168.1.10" | sudo tee -a /etc/dnsmasq.conf

# Reiniciar dnsmasq
sudo systemctl restart dnsmasq
sudo systemctl enable dnsmasq

Luego configura BunkerWeb para que use dnsmasq estableciendo DNS_RESOLVERS en 127.0.0.1:

Navega a la página de Configuración Global, selecciona el plugin NGINX y establece los resolutores de DNS en 127.0.0.1.

Configuración de resolutores de DNS usando la interfaz de usuario web
Configuración de resolutores de DNS usando la interfaz de usuario web

Necesitarás modificar el archivo /etc/bunkerweb/variables.env:

...
DNS_RESOLVERS=127.0.0.1
...

Después de hacer este cambio, recarga el Programador:

sudo systemctl reload bunkerweb-scheduler

Cuando uses el contenedor Todo en uno, ejecuta dnsmasq en un contenedor separado y configura BunkerWeb para usarlo:

# Crear una red personalizada para la comunicación DNS
docker network create bw-dns

# Ejecutar el contenedor dnsmasq usando dockurr/dnsmasq con Quad9 DNS
# Quad9 proporciona resolución de DNS centrada en la seguridad con bloqueo de malware
docker run -d \
    --name dnsmasq \
    --network bw-dns \
    -e DNS1="9.9.9.9" \
    -e DNS2="149.112.112.112" \
    -p 53:53/udp \
    -p 53:53/tcp \
    --cap-add=NET_ADMIN \
    --restart=always \
    dockurr/dnsmasq

# Ejecutar BunkerWeb Todo en uno con el resolutor de DNS dnsmasq
docker run -d \
    --name bunkerweb-aio \
    --network bw-dns \
    -v bw-storage:/data \
    -e DNS_RESOLVERS="dnsmasq" \
    -p 80:8080/tcp \
    -p 443:8443/tcp \
    -p 443:8443/udp \
    bunkerity/bunkerweb-all-in-one:1.6.18-rc1

Agrega un servicio dnsmasq a tu archivo docker-compose y configura BunkerWeb para usarlo:

services:
  dnsmasq:
    image: dockurr/dnsmasq
    container_name: dnsmasq
    environment:
      # Usando los servidores DNS de Quad9 para mayor seguridad y privacidad
      # Primario: 9.9.9.9 (Quad9 con bloqueo de malware)
      # Secundario: 149.112.112.112 (Servidor de respaldo de Quad9)
      DNS1: "9.9.9.9"
      DNS2: "149.112.112.112"
    ports:
      - 53:53/udp
      - 53:53/tcp
    cap_add:
      - NET_ADMIN
    restart: always
    networks:
      - bw-dns

  bunkerweb:
    image: bunkerity/bunkerweb:1.6.18-rc1
    ...
    environment:
      DNS_RESOLVERS: "dnsmasq"
    ...
    networks:
      - bw-universe
      - bw-services
      - bw-dns

  bw-scheduler:
    image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
    ...
    environment:
      DNS_RESOLVERS: "dnsmasq"
    ...
    networks:
      - bw-universe
      - bw-dns

networks:
  # ...redes existentes...
  bw-dns:
    name: bw-dns

Configuraciones personalizadas

Para personalizar y añadir configuraciones personalizadas a BunkerWeb, puedes aprovechar su base NGINX. Las configuraciones personalizadas de NGINX se pueden añadir en diferentes contextos de NGINX, incluidas las configuraciones para el Firewall de Aplicaciones Web (WAF) ModSecurity, que es un componente central de BunkerWeb. Se pueden encontrar más detalles sobre las configuraciones de ModSecurity aquí.

Estos son los tipos de configuraciones personalizadas disponibles:

  • http: Configuraciones a nivel HTTP de NGINX.
  • server-http: Configuraciones a nivel HTTP/Servidor de NGINX.
  • default-server-http: Configuraciones a nivel de Servidor de NGINX, específicamente para el "servidor predeterminado" cuando el nombre del cliente proporcionado no coincide con ningún nombre de servidor en SERVER_NAME.
  • modsec-crs: Configuraciones aplicadas antes de que se cargue el Core Rule Set de OWASP.
  • modsec: Configuraciones aplicadas después de que se cargue el Core Rule Set de OWASP, o se utilizan cuando el Core Rule Set no está cargado.
  • crs-plugins-before: Configuraciones para los plugins CRS, aplicadas antes de que se carguen los plugins CRS.
  • crs-plugins-after: Configuraciones para los plugins CRS, aplicadas después de que se carguen los plugins CRS.
  • stream: Configuraciones a nivel de Stream de NGINX.
  • server-stream: Configuraciones a nivel de Stream/Servidor de NGINX.

Las configuraciones personalizadas se pueden aplicar globalmente o específicamente para un servidor en particular, dependiendo del contexto aplicable y de si el modo multisitio está habilitado.

El método para aplicar configuraciones personalizadas depende de la integración que se esté utilizando. Sin embargo, el proceso subyacente implica añadir archivos con el sufijo .conf a carpetas específicas. Para aplicar una configuración personalizada para un servidor específico, el archivo debe colocarse en una subcarpeta con el nombre del servidor principal.

Algunas integraciones proporcionan formas más convenientes de aplicar configuraciones, como el uso de Configs en Docker Swarm o ConfigMap en Kubernetes. Estas opciones ofrecen enfoques más sencillos para gestionar y aplicar configuraciones.

Navega a la página de Configuraciones, haz clic en Crear nueva configuración personalizada, luego puedes elegir si es global o específica para un servicio, el tipo de configuración y el nombre de la configuración:

Configuraciones personalizadas usando la interfaz de usuario web
Configuraciones personalizadas usando la interfaz de usuario web

No olvides hacer clic en el botón 💾 Guardar.

Cuando se utiliza la integración de Linux, las configuraciones personalizadas deben escribirse en la carpeta /etc/bunkerweb/configs.

Aquí hay un ejemplo para server-http/hello-world.conf:

location /hello {
  default_type 'text/plain';
  content_by_lua_block {
    ngx.say('world')
  }
}

Debido a que BunkerWeb se ejecuta como un usuario sin privilegios (nginx:nginx), necesitarás editar los permisos:

chown -R root:nginx /etc/bunkerweb/configs && \
chmod -R 770 /etc/bunkerweb/configs

Ahora verifiquemos el estado del Programador:

systemctl status bunkerweb-scheduler

Si ya se está ejecutando, podemos recargarlo:

systemctl reload bunkerweb-scheduler

De lo contrario, tendremos que iniciarlo:

systemctl start bunkerweb-scheduler

La recarga vuelve a leer la carpeta

Una recarga vuelve a leer /etc/bunkerweb/configs: los archivos creados, modificados o eliminados allí se aplican y se guardan en la base de datos. Una configuración que pertenece a la interfaz web o a la API conserva su propietario, solo su contenido se actualiza desde el archivo.

Cuando se utiliza la imagen Todo en uno, tienes dos opciones para añadir configuraciones personalizadas:

  • Usar configuraciones específicas *_CUSTOM_CONF_* como variables de entorno al ejecutar el contenedor (recomendado).
  • Escribir archivos .conf en el directorio /data/configs/ dentro del volumen montado en /data.

Usando configuraciones (Variables de Entorno)

Las configuraciones a usar deben seguir el patrón <SITE>_CUSTOM_CONF_<TYPE>_<NAME>:

  • <SITE> : Nombre del servidor principal opcional si el modo multisitio está habilitado y la configuración debe aplicarse a un servicio específico.
  • <TYPE> : El tipo de configuración, los valores aceptados son HTTP, DEFAULT_SERVER_HTTP, SERVER_HTTP, MODSEC, MODSEC_CRS, CRS_PLUGINS_BEFORE, CRS_PLUGINS_AFTER, STREAM y SERVER_STREAM.
  • <NAME> : El nombre de la configuración sin el sufijo .conf.

Aquí hay un ejemplo de prueba al ejecutar el contenedor Todo en uno:

docker run -d \
    --name bunkerweb-aio \
    -v bw-storage:/data \
    -e "CUSTOM_CONF_SERVER_HTTP_hello-world=location /hello { \
        default_type 'text/plain'; \
        content_by_lua_block { \
          ngx.say('world'); \
        } \
      }" \
    -p 80:8080/tcp \
    -p 443:8443/tcp \
    bunkerity/bunkerweb-all-in-one:1.6.18-rc1

Ten en cuenta que si tu contenedor ya está creado, necesitarás eliminarlo y recrearlo para que se apliquen las nuevas variables de entorno.

Usando archivos

Lo primero que hay que hacer es crear las carpetas:

mkdir -p ./bw-data/configs/server-http

Ahora puedes escribir tus configuraciones:

echo "location /hello {
  default_type 'text/plain';
  content_by_lua_block {
    ngx.say('world')
  }
}" > ./bw-data/configs/server-http/hello-world.conf

Debido a que el programador se ejecuta como un usuario sin privilegios con UID y GID 101, necesitarás editar los permisos:

chown -R root:101 bw-data && \
chmod -R 770 bw-data

Al iniciar el contenedor del programador, necesitarás montar la carpeta en /data:

docker run -d \
    --name bunkerweb-aio \
    -v ./bw-data:/data \
    -p 80:8080/tcp \
    -p 443:8443/tcp \
    -p 443:8443/udp \
    bunkerity/bunkerweb-all-in-one:1.6.18-rc1

Cuando se utiliza la integración de Docker, tienes dos opciones para añadir configuraciones personalizadas:

  • Usar configuraciones específicas *_CUSTOM_CONF_* como variables de entorno (recomendado)
  • Escribir archivos .conf en el volumen montado en /data del programador

Usando configuraciones

Las configuraciones a usar deben seguir el patrón <SITE>_CUSTOM_CONF_<TYPE>_<NAME>:

  • <SITE>: nombre del servidor principal opcional si el modo multisitio está habilitado y la configuración debe aplicarse a un servicio específico
  • <TYPE>: el tipo de configuración, los valores aceptados son HTTP, DEFAULT_SERVER_HTTP, SERVER_HTTP, MODSEC, MODSEC_CRS, CRS_PLUGINS_BEFORE, CRS_PLUGINS_AFTER, STREAM y SERVER_STREAM
  • <NAME>: el nombre de la configuración sin el sufijo .conf

Aquí hay un ejemplo de prueba usando un archivo docker-compose:

...
bw-scheduler:
  image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
  environment:
    - |
      CUSTOM_CONF_SERVER_HTTP_hello-world=
      location /hello {
        default_type 'text/plain';
        content_by_lua_block {
          ngx.say('world')
        }
      }
  ...

Usando archivos

Lo primero que hay que hacer es crear las carpetas:

mkdir -p ./bw-data/configs/server-http

Ahora puedes escribir tus configuraciones:

echo "location /hello {
  default_type 'text/plain';
  content_by_lua_block {
    ngx.say('world')
  }
}" > ./bw-data/configs/server-http/hello-world.conf

Debido a que el programador se ejecuta como un usuario sin privilegios con UID y GID 101, necesitarás editar los permisos:

chown -R root:101 bw-data && \
chmod -R 770 bw-data

Al iniciar el contenedor del programador, necesitarás montar la carpeta en /data:

bw-scheduler:
  image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
  volumes:
    - ./bw-data:/data
  ...

Cuando se utiliza la integración de autoconfiguración de Docker, tienes dos opciones para añadir configuraciones personalizadas:

  • Usar configuraciones específicas *_CUSTOM_CONF_* como etiquetas (más fácil)
  • Escribir archivos .conf en el volumen montado en /data del programador

Usando etiquetas

Limitaciones al usar etiquetas

Cuando usas etiquetas con la integración de autoconfiguración de Docker, solo puedes aplicar configuraciones personalizadas para el servicio web correspondiente. No es posible aplicar configuraciones http, default-server-http, stream o cualquier ajuste global (como server-http o server-stream para todos los servicios): necesitarás montar archivos para ese propósito.

Las etiquetas a usar deben seguir el patrón bunkerweb.CUSTOM_CONF_<TYPE>_<NAME>:

  • <TYPE>: el tipo de configuración, los valores aceptados son SERVER_HTTP, MODSEC, MODSEC_CRS, CRS_PLUGINS_BEFORE, CRS_PLUGINS_AFTER y SERVER_STREAM
  • <NAME>: el nombre de la configuración sin el sufijo .conf

Aquí hay un ejemplo de prueba usando un archivo docker-compose:

myapp:
  image: bunkerity/bunkerweb-hello:v1.0
  labels:
    - |
      bunkerweb.CUSTOM_CONF_SERVER_HTTP_hello-world=
      location /hello {
        default_type 'text/plain';
        content_by_lua_block {
            ngx.say('world')
        }
      }
  ...

Usando archivos

Lo primero que hay que hacer es crear las carpetas:

mkdir -p ./bw-data/configs/server-http

Ahora puedes escribir tus configuraciones:

echo "location /hello {
  default_type 'text/plain';
  content_by_lua_block {
    ngx.say('world')
  }
}" > ./bw-data/configs/server-http/hello-world.conf

Debido a que el programador se ejecuta como un usuario sin privilegios con UID y GID 101, necesitarás editar los permisos:

chown -R root:101 bw-data && \
chmod -R 770 bw-data

Al iniciar el contenedor del programador, necesitarás montar la carpeta en /data:

bw-scheduler:
  image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
  volumes:
    - ./bw-data:/data
  ...

Cuando se utiliza la integración de Kubernetes, las configuraciones personalizadas se gestionan mediante ConfigMap.

No es necesario montar la ConfigMap en un Pod (por ejemplo, como variable de entorno o volumen). El pod de autoconfiguración escucha los eventos de ConfigMap y aplica los cambios en cuanto se detectan.

Anota cada ConfigMap que deba gestionar el controlador de Ingress:

  • bunkerweb.io/CONFIG_TYPE: obligatorio. Elige uno de los tipos compatibles (http, server-http, default-server-http, modsec, modsec-crs, crs-plugins-before, crs-plugins-after, stream, server-stream o settings).
  • bunkerweb.io/CONFIG_SITE: opcional. Establece el nombre del servidor principal (tal como se publica a través del Ingress) para limitar la configuración a ese servicio; déjalo vacío para aplicarla globalmente.

Aquí está el ejemplo:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cfg-bunkerweb-all-server-http
  annotations:
    bunkerweb.io/CONFIG_TYPE: "server-http"
data:
  myconf: |
  location /hello {
    default_type 'text/plain';
    content_by_lua_block {
      ngx.say('world')
    }
  }

Cómo funciona la reconciliación

  • El controlador de Ingress vigila continuamente las ConfigMap anotadas.
  • Si la variable de entorno NAMESPACES está definida, solo se tienen en cuenta las ConfigMap de esos espacios de nombres.
  • Crear o actualizar una ConfigMap gestionada provoca la recarga inmediata de la configuración.
  • Eliminar la ConfigMap, o quitar la anotación bunkerweb.io/CONFIG_TYPE, elimina la configuración personalizada asociada.
  • Si defines bunkerweb.io/CONFIG_SITE, el servicio referenciado debe existir previamente; de lo contrario, la ConfigMap se ignora hasta que aparezca el servicio.

Configuración extra personalizada

Desde la versión 1.6.0, puedes añadir o sobrescribir parámetros anotando una ConfigMap con bunkerweb.io/CONFIG_TYPE=settings. El controlador de Ingress de autoconf lee cada entrada de data y la aplica como si fuera una variable de entorno:

  • Sin bunkerweb.io/CONFIG_SITE, todas las claves se aplican globalmente.
  • Cuando bunkerweb.io/CONFIG_SITE está definido, el controlador añade automáticamente el prefijo <nombre-del-servidor>_ (cada / se sustituye por _) a las claves que aún no están acotadas. Añade el prefijo manualmente si necesitas mezclar claves globales y específicas en la misma ConfigMap.
  • Los nombres o valores no válidos se omiten y el controlador autoconf registra una advertencia.

Aquí hay un ejemplo:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cfg-bunkerweb-extra-settings
  annotations:
    bunkerweb.io/CONFIG_TYPE: "settings"
data:
  USE_ANTIBOT: "captcha" # configuración multisitio que se aplicará a todos los servicios que no la sobrescriban
  USE_REDIS: "yes" # ajuste global que se aplicará globalmente
  ...

Obsoleto

La integración de Swarm está obsoleta y se eliminará en una futura versión. Por favor, considera usar la integración de Kubernetes en su lugar.

Puedes encontrar más información en la documentación de la integración de Swarm.

Cuando se utiliza la integración de Swarm, las configuraciones personalizadas se gestionan mediante Docker Configs.

Para mantenerlo simple, ni siquiera necesitas adjuntar la Configuración a un servicio: el servicio de autoconfiguración está escuchando los eventos de Configuración y actualizará las configuraciones personalizadas cuando sea necesario.

Al crear una Configuración, necesitarás añadir etiquetas especiales:

  • bunkerweb.CONFIG_TYPE: debe establecerse a un tipo de configuración personalizada válido (http, server-http, default-server-http, modsec, modsec-crs, crs-plugins-before, crs-plugins-after, stream, server-stream o settings)
  • bunkerweb.CONFIG_SITE: establece un nombre de servidor para aplicar la configuración a ese servidor específico (opcional, se aplicará globalmente si no se establece)

Aquí está el ejemplo:

echo "location /hello {
  default_type 'text/plain';
  content_by_lua_block {
    ngx.say('world')
  }
}" | docker config create -l bunkerweb.CONFIG_TYPE=server-http my-config -

No hay mecanismo de actualización: la alternativa es eliminar una configuración existente usando docker config rm y luego recrearla.

Ejecutando muchos servicios en producción

CRS Global

Plugins CRS

Cuando el CRS se carga globalmente, los plugins CRS no son compatibles. Si necesitas usarlos, tendrás que cargar el CRS por servicio.

Si usas BunkerWeb en producción con un gran número de servicios y habilitas la característica de ModSecurity globalmente con las reglas CRS, el tiempo requerido para cargar las configuraciones de BunkerWeb puede volverse demasiado largo, resultando potencialmente en un tiempo de espera agotado.

La solución es cargar las reglas CRS globalmente en lugar de por servicio. Este comportamiento no está habilitado por defecto por razones de compatibilidad con versiones anteriores y porque tiene un inconveniente: si habilitas la carga global de reglas CRS, ya no será posible definir reglas modsec-crs (ejecutadas antes de las reglas CRS) por servicio. Sin embargo, esta limitación puede ser superada escribiendo reglas de exclusión globales modsec-crs como esta:

SecRule REQUEST_FILENAME "@rx ^/somewhere$" "nolog,phase:4,allow,id:1010,chain"
SecRule REQUEST_HEADERS:Host "@rx ^app1\.example\.com$" "nolog"

Puedes habilitar la carga global de CRS estableciendo USE_MODSECURITY_GLOBAL_CRS en yes.

Ajustar max_allowed_packet para MariaDB/MySQL

Parece que el valor predeterminado para el parámetro max_allowed_packet en los servidores de bases de datos MariaDB y MySQL no es suficiente cuando se utiliza BunkerWeb con un gran número de servicios.

Si encuentras errores como este, especialmente en el programador:

[Warning] Aborted connection 5 to db: 'db' user: 'bunkerweb' host: '172.20.0.4' (Got a packet bigger than 'max_allowed_packet' bytes)

Necesitarás aumentar el max_allowed_packet en tu servidor de base de datos.

El valor recomendado es 67108864 bytes (64 MiB). Cuando la base de datos se ejecuta en un contenedor, configúralo mediante la directiva command::

bw-db:
    image: mariadb:11
    command: --max-allowed-packet=67108864
    ...

Para una base de datos instalada localmente o externa, añade en su lugar el parámetro a la configuración del servidor (por ejemplo, un archivo dedicado en /etc/mysql/mariadb.conf.d/ o /etc/my.cnf.d/):

[mysqld]
max_allowed_packet = 64M

Persistencia de bloqueos e informes

Por defecto, BunkerWeb almacena los bloqueos e informes en un almacén de datos Lua local. Aunque es simple y eficiente, esta configuración significa que los datos se pierden cuando se reinicia la instancia. Para asegurar que los bloqueos e informes persistan a través de los reinicios, puedes configurar BunkerWeb para que utilice un servidor remoto Redis o Valkey.

¿Por qué usar Redis/Valkey?

Redis y Valkey son potentes almacenes de datos en memoria comúnmente utilizados como bases de datos, cachés y agentes de mensajes. Son altamente escalables y soportan una variedad de estructuras de datos, incluyendo:

  • Strings: Pares básicos de clave-valor.
  • Hashes: Pares de campo-valor dentro de una sola clave.
  • Lists: Colecciones ordenadas de cadenas.
  • Sets: Colecciones no ordenadas de cadenas únicas.
  • Sorted Sets: Colecciones ordenadas con puntuaciones.

Al aprovechar Redis o Valkey, BunkerWeb puede almacenar persistentemente bloqueos, informes y datos de caché, asegurando durabilidad y escalabilidad.

Habilitando el soporte de Redis/Valkey

Para habilitar el soporte de Redis o Valkey, configura los siguientes ajustes en tu archivo de configuración de BunkerWeb:

# Habilitar el soporte de Redis/Valkey
USE_REDIS=yes

# Nombre de host o dirección IP del servidor Redis/Valkey
REDIS_HOST=<hostname>

# Número de puerto del servidor Redis/Valkey (predeterminado: 6379)
REDIS_PORT=6379

# Número de base de datos de Redis/Valkey (predeterminado: 0)
REDIS_DATABASE=0
  • USE_REDIS: Establécelo en yes para habilitar la integración con Redis/Valkey.
  • REDIS_HOST: Especifica el nombre de host o la dirección IP del servidor Redis/Valkey.
  • REDIS_PORT: Especifica el número de puerto para el servidor Redis/Valkey. El valor predeterminado es 6379.
  • REDIS_DATABASE: Especifica el número de la base de datos de Redis/Valkey a utilizar. El valor predeterminado es 0.

Si necesitas configuraciones más avanzadas, como autenticación, soporte SSL/TLS o modo Sentinel, consulta la documentación de configuración del plugin de Redis para obtener una guía detallada.

Proteger aplicaciones UDP/TCP

Característica experimental

Esta característica no está lista para producción. Siéntete libre de probarla y reportarnos cualquier error usando los issues en el repositorio de GitHub.

BunkerWeb ofrece la capacidad de funcionar como un proxy inverso genérico UDP/TCP, permitiéndote proteger cualquier aplicación basada en red que opere al menos en la capa 4 del modelo OSI. En lugar de utilizar el módulo HTTP "clásico", BunkerWeb aprovecha el módulo stream de NGINX.

Es importante tener en cuenta que no todas las configuraciones y características de seguridad están disponibles cuando se utiliza el módulo stream. Puedes encontrar información adicional sobre esto en las secciones de características de la documentación.

Configurar un proxy inverso básico es bastante similar a la configuración HTTP, ya que implica usar las mismas configuraciones: USE_REVERSE_PROXY=yes y REVERSE_PROXY_HOST=myapp:9000. Incluso cuando BunkerWeb está posicionado detrás de un Balanceador de Carga, las configuraciones siguen siendo las mismas (siendo el protocolo PROXY la opción soportada por razones evidentes).

Además de eso, se utilizan las siguientes configuraciones específicas:

  • SERVER_TYPE=stream: activa el modo stream (UDP/TCP genérico) en lugar del http (que es el predeterminado)
  • LISTEN_STREAM_PORT=4242: el puerto de escucha "plano" (sin SSL/TLS) en el que BunkerWeb escuchará
  • LISTEN_STREAM_PORT_SSL=4343: el puerto de escucha "ssl/tls" en el que BunkerWeb escuchará
  • USE_UDP=no: escucha y reenvía paquetes UDP en lugar de TCP

Para obtener una lista completa de las configuraciones relacionadas con el modo stream, consulta la sección de características de la documentación.

múltiples puertos de escucha

Desde la versión 1.6.0, BunkerWeb soporta múltiples puertos de escucha para el modo stream. Puedes especificarlos usando las configuraciones LISTEN_STREAM_PORT y LISTEN_STREAM_PORT_SSL.

Aquí hay un ejemplo:

...
LISTEN_STREAM_PORT=4242
LISTEN_STREAM_PORT_SSL=4343
LISTEN_STREAM_PORT_1=4244
LISTEN_STREAM_PORT_SSL_1=4344
...

Necesitarás agregar la configuración a las variables de entorno al ejecutar el contenedor Todo en uno. También necesitarás exponer los puertos de stream.

Este ejemplo configura BunkerWeb para hacer proxy de dos aplicaciones basadas en stream, app1.example.com y app2.example.com.

docker run -d \
    --name bunkerweb-aio \
    -v bw-storage:/data \
    -e SERVICE_UI="no" \
    -e SERVER_NAME="app1.example.com app2.example.com" \
    -e MULTISITE="yes" \
    -e USE_REVERSE_PROXY="yes" \
    -e SERVER_TYPE="stream" \
    -e app1.example.com_REVERSE_PROXY_HOST="myapp1:9000" \
    -e app1.example.com_LISTEN_STREAM_PORT="10000" \
    -e app2.example.com_REVERSE_PROXY_HOST="myapp2:9000" \
    -e app2.example.com_LISTEN_STREAM_PORT="20000" \
    -p 80:8080/tcp \
    -p 443:8443/tcp \
    -p 443:8443/udp \
    -p 10000:10000/tcp \
    -p 20000:20000/tcp \
    bunkerity/bunkerweb-all-in-one:1.6.18-rc1

Ten en cuenta que si tu contenedor ya está creado, necesitarás eliminarlo y recrearlo para que se apliquen las nuevas variables de entorno.

Tus aplicaciones (myapp1, myapp2) deberían estar ejecutándose en contenedores separados (o ser accesibles de otra manera) y sus nombres de host/IPs (p. ej., myapp1, myapp2 usados en _REVERSE_PROXY_HOST) deben ser resolvibles y alcanzables desde el contenedor bunkerweb-aio. Esto típicamente implica conectarlos a una red Docker compartida.

Desactivar el servicio de la interfaz de usuario

Se recomienda desactivar el servicio de la interfaz de usuario (p. ej., estableciendo SERVICE_UI=no como una variable de entorno) ya que la interfaz de usuario web no es compatible con SERVER_TYPE=stream.

Cuando se utiliza la integración con Docker, la forma más fácil de proteger las aplicaciones de red existentes es agregar los servicios a la red bw-services:

x-bw-api-env: &bw-api-env
  # Usamos un ancla para evitar repetir la misma configuración para todos los servicios
  API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24"
  # Token de API opcional para llamadas de API autenticadas
  API_TOKEN: ""

services:
  bunkerweb:
    image: bunkerity/bunkerweb:1.6.18-rc1
    ports:
      - "80:8080" # Mantenlo si quieres usar la automatización de Let's Encrypt al usar el tipo de desafío http
      - "10000:10000" # app1
      - "20000:20000" # app2
    labels:
      - "bunkerweb.INSTANCE=yes"
    environment:
      <<: *bw-api-env
    restart: "unless-stopped"
    networks:
      - bw-universe
      - bw-services

  bw-scheduler:
    image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
    environment:
      <<: *bw-api-env
      BUNKERWEB_INSTANCES: "bunkerweb" # Esta configuración es obligatoria para especificar la instancia de BunkerWeb
      SERVER_NAME: "app1.example.com app2.example.com"
      MULTISITE: "yes"
      USE_REVERSE_PROXY: "yes" # Se aplicará a todos los servicios
      SERVER_TYPE: "stream" # Se aplicará a todos los servicios
      app1.example.com_REVERSE_PROXY_HOST: "myapp1:9000"
      app1.example.com_LISTEN_STREAM_PORT: "10000"
      app2.example.com_REVERSE_PROXY_HOST: "myapp2:9000"
      app2.example.com_LISTEN_STREAM_PORT: "20000"
    volumes:
      - bw-storage:/data # Esto se usa para persistir la caché y otros datos como las copias de seguridad
    restart: "unless-stopped"
    networks:
      - bw-universe

  myapp1:
    image: istio/tcp-echo-server:1.3
    command: [ "9000", "app1" ]
    networks:
      - bw-services

  myapp2:
    image: istio/tcp-echo-server:1.3
    command: [ "9000", "app2" ]
    networks:
      - bw-services

volumes:
  bw-storage:

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

Antes de ejecutar el stack de integración Docker autoconf en tu máquina, necesitarás editar los puertos:

services:
  bunkerweb:
    image: bunkerity/bunkerweb:1.6.18-rc1
    ports:
      - "80:8080" # Mantenlo si quieres usar la automatización de Let's Encrypt cuando usas el tipo de desafío http
      - "10000:10000" # app1
      - "20000:20000" # app2
...

Una vez que el stack esté en ejecución, puedes conectar tus aplicaciones existentes a la red bw-services y configurar BunkerWeb con etiquetas:

services:
  myapp1:
    image: istio/tcp-echo-server:1.3
    command: [ "9000", "app1" ]
    networks:
      - bw-services
    labels:
      - "bunkerweb.SERVER_NAME=app1.example.com"
      - "bunkerweb.SERVER_TYPE=stream"
      - "bunkerweb.USE_REVERSE_PROXY=yes"
      - "bunkerweb.REVERSE_PROXY_HOST=myapp1:9000"
      - "bunkerweb.LISTEN_STREAM_PORT=10000"

  myapp2:
    image: istio/tcp-echo-server:1.3
    command: [ "9000", "app2" ]
    networks:
      - bw-services
    labels:
      - "bunkerweb.SERVER_NAME=app2.example.com"
      - "bunkerweb.SERVER_TYPE=stream"
      - "bunkerweb.USE_REVERSE_PROXY=yes"
      - "bunkerweb.REVERSE_PROXY_HOST=myapp2:9000"
      - "bunkerweb.LISTEN_STREAM_PORT=20000"

networks:
  bw-services:
    external: true
    name: bw-services

Característica experimental

Por el momento, los Ingresses no soportan el modo stream. Lo que estamos haciendo aquí es una solución alternativa para que funcione.

Siéntete libre de probarlo y reportarnos cualquier error usando los issues en el repositorio de GitHub.

Antes de ejecutar el stack de la integración de Kubernetes en tu máquina, necesitarás abrir los puertos en tu balanceador de carga:

apiVersion: v1
kind: Service
metadata:
  name: lb
spec:
  type: LoadBalancer
  ports:
    - name: http # Mantenlo si quieres usar la automatización de Let's Encrypt cuando usas el tipo de desafío http
      port: 80
      targetPort: 8080
    - name: app1
      port: 10000
      targetPort: 10000
    - name: app2
      port: 20000
      targetPort: 20000
  selector:
    app: bunkerweb

Una vez que el stack esté en ejecución, puedes crear tus recursos de ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress
  namespace: services
  annotations:
    bunkerweb.io/SERVER_TYPE: "stream" # Se aplicará a todos los servicios
    bunkerweb.io/app1.example.com_LISTEN_STREAM_PORT: "10000"
    bunkerweb.io/app2.example.com_LISTEN_STREAM_PORT: "20000"
spec:
  rules:
    - host: app1.example.com
      http:
        paths:
          - path: / # Esto no se usa en modo stream pero es obligatorio
            pathType: Prefix
            backend:
              service:
                name: svc-app1
                port:
                  number: 9000
    - host: app2.example.com
      http:
        paths:
          - path: / # Esto no se usa en modo stream pero es obligatorio
            pathType: Prefix
            backend:
              service:
                name: svc-app2
                port:
                  number: 9000
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app1
  namespace: services
  labels:
    app: app1
spec:
  replicas: 1
  selector:
    matchLabels:
      app: app1
  template:
    metadata:
      labels:
        app: app1
    spec:
      containers:
        - name: app1
          image: istio/tcp-echo-server:1.3
          args: ["9000", "app1"]
          ports:
            - containerPort: 9000
---
apiVersion: v1
kind: Service
metadata:
  name: svc-app1
  namespace: services
spec:
  selector:
    app: app1
  ports:
    - protocol: TCP
      port: 9000
      targetPort: 9000
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app2
  namespace: services
  labels:
    app: app2
spec:
  replicas: 1
  selector:
    matchLabels:
      app: app2
  template:
    metadata:
      labels:
        app: app2
    spec:
      containers:
        - name: app2
          image: istio/tcp-echo-server:1.3
          args: ["9000", "app2"]
          ports:
            - containerPort: 9000
---
apiVersion: v1
kind: Service
metadata:
  name: svc-app2
  namespace: services
spec:
  selector:
    app: app2
  ports:
    - protocol: TCP
      port: 9000
      targetPort: 9000

Necesitarás agregar la configuración al archivo /etc/bunkerweb/variables.env:

...
SERVER_NAME=app1.example.com app2.example.com
MULTISITE=yes
USE_REVERSE_PROXY=yes
SERVER_TYPE=stream
app1.example.com_REVERSE_PROXY_HOST=myapp1.domain.or.ip:9000
app1.example.com_LISTEN_STREAM_PORT=10000
app2.example.com_REVERSE_PROXY_HOST=myapp2.domain.or.ip:9000
app2.example.com_LISTEN_STREAM_PORT=20000
...

Ahora verifiquemos el estado del Programador:

systemctl status bunkerweb-scheduler

Si ya se está ejecutando, podemos recargarlo:

systemctl reload bunkerweb-scheduler

De lo contrario, tendremos que iniciarlo:

systemctl start bunkerweb-scheduler

Obsoleto

La integración de Swarm está obsoleta y se eliminará en una futura versión. Por favor, considera usar la integración de Kubernetes en su lugar.

Puedes encontrar más información en la documentación de la integración de Swarm.

Antes de ejecutar el stack de integración de Swarm en tu máquina, necesitarás editar los puertos:

services:
  bunkerweb:
    image: bunkerity/bunkerweb:1.6.18-rc1
    ports:
      # Mantenlo si quieres usar la automatización de Let's Encrypt cuando usas el tipo de desafío http
      - published: 80
        target: 8080
        mode: host
        protocol: tcp
      # app1
      - published: 10000
        target: 10000
        mode: host
        protocol: tcp
      # app2
      - published: 20000
        target: 20000
        mode: host
        protocol: tcp
...

Una vez que el stack esté en ejecución, puedes conectar tus aplicaciones existentes a la red bw-services y configurar BunkerWeb con etiquetas:

services:

  myapp1:
    image: istio/tcp-echo-server:1.3
    command: [ "9000", "app1" ]
    networks:
      - bw-services
    deploy:
      placement:
        constraints:
          - "node.role==worker"
      labels:
        - "bunkerweb.SERVER_NAME=app1.example.com"
        - "bunkerweb.SERVER_TYPE=stream"
        - "bunkerweb.USE_REVERSE_PROXY=yes"
        - "bunkerweb.REVERSE_PROXY_HOST=myapp1:9000"
        - "bunkerweb.LISTEN_STREAM_PORT=10000"

  myapp2:
    image: istio/tcp-echo-server:1.3
    command: [ "9000", "app2" ]
    networks:
      - bw-services
    deploy:
      placement:
        constraints:
          - "node.role==worker"
      labels:
        - "bunkerweb.SERVER_NAME=app2.example.com"
        - "bunkerweb.SERVER_TYPE=stream"
        - "bunkerweb.USE_REVERSE_PROXY=yes"
        - "bunkerweb.REVERSE_PROXY_HOST=myapp2:9000"
        - "bunkerweb.LISTEN_STREAM_PORT=20000"

networks:
  bw-services:
    external: true
    name: bw-services

PHP

Característica experimental

Por el momento, el soporte de PHP con BunkerWeb todavía está en beta y te recomendamos que utilices una arquitectura de proxy inverso si puedes. Por cierto, PHP no es compatible en absoluto con algunas integraciones como Kubernetes.

BunkerWeb soporta PHP usando instancias externas o remotas de PHP-FPM. Asumiremos que ya estás familiarizado con la gestión de este tipo de servicios.

Se pueden usar las siguientes configuraciones:

  • REMOTE_PHP: Nombre de host de la instancia remota de PHP-FPM.
  • REMOTE_PHP_PATH: Carpeta raíz que contiene los archivos en la instancia remota de PHP-FPM.
  • REMOTE_PHP_PORT: Puerto de la instancia remota de PHP-FPM (el predeterminado es 9000).
  • LOCAL_PHP: Ruta al archivo de socket local de la instancia de PHP-FPM.
  • LOCAL_PHP_PATH: Carpeta raíz que contiene los archivos en la instancia local de PHP-FPM.

Cuando se utiliza la imagen Todo en uno, para soportar aplicaciones PHP, necesitarás:

  • Montar tus archivos PHP en la carpeta /var/www/html de BunkerWeb.
  • Configurar un contenedor PHP-FPM para tu aplicación y montar la carpeta que contiene los archivos PHP.
  • Usar las configuraciones específicas REMOTE_PHP y REMOTE_PHP_PATH como variables de entorno al ejecutar BunkerWeb.

Si habilitas el modo multisitio, necesitarás crear directorios separados para cada una de tus aplicaciones. Cada subdirectorio debe nombrarse usando el primer valor de SERVER_NAME. Aquí hay un ejemplo de prueba:

www
├── app1.example.com
│   └── index.php
└── app2.example.com
    └── index.php

2 directorios, 2 archivos

Asumiremos que tus aplicaciones PHP están ubicadas en una carpeta llamada www. Ten en cuenta que necesitarás corregir los permisos para que BunkerWeb (UID/GID 101) pueda al menos leer archivos y listar carpetas, y que PHP-FPM (UID/GID 33 si usas la imagen php:fpm) sea el propietario de los archivos y carpetas:

chown -R 33:101 ./www && \
find ./www -type f -exec chmod 0640 {} \; && \
find ./www -type d -exec chmod 0750 {} \;

Ahora puedes ejecutar BunkerWeb, configurarlo para tu aplicación PHP y también ejecutar las aplicaciones PHP. Necesitarás crear una red Docker personalizada para permitir que BunkerWeb se comunique con tus contenedores PHP-FPM.

# Crear una red personalizada
docker network create php-network

# Ejecutar contenedores PHP-FPM
docker run -d --name myapp1-php --network php-network -v ./www/app1.example.com:/app php:fpm
docker run -d --name myapp2-php --network php-network -v ./www/app2.example.com:/app php:fpm

# Ejecutar BunkerWeb Todo en uno
docker run -d \
    --name bunkerweb-aio \
    --network php-network \
    -v ./www:/var/www/html \
    -v bw-storage:/data \
    -e SERVER_NAME="app1.example.com app2.example.com" \
    -e MULTISITE="yes" \
    -e REMOTE_PHP_PATH="/app" \
    -e app1.example.com_REMOTE_PHP="myapp1-php" \
    -e app2.example.com_REMOTE_PHP="myapp2-php" \
    -p 80:8080/tcp \
    -p 443:8443/tcp \
    -p 443:8443/udp \
    bunkerity/bunkerweb-all-in-one:1.6.18-rc1

Ten en cuenta que si tu contenedor ya está creado, necesitarás eliminarlo y recrearlo para que se apliquen las nuevas variables de entorno.

Cuando se utiliza la integración de Docker, para admitir aplicaciones PHP, necesitarás:

  • Montar tus archivos PHP en la carpeta /var/www/html de BunkerWeb
  • Configurar un contenedor PHP-FPM para tu aplicación y montar la carpeta que contiene los archivos PHP
  • Usar las configuraciones específicas REMOTE_PHP y REMOTE_PHP_PATH como variables de entorno al iniciar BunkerWeb

Si habilitas el modo multisitio, necesitarás crear directorios separados para cada una de tus aplicaciones. Cada subdirectorio debe nombrarse utilizando el primer valor de SERVER_NAME. Aquí hay un ejemplo de prueba:

www
├── app1.example.com
│   └── index.php
├── app2.example.com
│   └── index.php
└── app3.example.com
    └── index.php

3 directorios, 3 archivos

Asumiremos que tus aplicaciones PHP están ubicadas en una carpeta llamada www. Ten en cuenta que necesitarás arreglar los permisos para que BunkerWeb (UID/GID 101) pueda al menos leer archivos y listar carpetas y PHP-FPM (UID/GID 33 si usas la imagen php:fpm) sea el propietario de los archivos y carpetas:

chown -R 33:101 ./www && \
find ./www -type f -exec chmod 0640 {} \; && \
find ./www -type d -exec chmod 0750 {} \;

Ahora puedes ejecutar BunkerWeb, configurarlo para tu aplicación PHP y también ejecutar las aplicaciones PHP:

x-bw-api-env: &bw-api-env
  # Usamos un ancla para evitar repetir la misma configuración para todos los servicios
  API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24"

services:
  bunkerweb:
    image: bunkerity/bunkerweb:1.6.18-rc1
    ports:
      - "80:8080/tcp"
      - "443:8443/tcp"
      - "443:8443/udp" # QUIC
    environment:
      <<: *bw-api-env
    volumes:
      - ./www:/var/www/html
    restart: "unless-stopped"
    networks:
      - bw-universe
      - bw-services

  bw-scheduler:
    image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
    environment:
      <<: *bw-api-env
      BUNKERWEB_INSTANCES: "bunkerweb" # Esta configuración es obligatoria para especificar la instancia de BunkerWeb
      SERVER_NAME: "app1.example.com app2.example.com"
      MULTISITE: "yes"
      REMOTE_PHP_PATH: "/app" # Se aplicará a todos los servicios gracias a la configuración MULTISITE
      app1.example.com_REMOTE_PHP: "myapp1"
      app2.example.com_REMOTE_PHP: "myapp2"
      app3.example.com_REMOTE_PHP: "myapp3"
    volumes:
      - bw-storage:/data # Esto se usa para persistir la caché y otros datos como las copias de seguridad
    restart: "unless-stopped"
    networks:
      - bw-universe

  myapp1:
    image: php:fpm
    volumes:
      - ./www/app1.example.com:/app
    networks:
      - bw-services

  myapp2:
    image: php:fpm
    volumes:
      - ./www/app2.example.com:/app
    networks:
      - bw-services

  myapp3:
    image: php:fpm
    volumes:
      - ./www/app3.example.com:/app
    networks:
      - bw-services

volumes:
  bw-storage:

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

Modo multisitio habilitado

La integración de Docker autoconf implica el uso del modo multisitio: proteger una aplicación PHP es lo mismo que proteger varias.

Cuando se utiliza la integración de Docker autoconf, para admitir aplicaciones PHP, necesitarás:

  • Montar tus archivos PHP en la carpeta /var/www/html de BunkerWeb
  • Configurar contenedores PHP-FPM para tus aplicaciones y montar la carpeta que contiene las aplicaciones PHP
  • Usar las configuraciones específicas REMOTE_PHP y REMOTE_PHP_PATH como etiquetas para tu contenedor PHP-FPM

Dado que la autoconfiguración de Docker implica el uso del modo multisitio, necesitarás crear directorios separados para cada una de tus aplicaciones. Cada subdirectorio debe tener el nombre del primer valor de SERVER_NAME. Aquí hay un ejemplo de prueba:

www
├── app1.example.com
│   └── index.php
├── app2.example.com
│   └── index.php
└── app3.example.com
    └── index.php

3 directorios, 3 archivos

Una vez creadas las carpetas, copia tus archivos y corrige los permisos para que BunkerWeb (UID/GID 101) pueda al menos leer archivos y listar carpetas, y PHP-FPM (UID/GID 33 si usas la imagen php:fpm) sea el propietario de los archivos y carpetas:

chown -R 33:101 ./www && \
find ./www -type f -exec chmod 0640 {} \; && \
find ./www -type d -exec chmod 0750 {} \;

Cuando inicies el stack de autoconfiguración de BunkerWeb, monta la carpeta www en /var/www/html para el contenedor del Scheduler:

x-bw-api-env: &bw-api-env
  # Usamos un ancla para evitar repetir la misma configuración para todos los servicios
  AUTOCONF_MODE: "yes"
  API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24"

services:
  bunkerweb:
    image: bunkerity/bunkerweb:1.6.18-rc1
    labels:
      - "bunkerweb.INSTANCE=yes"
    environment:
      <<: *bw-api-env
    volumes:
      - ./www:/var/www/html
    restart: "unless-stopped"
    networks:
      - bw-universe
      - bw-services

  bw-scheduler:
    image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
    environment:
      <<: *bw-api-env
      BUNKERWEB_INSTANCES: "" # No necesitamos especificar la instancia de BunkerWeb aquí, ya que son detectadas automáticamente por el servicio de autoconfiguración
      SERVER_NAME: "" # El nombre del servidor se llenará con las etiquetas de los servicios
      MULTISITE: "yes" # Configuración obligatoria para la autoconfiguración
      DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db" # Recuerda establecer una contraseña más segura para la base de datos
    volumes:
      - bw-storage:/data # Se utiliza para persistir la caché y otros datos como las copias de seguridad
    restart: "unless-stopped"
    networks:
      - bw-universe
      - bw-db

  bw-autoconf:
    image: bunkerity/bunkerweb-autoconf:1.6.18-rc1
    depends_on:
      - bunkerweb
      - bw-docker
    environment:
      AUTOCONF_MODE: "yes"
      DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db" # Recuerda establecer una contraseña más segura para la base de datos
      DOCKER_HOST: "tcp://bw-docker:2375" # El socket de Docker
    restart: "unless-stopped"
    networks:
      - bw-universe
      - bw-docker
      - bw-db

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

  bw-db:
    image: mariadb:11
    # Establecemos el tamaño máximo de paquete permitido para evitar problemas con consultas grandes
    command: --max-allowed-packet=67108864
    environment:
      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
      MYSQL_DATABASE: "db"
      MYSQL_USER: "bunkerweb"
      MYSQL_PASSWORD: "changeme" # Recuerda establecer una contraseña más segura para la base de datos
    volumes:
      - bw-data:/var/lib/mysql
    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-docker:
    name: bw-docker

Ahora puedes crear tus contenedores PHP-FPM, montar las subcarpetas correctas y usar etiquetas para configurar BunkerWeb:

services:
  myapp1:
      image: php:fpm
      volumes:
        - ./www/app1.example.com:/app
      networks:
        bw-services:
            aliases:
              - myapp1
      labels:
        - "bunkerweb.SERVER_NAME=app1.example.com"
        - "bunkerweb.REMOTE_PHP=myapp1"
        - "bunkerweb.REMOTE_PHP_PATH=/app"

  myapp2:
      image: php:fpm
      volumes:
        - ./www/app2.example.com:/app
      networks:
        bw-services:
            aliases:
              - myapp2
      labels:
        - "bunkerweb.SERVER_NAME=app2.example.com"
        - "bunkerweb.REMOTE_PHP=myapp2"
        - "bunkerweb.REMOTE_PHP_PATH=/app"

  myapp3:
      image: php:fpm
      volumes:
        - ./www/app3.example.com:/app
      networks:
        bw-services:
            aliases:
              - myapp3
      labels:
        - "bunkerweb.SERVER_NAME=app3.example.com"
        - "bunkerweb.REMOTE_PHP=myapp3"
        - "bunkerweb.REMOTE_PHP_PATH=/app"

networks:
  bw-services:
    external: true
    name: bw-services

PHP no es compatible con Kubernetes

La integración de Kubernetes permite la configuración a través de Ingress y el controlador de BunkerWeb solo admite aplicaciones HTTP por el momento.

Asumiremos que ya tienes el stack de integración de Linux funcionando en tu máquina.

Por defecto, BunkerWeb buscará archivos web dentro de la carpeta /var/www/html. Puedes usarla para almacenar tus aplicaciones PHP. Ten en cuenta que necesitarás configurar tu servicio PHP-FPM para obtener o establecer el usuario/grupo de los procesos en ejecución y el archivo de socket UNIX utilizado para comunicarse con BunkerWeb.

En primer lugar, deberás asegurarte de que tu instancia de PHP-FPM pueda acceder a los archivos dentro de la carpeta /var/www/html y también de que BunkerWeb pueda acceder al archivo de socket UNIX para comunicarse con PHP-FPM. Recomendamos establecer un usuario diferente como www-data para el servicio PHP-FPM y dar al grupo nginx acceso al archivo de socket UNIX. Aquí está la configuración correspondiente de PHP-FPM:

...
[www]
user = www-data
group = www-data
listen = /run/php/php-fpm.sock
listen.owner = www-data
listen.group = nginx
listen.mode = 0660
...

No olvides reiniciar tu servicio PHP-FPM:

systemctl restart php-fpm

Si habilitas el modo multisitio, necesitarás crear directorios separados para cada una de tus aplicaciones. Cada subdirectorio debe nombrarse utilizando el primer valor de SERVER_NAME. Aquí hay un ejemplo de prueba:

/var/www/html
├── app1.example.com
│   └── index.php
├── app2.example.com
│   └── index.php
└── app3.example.com
    └── index.php

3 directorios, 3 archivos

Ten en cuenta que necesitarás arreglar los permisos para que BunkerWeb (grupo nginx) pueda al menos leer archivos y listar carpetas, y PHP-FPM (usuario www-data, pero podría ser diferente dependiendo de tu sistema) sea el propietario de los archivos y carpetas:

chown -R www-data:nginx /var/www/html && \
find /var/www/html -type f -exec chmod 0640 {} \; && \
find /var/www/html -type d -exec chmod 0750 {} \;

Ahora puedes editar el archivo /etc/bunkerweb/variable.env:

HTTP_PORT=80
HTTPS_PORT=443
DNS_RESOLVERS=9.9.9.9 8.8.8.8 8.8.4.4
API_LISTEN_IP=127.0.0.1
MULTISITE=yes
SERVER_NAME=app1.example.com app2.example.com app3.example.com
app1.example.com_LOCAL_PHP=/run/php/php-fpm.sock
app1.example.com_LOCAL_PHP_PATH=/var/www/html/app1.example.com
app2.example.com_LOCAL_PHP=/run/php/php-fpm.sock
app2.example.com_LOCAL_PHP_PATH=/var/www/html/app2.example.com
app3.example.com_LOCAL_PHP=/run/php/php-fpm.sock
app3.example.com_LOCAL_PHP_PATH=/var/www/html/app3.example.com

Ahora verifiquemos el estado del Programador:

systemctl status bunkerweb-scheduler

Si ya se están ejecutando, podemos recargarlo:

systemctl reload bunkerweb-scheduler

De lo contrario, tendremos que iniciarlo:

systemctl start bunkerweb-scheduler

Obsoleto

La integración de Swarm está obsoleta y se eliminará en una futura versión. Por favor, considera usar la integración de Kubernetes en su lugar.

Se puede encontrar más información en la documentación de integración de Swarm.

Modo multisitio habilitado

La integración Swarm implica el uso del modo multisitio: proteger una aplicación PHP es lo mismo que proteger varias.

Volumen compartido

Usar PHP con la integración de Docker Swarm necesita un volumen compartido entre todas las instancias de BunkerWeb y PHP-FPM, lo cual no se cubre en esta documentación.

Cuando se usa la integración Swarm, para admitir aplicaciones PHP, necesitarás:

  • Montar tus archivos PHP en la carpeta /var/www/html de BunkerWeb
  • Configurar contenedores PHP-FPM para tus aplicaciones y montar la carpeta que contiene las aplicaciones PHP
  • Usar las configuraciones específicas REMOTE_PHP y REMOTE_PHP_PATH como etiquetas para tu contenedor PHP-FPM

Dado que la integración de Swarm implica el uso del modo multisitio, necesitarás crear directorios separados para cada una de tus aplicaciones. Cada subdirectorio debe tener el nombre del primer valor de SERVER_NAME. Aquí hay un ejemplo de prueba:

www
├── app1.example.com
│   └── index.php
├── app2.example.com
│   └── index.php
└── app3.example.com
    └── index.php

3 directorios, 3 archivos

Como ejemplo, consideraremos que tienes una carpeta compartida montada en tus nodos de trabajo en el punto final /shared.

Una vez creadas las carpetas, copia tus archivos y corrige los permisos para que BunkerWeb (UID/GID 101) pueda al menos leer archivos y listar carpetas, y PHP-FPM (UID/GID 33 si usas la imagen php:fpm) sea el propietario de los archivos y carpetas:

chown -R 33:101 /shared/www && \
find /shared/www -type f -exec chmod 0640 {} \; && \
find /shared/www -type d -exec chmod 0750 {} \;

Cuando inicies el stack de BunkerWeb, monta la carpeta /shared/www en /var/www/html para el contenedor del Scheduler:

services:
  bunkerweb:
    image: bunkerity/bunkerweb:1.6.18-rc1
    volumes:
      - /shared/www:/var/www/html
...

Ahora puedes crear tus servicios PHP-FPM, montar las subcarpetas correctas y usar etiquetas para configurar BunkerWeb:

services:
  myapp1:
      image: php:fpm
      volumes:
        - ./www/app1.example.com:/app
      networks:
        bw-services:
            aliases:
              - myapp1
      deploy:
        placement:
          constraints:
            - "node.role==worker"
        labels:
          - "bunkerweb.SERVER_NAME=app1.example.com"
          - "bunkerweb.REMOTE_PHP=myapp1"
          - "bunkerweb.REMOTE_PHP_PATH=/app"

  myapp2:
      image: php:fpm
      volumes:
        - ./www/app2.example.com:/app
      networks:
        bw-services:
            aliases:
              - myapp2
      deploy:
        placement:
          constraints:
            - "node.role==worker"
        labels:
          - "bunkerweb.SERVER_NAME=app2.example.com"
          - "bunkerweb.REMOTE_PHP=myapp2"
          - "bunkerweb.REMOTE_PHP_PATH=/app"

  myapp3:
      image: php:fpm
      volumes:
        - ./www/app3.example.com:/app
      networks:
        bw-services:
            aliases:
              - myapp3
      deploy:
        placement:
          constraints:
            - "node.role==worker"
        labels:
          - "bunkerweb.SERVER_NAME=app3.example.com"
          - "bunkerweb.REMOTE_PHP=myapp3"
          - "bunkerweb.REMOTE_PHP_PATH=/app"

networks:
  bw-services:
    external: true
    name: bw-services

IPv6

Característica experimental

Esta característica no está lista para producción. Siéntete libre de probarla y reportarnos cualquier error usando los issues en el repositorio de GitHub.

Por defecto, BunkerWeb solo escuchará en direcciones IPv4 y no usará IPv6 para las comunicaciones de red. Si quieres habilitar el soporte de IPv6, necesitas establecer USE_IPV6=yes. Ten en cuenta que la configuración de IPv6 de tu red y entorno está fuera del alcance de esta documentación.

En primer lugar, necesitarás configurar tu demonio de Docker para habilitar el soporte de IPv6 para los contenedores y usar ip6tables si es necesario. Aquí hay una configuración de ejemplo para tu archivo /etc/docker/daemon.json:

{
  "experimental": true,
  "ipv6": true,
  "ip6tables": true,
  "fixed-cidr-v6": "fd00:dead:beef::/48"
}

Ahora puedes reiniciar el servicio de Docker para aplicar los cambios:

systemctl restart docker

Una vez que Docker esté configurado para soportar IPv6, puedes agregar la configuración USE_IPV6 y configurar la red bw-services para IPv6:

services:
  bw-scheduler:
    image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
    environment:
      USE_IPv6: "yes"

...

networks:
  bw-services:
    name: bw-services
    enable_ipv6: true
    ipam:
      config:
        - subnet: fd00:13:37::/48
          gateway: fd00:13:37::1

...

Necesitarás agregar la configuración al archivo /etc/bunkerweb/variables.env:

...
USE_IPV6=yes
...

Verifiquemos el estado de BunkerWeb:

systemctl status bunkerweb

Si ya se está ejecutando, podemos reiniciar el scheduler para que vuelva a renderizar la configuración de NGINX con IPv6 habilitado:

systemctl restart bunkerweb-scheduler

De lo contrario, tendremos que iniciarlo:

systemctl start bunkerweb

Opciones de configuración de registros

BunkerWeb ofrece una configuración de registros flexible que permite enviar registros a múltiples destinos (por ejemplo, archivos, stdout/stderr o syslog) simultáneamente. Esto es especialmente útil para integrarse con recopiladores externos de registros mientras se mantienen registros locales para la interfaz web.

Hay dos categorías principales de registros para configurar:

  1. Registros de servicio: Logs generados por los componentes de BunkerWeb (Scheduler, UI, Autoconf, etc.). Se controlan por servicio mediante LOG_TYPES (y opcionalmente LOG_FILE_PATH, LOG_SYSLOG_ADDRESS, LOG_SYSLOG_TAG).
  2. Registros de acceso y error: Registros HTTP de acceso y errores generados por NGINX. Solo el servicio bunkerweb usa estos (ACCESS_LOG / ERROR_LOG / LOG_LEVEL).

Registros de servicio

Los registros de servicio se controlan con la configuración LOG_TYPES, que puede aceptar múltiples valores separados por espacios (por ejemplo, LOG_TYPES="stderr syslog").

Valor Descripción
file Escribe los registros en un archivo plano. En instalaciones Linux, la rotación externa la gestiona logrotate. En un contenedor, nada rota un archivo que un servicio escribe por sí mismo: la retención es responsabilidad del operador, así que monta el archivo en un volumen y rótalo tú mismo, o prefiere stderr/syslog ahí. Requerido para el visor de registros de la interfaz UI.
stderr Escribe los registros en la salida de error estándar. Estándar en entornos con contenedores (docker logs).
syslog Envía los registros a un servidor syslog. Requiere definir LOG_SYSLOG_ADDRESS.

Al usar file, también debes configurar:

  • LOG_FILE_PATH: Ruta donde se escriben los archivos de log cuando LOG_TYPES incluye file.

Al usar syslog, también debes configurar:

  • LOG_SYSLOG_ADDRESS: La dirección del servidor syslog (por ejemplo, udp://bw-syslog:514 o /dev/log).
  • LOG_SYSLOG_TAG: Una etiqueta única para el servicio (por ejemplo, bw-scheduler) para distinguir sus entradas.

Registros de acceso y error

Estos son registros estándar de NGINX, configurados únicamente mediante el servicio bunkerweb. Soportan múltiples destinos añadiendo sufijos numerados a la configuración (por ejemplo, ACCESS_LOG, ACCESS_LOG_1 junto con LOG_FORMAT, LOG_FORMAT_1, o ERROR_LOG, ERROR_LOG_1 con sus respectivos LOG_LEVEL, LOG_LEVEL_1).

  • ACCESS_LOG: Destino para los registros de acceso (por defecto: /var/log/bunkerweb/access.log). Acepta ruta de archivo, syslog:server=host[:port][,param=value], buffer compartido memory:name:size, o off para desactivar. Consulta la documentación de NGINX sobre access_log para más detalles.
  • ERROR_LOG: Destino para los registros de error (por defecto: /var/log/bunkerweb/error.log). Acepta ruta de archivo, stderr, syslog:server=host[:port][,param=value], o buffer compartido memory:size. Consulta la documentación de NGINX sobre error_log para más detalles.
  • LOG_LEVEL: Nivel de verbosidad de los registros de error (por defecto: notice).

Estas configuraciones aceptan valores estándar de NGINX, incluyendo rutas de archivo, stderr, syslog:server=... (ver documentación de syslog en NGINX), o buffers en memoria compartida. Soportan múltiples destinos mediante sufijos numerados (consulta la convención de múltiples ajustes). Los demás servicios (Scheduler, UI, Autoconf, etc.) dependen únicamente de LOG_TYPES/LOG_FILE_PATH/LOG_SYSLOG_*.

Ejemplo con múltiples registros de acceso/errores (solo bunkerweb, sufijos numerados):

ACCESS_LOG=/var/log/bunkerweb/access.log
ACCESS_LOG_1=syslog:server=unix:/dev/log,tag=bunkerweb
LOG_FORMAT=$host $remote_addr - $request_id $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"
LOG_FORMAT_1=$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent
ERROR_LOG=/var/log/bunkerweb/error.log
ERROR_LOG_1=syslog:server=unix:/dev/log,tag=bunkerweb
LOG_LEVEL=notice
LOG_LEVEL_1=error

Retención de los archivos de registro

Solo las integraciones que mantienen archivos de registro reales necesitan retención, y ambas usan el mismo mecanismo: logrotate, con la política que BunkerWeb instala en /etc/logrotate.d/bunkerweb. Rota cada archivo que coincida con /var/log/bunkerweb/*.log a diario, o antes si el archivo supera los 100 MB, conserva catorce generaciones numeradas (modsec_audit.log.1, .2.gz, etc.) y usa copytruncate.

  • Linux: los paquetes dependen de logrotate y el sistema lo ejecuta con su propio temporizador. No hay nada más que hacer.
  • All-in-one: la imagen incluye logrotate y lo ejecuta cada hora bajo supervisor, usando ese mismo archivo de política.
  • Docker, Autoconf, Swarm y Kubernetes: no hay nada que rotar. src/bw/Dockerfile sustituye access.log, error.log y modsec_audit.log por enlaces simbólicos a la salida estándar y al error estándar del propio contenedor al construir la imagen, de modo que la retención corresponde al driver de logging de tu entorno de ejecución de contenedores (consulta las buenas prácticas de logging de Docker más abajo).

copytruncate es lo que hace que una sola política funcione para todas ellas. Copia el archivo aparte y vacía el original en el mismo sitio en lugar de renombrarlo, de modo que un proceso que nunca reabre su registro sigue escribiendo en el archivo correcto. ModSecurity es exactamente ese proceso: abre el registro de auditoría una vez, cuando se carga la configuración, y mantiene el descriptor abierto. Rotar mediante renombrado lo dejaría escribiendo en el archivo archivado para siempre, con el archivo activo vacío.

Edita /etc/logrotate.d/bunkerweb para cambiar el umbral, el número de generaciones, o para añadir un maxage. En el All-in-one, monta tu propio archivo sobre esa ruta.

Dos directivas son decisivas ahí. maxsize es lo que mantiene vivo a daily: la directiva size, muy parecida, es excluyente con las directivas de intervalo y rotaría solo por tamaño. Y añadir dateext nombraría cada archivo comprimido según la fecha, de modo que una segunda rotación en la misma fecha falla con destination ... already exists, skipping rotation y deja el archivo activo sin rotar hasta que cambie la fecha.

La ubicación del registro de auditoría se establece mediante MODSECURITY_SEC_AUDIT_LOG (multisite, por defecto /var/log/bunkerweb/modsec_audit.log); consulta los ajustes de ModSecurity. Si lo apuntas fuera de /var/log/bunkerweb, queda fuera de la política anterior, y en una integración de contenedores sustituye el enlace simbólico por un archivo real que nada rota. Si lo mueves, móntalo en un volumen y rótalo tú mismo. El ajuste solo acepta una ruta bajo /var/log/bunkerweb, así que no puede apuntar a /data: para conservar el historial de auditoría tras recrear el contenedor, monta un volumen sobre /var/log/bunkerweb, lo que preserva todo el conjunto de registros y no solo el de auditoría.

Con el valor por defecto BCFH de MODSECURITY_SEC_AUDIT_LOG_PARTS, la parte C coloca el cuerpo de la petición en el registro de auditoría. Trata el archivo como sensible antes de copiarlo a ningún sitio.

Valores por defecto e integración — Ejemplos

Comportamiento predeterminado: LOG_TYPES="file". Los registros se escriben en /var/log/bunkerweb/*.log. La rotación la gestiona la configuración del sistema logrotate instalada en /etc/logrotate.d/bunkerweb (diaria o al superar 100 MB, catorce generaciones, comprimida con copytruncate).

Ejemplo: Mantener archivos locales (para la interfaz web) y también enviar una copia al syslog del sistema.

  # Registros de servicio (establecidos en /etc/bunkerweb/variables.env o en archivos env específicos del servicio)
  LOG_TYPES="file syslog"
  LOG_SYSLOG_ADDRESS=/dev/log
  SCHEDULER_LOG_FILE_PATH=/var/log/bunkerweb/scheduler.log
  UI_LOG_FILE_PATH=/var/log/bunkerweb/ui.log
  # ...
  # LOG_SYSLOG_TAG se asigna automáticamente por servicio (anular por servicio si es necesario)

  # Registros de NGINX (solo servicio bunkerweb; establecer en /etc/bunkerweb/variables.env)
  ACCESS_LOG_1=syslog:server=unix:/dev/log,tag=bunkerweb_access
  ERROR_LOG_1=syslog:server=unix:/dev/log,tag=bunkerweb

Comportamiento predeterminado: LOG_TYPES="stderr". Los registros son visibles mediante docker logs.

Estas imágenes no tienen, de entrada, ningún archivo de registro gestionado por BunkerWeb que limitar: src/bw/Dockerfile elimina access.log, error.log y modsec_audit.log al construir la imagen y sustituye los tres por enlaces simbólicos a la salida estándar y al error estándar del propio contenedor, de modo que ACCESS_LOG, ERROR_LOG y MODSECURITY_SEC_AUDIT_LOG van directamente al flujo de registro del contenedor por defecto. La retención ahí es responsabilidad de tu entorno de ejecución, a través del driver de logging (consulta las buenas prácticas de logging de Docker más abajo) o de un colector externo; BunkerWeb no incluye logrotate en sus imágenes.

Ejemplo (adaptado de la guía de inicio rápido): Mantener docker logs (stderr) Y enviar también a un contenedor syslog central (necesario para la interfaz web y CrowdSec).

x-bw-env:
  &bw-env # Usamos un ancla para evitar repetir la misma configuración para ambos servicios
  API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24" # Asegúrate de establecer el rango de IP correcto para que el Scheduler pueda enviar la configuración a la instancia
  # Opcional: establece un token de API y refléjalo en ambos contenedores
  API_TOKEN: ""
  DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db" # Recuerda establecer una contraseña más segura para la base de datos
  # Registros de servicio
  LOG_TYPES: "stderr syslog"
  LOG_SYSLOG_ADDRESS: "udp://bw-syslog:514"
  # LOG_SYSLOG_TAG se asigna automáticamente por servicio (anular por servicio si es necesario)
  # Registros NGINX: enviar a Syslog (solo bunkerweb)
  ACCESS_LOG_1: "syslog:server=bw-syslog:514,tag=bunkerweb_access"
  ERROR_LOG_1: "syslog:server=bw-syslog:514,tag=bunkerweb"

services:
  bunkerweb:
    # Este es el nombre que se usará para identificar la instancia en el Scheduler
    image: bunkerity/bunkerweb:1.6.18-rc1
    ports:
      - "80:8080/tcp"
      - "443:8443/tcp"
      - "443:8443/udp" # Para soporte QUIC / HTTP3
    environment:
      <<: *bw-env # Usamos el ancla para evitar repetir la misma configuración para todos los servicios
    restart: "unless-stopped"
    networks:
      - bw-universe
      - bw-services

  bw-scheduler:
    image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
    environment:
      <<: *bw-env
      BUNKERWEB_INSTANCES: "bunkerweb" # Asegúrate de establecer el nombre correcto de la instancia
      SERVER_NAME: ""
      MULTISITE: "yes"
      UI_HOST: "http://bw-ui:7000" # Cambia si es necesario
      USE_REDIS: "yes"
      REDIS_HOST: "redis"
    volumes:
      - bw-storage:/data # Esto se usa para persistir la caché y otros datos como las copias de seguridad
    restart: "unless-stopped"
    networks:
      - bw-universe
      - bw-db

  bw-ui:
    image: bunkerity/bunkerweb-ui:1.6.18-rc1
    environment:
      <<: *bw-env
    volumes:
      - bw-logs:/var/log/bunkerweb # Esto se usa para leer los registros syslog desde la interfaz web
      - bw-ui-data:/data # Se usa para conservar los secretos de la interfaz web (secreto Flask, claves de cifrado TOTP, claves Biscuit)
    restart: "unless-stopped"
    networks:
      - bw-universe
      - bw-db

  bw-db:
    image: mariadb:11
    # Establecemos el tamaño máximo de paquete permitido para evitar problemas con consultas grandes
    command: --max-allowed-packet=67108864
    environment:
      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
      MYSQL_DATABASE: "db"
      MYSQL_USER: "bunkerweb"
      MYSQL_PASSWORD: "changeme" # Recuerda establecer una contraseña más segura para la base de datos
    volumes:
      - bw-data:/var/lib/mysql
    restart: "unless-stopped"
    networks:
      - bw-db

  redis: # Servicio Redis para la persistencia de reportes/bloqueos/estadísticas
    image: redis:8-alpine
    command: >
      redis-server
      --maxmemory 256mb
      --maxmemory-policy volatile-lru
      --save 60 1000
      --appendonly yes
    volumes:
      - redis-data:/data
    restart: "unless-stopped"
    networks:
      - bw-universe

  bw-syslog:
    image: balabit/syslog-ng:4.10.2
    cap_add:
      - NET_BIND_SERVICE # Enlazar a puertos bajos
      - NET_BROADCAST # Enviar broadcasts
      - NET_RAW # Usar sockets raw
      - DAC_READ_SEARCH # Leer archivos saltando permisos
      - DAC_OVERRIDE # Anular permisos de archivos
      - CHOWN # Cambiar propiedad de archivos
      - SYSLOG # Escribir en logs del sistema
    volumes:
      - bw-logs:/var/log/bunkerweb # Este es el volumen usado para almacenar los registros
      - ./syslog-ng.conf:/etc/syslog-ng/syslog-ng.conf # Este es el archivo de configuración de syslog-ng
    restart: "unless-stopped"
    networks:
      - bw-universe

volumes:
  bw-data:
  bw-storage:
  redis-data:
  bw-logs:
  bw-ui-data:

networks:
  bw-universe:
    name: bw-universe
  ipam:
    driver: default
    config:
      - subnet: 10.20.30.0/24 # Asegúrate de establecer el rango de IP correcto para que el Scheduler pueda enviar la configuración a la instancia
  bw-services:
    name: bw-services
  bw-db:
    name: bw-db

Comportamiento predeterminado: igual que Docker (LOG_TYPES="stderr"), pero la imagen All-in-one conserva ACCESS_LOG, ERROR_LOG y MODSECURITY_SEC_AUDIT_LOG como archivos reales bajo /var/log/bunkerweb/ (los mismos valores por defecto que en Linux), porque tanto el CrowdSec incluido como el visor de registros de la interfaz web los leen desde disco.

BunkerWeb los limita por ti ahí: la imagen incluye logrotate y lo ejecuta cada hora bajo supervisor, con la misma política que instalan los paquetes de Linux (consulta Retención de los archivos de registro más arriba). Como la rotación se hace con copytruncate, los archivos conservan su inodo, de modo que el analizador de CrowdSec y el visor de registros los siguen a través de una rotación sin necesidad de reiniciar.

Comportamiento predeterminado: Los registros se escriben en stderr y son visibles mediante kubectl logs.

Ejemplo: Habilitar el sidecar syslog integrado en el chart de Helm para recopilar registros para la interfaz web (requiere BunkerWeb 1.6.7+).

ui:
  logs:
    # Habilitar sidecar de recopilación de registros
    enabled: true

    # Dirección syslog para reenvío de registros
    # Se configura automáticamente al servicio Sidecar si está vacío
    syslogAddress: ""

    # Contenedor syslog-ng para recopilación de registros
    repository: docker.io/balabit/syslog-ng
    pullPolicy: Always
    tag: 4.8.0

    # Almacenamiento persistente para registros
    persistence:
      size: 5Gi
      storageClass: ""

Consulte el ejemplo completo logging.yaml en el repositorio bunkerity/bunkerweb-helm.

Configuración de syslog-ng

Aquí tienes un ejemplo de un archivo syslog-ng.conf que puedes usar para reenviar los registros a un archivo:

@version: 4.10

# Configuración de la fuente para recibir registros enviados por los servicios de BunkerWeb (ACCESS_LOG / ERROR_LOG y LOG_TYPES=syslog)
source s_net {
  udp(
    ip("0.0.0.0")
  );
};

# Plantilla para formatear los mensajes de registro
template t_imp {
  template("$MSG\n");
  template_escape(no);
};

# Configuración de destino para escribir registros en archivos con nombre dinámico
destination d_dyna_file {
  file(
    "/var/log/bunkerweb/${PROGRAM}.log"
    template(t_imp)
    owner("101")
    group("101")
    dir_owner("root")
    dir_group("101")
    perm(0440)
    dir_perm(0770)
    create_dirs(yes)
    logrotate(
      enable(yes),
      size(100MB),
      rotations(7)
    )
  );
};

# Ruta de registro para dirigir los registros a archivos con nombre dinámico
log {
  source(s_net);
  destination(d_dyna_file);
};

Buenas prácticas de registro de Docker

Cuando se utiliza Docker, es importante gestionar los registros de los contenedores para evitar que consuman un espacio excesivo en el disco. Por defecto, Docker utiliza el controlador de registro json-file, lo que puede dar lugar a archivos de registro muy grandes si no se configura.

Para evitar esto, puede configurar la rotación de registros. Esto se puede hacer para servicios específicos en su archivo docker-compose.yml, o globalmente para el demonio de Docker.

Configuración por servicio

Puede configurar el controlador de registro para sus servicios en su archivo docker-compose.yml para rotar automáticamente los registros. Aquí hay un ejemplo que mantiene hasta 10 archivos de registro de 20 MB cada uno:

services:
  bunkerweb:
    image: bunkerity/bunkerweb:1.6.18-rc1
    logging:
      driver: "json-file"
      options:
        max-size: "20m"
        max-file: "10"
    ...

Esta configuración asegura que los registros se roten, evitando que llenen su disco. Puede aplicar esto a cualquier servicio en su configuración de Docker Compose.

Ajustes globales (daemon.json)

Si desea aplicar esta configuración de registro a todos los contenedores en el host por defecto, puede configurar el demonio de Docker editando (o creando) el archivo /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "20m",
    "max-file": "10"
  }
}

Después de modificar daemon.json, debe reiniciar el demonio de Docker para que los cambios surtan efecto:

sudo systemctl restart docker

Estos ajustes globales serán heredados por todos los contenedores. Sin embargo, cualquier configuración de registro definida por servicio en un archivo docker-compose.yml anulará los ajustes globales en daemon.json.

Ajuste de seguridad

BunkerWeb ofrece muchas características de seguridad que puedes configurar con características. Aunque los valores predeterminados de las configuraciones aseguran una "seguridad por defecto" mínima, te recomendamos encarecidamente que los ajustes. Al hacerlo, podrás asegurar el nivel de seguridad de tu elección y también gestionar los falsos positivos.

Otras características

Esta sección solo se enfoca en el ajuste de seguridad, consulta la sección de características de la documentación para otras configuraciones.

Descripción general

Descripción general y orden de los plugins de seguridad principales

Integración con la Consola de CrowdSec

Si aún no estás familiarizado con la integración de la Consola de CrowdSec, CrowdSec aprovecha la inteligencia de la comunidad para combatir las amenazas cibernéticas. Piénsalo como el "Waze de la ciberseguridad"—cuando un servidor es atacado, otros sistemas en todo el mundo son alertados y protegidos de los mismos atacantes. Puedes aprender más sobre ello aquí.

¡Felicidades, tu instancia de BunkerWeb ahora está inscrita en tu Consola de CrowdSec!

Consejo profesional: Al ver tus alertas, haz clic en la opción "columnas" y marca la casilla "contexto" para acceder a los datos específicos de BunkerWeb.

Descripción general

Datos de BunkerWeb mostrados en la columna de contexto

Proxy directo para tráfico saliente

Si tu entorno requiere que el tráfico HTTP(S) saliente pase por un proxy directo (por ejemplo un proxy corporativo o Squid), puedes usar las variables de entorno estándar del proxy. No hay una configuración específica de BunkerWeb para esto.

NGINX no utiliza estas variables para el tráfico upstream, por lo que la configuración del proxy directo solo afecta a los componentes que inician solicitudes salientes. En la práctica, configúralas en el Scheduler, porque gestiona tareas periódicas como las renovaciones de certificados de Let's Encrypt, llamadas a API externas y webhooks.

Las variables habituales son:

  • HTTP_PROXY / HTTPS_PROXY: URL del proxy, opcionalmente con credenciales.
  • NO_PROXY: lista separada por comas de hosts, dominios o CIDR que deben excluir el proxy (ajusta según la integración: nombres de servicios en Docker/Swarm, dominios del clúster en Kubernetes, o solo localhost en Linux).
  • REQUESTS_CA_BUNDLE / SSL_CERT_FILE: opcional, necesario si el proxy usa una CA personalizada. Monta el bundle de CA en el contenedor y apunta las variables a él para que las solicitudes de Python validen TLS (ajusta la ruta a tu imagen base).

NO_PROXY es obligatorio para el tráfico interno

Si omites rangos internos o nombres de servicios, el tráfico interno puede ir al proxy y fallar. Ajusta la lista a tu integración (por ejemplo nombres de servicios Docker, dominios del clúster de Kubernetes o solo localhost en Linux).

Añade las variables a /etc/bunkerweb/variables.env. Este archivo se carga para ambos servicios, pero solo el Scheduler las utilizará:

HTTP_PROXY=http://proxy.example.local:3128
HTTPS_PROXY=http://proxy.example.local:3128
NO_PROXY=localhost,127.0.0.1
REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

Reinicia los servicios para recargar el entorno:

sudo systemctl restart bunkerweb && \
sudo systemctl restart bunkerweb-scheduler

Proporciona las variables al crear el contenedor (y monta el bundle de CA si es necesario). La imagen All-in-one incluye el Scheduler, así que esto cubre las tareas salientes:

docker run -d \
    --name bunkerweb-aio \
    -v bw-storage:/data \
    -v /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro \
    -e HTTP_PROXY="http://proxy.example.local:3128" \
    -e HTTPS_PROXY="http://proxy.example.local:3128" \
    -e NO_PROXY="localhost,127.0.0.1" \
    -e REQUESTS_CA_BUNDLE="/etc/ssl/certs/ca-certificates.crt" \
    -e SSL_CERT_FILE="/etc/ssl/certs/ca-certificates.crt" \
    -p 80:8080/tcp \
    -p 443:8443/tcp \
    -p 443:8443/udp \
    bunkerity/bunkerweb-all-in-one:1.6.18-rc1

Si el contenedor ya existe, recréalo para aplicar el nuevo entorno.

Añade las variables al contenedor scheduler:

bw-scheduler:
  image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
  ...
  environment:
    HTTP_PROXY: "http://proxy.example.local:3128"
    HTTPS_PROXY: "http://proxy.example.local:3128"
    NO_PROXY: "localhost,127.0.0.1,bunkerweb,bw-scheduler,redis,db"
    REQUESTS_CA_BUNDLE: "/etc/ssl/certs/ca-certificates.crt"
    SSL_CERT_FILE: "/etc/ssl/certs/ca-certificates.crt"
  volumes:
    - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro
  ...

Aplica las variables al contenedor scheduler:

bw-scheduler:
  image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
  ...
  environment:
    HTTP_PROXY: "http://proxy.example.local:3128"
    HTTPS_PROXY: "http://proxy.example.local:3128"
    NO_PROXY: "localhost,127.0.0.1,bunkerweb,bw-scheduler,redis,db"
    REQUESTS_CA_BUNDLE: "/etc/ssl/certs/ca-certificates.crt"
    SSL_CERT_FILE: "/etc/ssl/certs/ca-certificates.crt"
  volumes:
    - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro
  ...

Añade las variables al pod del Scheduler usando extraEnvs. Si necesitas una CA personalizada, móntala mediante extraVolumes/extraVolumeMounts y apunta las variables a la ruta montada:

scheduler:
  extraEnvs:
    - name: HTTP_PROXY
      value: "http://proxy.example.local:3128"
    - name: HTTPS_PROXY
      value: "http://proxy.example.local:3128"
    - name: NO_PROXY
      value: "localhost,127.0.0.1,.svc,.cluster.local"
    - name: REQUESTS_CA_BUNDLE
      value: "/etc/ssl/certs/ca-certificates.crt"
    - name: SSL_CERT_FILE
      value: "/etc/ssl/certs/ca-certificates.crt"

Obsoleto

La integración Swarm está obsoleta y se eliminará en una versión futura. Considera usar la integración Kubernetes en su lugar.

Más información en la documentación de la integración Swarm.

Añade las variables al servicio scheduler:

bw-scheduler:
  image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
  ...
  environment:
    HTTP_PROXY: "http://proxy.example.local:3128"
    HTTPS_PROXY: "http://proxy.example.local:3128"
    NO_PROXY: "localhost,127.0.0.1,bunkerweb,bw-scheduler,redis,db"
    REQUESTS_CA_BUNDLE: "/etc/ssl/certs/ca-certificates.crt"
    SSL_CERT_FILE: "/etc/ssl/certs/ca-certificates.crt"
  volumes:
    - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro
  ...

Monitoreo y reportes

Monitoreo crown pro icon (PRO)

Soporte STREAM ❌

El plugin de monitoreo te permite recolectar y recuperar métricas sobre BunkerWeb. Al habilitarlo, tu(s) instancia(s) comenzará(n) a recolectar varios datos relacionados con ataques, solicitudes y rendimiento. Luego puedes recuperarlos llamando al punto final de la API /monitoring de forma regular o usando otros plugins como el exportador de Prometheus.

Lista de características

  • Habilitar la recolección de varias métricas de BunkerWeb
  • Recuperar métricas de la API
  • Usar en combinación con otros plugins (p. ej. exportador de Prometheus)
  • Página de interfaz de usuario dedicada para monitorear tu(s) instancia(s)

Lista de configuraciones

Configuración Predeterminado Contexto Múltiple Descripción
USE_MONITORING yes global no Habilitar el monitoreo de BunkerWeb.
MONITORING_METRICS_DICT_SIZE 10M global no Tamaño del diccionario para almacenar métricas de monitoreo.
MONITORING_IGNORE_URLS global no Lista de rutas URL separadas por espacios que se excluirán del monitoreo (p. ej. /health /ready).

Exportador de Prometheus crown pro icon (PRO)

Soporte STREAM ❌

El plugin exportador de Prometheus agrega un exportador de Prometheus en tu(s) instancia(s) de BunkerWeb. Cuando está habilitado, puedes configurar tu(s) instancia(s) de Prometheus para que extraigan datos de un punto final específico en BunkerWeb y recopilen métricas internas.

También proporcionamos un panel de control de Grafana que puedes importar en tu propia instancia y conectar a tu propia fuente de datos de Prometheus.

Ten en cuenta que el uso del plugin exportador de Prometheus requiere habilitar el plugin de Monitoreo (USE_MONITORING=yes)

Lista de características

  • Exportador de Prometheus que proporciona métricas internas de BunkerWeb
  • Puerto, IP de escucha y URL dedicados y configurables
  • Lista blanca de IP/red para máxima seguridad

Lista de configuraciones

Configuración Predeterminado Contexto Múltiple Descripción
USE_PROMETHEUS_EXPORTER no global no Habilitar el exportador de Prometheus.
PROMETHEUS_EXPORTER_IP 0.0.0.0 global no IP de escucha del exportador de Prometheus.
PROMETHEUS_EXPORTER_PORT 9113 global no Puerto de escucha del exportador de Prometheus.
PROMETHEUS_EXPORTER_URL /metrics global no URL HTTP del exportador de Prometheus.
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 no Lista de IP/redes permitidas para contactar el punto final del exportador de Prometheus.

Reportes crown pro icon (PRO)

Soporte STREAM ❌

Plugin de monitoreo necesario

Este plugin requiere que el plugin de monitoreo Pro esté instalado y habilitado con la configuración USE_MONITORING establecida en yes.

El plugin de Reportes proporciona una solución integral para reportes regulares de datos importantes de BunkerWeb, incluyendo estadísticas globales, ataques, bloqueos, solicitudes, razones e información de AS. Ofrece una amplia gama de características, incluyendo creación automática de reportes, opciones de personalización e integración perfecta con el plugin de monitoreo pro. Con el plugin de Reportes, puedes generar y gestionar fácilmente reportes para monitorear el rendimiento y la seguridad de tu aplicación.

Lista de características

  • Reportes regulares de datos importantes de BunkerWeb, incluyendo estadísticas globales, ataques, bloqueos, solicitudes, razones e información de AS.
  • Integración con el plugin de monitoreo Pro para una integración perfecta y capacidades de reporte mejoradas.
  • Soporte para webhooks (clásicos, Discord y Slack) para notificaciones en tiempo real.
  • Soporte para SMTP para notificaciones por correo electrónico.
  • Opciones de configuración para personalización y flexibilidad.

Lista de configuraciones

Configuración Predeterminado Contexto Descripción
USE_REPORTING_SMTP no global Habilitar el envío del reporte por correo electrónico (HTML).
USE_REPORTING_WEBHOOK no global Habilitar el envío del reporte por webhook (Markdown).
REPORTING_SCHEDULE weekly global Cadencia del reporte: daily, weekly o monthly.
REPORTING_WEBHOOK_URLS global URLs de webhook separadas por espacios; Discord y Slack se detectan automáticamente.
REPORTING_SMTP_EMAILS global Destinatarios de correo electrónico separados por espacios.
REPORTING_SMTP_HOST global Nombre de host o IP del servidor SMTP.
REPORTING_SMTP_PORT 465 global Puerto SMTP. Usa 465 para SSL, 587 para TLS.
REPORTING_SMTP_FROM_EMAIL global Dirección del remitente (desactiva 2FA si es requerido por tu proveedor).
REPORTING_SMTP_FROM_USER global Nombre de usuario SMTP (recurre al correo del remitente cuando se omite y se establece una contraseña).
REPORTING_SMTP_FROM_PASSWORD global Contraseña SMTP.
REPORTING_SMTP_SSL SSL global Seguridad de conexión: no, SSL o TLS.
REPORTING_SMTP_SUBJECT BunkerWeb Report global Línea de asunto para entregas por correo electrónico.

Notas de comportamiento

  • REPORTING_SMTP_EMAILS es requerido cuando la entrega SMTP está habilitada; REPORTING_WEBHOOK_URLS es requerido cuando la entrega por webhook está habilitada.
  • Si tanto los webhooks como SMTP fallan, la entrega se reintenta en la próxima ejecución programada.
  • Las plantillas HTML y Markdown se encuentran en reporting/files/; personalízalas con precaución para mantener los marcadores de posición intactos.

Copia de seguridad y restauración

Copia de seguridad S3 crown pro icon (PRO)

Soporte STREAM ✅

La herramienta de Copia de seguridad S3 automatiza sin problemas la protección de datos, de forma similar al plugin de copia de seguridad de la comunidad. Sin embargo, se destaca por almacenar de forma segura las copias de seguridad directamente en un bucket S3.

Al activar esta función, estás salvaguardando proactivamente la integridad de tus datos. Almacenar las copias de seguridad de forma remota protege la información crucial de amenazas como fallos de hardware, ciberataques o desastres naturales. Esto garantiza tanto la seguridad como la disponibilidad, permitiendo una rápida recuperación durante eventos inesperados, preservando la continuidad operativa y asegurando la tranquilidad.

Información para usuarios de Red Hat Enterprise Linux (RHEL) 8.9

Si estás utilizando RHEL 8.9 y planeas usar una base de datos externa, necesitarás instalar el paquete mysql-community-client para asegurar que el comando mysqldump esté disponible. Puedes instalar el paquete ejecutando los siguientes comandos:

  1. Instalar el paquete de configuración del repositorio de MySQL

    sudo dnf install https://dev.mysql.com/get/mysql80-community-release-el8-9.noarch.rpm

  2. Habilitar el repositorio de MySQL

    sudo dnf config-manager --enable mysql80-community

  3. Instalar el cliente de MySQL

    sudo dnf install mysql-community-client

  1. Instalar el paquete de configuración del repositorio de PostgreSQL

    dnf install "https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-$(uname -m)/pgdg-redhat-repo-latest.noarch.rpm"

  2. Instalar el cliente de PostgreSQL

    dnf install postgresql<version>

Lista de características

  • Copia de seguridad automática de datos a un bucket S3
  • Opciones de programación flexibles: diaria, semanal o mensual
  • Gestión de rotación para controlar el número de copias de seguridad a mantener
  • Nivel de compresión personalizable para los archivos de copia de seguridad

Lista de configuraciones

Configuración Predeterminado Contexto Descripción
USE_BACKUP_S3 no global Habilitar o deshabilitar la función de copia de seguridad S3
BACKUP_S3_SCHEDULE daily global La frecuencia de la copia de seguridad
BACKUP_S3_ROTATION 7 global El número de copias de seguridad a mantener
BACKUP_S3_ENDPOINT global El punto final S3
BACKUP_S3_BUCKET global El bucket S3
BACKUP_S3_DIR global El directorio S3
BACKUP_S3_REGION global La región S3
BACKUP_S3_ACCESS_KEY_ID global El ID de la clave de acceso S3
BACKUP_S3_ACCESS_KEY_SECRET global El secreto de la clave de acceso S3
BACKUP_S3_COMP_LEVEL 6 global El nivel de compresión del archivo zip de la copia de seguridad

Copia de seguridad manual

Para iniciar manualmente una copia de seguridad, ejecuta el siguiente comando:

bwcli plugin backup_s3 save

docker exec -it <scheduler_container> bwcli plugin backup_s3 save

Este comando creará una copia de seguridad de tu base de datos y la almacenará en el bucket S3 especificado en la configuración BACKUP_S3_BUCKET.

También puedes especificar un bucket S3 personalizado para la copia de seguridad proporcionando la variable de entorno BACKUP_S3_BUCKET al ejecutar el comando:

BACKUP_S3_BUCKET=your-bucket-name bwcli plugin backup_s3 save

docker exec -it -e BACKUP_S3_BUCKET=your-bucket-name <scheduler_container> bwcli plugin backup_s3 save

Compatibilidad del cliente MariaDB/MySQL

Las imágenes Docker de BunkerWeb incluyen los plugins de autenticación de MariaDB Connector/C que requiere caching_sha2_password de MySQL. En Linux, si el cliente indica que no se pudo cargar caching_sha2_password, instala los plugins de autenticación de MariaDB Connector/C de tu distribución o un cliente MySQL compatible. No cambies la cuenta de la base de datos a mysql_native_password, ya que no está disponible en MySQL v9.

Restauración manual

Para iniciar manualmente una restauración, ejecuta el siguiente comando:

bwcli plugin backup_s3 restore

docker exec -it <scheduler_container> bwcli plugin backup_s3 restore

Este comando creará una copia de seguridad temporal de tu base de datos en el bucket S3 especificado en la configuración BACKUP_S3_BUCKET y restaurará tu base de datos a la última copia de seguridad disponible en el bucket.

También puedes especificar un archivo de copia de seguridad personalizado para la restauración proporcionando la ruta al mismo como argumento al ejecutar el comando:

bwcli plugin backup_s3 restore s3_backup_file.zip

docker exec -it <scheduler_container> bwcli plugin backup restore s3_backup_file.zip

En caso de fallo

No te preocupes si la restauración falla, siempre puedes restaurar tu base de datos al estado anterior ejecutando el comando de nuevo, ya que se crea una copia de seguridad antes de la restauración:

bwcli plugin backup_s3 restore

docker exec -it <scheduler_container> bwcli plugin backup_s3 restore

Servidor MCP

El servidor MCP de BunkerWeb permite que asistentes de IA como Claude Code y Claude Desktop gestionen tu instalación de BunkerWeb a través del Model Context Protocol (MCP).

Requisito

El servidor MCP requiere que la API externa de BunkerWeb (bunkerity/bunkerweb-api) esté desplegada. Se comunica con BunkerWeb exclusivamente a través de esta API.

Características

  • 43 herramientas para gestionar instancias, servicios, configuraciones, baneos, plugins, jobs y caché
  • Recursos MCP para acceso de solo lectura (@config://global, @bans://active, etc.)
  • Múltiples transportes: Stdio, HTTP, WebSocket

Ejemplo de Docker Compose

Un ejemplo completo está disponible en examples/mcp-stack/:

services:
  bw-api:
    image: bunkerity/bunkerweb-api:1.6.18-rc1
    environment:
      API_TOKEN: "my-bearer-token-for-mcp"
      DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db"
      FORWARDED_ALLOW_IPS: "127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
    networks:
      - bw-universe
      - bw-db
      - bw-mcp

  bw-mcp:
    image: bunkerity/bunkerweb-mcp:0.2.0
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      BUNKERWEB_BASE_URL: "http://bw-api:8888"
      BUNKERWEB_API_TOKEN: "my-bearer-token-for-mcp"
      BUNKERWEB_LOG_LEVEL: INFO
    networks:
      - bw-mcp

Uso con Claude Code

Añade un archivo .mcp.json en la raíz de tu proyecto (o en ~/.claude/.mcp.json para una configuración global):

{
  "mcpServers": {
    "bunkerweb": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp/"
    }
  }
}

Ejemplos de consultas:

> Lista todas las instancias de BunkerWeb
> Muéstrame los baneos actuales
> Analiza @config://global y sugiere mejoras de seguridad

Integración con Kubernetes

El servidor MCP se puede desplegar junto con BunkerWeb utilizando el chart Helm oficial. Un ejemplo completo está disponible en examples/mcp-integration.yaml.

Valores de Helm

mcp:
  # Habilitar el servidor MCP
  enabled: true

  # Configuración de la imagen del contenedor
  repository: docker.io/bunkerity/bunkerweb-mcp
  tag: 0.2.0

  # Configuración del servidor MCP
  config:
    logLevel: "INFO"
    enableDnsRebindingProtection: true
    allowedHosts: "localhost,127.0.0.1,mcp.example.com"
    cacheEnabled: true

  # Credenciales para la autenticación del MCP con la API de BunkerWeb
  secrets:
    bunkerwebApiToken: "tu-token-api-seguro"

  # Configuración de Ingress (opcional)
  ingress:
    enabled: false
    ingressClassName: "bunkerweb"
    serverName: "mcp.example.com"
    annotations:
      bunkerweb.io/AUTO_LETS_ENCRYPT: "yes"
      bunkerweb.io/USE_REVERSE_PROXY: "yes"
      bunkerweb.io/REVERSE_PROXY_URL: "/"
      bunkerweb.io/REVERSE_PROXY_HOST: "http://mcp-bunkerweb.bunkerweb.svc.cluster.local:8080"
      # SEGURIDAD: Restringir el acceso solo a IPs de confianza
      bunkerweb.io/USE_WHITELIST: "yes"
      bunkerweb.io/WHITELIST_IP: "10.0.0.0/8 192.168.0.0/16"

Despliegue

# Desplegar BunkerWeb con MCP habilitado
helm install bunkerweb bunkerweb/bunkerweb -f mcp-integration.yaml

# Acceder al MCP localmente via port-forward (recomendado para seguridad)
kubectl port-forward svc/mcp-bunkerweb 8080:8080

# Configurar Claude Code con http://localhost:8080/mcp

Seguridad

El servidor MCP no tiene autenticación integrada para el endpoint /mcp. Asegura el acceso usando:

  • Lista blanca de IPs mediante anotaciones de BunkerWeb (USE_WHITELIST, WHITELIST_IP)
  • Políticas de red para restringir la comunicación entre pods
  • Port-forward en lugar de exponer externamente (recomendado para desarrollo)

Para la documentación completa, visita el repositorio BunkerWeb MCP.

Migración crown pro icon (PRO)

Soporte STREAM ✅

El plugin de Migración revoluciona las transferencias de configuración de BunkerWeb entre instancias con su interfaz web fácil de usar, simplificando todo el proceso de migración. Ya sea que estés actualizando sistemas, escalando la infraestructura o haciendo la transición de entornos, esta herramienta te permite transferir sin esfuerzo configuraciones, preferencias y datos con una facilidad y confianza inigualables. Di adiós a los engorrosos procesos manuales y hola a una experiencia de migración fluida y sin complicaciones.

Lista de características

  • Migración sin esfuerzo: Transfiere fácilmente las configuraciones de BunkerWeb entre instancias sin las complejidades de los procedimientos manuales.

  • Interfaz web intuitiva: Navega por el proceso de migración sin esfuerzo con una interfaz web fácil de usar diseñada para una operación intuitiva.

  • Compatibilidad entre bases de datos: Disfruta de una migración fluida a través de varias plataformas de bases de datos, incluidas SQLite, MySQL, MariaDB y PostgreSQL, lo que garantiza la compatibilidad con tu entorno de base de datos preferido.

Crear un archivo de migración

Para crear manualmente un archivo de migración, ejecuta el siguiente comando:

bwcli plugin migration create /path/to/migration/file

  1. Crear un archivo de migración:

    docker exec -it <scheduler_container> bwcli plugin migration create /path/to/migration/file

  2. Copiar el archivo de migración a tu máquina local:

    docker cp <scheduler_container>:/path/to/migration/file /path/to/migration/file

Este comando creará una copia de seguridad de tu base de datos y la almacenará en el directorio de copia de seguridad especificado en el comando.

Compatibilidad del cliente MariaDB/MySQL

Las imágenes Docker de BunkerWeb incluyen los plugins de autenticación de MariaDB Connector/C que requiere caching_sha2_password de MySQL. En Linux, si el cliente indica que no se pudo cargar caching_sha2_password, instala los plugins de autenticación de MariaDB Connector/C de tu distribución o un cliente MySQL compatible. No cambies la cuenta de la base de datos a mysql_native_password, ya que no está disponible en MySQL v9.

Iniciar una migración

Para iniciar manualmente una migración, ejecuta el siguiente comando:

bwcli plugin migration migrate /path/to/migration/file

  1. Copia el archivo de migración al contenedor:

    docker cp /path/to/migration/file <scheduler_container>:/path/to/migration/file

  2. Inicia la migración:

    docker exec -it <scheduler_container> bwcli plugin migration migrate /path/to/migration/file

  1. Copia el archivo de migración al contenedor:

    docker cp /path/to/migration/file bunkerweb-aio:/path/to/migration/file

  2. Inicia la migración:

    docker exec -it bunkerweb-aio bwcli plugin migration migrate /path/to/migration/file

Este comando migra sin problemas tus datos de BunkerWeb para que coincidan precisamente con la configuración descrita en el archivo de migración.

Anti DDoS crown pro icon (PRO)

Soporte STREAM ❌

El plugin Anti DDoS proporciona protección avanzada contra ataques de denegación de servicio distribuido (DDoS) mediante el monitoreo, análisis y filtrado de tráfico sospechoso en tiempo real.

Mediante el empleo de un mecanismo de ventana deslizante, el plugin mantiene un diccionario en memoria de las marcas de tiempo de las solicitudes para detectar picos de tráfico anormales de direcciones IP individuales. Según el modo de seguridad configurado, puede bloquear las conexiones ofensivas o registrar la actividad sospechosa para una revisión posterior.

Características

  • Análisis de tráfico en tiempo real: Monitorea continuamente las solicitudes entrantes para detectar posibles ataques DDoS.
  • Mecanismo de ventana deslizante: Rastrea la actividad de solicitudes recientes dentro de una ventana de tiempo configurable.
  • Umbrales configurables: Te permite definir el número máximo de solicitudes sospechosas por IP.
  • Lógica de bloqueo avanzada: Evalúa tanto el recuento de solicitudes por IP como el número de IP distintas que superan el umbral.
  • Modos de seguridad flexibles: Elige entre el bloqueo inmediato de la conexión o el modo de solo detección (registro).
  • Almacén de datos en memoria optimizado: Garantiza búsquedas de alta velocidad y un seguimiento eficiente de las métricas.
  • Mantenimiento automático: Borra periódicamente los datos obsoletos para mantener un rendimiento óptimo.

Configuración

Personaliza el comportamiento del plugin usando las siguientes configuraciones:

Configuración Predeterminado Contexto Múltiple Descripción
USE_ANTIDDOS no global no Habilita o deshabilita la protección Anti DDoS. Establécelo en "yes" para activar el plugin.
ANTIDDOS_METRICS_DICT_SIZE 10M global no Tamaño del almacén de datos en memoria para el seguimiento de métricas de DDoS (p. ej., 10M, 500k).
ANTIDDOS_THRESHOLD 100 global no Número máximo de solicitudes sospechosas permitidas por IP dentro de la ventana de tiempo definida.
ANTIDDOS_WINDOW_TIME 10 global no Ventana de tiempo en segundos durante la cual se cuentan las solicitudes sospechosas.
ANTIDDOS_STATUS_CODES 429 403 444 global no Códigos de estado HTTP considerados sospechosos y utilizados para activar acciones anti-DDoS.
ANTIDDOS_DISTINCT_IP 5 global no Número mínimo de IP distintas que deben superar el umbral antes de aplicar el modo de bloqueo.

Mejores prácticas

  • Ajuste de umbrales: Ajusta ANTIDDOS_THRESHOLD y ANTIDDOS_WINDOW_TIME según tus patrones de tráfico típicos.
  • Revisión de códigos de estado: Actualiza regularmente ANTIDDOS_STATUS_CODES para capturar comportamientos sospechosos nuevos o en evolución.
  • Monitoreo: Analiza los registros y las métricas periódicamente para ajustar la configuración y mejorar la protección general.

User Manager crown pro icon (PRO)

Soporte STREAM ❌

El plugin User Manager ofrece una interfaz robusta para administrar cuentas de usuario dentro de su sistema.

Con este plugin, los administradores pueden crear, actualizar y deshabilitar cuentas de usuario sin esfuerzo, gestionar roles de usuario, activar o desactivar la autenticación de dos factores (2FA) y ver información detallada del usuario, como las marcas de tiempo del último inicio de sesión y los estados de la cuenta (activa o inactiva). Diseñado teniendo en cuenta la seguridad y la facilidad de uso, este plugin simplifica las tareas rutinarias de gestión de usuarios al tiempo que garantiza el cumplimiento y la auditabilidad.

Características

  • Operaciones de cuenta de usuario: Importar en formato CSV/XLSX, crear, editar y eliminar cuentas de usuario con facilidad.
  • Control de acceso basado en roles: Asignar y modificar roles de usuario para gestionar permisos y niveles de acceso.
  • Gestión de 2FA: Desactivar la autenticación de dos factores según las decisiones administrativas.
  • Información completa del usuario: Supervisar los datos clave del usuario, incluidos los últimos tiempos de inicio de sesión, las fechas de creación de la cuenta y el estado activo/inactivo.
  • Registro de auditoría: Mantener un registro de auditoría de todas las acciones de gestión de usuarios para mejorar la seguridad y el cumplimiento.

Configuración

Configuración Predeterminado Contexto Múltiple Descripción
USERS_REQUIRE_2FA no global no Exigir autenticación de dos factores a todos los usuarios.

Descripción general

Página de User Manager

Formulario de creación de usuario

User Manager - Formulario de creación de usuario

Página de actividades

User Manager - Página de actividades

UI Single Sign-On crown pro icon (PRO)

Soporte STREAM ❌

El plugin UI Single Sign-On habilita la autenticación SSO para la interfaz web de BunkerWeb leyendo cabeceras establecidas por un proxy de autenticación externo (como Authentik, Authelia, Keycloak o Traefik Forward Auth) ubicado delante de la interfaz web.

En lugar de gestionar credenciales separadas para BunkerWeb, los administradores pueden delegar la autenticación a un proveedor de identidad existente. El proxy de autenticación gestiona el inicio de sesión del usuario e inyecta cabeceras de identidad antes de reenviar las solicitudes a la interfaz web de BunkerWeb.

Riesgo de suplantación de cabeceras

Las cabeceras SSO pueden ser falsificadas fácilmente por cualquier cliente. Debe restringir UI_SSO_TRUSTED_IPS a la(s) dirección(es) IP de su proxy de autenticación. Si este ajuste está mal configurado, cualquier cliente puede enviar cabeceras falsas y obtener acceso no autorizado, incluido acceso de administrador.

El valor predeterminado 127.0.0.1,::1 solo confía en localhost. En despliegues Docker, Swarm o Kubernetes, el proxy de autenticación se ejecuta en un contenedor independiente con su propia IP. Establezca UI_SSO_TRUSTED_IPS con la IP real o CIDR del contenedor del proxy de autenticación (p. ej. 10.20.30.5 o 172.18.0.0/16). Nunca lo establezca como 0.0.0.0/0.

Características

  • Autenticación basada en cabeceras: lee nombre de usuario, correo electrónico, nombre para mostrar y grupos desde las cabeceras del proxy de autenticación.
  • Asignación de grupo a rol: mapea grupos del IdP a roles de BunkerWeb (admin, writer, reader).
  • Aprovisionamiento automático de usuarios: crea cuentas locales en el primer inicio de sesión SSO con rol predeterminado configurable.
  • Vinculación de cuentas: asocia usuarios SSO entrantes con cuentas locales existentes por nombre de usuario o correo electrónico.
  • Aplicación de IP de confianza: solo acepta cabeceras SSO desde direcciones IP o rangos CIDR configurados.
  • Respaldo al inicio de sesión normal: permite opcionalmente el inicio de sesión con contraseña cuando las cabeceras SSO no están presentes.
  • Redirección de cierre de sesión: redirige a los usuarios al endpoint de cierre de sesión del proveedor SSO tras el cierre de sesión local.

Configuración

Configuración Predeterminado Contexto Múltiple Descripción
USE_UI_SSO no global no Habilitar o deshabilitar la autenticación UI Single Sign-On para la interfaz web.
UI_SSO_HEADER_USERNAME X-User global no Cabecera HTTP que contiene el nombre de usuario autenticado.
UI_SSO_HEADER_EMAIL X-Email global no Cabecera HTTP que contiene la dirección de correo electrónico del usuario.
UI_SSO_HEADER_GROUPS X-Groups global no Cabecera HTTP que contiene los grupos del usuario (separados por coma o espacio).
UI_SSO_HEADER_NAME X-Name global no Cabecera HTTP que contiene el nombre para mostrar del usuario.
UI_SSO_TRUSTED_IPS 127.0.0.1,::1 global no Lista separada por comas de direcciones IP o rangos CIDR de confianza para enviar cabeceras SSO.
UI_SSO_AUTO_CREATE_USERS yes global no Crear automáticamente nuevos usuarios la primera vez que se autentican mediante SSO.
UI_SSO_DEFAULT_ROLE reader global no Rol predeterminado asignado a nuevos usuarios SSO cuando no coincide ningún mapeo de grupo.
UI_SSO_GROUP_ADMIN global no Nombre del grupo que otorga el rol admin (máxima prioridad).
UI_SSO_GROUP_WRITER global no Nombre del grupo que otorga el rol writer.
UI_SSO_GROUP_READER global no Nombre del grupo que otorga el rol reader.
UI_SSO_FALLBACK_TO_LOGIN yes global no Permitir a los usuarios volver al inicio de sesión normal cuando las cabeceras SSO no están presentes.
UI_SSO_UPDATE_USER_ON_LOGIN yes global no Actualizar la información del usuario (correo, rol) desde las cabeceras SSO en cada inicio de sesión.
UI_SSO_ACCOUNT_LINKING username_or_email global no Cómo asociar usuarios SSO entrantes con cuentas locales (username_only o username_or_email).
UI_SSO_LOGOUT_REDIRECT_URL global no URL de redirección tras el cierre de sesión (p. ej. endpoint de logout del proveedor SSO).

Inicio rápido

  1. Coloque un proxy de autenticación (Authentik, Authelia, Keycloak, etc.) delante de la interfaz web de BunkerWeb.
  2. Habilite el plugin: USE_UI_SSO=yes.
  3. Asegúrese de que el proxy establece las cabeceras esperadas (X-User, X-Email, X-Groups, X-Name) -- o ajuste los nombres de las cabeceras mediante los ajustes UI_SSO_HEADER_*.
  4. Restrinja las fuentes de confianza: establezca UI_SSO_TRUSTED_IPS con la(s) dirección(es) IP del proxy de autenticación.
  5. Mapee grupos a roles: establezca UI_SSO_GROUP_ADMIN, UI_SSO_GROUP_WRITER y UI_SSO_GROUP_READER para que coincidan con los nombres de grupo de su IdP.

Consejos de uso

  • Establezca UI_SSO_FALLBACK_TO_LOGIN=no en producción para imponer acceso exclusivo por SSO. Cuando se deja en yes (valor predeterminado), los usuarios pueden eludir el SSO e iniciar sesión con credenciales locales, omitiendo cualquier MFA o política de sesión aplicada por su proveedor de identidad.
  • Mantenga UI_SSO_UPDATE_USER_ON_LOGIN en su valor predeterminado (yes) para garantizar que los roles permanezcan sincronizados con los cambios de grupo en el IdP.
  • Al usar UI_SSO_ACCOUNT_LINKING=username_or_email, las cuentas locales existentes se vinculan automáticamente en el primer inicio de sesión SSO si el nombre de usuario o correo electrónico coincide. Use username_only si su IdP permite a los usuarios establecer direcciones de correo electrónico arbitrarias, para prevenir la toma de cuentas mediante suplantación de correo electrónico.

Easy Resolve crown pro icon (PRO)

El plugin Easy Resolve te permite remediar rápidamente falsos positivos y problemas recurrentes directamente desde la página de Informes. Convierte las acciones guiadas de "Resolver" en actualizaciones de configuración seguras y acotadas, sin edición manual.

Características

  • Acciones con un solo clic desde Informes y detalles del informe.
  • Sugerencias contextuales para ModSecurity, lista negra, DNSBL, limitación de velocidad, métodos HTTP permitidos y países en lista blanca/negra.
  • Genera exclusiones seguras de ModSecurity o actualiza las listas de ignorados.
  • Aplica cambios a nivel de servicio o global con comprobaciones de permisos.
  • Apertura automática opcional de la página de configuración relacionada después de aplicar.

Descripción general

Página de informes - con Easy Resolve

Load Balancer crown pro icon (PRO)

El Plugin de Load Balancer convierte BunkerWeb en un director de tráfico con guardarraíles. Declare pools upstream una vez, apunte su proxy inverso a ellos, y deje que el balanceo consciente de salud mantenga a los usuarios en backends responsivos. El modo sticky cookie emite automáticamente una cookie BWLBID para que las sesiones se mantengan ancladas donde quiera.

Características

  • Bloques por upstream: nombre pools y reutilícelos en hosts de proxy inverso.
  • Balanceo flexible: round-robin por defecto, o sticky vía IP o cookie firmado.
  • Objetivos inteligentes: resolución DNS opcional para backends de hostname más ajuste de keepalive.
  • Salud integrada: sondas HTTP/HTTPS con rutas personalizadas, intervalos, códigos de estado y verificaciones SSL.
  • Continuidad de sesión: cookie BWLBID automática cuando se habilita el modo sticky-cookie.

Configuración

Definición de upstream

Configuración Predeterminado Contexto Múltiple Descripción
LOADBALANCER_UPSTREAM_NAME global sí Identificador upstream (referenciado por REVERSE_PROXY_HOST).
LOADBALANCER_UPSTREAM_SERVERS global sí Lista separada por espacios de direcciones backend (ej. 10.0.0.1:8080 10.0.0.2:8080).
LOADBALANCER_UPSTREAM_MODE round-robin global sí Estrategia de balanceo (round-robin o sticky).
LOADBALANCER_UPSTREAM_STICKY_METHOD ip global sí Método sticky (ip o cookie). Modo cookie emite BWLBID.
LOADBALANCER_UPSTREAM_RESOLVE no global sí Resolver hostnames upstream vía DNS.
LOADBALANCER_UPSTREAM_KEEPALIVE global sí Conexiones keepalive por worker.
LOADBALANCER_UPSTREAM_KEEPALIVE_TIMEOUT 60s global sí Timeout inactivo para conexiones keepalive.
LOADBALANCER_UPSTREAM_KEEPALIVE_TIME 1h global sí Vida máxima para conexiones keepalive.

Verificaciones de salud

Configuración Predeterminado Contexto Múltiple Descripción
LOADBALANCER_HEALTHCHECK_DICT_SIZE 10m global no Tamaño de diccionario compartido para estado de verificación de salud.
LOADBALANCER_HEALTHCHECK_URL /status global sí Ruta para sondear en cada backend.
LOADBALANCER_HEALTHCHECK_INTERVAL 2000 global sí Intervalo entre verificaciones (ms).
LOADBALANCER_HEALTHCHECK_TIMEOUT 1000 global sí Timeout por verificación (ms).
LOADBALANCER_HEALTHCHECK_FALL 3 global sí Fallos consecutivos antes de marcar como down.
LOADBALANCER_HEALTHCHECK_RISE 1 global sí Éxitos consecutivos antes de marcar como up.
LOADBALANCER_HEALTHCHECK_VALID_STATUSES 200 global sí Lista separada por espacios de códigos de estado HTTP válidos.
LOADBALANCER_HEALTHCHECK_CONCURRENCY 10 global sí Máximo de sondas concurrentes.
LOADBALANCER_HEALTHCHECK_TYPE http global sí Protocolo para verificaciones de salud (http o https).
LOADBALANCER_HEALTHCHECK_SSL_VERIFY yes global sí Verificar certificados TLS al usar verificaciones HTTPS.
LOADBALANCER_HEALTHCHECK_HOST global sí Sobrescribir header Host durante verificaciones (útil para SNI).

Inicio rápido

  1. Defina su pool: configure LOADBALANCER_UPSTREAM_NAME=my-app y liste objetivos en LOADBALANCER_UPSTREAM_SERVERS (ej. 10.0.0.1:8080 10.0.0.2:8080).
  2. Dirija tráfico: configure REVERSE_PROXY_HOST=http://my-app para que el proxy inverso use el upstream nombrado.
  3. Elija un modo: mantenga round-robin por defecto o configure LOADBALANCER_UPSTREAM_MODE=sticky con LOADBALANCER_UPSTREAM_STICKY_METHOD=cookie o ip.
  4. Agregue salud: mantenga /status o ajuste URLs, intervalos y estados válidos para reflejar el comportamiento de su app.
  5. Ajuste conexiones: configure valores keepalive para reutilizar conexiones backend y reducir sobrecarga de handshake.

Consejos de uso

  • Haga coincidir REVERSE_PROXY_HOST con LOADBALANCER_UPSTREAM_NAME al usar cookies sticky para que los clientes se fijen al pool correcto.
  • Mantenga intervalos y timeouts de verificación de salud balanceados para evitar fluctuaciones en enlaces lentos.
  • Habilite LOADBALANCER_UPSTREAM_RESOLVE cuando apunte a hostnames que puedan cambiar vía DNS.
  • Ajuste valores keepalive para reflejar capacidad backend y objetivos de reutilización de conexiones.

Custom Pages crown pro icon (PRO)

El plugin Custom Pages le permite reemplazar las páginas integradas de BunkerWeb (páginas de error, página del servidor por defecto y páginas de desafío antibot) con sus propias plantillas HTML o Lua personalizadas. Esto le permite mantener una marca consistente en todas las páginas orientadas al usuario servidas por BunkerWeb.

Para obtener información sobre el comportamiento y la personalización de Maintenance, consulte la guía avanzada de Maintenance.

Características

  • Páginas de error personalizadas por servicio y páginas de desafío antibot (captcha, verificación JavaScript, reCAPTCHA, hCaptcha, Turnstile, mCaptcha, Cap.js).
  • Página del servidor por defecto personalizada global para el vhost de respaldo/por defecto.
  • Análisis HTML y verificaciones de balance de etiquetas de plantilla Lua antes de que una plantilla sea aceptada.
  • Caché automático a /var/cache/bunkerweb/custom_pages con detección de cambios para activar recargas.
  • Configuración por sitio o global a través de configuraciones/UI o variables de entorno.

Cómo funciona

  1. Al iniciar (o cuando cambian las configuraciones), el job custom-pages.py lee las rutas de plantilla configuradas.
  2. Cada archivo debe existir y ser legible por el scheduler; el job valida la estructura HTML y el balance de etiquetas de plantilla Lua ({% %}, {{ }}, {* *}).
  3. Los archivos aceptados se almacenan en caché bajo /var/cache/bunkerweb/custom_pages/<type>.html; configuraciones faltantes/vacías eliminan el archivo en caché.
  4. NGINX apunta al directorio de caché vía $template_root cuando existe al menos una página en caché, de modo que sus plantillas se sirven en lugar de las predeterminadas.

Configuraciones

Configuración Predeterminado Contexto Descripción
CUSTOM_MAINTENANCE_PAGE multisite Ruta absoluta a la plantilla de página de mantenimiento personalizada.
CUSTOM_ERROR_PAGE multisite Ruta absoluta a la plantilla de página de error personalizada.
CUSTOM_DEFAULT_SERVER_PAGE global Ruta absoluta a la plantilla de página del servidor por defecto personalizada.
CUSTOM_ANTIBOT_CAPTCHA_PAGE multisite Ruta absoluta a la página de desafío CAPTCHA antibot personalizada.
CUSTOM_ANTIBOT_JAVASCRIPT_PAGE multisite Ruta absoluta a la página de verificación JavaScript antibot personalizada.
CUSTOM_ANTIBOT_RECAPTCHA_PAGE multisite Ruta absoluta a la página reCAPTCHA antibot personalizada.
CUSTOM_ANTIBOT_HCAPTCHA_PAGE multisite Ruta absoluta a la página hCaptcha antibot personalizada.
CUSTOM_ANTIBOT_TURNSTILE_PAGE multisite Ruta absoluta a la página Turnstile antibot personalizada.
CUSTOM_ANTIBOT_MCAPTCHA_PAGE multisite Ruta absoluta a la página mCaptcha antibot personalizada.
CUSTOM_ANTIBOT_CAPJS_PAGE multisite Ruta absoluta a la página Cap.js antibot personalizada.

Referencia de variables de plantilla

Las plantillas de BunkerWeb usan el motor lua-resty-template. Las siguientes variables están disponibles según el tipo de página:

Variables de página de error

Estas variables están disponibles en plantillas de página de error personalizadas (CUSTOM_ERROR_PAGE):

Variable Tipo Descripción
title string Título completo de la página (ej. 403 - Forbidden)
error_title string Texto del título de error (ej. Forbidden)
error_code string Código de estado HTTP (ej. 403, 404, 500)
error_text string Mensaje de error descriptivo
error_type string Categoría de error: client (4xx) o server (5xx)
error_solution string Texto de solución sugerida
nonce_script string Valor nonce para etiquetas <script> inline (cumplimiento CSP)
nonce_style string Valor nonce para etiquetas <style> inline (cumplimiento CSP)
request_id string Identificador de solicitud único para depuración
client_ip string Dirección IP del cliente
request_time string Marca de tiempo de la solicitud (formato: YYYY-MM-DD HH:MM:SS UTC)

Variables de página del servidor por defecto

Estas variables están disponibles en plantillas de página del servidor por defecto personalizadas (CUSTOM_DEFAULT_SERVER_PAGE):

Variable Tipo Descripción
nonce_style string Valor nonce para etiquetas <style> inline (cumplimiento CSP)

Variables de página de desafío antibot

Estas variables están disponibles en plantillas de página de desafío antibot:

Variables comunes (todas las páginas antibot):

Variable Tipo Descripción
antibot_uri string URI de acción del formulario para enviar el desafío
nonce_script string Valor nonce para etiquetas <script> inline (cumplimiento CSP)
nonce_style string Valor nonce para etiquetas <style> inline (cumplimiento CSP)

Desafío JavaScript (CUSTOM_ANTIBOT_JAVASCRIPT_PAGE):

Variable Tipo Descripción
random string Cadena aleatoria usada para resolución proof-of-work

Captcha (CUSTOM_ANTIBOT_CAPTCHA_PAGE):

Variable Tipo Descripción
captcha string Imagen captcha codificada en Base64 (formato JPEG)

reCAPTCHA (CUSTOM_ANTIBOT_RECAPTCHA_PAGE):

Variable Tipo Descripción
recaptcha_sitekey string Su clave de sitio reCAPTCHA
recaptcha_classic boolean true si usa reCAPTCHA clásico, false para v3

hCaptcha (CUSTOM_ANTIBOT_HCAPTCHA_PAGE):

Variable Tipo Descripción
hcaptcha_sitekey string Su clave de sitio hCaptcha

Turnstile (CUSTOM_ANTIBOT_TURNSTILE_PAGE):

Variable Tipo Descripción
turnstile_sitekey string Su clave de sitio Cloudflare Turnstile

mCaptcha (CUSTOM_ANTIBOT_MCAPTCHA_PAGE):

Variable Tipo Descripción
mcaptcha_sitekey string Su clave de sitio mCaptcha
mcaptcha_url string Su URL de mCaptcha

Cap.js (CUSTOM_ANTIBOT_CAPJS_PAGE):

Variable Tipo Descripción
capjs_sitekey string Su clave de sitio Cap.js
capjs_url string URL base del frontend de Cap.js

Sintaxis de plantilla

Las plantillas usan sintaxis de plantilla Lua con los siguientes delimitadores:

  • {{ variable }} – Mostrar una variable (escapada HTML)
  • {* variable *} – Mostrar una variable (sin procesar, sin escapar)
  • {% lua_code %} – Ejecutar código Lua (condicionales, bucles, etc.)
  • {-raw-} ... {-raw-} – Bloque sin procesar (sin procesamiento)

Importante: Siempre use atributos nonce para scripts y estilos inline para cumplir con la Content Security Policy (CSP):

<style nonce="{*nonce_style*}">
  /* Su CSS aquí */
</style>
<script nonce="{*nonce_script*}">
  // Su JavaScript aquí
</script>

Ejemplos

Cree una plantilla de página de error personalizada en /etc/bunkerweb/templates/error.html:

{-raw-}<!doctype html>
<html lang="es">
  <head>
    <meta charset="utf-8" />
    <title>{{ title }}</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    {-raw-}
    <style nonce="{*nonce_style*}">
      body {
        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
        display: flex;
        justify-content: center;
        align-items: center;
        min-height: 100vh;
        margin: 0;
        background: #f5f5f5;
        color: #333;
      }
      .container {
        text-align: center;
        padding: 2rem;
      }
      .error-code {
        font-size: 6rem;
        font-weight: bold;
        color: {% if error_type == "server" %}#dc3545{% else %}#ffc107{% end %};
        margin: 0;
      }
      .error-title {
        font-size: 1.5rem;
        margin: 1rem 0;
      }
      .error-text {
        color: #666;
        margin-bottom: 1rem;
      }
      .request-info {
        font-size: 0.8rem;
        color: #999;
        margin-top: 2rem;
      }
    </style>
    {-raw-}
  </head>
  <body>
    <div class="container">
      <p class="error-code">{{ error_code }}</p>
      <h1 class="error-title">{{ error_title }}</h1>
      <p class="error-text">{{ error_text }}</p>
      <p class="error-text">{{ error_solution }}</p>
      <div class="request-info">
        {% if request_id %}
        <p>ID de solicitud: <code>{{ request_id }}</code></p>
        {% end %}
        {% if request_time %}
        <p>Hora: {{ request_time }}</p>
        {% end %}
      </div>
    </div>
  </body>
</html>
{-raw-}

Cree una página de desafío captcha personalizada en /etc/bunkerweb/templates/captcha.html:

{-raw-}<!doctype html>
<html lang="es">
  <head>
    <meta charset="utf-8" />
    <title>Verificación de seguridad</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    {-raw-}
    <style nonce="{*nonce_style*}">
      body {
        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
        display: flex;
        justify-content: center;
        align-items: center;
        min-height: 100vh;
        margin: 0;
        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      }
      .card {
        background: white;
        padding: 2rem;
        border-radius: 1rem;
        box-shadow: 0 10px 40px rgba(0,0,0,0.2);
        text-align: center;
        max-width: 400px;
      }
      h1 {
        color: #333;
        margin-bottom: 1rem;
      }
      .captcha-img {
        margin: 1rem 0;
        border-radius: 0.5rem;
      }
      input[type="text"] {
        width: 100%;
        padding: 0.75rem;
        font-size: 1.2rem;
        border: 2px solid #ddd;
        border-radius: 0.5rem;
        text-align: center;
        box-sizing: border-box;
      }
      button {
        margin-top: 1rem;
        padding: 0.75rem 2rem;
        font-size: 1rem;
        background: #667eea;
        color: white;
        border: none;
        border-radius: 0.5rem;
        cursor: pointer;
      }
      button:hover {
        background: #5a6fd6;
      }
    </style>
    {-raw-}
  </head>
  <body>
    <div class="card">
      <h1>🔒 Verificación de seguridad</h1>
      <p>Por favor ingrese el texto que ve abajo para continuar.</p>
      {-raw-}
      <form method="POST" action="{*antibot_uri*}">
        <img class="captcha-img" src="data:image/jpeg;base64,{*captcha*}" alt="Captcha" />
        {-raw-}
        <input type="text" name="captcha" placeholder="Ingrese el código" required autocomplete="off" />
        <button type="submit">Verificar</button>
      </form>
    </div>
  </body>
</html>
{-raw-}

Cree una página del servidor por defecto personalizada en /etc/bunkerweb/templates/default.html:

{-raw-}<!doctype html>
<html lang="es">
  <head>
    <meta charset="utf-8" />
    <title>Bienvenido</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    {-raw-}
    <style nonce="{*nonce_style*}">
      body {
        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
        display: flex;
        justify-content: center;
        align-items: center;
        min-height: 100vh;
        margin: 0;
        background: #1a1a2e;
        color: #eee;
      }
      .container {
        text-align: center;
      }
      h1 {
        font-size: 3rem;
        margin-bottom: 0.5rem;
      }
      p {
        color: #888;
      }
    </style>
    {-raw-}
  </head>
  <body>
    <div class="container">
      <h1>🛡️ Protegido por BunkerWeb</h1>
      <p>Este servidor está seguro y listo.</p>
    </div>
  </body>
</html>
{-raw-}

Ejemplos de despliegue

  1. Cree sus archivos de plantilla en un directorio de su elección (ej. /opt/bunkerweb/templates/):

    sudo mkdir -p /opt/bunkerweb/templates
sudo nano /opt/bunkerweb/templates/error.html
# Pegue su plantilla de página de error personalizada

  2. Configure BunkerWeb editando /etc/bunkerweb/variables.env:

    # Página de error personalizada para todos los servicios (o use por servicio con prefijo)
CUSTOM_ERROR_PAGE=/opt/bunkerweb/templates/error.html

# Página del servidor por defecto personalizada (solo global)
CUSTOM_DEFAULT_SERVER_PAGE=/opt/bunkerweb/templates/default.html

# Página captcha personalizada (por servicio o global)
CUSTOM_ANTIBOT_CAPTCHA_PAGE=/opt/bunkerweb/templates/captcha.html

  3. Recargue el scheduler de BunkerWeb para que tome las nuevas plantillas:

    sudo systemctl reload bunkerweb-scheduler

El scheduler es responsable de leer, validar y almacenar en caché sus plantillas personalizadas. Solo el scheduler necesita acceso a los archivos de plantilla—BunkerWeb recibe la configuración validada automáticamente.

  1. Cree sus archivos de plantilla en un directorio local (ej. ./templates/) y establezca los permisos correctos:

    mkdir templates && \
chown root:101 templates && \
chmod 770 templates

    ¿Por qué UID/GID 101?

    El contenedor scheduler se ejecuta como un usuario sin privilegios con UID 101 y GID 101. El directorio debe ser legible por este usuario para que el scheduler pueda acceder a sus plantillas.

    Si la carpeta ya existe:

    chown -R root:101 templates && \
chmod -R 770 templates

    Al usar Docker en modo rootless o Podman, los UID/GID de contenedor se remapean. Verifique sus rangos subuid/subgid:

    grep ^$(whoami): /etc/subuid && \
grep ^$(whoami): /etc/subgid

    Por ejemplo, si el rango comienza en 100000, el GID efectivo se convierte en 100100 (100000 + 100):

    mkdir templates && \
sudo chgrp 100100 templates && \
chmod 770 templates

  2. Monte el directorio de plantillas al scheduler y configure los ajustes en el scheduler (el scheduler actúa como gestor y distribuye la configuración a los workers de BunkerWeb). Puede montar las plantillas en cualquier ruta dentro del contenedor:

    services:
  bunkerweb:
    image: bunkerity/bunkerweb:1.6.18-rc1
    # ... otras configuraciones (no se necesitan variables de entorno aquí para páginas personalizadas)

  bw-scheduler:
    image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
    volumes:
      - ./templates:/custom_templates:ro
    environment:
      - CUSTOM_ERROR_PAGE=/custom_templates/error.html
      - CUSTOM_DEFAULT_SERVER_PAGE=/custom_templates/default.html
      - CUSTOM_ANTIBOT_CAPTCHA_PAGE=/custom_templates/captcha.html
      # ... otras configuraciones

Acceso al scheduler requerido

Si el scheduler no puede leer los archivos de plantilla (debido a montaje faltante o permisos incorrectos), las plantillas serán silenciosamente ignoradas y se usarán las páginas por defecto. Verifique los logs del scheduler para errores de validación.

El scheduler es responsable de leer, validar y almacenar en caché sus plantillas personalizadas. Necesita montar las plantillas al pod del scheduler.

  1. Cree un ConfigMap con sus plantillas:

    apiVersion: v1
kind: ConfigMap
metadata:
  name: bunkerweb-custom-templates
data:
  error.html: |
    {-raw-}<!doctype html>
    <html lang="es">
      <head>
        <meta charset="utf-8" />
        <title>{{ title }}</title>
        {-raw-}
        <style nonce="{*nonce_style*}">
          body { font-family: sans-serif; text-align: center; padding: 2rem; }
          .error-code { font-size: 4rem; color: #dc3545; }
        </style>
        {-raw-}
      </head>
      <body>
        <p class="error-code">{{ error_code }}</p>
        <h1>{{ error_title }}</h1>
        <p>{{ error_text }}</p>
      </body>
    </html>
    {-raw-}
  captcha.html: |
    {-raw-}<!doctype html>
    <html lang="es">
      <head>
        <meta charset="utf-8" />
        <title>Verificación de seguridad</title>
        {-raw-}
        <style nonce="{*nonce_style*}">
          body { font-family: sans-serif; text-align: center; padding: 2rem; }
        </style>
        {-raw-}
      </head>
      <body>
        <h1>Por favor verifique que es humano</h1>
        {-raw-}
        <form method="POST" action="{*antibot_uri*}">
          <img src="data:image/jpeg;base64,{*captcha*}" alt="Captcha" />
          {-raw-}
          <input type="text" name="captcha" placeholder="Ingrese el código" required />
          <button type="submit">Verificar</button>
        </form>
      </body>
    </html>
    {-raw-}

  2. Monte el ConfigMap de plantillas al pod del scheduler y configure los ajustes como variables de entorno:

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: bunkerweb-scheduler
spec:
  template:
    spec:
      containers:
        - name: bunkerweb-scheduler
          image: bunkerity/bunkerweb-scheduler:1.6.18-rc1
          env:
            - name: CUSTOM_ERROR_PAGE
              value: "/custom_templates/error.html"
            - name: CUSTOM_ANTIBOT_CAPTCHA_PAGE
              value: "/custom_templates/captcha.html"
            # ... otras configuraciones
          volumeMounts:
            - name: custom-templates
              mountPath: /custom_templates
              readOnly: true
          # ... otras configuraciones del contenedor
      volumes:
        - name: custom-templates
          configMap:
            name: bunkerweb-custom-templates
      # ... otras configuraciones del pod

Usando el controlador Ingress de BunkerWeb

Si está usando el controlador Ingress de BunkerWeb, el scheduler está integrado en el controlador. Monte el ConfigMap al pod del controlador en su lugar.

Notas y solución de problemas

  • Las rutas deben ser absolutas y terminar con un nombre de archivo; valores vacíos desactivan la página personalizada correspondiente y eliminan su caché.
  • Si la validación falla (HTML incorrecto o etiquetas Lua desbalanceadas), la plantilla se omite y la página por defecto permanece activa. Verifique los logs del scheduler para detalles.
  • Los archivos en caché están en /var/cache/bunkerweb/custom_pages; actualizar el archivo fuente es suficiente—el job detecta el nuevo hash y recarga NGINX automáticamente.
  • Cumplimiento CSP: Siempre use las variables nonce_script y nonce_style para scripts y estilos inline para asegurar el manejo adecuado de la Content Security Policy.
  • Probando plantillas: Puede probar sus plantillas localmente renderizándolas con un motor de plantillas Lua antes de desplegarlas en BunkerWeb.

Mantenimiento crown pro icon (PRO)

Mantenimiento reemplaza las respuestas de las ubicaciones estándar de proxy inverso por una página de mantenimiento mientras la aplicación no está disponible. Se activa de forma opcional por servicio, devuelve 503 Service Unavailable y nunca llega al upstream. La configuración multisite tiene no como valor predeterminado.

Habilitar y aplicar el modo de mantenimiento

Establezca USE_MAINTENANCE en yes en un servicio multisite existente que utilice el proxy inverso estándar. Este fragmento muestra las claves de entorno relevantes; intégrelo en la configuración del scheduler en lugar de tratarlo como un archivo Compose completo:

# Fragmento: entorno del scheduler para un servicio con proxy inverso
environment:
  app.example.com_USE_REVERSE_PROXY: "yes"
  app.example.com_REVERSE_PROXY_HOST: "http://app:8080"
  app.example.com_USE_MAINTENANCE: "yes"

Aplíquelo mediante su integración habitual de BunkerWeb. El scheduler genera la configuración del servicio y recarga los workers. Establezca app.example.com_USE_MAINTENANCE en no y vuelva a aplicar para restaurar el proxy. Si la configuración del proxy inverso ya existe, solo necesita este ajuste.

La interfaz web proporciona dos interruptores rápidos: el botón con el icono de llave inglesa en la columna Maintenance en la página de servicios y el botón de llave inglesa flotante en la página de edición de un servicio. Ambos actualizan el ajuste del servicio y lo aplican sin recargar la página. El formulario de edición permanece sincronizado, incluidos los modos Easy/Advanced y el editor sin formato, mientras los cambios no guardados que no están relacionados permanecen en su lugar.

Los interruptores requieren una base de datos con permisos de escritura y acceso de escritura al servicio. Se desactivan para usuarios de solo lectura, bases de datos de solo lectura y servicios USE_UI=yes para que la interfaz integrada siga disponible. Rechazan sobrescribir un valor de USE_MAINTENANCE administrado externamente; cámbielo a través de su propietario. Un interruptor se rechaza mientras una aplicación está en curso.

Comportamiento y alcance de las solicitudes

Mantenimiento se aplica únicamente a las ubicaciones generadas a partir de la configuración de proxy inverso estándar de BunkerWeb, incluidas REVERSE_PROXY_HOST y sus variantes numeradas. No añade ubicaciones de proxy, modifica ubicaciones personalizadas ni se apropia de los controladores de reescritura manuales. Si la configuración personalizada reemplaza esos controladores o las variables del backend, integre usted mismo la respuesta de mantenimiento.

Mantenimiento conserva la política HTTPS existente, por lo que una redirección de HTTP a HTTPS habilitada ocurre primero. En el origen HTTPS efectivo devuelve 503 con Cache-Control: no-store, una Content Security Policy restrictiva y X-Content-Type-Options: nosniff.

Las solicitudes GET, POST, OPTIONS y los handshakes de WebSocket reciben la página de mantenimiento. BunkerWeb descarta el cuerpo de la solicitud, por lo que el cuerpo de un POST nunca se reenvía ni se reproduce. HEAD recibe el mismo estado y las mismas cabeceras sin cuerpo. Los WebSockets existentes no se cierran explícitamente; se aplica el apagado normal de los workers durante la recarga.

Mantenimiento se ejecuta antes de la autenticación, antibot y otras comprobaciones de acceso, por lo que los clientes incluidos en la lista blanca y los servicios en modo de detección también la reciben. Las ubicaciones locales de NGINX, la API interna y los endpoints de estado conservan su comportamiento normal. Lo mismo se aplica a /.well-known/acme-challenge/ y al passthrough de Let's Encrypt configurado. Mantenimiento conserva esta excepción; no emite certificados ni crea un controlador ACME.

Personalizar la página de mantenimiento

La página incluida funciona sin Custom Pages. Para personalizarla con Custom Pages, abra el editor de Custom Pages y elija Maintenance. Easy Mode edita el título y el mensaje de mantenimiento, el favicon, el logotipo/texto del pie de página y la ilustración SVG. El título actualiza el título del navegador y el encabezado; un título o una ilustración vacíos conservan el valor predeterminado. Conserve las clases SVG maintenance-top y maintenance-tool para la animación de la ilustración.

En Advanced Mode, edite la plantilla HTML/Lua completa. Las variables disponibles son:

Variable Propósito
title Site under maintenance, el título de página proporcionado por el plugin.
nonce_style Nonce CSP por respuesta para elementos <style> inline.
nonce_script Nonce CSP por respuesta para elementos <script> inline.

Use los valores nonce en cada estilo y script inline, por ejemplo nonce="{* nonce_style *}". La respuesta permite imágenes incrustadas, SVG y fuentes mediante URL data: y bloquea otros orígenes. Incruste los recursos inline o como URL de datos; las URL de recursos de la aplicación también reciben mantenimiento y no pueden cargar dependencias.

Para una página administrada mediante archivo, establezca CUSTOM_MAINTENANCE_PAGE en una ruta absoluta que el scheduler pueda leer. Tiene prioridad sobre una plantilla de la UI y bloquea ese ámbito en el editor. Sin ella, un servicio utiliza su propia plantilla de la UI o hereda la plantilla global. Delete elimina una anulación del servicio y restaura la herencia. Reset elimina la plantilla de la UI y fuerza la página incluida, incluso cuando existe una personalización global. Guardar una nueva anulación de servicio borra su marcador de restablecimiento. Active o desactive el mantenimiento por separado con USE_MAINTENANCE.

El job de Custom Pages valida el HTML y protege contra peligros conocidos de compilación de plantillas Lua antes de almacenar en caché. Una fuente no válida conserva la última caché aceptada. Una página activa no disponible o que falla recurre a la página incluida y después a una página de emergencia mínima. Un error de renderizado nunca restaura el tráfico del proxy.

Solución de problemas del mantenimiento

  • El interruptor está desactivado o se rechaza: compruebe los permisos de escritura, USE_UI y la propiedad externa de USE_MAINTENANCE; cambie los valores administrados externamente a través de su propietario.
  • La aplicación sigue respondiendo: confirme que una ubicación de proxy inverso estándar tiene USE_REVERSE_PROXY=yes y USE_MAINTENANCE=yes. Las rutas locales y ACME son excepciones.
  • Recibe una redirección en lugar de 503: la política HTTPS existente redirige primero; siga la URL HTTPS.
  • Se muestra la página incluida: compruebe el archivo legible por el scheduler, la validación de la plantilla y el log del scheduler; un ajuste de archivo bloquea la plantilla de la UI.
  • Faltan recursos o scripts inline: incrústelos y use nonce_style o nonce_script; las URL de la aplicación no están disponibles.

OpenID Connect crown pro icon (PRO)

El plugin OpenID Connect (PRO) agrega Single Sign-On (SSO) delante de su aplicación utilizando el flujo estándar OAuth 2.0 / OIDC Authorization Code.

Se ejecuta dentro de BunkerWeb (NGINX/Lua) y aplica la autenticación durante la fase access, por lo que las solicitudes no autenticadas se bloquean antes de llegar a su upstream.

Cómo funciona el flujo de la solicitud

Cuando un navegador solicita una URL protegida:

  1. Si no hay una sesión válida, BunkerWeb redirige al usuario al proveedor de identidad (IdP).
  2. El IdP autentica al usuario y redirige de vuelta a BunkerWeb en OPENIDC_REDIRECT_URI (por defecto: /callback) con un código de autorización.
  3. BunkerWeb intercambia el código por tokens en el endpoint token del IdP.
  4. Los tokens se validan (issuer, audience, expiración, iat con tolerancia y firma mediante JWKS).
  5. Se crea una sesión y el navegador es redirigido a la URL original.
sequenceDiagram
  participant B as Navegador
  participant BW as BunkerWeb (OpenIDC)
  participant IdP as Proveedor de identidad
  participant Up as Upstream

  B->>BW: GET /protected
  alt No autenticado
  BW-->>B: 302 Redirección al endpoint authorize del IdP
  B->>IdP: Solicitud de autorización (nonce/PKCE opcional)
  IdP-->>B: 302 Redirección a /callback?code=...
  B->>BW: GET /callback?code=...
  BW->>IdP: Solicitud de token (intercambio del código)
  IdP-->>BW: ID token + access token (+ refresh token)
  BW-->>B: 302 Redirección a la URL original
  end
  B->>BW: GET /protected (autenticado)
  BW->>Up: Reenviar solicitud (+ header de identidad opcional)
  Up-->>BW: Respuesta
  BW-->>B: Respuesta

La URL de callback debe coincidir con la configuración del cliente en el IdP

Registre la URL completa de callback en el IdP (esquema + host + ruta). Por ejemplo con valores por defecto: https://app.example.com/callback.

Ajustes (explicados)

Ajustes requeridos

Como mínimo, OPENIDC_DISCOVERY y OPENIDC_CLIENT_ID deben estar configurados para que el plugin funcione.

Activación

  • USE_OPENIDC (por defecto: no): habilita o deshabilita la autenticación OpenID Connect para el sitio.

Proveedor de identidad (IdP) + registro del cliente

  • OPENIDC_DISCOVERY: URL de discovery (p. ej. https://idp.example.com/.well-known/openid-configuration).
  • OPENIDC_CLIENT_ID: identificador del cliente OAuth 2.0 registrado en el IdP.
  • OPENIDC_CLIENT_SECRET: secreto del cliente OAuth 2.0 (usado por basic, post y secret_jwt).

Callback / redirección

  • OPENIDC_REDIRECT_URI (por defecto: /callback): ruta de callback usada por el IdP tras autenticar (debe registrarse en el IdP).

Scopes y parámetros de autorización

  • OPENIDC_SCOPE (por defecto: openid email profile): lista de scopes separados por espacios.
  • OPENIDC_AUTHORIZATION_PARAMS: parámetros extra de autorización como pares key=value separados por comas.

Refuerzo de seguridad

  • OPENIDC_USE_NONCE (por defecto: yes): añade nonce a las solicitudes de autorización.
  • OPENIDC_USE_PKCE (por defecto: no): habilita PKCE para el flujo Authorization Code.
  • OPENIDC_IAT_SLACK (por defecto: 120): tolerancia de desfase de reloj (segundos) para validar tokens.
  • OPENIDC_ACCEPT_UNSUPPORTED_ALG (por defecto: no): acepta tokens con algoritmos no soportados (no recomendado).
  • OPENIDC_FORCE_REAUTHORIZE (por defecto: no): fuerza reautorización en cada solicitud (solo debug).

Control de acceso basado en claims (ACL)

Los claims son pares clave-valor en el token OIDC que describen al usuario (p. ej. email, groups, sub). La funcionalidad ACL permite restringir el acceso en base a valores de claims específicos.

Configuración Predeterminado Contexto Múltiple Descripción
OPENIDC_USE_ACL no multisite no Habilitar el control de acceso basado en claims tras la autenticación OIDC. Solo se concederá acceso a los usuarios cuyos claims coincidan con las reglas configuradas.
OPENIDC_ACL_MATCH_MODE all multisite no Cómo se evalúan múltiples reglas ACL. all = todas deben cumplirse (AND). any = al menos una debe cumplirse (OR).
OPENIDC_ACL_DENIED_URL multisite no URL de redirección cuando el ACL deniega el acceso. Si está vacío, devuelve una respuesta 403 Forbidden.
OPENIDC_ACL_CLAIM multisite sí Nombre del claim OIDC a verificar (p. ej. groups, email, sub). Se empareja con OPENIDC_ACL_CLAIM_VALUE.
OPENIDC_ACL_CLAIM_VALUE multisite sí Valor esperado del claim. Para claims de tipo array (p. ej. groups), verifica pertenencia. Para claims de tipo string, verifica igualdad estricta.

Múltiples reglas ACL

Use sufijos numéricos para definir múltiples reglas. Cada par OPENIDC_ACL_CLAIM / OPENIDC_ACL_CLAIM_VALUE forma una regla:

OPENIDC_USE_ACL: "yes"
OPENIDC_ACL_MATCH_MODE: "any"
OPENIDC_ACL_CLAIM: "groups"
OPENIDC_ACL_CLAIM_VALUE: "engineering"
OPENIDC_ACL_CLAIM_1: "email"
OPENIDC_ACL_CLAIM_VALUE_1: "admin@example.com"

Con OPENIDC_ACL_MATCH_MODE=any, se concede acceso si el usuario pertenece al grupo engineering o tiene el correo admin@example.com. Con all, ambas condiciones deben cumplirse.

Ciclo de vida de sesión/tokens

  • OPENIDC_REFRESH_SESSION_INTERVAL: intervalo en segundos para reautenticar/renovar la sesión silenciosamente (vacío desactiva).
  • OPENIDC_ACCESS_TOKEN_EXPIRES_IN (por defecto: 3600): expiración por defecto del access token si el IdP no la especifica.
  • OPENIDC_RENEW_ACCESS_TOKEN_ON_EXPIRY (por defecto: yes): renueva el access token usando el refresh token cuando expira.

Ajustes de autenticación del endpoint token

  • OPENIDC_TOKEN_ENDPOINT_AUTH_METHOD (por defecto: basic): basic, post, secret_jwt, private_key_jwt.
  • OPENIDC_CLIENT_RSA_PRIVATE_KEY: requerido con private_key_jwt.
  • OPENIDC_CLIENT_RSA_PRIVATE_KEY_ID: kid opcional para private_key_jwt.
  • OPENIDC_CLIENT_JWT_ASSERTION_EXPIRES_IN: vida útil de la aserción JWT (segundos).

Comportamiento de logout

  • OPENIDC_LOGOUT_PATH (por defecto: /logout): ruta local de logout gestionada por BunkerWeb.
  • OPENIDC_REVOKE_TOKENS_ON_LOGOUT (por defecto: no): revoca tokens en el IdP al hacer logout.
  • OPENIDC_REDIRECT_AFTER_LOGOUT_URI: redirección después del logout local (vacío = comportamiento por defecto del IdP).
  • OPENIDC_POST_LOGOUT_REDIRECT_URI: redirección tras completar el logout en el IdP (si lo soporta).

Conectividad y TLS hacia el IdP

  • OPENIDC_TIMEOUT_CONNECT|SEND|READ (por defecto: 10000 ms cada uno): timeouts para llamadas HTTP al IdP.
  • OPENIDC_SSL_VERIFY (por defecto: yes): verifica certificados TLS del IdP.
  • OPENIDC_KEEPALIVE (por defecto: yes): keepalive para conexiones al IdP.
  • OPENIDC_HTTP_PROXY / OPENIDC_HTTPS_PROXY: proxies para llamadas al IdP.

Envío de identidad al upstream

  • OPENIDC_USER_HEADER (por defecto: X-User): header para pasar identidad al upstream (vacío desactiva).
  • OPENIDC_USER_HEADER_CLAIM (por defecto: sub): claim a extraer para el valor del header.
  • OPENIDC_DISPLAY_CLAIM (por defecto: preferred_username): claim para mostrar en logs/métricas.

Caché

  • OPENIDC_DISCOVERY_DICT_SIZE (por defecto: 1m): tamaño del shared dict para caché de discovery.
  • OPENIDC_JWKS_DICT_SIZE (por defecto: 1m): tamaño del shared dict para caché de JWKS.

Almacenamiento de sesión en Redis

Cuando USE_REDIS=yes está configurado globalmente en BunkerWeb, el plugin OpenIDC almacena las sesiones en Redis en lugar de cookies (con fallback automático a cookies si Redis no está disponible). Es el modo recomendado para despliegues multi-instancia / HA.

Caché de discovery + JWKS

El plugin usa OPENIDC_DISCOVERY (la URL .well-known/openid-configuration del IdP) para descubrir endpoints y luego obtiene y cachea claves JWKS para validar firmas.

Los datos de discovery/JWKS se cachean en shared dictionaries de NGINX. Si tiene muchos tenants/IdPs o conjuntos grandes de claves, incremente:

  • OPENIDC_DISCOVERY_DICT_SIZE (global)
  • OPENIDC_JWKS_DICT_SIZE (global)

Sesiones (cookies vs Redis)

Por defecto, las sesiones se almacenan como cookies seguras gestionadas por la librería de OpenID Connect.

Si USE_REDIS=yes está habilitado globalmente y Redis está configurado, el plugin cambia automáticamente a sesiones en Redis (con fallback automático a cookies si Redis no está disponible temporalmente). Recomendado en load balancing / HA y evita límites de tamaño de cookies cuando los tokens son grandes.

Envío de identidad del usuario al upstream

Si OPENIDC_USER_HEADER está configurado (por defecto: X-User), el plugin inyecta un valor de header extraído de un claim (por defecto: OPENIDC_USER_HEADER_CLAIM=sub).

Comportamiento de seguridad importante:

  • El plugin borra cualquier header entrante que coincida con OPENIDC_USER_HEADER para evitar spoofing del cliente.
  • Si el claim configurado falta, el header no se establece.
  • Configure OPENIDC_USER_HEADER como vacío para desactivar el envío de identidad.

Elegir un claim

Prefiera identificadores estables presentes en los tokens (p. ej. sub, email, preferred_username). Los claims se leen primero del ID token, luego de userinfo si existe.

Logout

Las solicitudes de logout se gestionan en OPENIDC_LOGOUT_PATH (por defecto: /logout).

  • Para revocar tokens en el IdP al hacer logout, configure OPENIDC_REVOKE_TOKENS_ON_LOGOUT=yes.
  • Use OPENIDC_REDIRECT_AFTER_LOGOUT_URI y OPENIDC_POST_LOGOUT_REDIRECT_URI para controlar redirecciones tras logout.

Autenticación del endpoint token

La mayoría de IdPs funcionan con el valor por defecto OPENIDC_TOKEN_ENDPOINT_AUTH_METHOD=basic (client secret via HTTP Basic). También se soportan:

  • post
  • secret_jwt
  • private_key_jwt (requiere OPENIDC_CLIENT_RSA_PRIVATE_KEY, opcional OPENIDC_CLIENT_RSA_PRIVATE_KEY_ID)

Ejemplos de configuración mínima

Ajustes mínimos requeridos por servicio protegido:

  • USE_OPENIDC=yes
  • OPENIDC_DISCOVERY=...
  • OPENIDC_CLIENT_ID=...
  • OPENIDC_CLIENT_SECRET=... (o configuración de clave JWT para private_key_jwt)

Opciones comunes de hardening/tuning:

  • OPENIDC_USE_NONCE=yes (por defecto)
  • OPENIDC_USE_PKCE=yes
  • OPENIDC_IAT_SLACK=... si hay desfase de reloj
  • OPENIDC_TIMEOUT_CONNECT|SEND|READ según latencia del IdP
  • OPENIDC_SSL_VERIFY=yes (por defecto)

Solución de problemas

  • 403 con "Authentication failed": normalmente URL de discovery incorrecta, mismatch de URL de callback en el IdP o IdP inaccesible.
  • Desfase de reloj / "token not yet valid": habilite NTP; ajuste OPENIDC_IAT_SLACK si es necesario.
  • No se inyecta el header de usuario: verifique que el claim de OPENIDC_USER_HEADER_CLAIM exista en el ID token/userinfo.
  • Despliegues multi-instancia: habilite USE_REDIS=yes y configure REDIS_HOST (o Sentinel) para compartir sesiones.

SAML crown pro icon (PRO)

El plugin SAML (PRO) convierte BunkerWeb en un proveedor de servicios (SP) SAML 2.0 para el SSO del navegador. Acepta una respuesta del IdP cuya aserción esté cubierta por una firma de confianza, crea una sesión y puede exponer atributos seleccionados al upstream protegido como cabeceras. Es compatible con BunkerWeb 1.6.14 y versiones posteriores de la serie 1.6.x.

Requisitos previos y material de confianza

Utilice un origen HTTPS público para cada servicio protegido, como https://app.example.com, sin barra final, ruta ni cadena de consulta. Se permite un puerto HTTPS no estándar. SAML necesita tres piezas de material PEM:

  • una clave privada RSA sin cifrar para el SP;
  • el certificado SP correspondiente en formato PEM; y
  • el certificado de firma PEM del IdP, en el que BunkerWeb confía al verificar las aserciones.

La clave y el certificado del SP deben coincidir y deben ser claves RSA de al menos 2048 bits. La URL SSO del IdP y, cuando se proporcione, la URL SLO del IdP deben usar HTTPS. Mantenga secreta la clave privada; BunkerWeb la utiliza para firmar las solicitudes de autenticación y cierre de sesión.

Configurar SAML en la UI

Abra SAML para el servicio de destino y elija su ámbito. El formulario agrupa los ajustes en secciones de IdP, SP, sesión, cabeceras de identidad y ACL. Utilice este orden:

  1. Habilite USE_SAML para el servicio.
  2. Introduzca el origen público del SP, el ID de entidad del SP, el certificado SP y la clave privada RSA sin cifrar.
  3. Introduzca el ID de entidad del IdP, la URL SSO HTTPS, el certificado de firma PEM de confianza y la URL SLO HTTPS opcional. Una URL SLO vacía utiliza la URL SSO.
  4. Mantenga las rutas locales predeterminadas salvo que entren en conflicto con una ruta existente. Guarde y aplique la configuración.
  5. Use Export metadata para descargar o mostrar los metadatos SP de BunkerWeb y, a continuación, registre esos metadatos y las URL ACS/SLO exactas en el IdP.
  6. Configure los atributos de identidad y las reglas ACL, y vuelva a guardar y aplicar.

BunkerWeb exporta los metadatos SP; no importa ni actualiza automáticamente los metadatos del IdP. Configure primero los campos y certificados del IdP y después exporte los metadatos para evitar una configuración circular.

Flujo de solicitudes del navegador

Un inicio de sesión iniciado por el SP firma la AuthnRequest con la clave privada del SP y la envía al IdP mediante HTTP-Redirect. El IdP devuelve a la ACS mediante HTTP-POST una respuesta cuya aserción está cubierta por su firma. BunkerWeb valida la correlación, el destino, el emisor, las marcas de tiempo de la aserción, la firma y el estado de repetición antes de crear una sesión. El cuerpo de la solicitud original no se reproduce.

sequenceDiagram
  participant B as Navegador
  participant BW as BunkerWeb (SP SAML)
  participant IdP as Proveedor de identidad
  participant Up as Upstream

  B->>BW: GET /protected
  BW-->>B: 302 AuthnRequest HTTP-Redirect firmada
  B->>IdP: GET URL SSO con SAMLRequest
  IdP-->>B: 200/POST SAMLResponse con aserción protegida por firma
  B->>BW: POST ACS con SAMLResponse
  BW->>BW: Validar firma, emisor, destino, expiración y repetición
  BW-->>B: 302 /protected con cookie de sesión
  B->>BW: GET /protected
  BW->>Up: Solicitud más cabeceras de identidad configuradas
  Up-->>BW: Respuesta
  BW-->>B: Respuesta

Endpoints

Todas las rutas de endpoint son rutas locales en el origen SP público. Las predeterminadas son ajustes multisite y pueden cambiarse cuando estén disponibles para el servicio.

Endpoint Configuración Predeterminado Método y propósito
Metadatos SP SAML_METADATA_PATH /saml/metadata GET o HEAD; publica los metadatos de entidad SP, ACS, SLO y certificado de firma.
Servicio consumidor de aserciones (ACS) SAML_ACS_PATH /saml/acs POST; recibe la respuesta del IdP cuya aserción está cubierta por su firma.
Cierre de sesión local SAML_LOGOUT_PATH /saml/logout Inicia el cierre de sesión local; una sesión autenticada activa una solicitud de cierre de sesión firmada al IdP.
Servicio de cierre de sesión único (SLS) SAML_SLS_PATH /saml/sls GET o POST; recibe una solicitud o respuesta de cierre de sesión del IdP.

SAML_LOGOUT_REDIRECT (predeterminado /) es la ruta local utilizada después del cierre de sesión. Mantenga las cuatro rutas de endpoint distintas y sin cadenas de consulta, fragmentos, barras invertidas, espacios en blanco ni segmentos de recorrido.

Registro en Keycloak 26.5.2

La guía del cliente SAML de Keycloak 26.5.2 utiliza las pestañas de cliente Settings, Keys y Advanced. Utilice los siguientes valores para la disposición de endpoints predeterminada de BunkerWeb. Reemplace https://app.example.com con el SAML_SP_BASE_URL exacto.

Cree un cliente SAML habilitado con estos valores de registro. En la UI de Keycloak, Enabled y Front channel logout están activados (true); el protocolo del cliente es SAML.

Configuración del cliente Valor
ID del cliente https://app.example.com/saml/metadata
Protocolo SAML
Habilitado true
Cierre de sesión del canal frontal true
URI de redirección válidas https://app.example.com/saml/acs y https://app.example.com/saml/sls

En la configuración del cliente, exija aserciones y documentos firmados, exija firmas del cliente, seleccione RSA_SHA256 y active Force POST Binding. Deje Encrypt Assertions desactivado: BunkerWeb requiere que la aserción esté cubierta por una firma de IdP de confianza, ya sea en la aserción o en la respuesta completa, y no acepta aserciones cifradas. En Keys, active Client Signature Required. Establezca Use metadata descriptor URL en OFF y proporcione manualmente el certificado SP, para que Keycloak pueda verificar las solicitudes firmadas de BunkerWeb sin un ciclo de importación de metadatos del IdP. En Advanced, establezca Assertion Consumer Service POST Binding URL en /saml/acs y tanto Logout Service POST Binding URL como Logout Service Redirect Binding URL en /saml/sls en el origen público. Establezca el formato Name ID en username y fuerce ese formato.

Los atributos de cliente correspondientes son:

saml.assertion.signature: "true"
saml.server.signature: "true"
saml.client.signature: "true"
saml.encrypt: "false"
saml.force.post.binding: "true"
saml.authnstatement: "true"
saml.signature.algorithm: "RSA_SHA256"
saml_name_id_format: "username"
saml_force_name_id_format: "true"
saml.signing.certificate: "SP_CERTIFICATE_BODY_WITHOUT_PEM_WRAPPERS"
saml_assertion_consumer_url_post: "https://app.example.com/saml/acs"
saml_single_logout_service_url_post: "https://app.example.com/saml/sls"
saml_single_logout_service_url_redirect: "https://app.example.com/saml/sls"

Añada mapeadores de protocolo para email, groups y name. Para cada mapeador, utilice protocol: "saml", protocolMapper: "saml-user-attribute-mapper" y consentRequired: false; establezca config.user.attribute y config.attribute.name en el mismo atributo, y config.attribute.nameformat en Basic. Asegúrese de que el usuario del IdP tenga realmente estos atributos; un claim ausente no produce la cabecera correspondiente en el upstream.

Configuraciones (explicadas)

Los valores predeterminados siguientes proceden de los ajustes del plugin SAML. Los valores predeterminados vacíos se muestran como empty.

Activación, confianza y rutas

Configuración Predeterminado Propósito
USE_SAML no Habilita SAML para el servicio.
SAML_SP_ENTITY_ID empty Emisor e identificador de cliente del SP.
SAML_SP_BASE_URL empty Origen HTTPS público sin ruta ni consulta.
SAML_IDP_ENTITY_ID empty Emisor del IdP de confianza.
SAML_IDP_SSO_URL empty Endpoint de inicio de sesión HTTPS del IdP.
SAML_IDP_SLO_URL empty Endpoint de cierre de sesión HTTPS del IdP; vacío utiliza SSO.
SAML_SP_CERT empty Certificado SP correspondiente en formato PEM.
SAML_SP_PRIVATE_KEY empty Clave privada RSA correspondiente y sin cifrar en formato PEM.
SAML_IDP_CERT empty Certificado de firma del IdP de confianza en formato PEM.
SAML_ACS_PATH /saml/acs Ruta ACS local.
SAML_LOGOUT_PATH /saml/logout Ruta de cierre de sesión local.
SAML_SLS_PATH /saml/sls Ruta de callback SLS local.
SAML_METADATA_PATH /saml/metadata Ruta de metadatos SP local.
SAML_LOGOUT_REDIRECT / Ruta local después del cierre de sesión.

Sesiones y cabeceras de identidad

Configuración Predeterminado Propósito
SAML_CLOCK_SKEW 60 Desfase de reloj permitido para la aserción en segundos; el rango válido es 0–300.
SAML_SESSION_IDLE_TIMEOUT 900 Duración de la sesión inactiva en segundos; el rango válido es 1–86400.
SAML_SESSION_ABSOLUTE_TIMEOUT 3600 Duración máxima de la sesión en segundos; el rango válido es 1–86400.
SAML_USER_HEADER X-User Cabecera del upstream para el valor de usuario; vacío la desactiva.
SAML_USER_ATTRIBUTE NameID Atributo para el valor de usuario; NameID significa el identificador del sujeto.
SAML_EMAIL_HEADER empty Cabecera del upstream para el correo electrónico; vacío la desactiva.
SAML_EMAIL_ATTRIBUTE email Atributo para el correo electrónico; NameID significa el identificador del sujeto.
SAML_GROUPS_HEADER empty Cabecera del upstream para los grupos; vacío la desactiva.
SAML_GROUPS_ATTRIBUTE groups Atributo para los grupos; NameID significa el identificador del sujeto.
SAML_NAME_HEADER empty Cabecera del upstream para el nombre mostrado; vacío la desactiva.
SAML_NAME_ATTRIBUTE name Atributo para el nombre mostrado; NameID significa el identificador del sujeto.
SAML_GROUPS_SEPARATOR , Une varios valores en una cabecera.

Antes de la autenticación, BunkerWeb elimina cada cabecera de identidad SAML configurada de la solicitud entrante. Solo añade una cabecera después de una respuesta válida y cuando existe el atributo asignado. Los nombres de cabecera deben ser únicos y sintácticamente válidos, y no pueden utilizar prefijos de enrutamiento o sensibles a la seguridad, como X-Forwarded-*, Proxy-* o Sec-*. Estas cabeceras llevan la identidad al upstream protegido; no inician sesión de un usuario en la interfaz web de BunkerWeb.

ACL de atributos

Configuración Predeterminado Propósito
SAML_ACL_RULE_COUNT empty Recuento explícito de reglas numeradas; 0 borra la lista.
SAML_USE_ACL no Habilita el control de acceso basado en atributos después de validar SAML.
SAML_ACL_MATCH_MODE all Combina las reglas con all o any.
SAML_ACL_DENIED_URL empty Redirige cuando se deniega el acceso; vacío devuelve el estado de denegación.
SAML_ACL_ATTRIBUTE empty Nombre del atributo para una regla ACL.
SAML_ACL_VALUE empty Valor requerido para una regla ACL.

Por ejemplo, este servicio requiere pertenecer a engineering y tener el correo electrónico del administrador:

app.example.com_USE_SAML: "yes"
app.example.com_SAML_USE_ACL: "yes"
app.example.com_SAML_ACL_RULE_COUNT: "2"
app.example.com_SAML_ACL_MATCH_MODE: "all"
app.example.com_SAML_ACL_ATTRIBUTE_1: "groups"
app.example.com_SAML_ACL_VALUE_1: "engineering"
app.example.com_SAML_ACL_ATTRIBUTE_2: "email"
app.example.com_SAML_ACL_VALUE_2: "admin@example.com"

El primer par es _1 y el segundo es _2; la UI numera las reglas desde 1. Con un recuento explícito de 2, se requieren ambos pares; un atributo ausente deniega el acceso, mientras que un valor configurado vacío es una denegación. Con all, todas las reglas deben coincidir; con any, basta una regla coincidente. Sin reglas, se permite el acceso a todos los usuarios autenticados. En un ámbito de servicio, la UI hereda la lista de reglas global hasta que elija una lista de servicio; guardar una lista de servicio reemplaza esa lista heredada, incluso cuando el reemplazo está explícitamente vacío. Deje SAML_ACL_RULE_COUNT vacío para descubrir reglas numeradas hasta las primeras 100 posiciones. Establézcalo en 0 para borrar todas las reglas. Un modo no válido o una lista explícita malformada deniega por defecto. SAML_ACL_DENIED_URL redirige cuando está establecido; de lo contrario, BunkerWeb devuelve su estado de denegación.

Protección contra repetición

Configuración Predeterminado Contexto Propósito
SAML_REPLAY_DICT_SIZE 10m global Capacidad de memoria compartida para la protección contra repetición en una instancia.

Cada ID de aserción aceptado se añade atómicamente al almacén de repeticiones durante el tiempo en que todavía podría aceptarse. El ID de AuthnRequest pendiente es un valor de correlación de sesión separado. En una instancia, aumente SAML_REPLAY_DICT_SIZE cuando el diccionario compartido sea demasiado pequeño. Para réplicas, habilite el modo de sesión USE_REDIS=yes del núcleo y dirija cada instancia al mismo servicio Redis para que las claves de repetición utilicen el almacén compartido. Mantenga también SESSIONS_SECRET del núcleo idéntico en cada réplica; de lo contrario, un worker no puede leer una sesión creada por otro. De forma predeterminada, las sesiones utilizan cookies seguras y restringidas al host, con HttpOnly, Secure y SameSite=None. Con Redis habilitado, los datos de sesión pasan a un almacén Redis con espacio de nombres en lugar de la cookie. SessionNotOnOrAfter del IdP puede finalizar una sesión antes que los tiempos de espera configurados. Una aserción consumida sigue consumida si falla un paso posterior del callback.

Cierre de sesión

Solicitar SAML_LOGOUT_PATH borra el estado autenticado, guarda una correlación de cierre de sesión pendiente e inicia el SLO de front-channel. BunkerWeb envía una solicitud de cierre de sesión firmada mediante el binding Redirect. Después de una LogoutResponse firmada y válida, destruye la sesión local y redirige el navegador a SAML_LOGOUT_REDIRECT. Una LogoutRequest iniciada por el IdP puede llegar a SAML_SLS_PATH; el SLS valida el emisor, el destino, el NameID, el índice de sesión y el estado de repetición, destruye la sesión local y devuelve una respuesta firmada al IdP. Si no existe una sesión local, la ruta de cierre de sesión destruye la sesión vacía y redirige localmente.

Límites y solución de problemas

Actualmente SAML admite el inicio de sesión de navegador iniciado por el SP con una AuthnRequest Redirect firmada y una respuesta ACS POST. No admite el inicio de sesión iniciado por el IdP, aserciones cifradas ni la importación y actualización automáticas de metadatos del IdP. Mantenga el IdP configurado para firmar documentos/aserciones y enviar la respuesta con binding POST. Los cuerpos POST de autenticación y cierre de sesión están limitados a 256 KiB; las solicitudes demasiado grandes se rechazan antes de procesarse.

  • La UI no habilita SAML: compruebe el origen HTTPS, los tres certificados/claves, la clave y el certificado RSA coincidentes, los valores de entidad/SSO del IdP y las cuatro rutas locales distintas. Se rechaza una configuración no válida y la solicitud deniega por defecto con 503; ninguna solicitud llega al upstream.
  • El IdP rechaza la AuthnRequest: compare el ID de entidad del SP, las URL ACS/SLS exactas, el certificado SP, el ajuste RSA-SHA256 y el requisito de firma del cliente. En Keycloak, compruebe que Use metadata descriptor URL esté desactivado y que el certificado SP proporcionado manualmente esté actualizado.
  • La ACS devuelve un error o 503: verifique el certificado de firma del IdP, la cobertura de la firma de la aserción, el emisor, el destino, la sincronización del reloj, el binding de respuesta, la correlación de solicitud pendiente y que el ID de aserción no se haya consumido ya. Compruebe que el IdP envíe los atributos asignados.
  • Un usuario se autentica pero recibe una denegación: habilite los atributos ACL esperados, confirme los pares numerados y SAML_ACL_RULE_COUNT, y compruebe all frente a any. Un valor de atributo vacío o un claim ausente pueden denegar por diseño.
  • Una sesión desaparece detrás de un balanceador de carga: utilice el mismo almacén Redis y el mismo secreto de sesión del núcleo en cada réplica. Redis debe estar disponible cuando USE_REDIS=yes; la protección contra repetición y las sesiones no recurren silenciosamente al estado por worker.

LDAP SSO crown pro icon (PRO)

Soporte STREAM ❌

El plugin LDAP SSO agrega Single Sign-On basado en LDAP a sus servicios de BunkerWeb. Proporciona un formulario de inicio de sesión, autentica a los usuarios contra un directorio LDAP, crea una sesión y, opcionalmente, reenvía el nombre de usuario autenticado a su upstream mediante una cabecera configurable.

El plugin admite dos modos de autenticación:

  • Modo búsqueda-luego-bind (recomendado, también llamado "modo de búsqueda empresarial"): una cuenta de servicio busca en el directorio al usuario y luego realiza el bind como el DN encontrado para verificar la contraseña. Se habilita cuando LDAP_USER_SEARCH_BASE_DN está configurado.
  • Modo bind directo: construye el DN del usuario a partir de una plantilla (LDAP_USER_DN_TEMPLATE) y realiza el bind directamente. Se usa como respaldo cuando el modo de búsqueda no está configurado.

Características

  • LDAP/LDAPS/STARTTLS: conexión mediante LDAP simple, LDAPS (TLS desde el inicio) o actualización STARTTLS.
  • Modo búsqueda-luego-bind: la cuenta de servicio realiza la búsqueda de usuarios con base, filtro, alcance y límites de tamaño/tiempo configurables.
  • Respaldo con bind directo: autenticación basada en plantilla de DN cuando el modo de búsqueda no es necesario.
  • Filtro de autorización: filtro LDAP adicional opcional para restringir el acceso más allá de la autenticación básica.
  • Pool de conexiones: keepalive con tamaño de pool y timeout configurables para reducir las ida y vuelta al servidor LDAP.
  • Gestión de sesiones: TTL configurable con limpieza automática de sesiones.
  • Reenvío de cabecera de usuario: pasa el nombre de usuario autenticado a los upstreams mediante una cabecera configurable (por defecto: X-User).
  • Rutas de login/logout: endpoints dedicados para autenticación y terminación de sesión.

Las credenciales se envían en texto plano por defecto

Con la configuración predeterminada (LDAP_LDAPS=no, LDAP_STARTTLS=no), las contraseñas de los usuarios se transmiten en texto claro al servidor LDAP. Habilite siempre LDAP_LDAPS=yes (con LDAP_PORT=636) o LDAP_STARTTLS=yes en producción. Mantenga LDAP_SSL_VERIFY=yes para prevenir ataques de degradación TLS.

Configuración

Ajustes principales

Configuración Predeterminado Contexto Múltiple Descripción
USE_LDAP no multisite no Habilitar o deshabilitar la autenticación LDAP SSO.
LDAP_HOST multisite no Nombre de host o dirección IP del servidor LDAP.
LDAP_PORT 389 multisite no Puerto del servidor LDAP (389 para LDAP/STARTTLS, 636 para LDAPS).
LDAP_LDAPS no multisite no Usar LDAPS (TLS desde el inicio de la conexión).
LDAP_STARTTLS no multisite no Usar actualización STARTTLS en la conexión LDAP.
LDAP_SSL_VERIFY yes multisite no Verificar el certificado TLS del servidor.
LDAP_TIMEOUT 10000 multisite no Timeout del socket LDAP en milisegundos.

Pool de conexiones

Configuración Predeterminado Contexto Múltiple Descripción
LDAP_KEEPALIVE_TIMEOUT 60000 multisite no Timeout de keepalive LDAP en milisegundos.
LDAP_KEEPALIVE_POOL_SIZE 10 multisite no Tamaño del pool de conexiones keepalive LDAP.
LDAP_KEEPALIVE_POOL_NAME multisite no Nombre personalizado opcional del pool keepalive LDAP.

Modo de búsqueda empresarial

Configuración Predeterminado Contexto Múltiple Descripción
LDAP_BIND_DN multisite no DN de la cuenta de servicio usada para realizar búsquedas LDAP de usuarios.
LDAP_BIND_PASSWORD multisite no Contraseña de la cuenta de servicio para el bind DN de LDAP.
LDAP_USER_SEARCH_BASE_DN multisite no Base DN para la búsqueda de usuarios (habilita el modo de búsqueda empresarial al configurarlo).
LDAP_USER_SEARCH_FILTER (&(objectClass=person)(\|(uid={username})(mail={username})(sAMAccountName={username})(userPrincipalName={username}))) multisite no Plantilla del filtro de búsqueda LDAP. Use el marcador {username}.
LDAP_AUTHZ_FILTER multisite no Filtro LDAP de autorización adicional opcional (combinado con AND al filtro de búsqueda).
LDAP_USER_SEARCH_SCOPE subtree multisite no Alcance de la búsqueda LDAP: base, onelevel o subtree.
LDAP_USER_SEARCH_DEREF_ALIASES always multisite no Modo de desreferencia de alias LDAP: always, never, in_searching o finding_base.
LDAP_USER_SEARCH_SIZE_LIMIT 10 multisite no Número máximo de entradas LDAP devueltas por la búsqueda de usuarios.
LDAP_USER_SEARCH_TIME_LIMIT 10 multisite no Tiempo máximo de búsqueda LDAP de usuarios en segundos.
LDAP_USER_SEARCH_ATTRIBUTES dn multisite no Atributos solicitados durante la búsqueda de usuarios (separados por espacios).
LDAP_USER_SEARCH_DN_FIELD object_name multisite no Nombre del campo en la respuesta de búsqueda para extraer el DN del usuario. El valor predeterminado object_name es el campo DN devuelto por la librería LDAP subyacente; normalmente no necesita cambiarlo.
LDAP_USER_SEARCH_REQUIRE_UNIQUE yes multisite no Exigir exactamente un resultado de búsqueda antes de autenticar al usuario.

Modo bind directo

Configuración Predeterminado Contexto Múltiple Descripción
LDAP_USER_DN_TEMPLATE uid={username},ou=people,dc=example,dc=com multisite no Plantilla de DN de usuario para bind directo. Debe incluir {username} al configurarlo.

Sesión y rutas

Configuración Predeterminado Contexto Múltiple Descripción
LDAP_USERNAME_REGEX ^[A-Za-z0-9@._-]+$ multisite no Regex PCRE para validar los nombres de usuario enviados.
LDAP_LOGIN_PATH /ldap/login multisite no Ruta de la página de inicio de sesión expuesta por el plugin LDAP.
LDAP_LOGOUT_PATH /ldap/logout multisite no Ruta de cierre de sesión expuesta por el plugin LDAP.
LDAP_SESSION_TTL 3600 multisite no Duración de validez de la sesión LDAP en segundos.
LDAP_REALM LDAP SSO multisite no Realm de autenticación mostrado en el formulario de inicio de sesión LDAP.
LDAP_USER_HEADER X-User multisite no Cabecera para enviar el nombre de usuario autenticado al upstream (vacío para deshabilitar).
LDAP_REDIRECT_AFTER_LOGIN / multisite no Ruta relativa de respaldo tras inicio de sesión exitoso cuando no se proporciona un destino de redirección.
LDAP_REDIRECT_AFTER_LOGOUT / multisite no Ruta relativa para redirigir a los usuarios tras el cierre de sesión.

Inicio rápido

  1. Establezca los valores mínimos por servicio protegido:
    • USE_LDAP=yes
    • LDAP_HOST=ldap.example.com
  2. Para el modo de búsqueda empresarial (recomendado), configure también:
    • LDAP_BIND_DN=cn=readonly,dc=example,dc=com
    • LDAP_BIND_PASSWORD=secret (use Docker secrets en producción)
    • LDAP_USER_SEARCH_BASE_DN=ou=people,dc=example,dc=com
  3. Para el modo bind directo, ajuste LDAP_USER_DN_TEMPLATE para que coincida con la estructura de su directorio.
  4. Opcionalmente, restrinja el acceso con LDAP_AUTHZ_FILTER (p. ej. (memberOf=cn=allowed,ou=groups,dc=example,dc=com)).

Consejos de uso

  • Prefiera el modo búsqueda-luego-bind sobre el bind directo: admite búsquedas flexibles de usuarios en múltiples atributos (uid, mail, sAMAccountName, UPN).
  • Use LDAPS (LDAP_LDAPS=yes) o STARTTLS (LDAP_STARTTLS=yes) en producción para cifrar las credenciales en tránsito.
  • Al habilitar LDAPS (LDAP_LDAPS=yes), recuerde también establecer LDAP_PORT=636. El puerto no cambia automáticamente.
  • Mantenga LDAP_SSL_VERIFY=yes salvo que esté realizando pruebas con certificados autofirmados.
  • Ajuste LDAP_KEEPALIVE_POOL_SIZE para que coincida con el volumen esperado de usuarios concurrentes y reducir la sobrecarga de conexiones LDAP.
  • Establezca LDAP_USER_HEADER como vacío para deshabilitar el reenvío de identidad a los upstreams.

OpenAPI Validator crown pro icon (PRO)

El plugin OpenAPI Validator aplica su contrato de API validando las solicitudes entrantes contra una especificación OpenAPI / Swagger. Asegura que la ruta solicitada exista, que el método HTTP esté permitido y, opcionalmente, valida los parámetros de consulta, cabecera, cookie y ruta contra sus definiciones de esquema.

Cómo funciona

  1. Un trabajo programado (openapi-download.py) obtiene el documento OpenAPI de una URL o archivo y lo guarda en caché en el disco (cada hora por defecto).
  2. En el momento de la inicialización de NGINX, el plugin compila las rutas de la especificación almacenada en caché y las guarda en un almacenamiento interno compartido.
  3. Durante el procesamiento de la solicitud, el plugin hace coincidir la solicitud con las rutas compiladas y aplica la validación.

Características

  • Validación de ruta y método con una respuesta 405 cuando el método no está permitido.
  • Validación opcional de parámetros para consulta, cabecera, cookie y ruta.
  • Sobrescritura de la ruta base mediante OPENAPI_BASE_PATH o derivación automática desde la especificación.
  • Permitir o denegar solicitudes a rutas no listadas en la especificación.
  • Lista de ignorados configurable para endpoints como documentación o archivos de especificación.
  • La especificación almacenada en caché se actualiza cada hora sin bloquear las solicitudes.

Configuración

Ajuste Por defecto Contexto Múltiple Descripción
USE_OPENAPI_VALIDATOR no multisite no Habilita la validación de rutas OpenAPI para este sitio.
OPENAPI_SPEC multisite no Ruta absoluta o URL HTTP(S) al documento OpenAPI en formato JSON/YAML.
OPENAPI_BASE_PATH multisite no Prefijo de ruta base opcional para anteponer a cada ruta en la especificación.
OPENAPI_ALLOW_UNSPECIFIED no multisite no Permite solicitudes a rutas no listadas en la especificación.
OPENAPI_ALLOW_INSECURE_URL no multisite no Permite obtener la especificación OpenAPI a través de HTTP simple (no recomendado).
OPENAPI_IGNORE_URLS ^/docs$ ^/redoc$ ^/openapi\\.json$ multisite no Lista de regex de URL separadas por espacios para omitir la validación OpenAPI.
OPENAPI_MAX_SPEC_SIZE 2M global no Tamaño máximo permitido del documento OpenAPI (acepta sufijos k/M/G).
OPENAPI_VALIDATE_PARAMS yes multisite no Valida parámetros de consulta, cabecera, cookie y ruta contra la especificación.

Notas de comportamiento

  • OPENAPI_SPEC puede ser un archivo local o una URL HTTPS. Las URL HTTP se bloquean a menos que OPENAPI_ALLOW_INSECURE_URL=yes.
  • Si OPENAPI_BASE_PATH está vacío, el plugin deriva la ruta base de servers[*].url (OpenAPI 3) o basePath (Swagger 2) cuando está presente.
  • Se aceptan solicitudes HEAD cuando se define GET para la misma ruta, y la coincidencia de ruta tolera una barra diagonal final.
  • Cuando una ruta falta en la especificación y OPENAPI_ALLOW_UNSPECIFIED=no, la solicitud se deniega utilizando el estado de denegación configurado.
  • Los fallos de validación de parámetros se deniegan y solo se registra el primer error para mantener los registros concisos.

Inicio rápido

Establezca los valores mínimos por servicio protegido:

  • USE_OPENAPI_VALIDATOR=yes
  • OPENAPI_SPEC=/ruta/a/openapi.yaml (o https://...)

Opcionalmente, permita rutas desconocidas durante el despliegue:

  • OPENAPI_ALLOW_UNSPECIFIED=yes

Cache crown pro icon (PRO)

Soporte STREAM ❌

El plugin Cache PRO habilita el almacenamiento en caché de respuestas a nivel de reverse proxy usando directivas NGINX proxy_cache*. Es útil para absorber lecturas repetidas de contenido cacheable, proteger a los upstreams durante picos de carga y servir contenido obsoleto durante fallos breves del backend.

Cómo funciona

  1. Cada valor global CACHE_PATH* crea una directiva proxy_cache_path en el contexto HTTP.
  2. Un servicio empieza a usar la caché solo cuando CACHE_ZONE coincide con una de las zonas declaradas en CACHE_PATH*.
  3. Las configuraciones a nivel de servicio controlan después la clave de caché, las condiciones de bypass/no-cache, el locking, el uso de stale y las reglas de validez.
  4. Si se define CACHE_HEADER, BunkerWeb añade una cabecera de respuesta que expone $upstream_cache_status como HIT, MISS, BYPASS, EXPIRED o STALE.

Lista de características

  • Caché de respuestas de reverse proxy con rutas y zonas configurables.
  • Activación de caché por servicio mediante CACHE_ZONE.
  • Cabecera opcional para exponer el estado de la caché con $upstream_cache_status.
  • Controles detallados para bypass, no-cache, clave, métodos, locking, stale y revalidación.
  • Varias reglas de validez mediante configuraciones CACHE_VALID*.

Lista de configuraciones

Configuración Predeterminado Contexto Múltiple Descripción
CACHE_PATH global sí Ruta y parámetros para una caché.
CACHE_ZONE multisite no Nombre de la zona de caché a usar (definida en una configuración CACHE_PATH).
CACHE_HEADER X-Cache multisite no Añade una cabecera que expone el estado de la caché.
CACHE_BACKGROUND_UPDATE no multisite no Habilita o deshabilita la actualización en segundo plano de la caché.
CACHE_BYPASS multisite no Lista de variables que determinan si se debe omitir la caché.
CACHE_NO_CACHE $http_pragma$http_authorization multisite no Evita almacenar en caché si ciertas variables están definidas.
CACHE_KEY $scheme$proxy_host$request_uri multisite no Clave usada para identificar elementos cacheados.
CACHE_CONVERT_HEAD_TO_GET yes multisite no Convierte solicitudes HEAD en GET al cachear.
CACHE_LOCK no multisite no Bloquea solicitudes concurrentes mientras se llena la caché.
CACHE_LOCK_AGE 5s multisite no Pasa la solicitud al upstream si el bloqueo dura ese tiempo.
CACHE_LOCK_TIMEOUT 5s multisite no Pasa la solicitud al upstream si el bloqueo persiste durante ese tiempo.
CACHE_METHODS GET HEAD multisite no Solo cachea respuestas para estos métodos HTTP.
CACHE_MIN_USES 1 multisite no Número de solicitudes antes de guardar la respuesta en caché.
CACHE_REVALIDATE no multisite no Revalida entradas expiradas con solicitudes condicionales al upstream.
CACHE_USE_STALE off multisite no Determina cuándo se puede servir contenido obsoleto.
CACHE_VALID 10m multisite sí Define la duración de caché con códigos HTTP opcionales.

Ejemplo de uso

  1. Define una ruta global de caché y una zona:
CACHE_PATH: "/var/cache/bunkerweb/proxy levels=1:2 keys_zone=htmlcache:10m max_size=1g inactive=60m use_temp_path=off"
  1. Habilita el reverse proxy y asocia la zona a un servicio:
www.example.com_USE_REVERSE_PROXY: "yes"
www.example.com_REVERSE_PROXY_HOST: "http://app:8080"
www.example.com_CACHE_ZONE: "htmlcache"
www.example.com_CACHE_HEADER: "X-Cache"
www.example.com_CACHE_VALID: "200 301 302 10m"
www.example.com_CACHE_VALID_1: "404 1m"
  1. Añade controles opcionales cuando sea necesario:
www.example.com_CACHE_BYPASS: "$cookie_nocache $arg_nocache"
www.example.com_CACHE_NO_CACHE: "$http_pragma $http_authorization"
www.example.com_CACHE_LOCK: "yes"
www.example.com_CACHE_BACKGROUND_UPDATE: "yes"
www.example.com_CACHE_USE_STALE: "error timeout updating http_500 http_502 http_503 http_504"

Comportamiento importante

  • Este plugin solo se aplica al tráfico reverse proxy. No cachea contenido servido directamente desde archivos estáticos locales ni servicios stream/TCP.
  • CACHE_ZONE debe coincidir con una zona definida en un valor CACHE_PATH* mediante keys_zone=<nombre>:<tamaño>.
  • Si CACHE_ZONE está vacío para un servicio, no se aplican directivas de caché a ese servicio.
  • Usa sufijos numéricos para valores repetidos como CACHE_PATH_1, CACHE_PATH_2, CACHE_VALID_1 y CACHE_VALID_2.
  • Mantén fuera de la caché el tráfico autenticado o específico de usuario salvo que CACHE_KEY varíe explícitamente según ese estado.
  • CACHE_LOCK=yes y CACHE_BACKGROUND_UPDATE=yes ayudan a reducir estampidas hacia el origen.

ACME crown pro icon (PRO)

Soporte STREAM ✅

El plugin ACME proporciona gestión avanzada de certificados mediante el protocolo ACME con soporte para Autoridades de Certificación personalizadas (Step CA, Vault PKI, Sectigo, Google Trust Services, etc.). Complementa el plugin integrado de Let's Encrypt agregando soporte para CA personalizadas, desafíos DNS-01 y TLS-ALPN-01, certificados wildcard, monitoreo de certificados con alertas de expiración, monitoreo de logs de Certificate Transparency y stapling OCSP mejorado.

Cuándo usar ACME vs el plugin integrado de Let's Encrypt

Si solo necesita certificados de Let's Encrypt con desafíos HTTP-01, el plugin integrado de Let's Encrypt (AUTO_LETS_ENCRYPT=yes) es suficiente. Use el plugin ACME cuando necesite CA personalizadas, desafíos DNS-01 o TLS-ALPN-01, certificados wildcard o monitoreo de certificados con alertas.

Características

  • Soporte para CA personalizadas: use cualquier Autoridad de Certificación compatible con ACME, no solo Let's Encrypt.
  • Múltiples tipos de desafío: HTTP-01, DNS-01 (requerido para wildcards) y TLS-ALPN-01.
  • Integración con proveedores DNS: soporte integrado para Cloudflare, Route53, DigitalOcean, OVH y más.
  • External Account Binding (EAB): para CA que requieren claves preregistradas (Sectigo, Google Trust Services).
  • Certificados wildcard: mediante desafío DNS-01.
  • Monitoreo de certificados: rastrea la expiración de todos los certificados gestionados (incluido Let's Encrypt OSS) con umbrales de alerta configurables.
  • Alertas de expiración: envía alertas por webhook o correo electrónico cuando los certificados se acercan a su vencimiento.
  • Monitoreo de Certificate Transparency: consulta crt.sh para detectar emisiones no autorizadas de certificados para sus dominios.
  • Stapling OCSP mejorado: obtención y almacenamiento proactivo de respuestas OCSP.
  • Tipos de clave configurables: ECDSA (256/384) o RSA (2048/4096).

Prerrequisitos

El desafío HTTP-01 requiere LETS_ENCRYPT_PASSTHROUGH=yes

Al usar ACME_CHALLENGE=http (el valor predeterminado), debe establecer LETS_ENCRYPT_PASSTHROUGH=yes en el mismo servicio.

El plugin principal de Let's Encrypt de BunkerWeb incluye tanto un bloque de ubicación NGINX como un handler de acceso Lua para /.well-known/acme-challenge/. Dado que el bloque de ubicación NGINX coincide antes de que se ejecute cualquier código de plugin Lua, intercepta las solicitudes del desafío antes de que ACME PRO pueda atenderlas. Establecer LETS_ENCRYPT_PASSTHROUGH=yes deshabilita ambos mecanismos para que ACME PRO pueda gestionar correctamente los tokens del desafío HTTP-01.

Esto solo es necesario para HTTP-01. Los desafíos DNS-01 y TLS-ALPN-01 no se ven afectados.

Passthrough ACME al upstream (ACME_PASSTHROUGH)

Si el servidor upstream detrás de BunkerWeb ya ejecuta su propio cliente ACME y debe encargarse él mismo de la validación HTTP-01, establezca ACME_PASSTHROUGH=yes en el servicio. ACME PRO dejará de renderizar su bloque de ubicación /.well-known/acme-challenge/ y no añadirá las rutas del desafío a la lista blanca en la fase access, de modo que los archivos de validación servidos por el upstream lleguen intactos a la CA.

Mantenga ACME_PASSTHROUGH=no (el valor predeterminado) cuando desee que ACME PRO obtenga y renueve los certificados por sí mismo. La combinación estándar HTTP-01 para los servicios gestionados por ACME PRO es LETS_ENCRYPT_PASSTHROUGH=yes (para que el plugin OSS principal de Let's Encrypt libere su ubicación del desafío) junto con ACME_PASSTHROUGH=no. Establezca ACME_PASSTHROUGH=yes únicamente cuando el upstream sea el propietario del ciclo de vida del certificado — en este modo BunkerWeb no intentará emitir un certificado para ese servicio.

Esta configuración refleja el comportamiento del LETS_ENCRYPT_PASSTHROUGH del núcleo OSS y solo afecta a HTTP-01; los desafíos DNS-01 y TLS-ALPN-01 no se ven afectados.

Orden de ejecución de plugins

El plugin ACME se reordena automáticamente para ejecutarse primero en la fase NGINX ssl_certificate, asegurando que los certificados del desafío TLS-ALPN-01 se sirvan antes de que otros plugins que proporcionan certificados (selfsigned, letsencrypt, customcert) puedan cortocircuitar el bucle.

Al usar ACME junto con otros plugins PRO que dependen de TLS válido (p. ej. OpenID Connect, UI SSO), se recomienda agregar explícitamente acme justo después de customcert en las configuraciones de orden de fases relevantes:

PLUGINS_ORDER_SSL_CERTIFICATE=customcert acme letsencrypt selfsigned
PLUGINS_ORDER_INIT=sessions whitelist blacklist greylist bunkernet limit authbasic securitytxt robotstxt crowdsec dnsbl headers customcert acme letsencrypt selfsigned

Los plugins externos/PRO no listados en las configuraciones PLUGINS_ORDER_* se agregan alfabéticamente después de los plugins principales ordenados explícitamente.

No habilite USE_ACME y AUTO_LETS_ENCRYPT en el mismo servicio

El plugin ACME y el plugin integrado de Let's Encrypt usan almacenamiento, endpoints de API y claves de caché independientes, pero habilitar ambos en el mismo servicio causará conflictos. Use uno u otro por servicio. En modo multisite, diferentes servicios pueden usar diferentes plugins -- por ejemplo, app1.example.com_USE_ACME=yes y app2.example.com_AUTO_LETS_ENCRYPT=yes.

Configuración

Ajustes principales de ACME

Configuración Predeterminado Contexto Múltiple Descripción
USE_ACME no multisite no Habilitar la gestión de certificados ACME para este servicio.
ACME_PASSTHROUGH no multisite no Pasar las solicitudes del desafío HTTP-01 al servidor upstream (el upstream ejecuta su propio cliente ACME).
ACME_DIRECTORY_URL multisite no URL del directorio ACME de la Autoridad de Certificación.
ACME_EMAIL multisite no Dirección de correo electrónico para el registro de cuenta ACME y notificaciones.
ACME_CHALLENGE http multisite no Tipo de desafío ACME: http, dns o alpn.
ACME_KEY_TYPE ecdsa multisite no Tipo de clave para el certificado: ecdsa o rsa.
ACME_KEY_SIZE 256 multisite no Tamaño de clave en bits. ECDSA: 256 o 384. RSA: 2048 o 4096.
ACME_RENEWAL_DAYS 30 multisite no Renovar el certificado cuando falten menos de estos días para la expiración.
ACME_SSL_VERIFY yes multisite no Verificar certificados SSL al comunicarse con el servidor ACME.
ACME_WILDCARD no multisite no Solicitar certificado wildcard (requiere desafío DNS-01).
ACME_MUST_STAPLE no multisite no Solicitar la extensión OCSP Must-Staple en el certificado.
ACME_MAX_RETRIES 3 multisite no Número de reintentos de generación del certificado en caso de fallo (0 deshabilita reintentos).
ACME_PREFERRED_CHAIN multisite no CN del emisor preferido de la cadena de certificados cuando la CA ofrece múltiples cadenas.
ACME_CA_CERT_PATH multisite no Ruta al certificado raíz de la CA para servidores ACME privados.

External Account Binding (EAB)

Configuración Predeterminado Contexto Múltiple Descripción
ACME_EAB_KID multisite no Key ID de External Account Binding (requerido por algunas CA).
ACME_EAB_HMAC_KEY multisite no Clave HMAC de External Account Binding (codificada en base64).

Desafío DNS-01

Configuración Predeterminado Contexto Múltiple Descripción
ACME_DNS_PROVIDER multisite no Proveedor DNS para los desafíos DNS-01.
ACME_DNS_CREDENTIAL_ITEM multisite sí Credencial del proveedor DNS en formato key value (p. ej. cloudflare_api_token YOUR_TOKEN). Use sufijos numéricos para múltiples elementos (p. ej. ACME_DNS_CREDENTIAL_ITEM_1). Los valores pueden estar codificados en base64.
ACME_DNS_CREDENTIAL_DECODE_BASE64 yes multisite sí Decodificar automáticamente credenciales del proveedor DNS en base64. Deshabilite si sus credenciales son texto plano que coincide con base64 válido.
ACME_DNS_PROPAGATION default multisite no Tiempo de espera para la propagación DNS en segundos (default o un número).

Monitoreo de certificados

Configuración Predeterminado Contexto Múltiple Descripción
USE_ACME_MONITORING yes global no Habilitar el monitoreo de expiración de certificados para todos los certificados gestionados (incluido Let's Encrypt OSS).
ACME_ALERT_DAYS 30 14 7 1 global no Lista de umbrales de días separados por espacios que activan alertas de expiración.

Alertas (webhook)

Configuración Predeterminado Contexto Múltiple Descripción
USE_ACME_ALERT_WEBHOOK no global no Enviar alertas de certificados por webhook.
ACME_ALERT_WEBHOOK_URLS global no Lista de URLs de webhook separadas por espacios para alertas.

Alertas (correo electrónico)

Configuración Predeterminado Contexto Múltiple Descripción
USE_ACME_ALERT_EMAIL no global no Enviar alertas de certificados por correo electrónico.
ACME_ALERT_SMTP_EMAILS global no Lista de destinatarios de correo separados por espacios.
ACME_ALERT_SMTP_HOST global no Host SMTP para correos de alertas de certificados.
ACME_ALERT_SMTP_PORT 465 global no Puerto SMTP (SSL=465, TLS=587).
ACME_ALERT_SMTP_FROM_EMAIL global no Dirección de correo del remitente para alertas de certificados.
ACME_ALERT_SMTP_FROM_USER global no Usuario de autenticación SMTP.
ACME_ALERT_SMTP_FROM_PASSWORD global no Contraseña de autenticación SMTP.
ACME_ALERT_SMTP_SSL SSL global no Tipo de conexión: no, SSL o TLS.

Monitoreo de Certificate Transparency

Configuración Predeterminado Contexto Múltiple Descripción
USE_ACME_CT_MONITORING no global no Habilitar el monitoreo de logs CT mediante crt.sh para detectar emisiones no autorizadas de certificados.
ACME_CT_MONITORED_DOMAINS global no Lista de dominios a monitorear separados por espacios. Déjelo vacío para detección automática.

Stapling OCSP

Configuración Predeterminado Contexto Múltiple Descripción
USE_ACME_OCSP_STAPLING no multisite no Habilitar stapling OCSP mejorado con obtención y almacenamiento proactivo de respuestas.
ACME_OCSP_CACHE_SIZE 1m global no Tamaño del diccionario compartido para el almacenamiento de respuestas OCSP.

Inicio rápido

  1. Establezca los valores mínimos por servicio protegido:
    • USE_ACME=yes
    • ACME_DIRECTORY_URL=https://ca.example.com/acme/directory
    • ACME_EMAIL=admin@example.com
  2. Para certificados wildcard, cambie al desafío DNS-01:
    • ACME_CHALLENGE=dns
    • ACME_DNS_PROVIDER=cloudflare
    • ACME_DNS_CREDENTIAL_ITEM=cloudflare_api_token YOUR_TOKEN (use Docker secrets en producción)
    • ACME_WILDCARD=yes
  3. Para CA que requieren External Account Binding:
    • ACME_EAB_KID=your-key-id
    • ACME_EAB_HMAC_KEY=your-base64-hmac-key (use Docker secrets en producción)
  4. Para CA privadas con certificados raíz autofirmados:
    • ACME_CA_CERT_PATH=/path/to/ca-root.pem
    • ACME_SSL_VERIFY=yes (proporcionar ACME_CA_CERT_PATH permite que la verificación funcione con CA privadas sin deshabilitar la verificación SSL)

Consejos de uso

  • El monitoreo de certificados (USE_ACME_MONITORING) está habilitado por defecto y también rastrea los certificados de Let's Encrypt OSS. Configure los umbrales de ACME_ALERT_DAYS y al menos un canal de alertas (webhook o correo electrónico) para recibir avisos de expiración.
  • Habilite el monitoreo CT (USE_ACME_CT_MONITORING=yes) para detectar certificados no autorizados emitidos para sus dominios mediante logs de Certificate Transparency.
  • Use claves ECDSA (valor predeterminado) para certificados más pequeños y rápidos. Cambie a RSA solo cuando se requiera compatibilidad con clientes antiguos.
  • Al usar desafíos DNS-01, ajuste ACME_DNS_PROPAGATION si su proveedor DNS tarda en propagar los registros.
  • Establezca ACME_MAX_RETRIES=0 para deshabilitar los reintentos automáticos si prefiere investigar los fallos manualmente.

Coexistencia con el plugin integrado de Let's Encrypt

ACME PRO y el plugin de Let's Encrypt OSS usan almacenamiento, endpoints de API y claves de caché completamente separados. Ambos pueden estar activos simultáneamente en diferentes servicios en modo multisite:

MULTISITE: "yes"
SERVER_NAME: "app1.example.com app2.example.com"

# ACME PRO para app1 (CA privada)
app1.example.com_USE_ACME: "yes"
app1.example.com_ACME_DIRECTORY_URL: "https://ca.internal:9000/acme/acme/directory"
app1.example.com_ACME_CA_CERT_PATH: "/certs/step-ca-root.pem"
app1.example.com_LETS_ENCRYPT_PASSTHROUGH: "yes"  # necesario para HTTP-01

# Let's Encrypt integrado para app2
app2.example.com_AUTO_LETS_ENCRYPT: "yes"

Solución de problemas

  • Fallo en el desafío HTTP-01: asegúrese de que LETS_ENCRYPT_PASSTHROUGH=yes esté configurado; sin él, el bloque de ubicación principal de BunkerWeb intercepta las solicitudes del desafío antes de que ACME PRO pueda atenderlas. Verifique también que el puerto 80 sea accesible desde el servidor ACME y que AUTO_LETS_ENCRYPT no esté habilitado para el mismo servicio.
  • Fallo en el desafío TLS-ALPN-01: asegúrese de que el puerto 443 sea accesible desde el servidor ACME y que ningún otro plugin esté sirviendo un certificado antes de ACME en la fase ssl_certificate. Revise PLUGINS_ORDER_SSL_CERTIFICATE en caso de duda.
  • Fallo en el desafío DNS-01: verifique las credenciales del proveedor DNS en ACME_DNS_CREDENTIAL_ITEM y ajuste ACME_DNS_PROPAGATION si su proveedor tarda en propagar los registros.
  • El certificado no se renueva: revise ACME_RENEWAL_DAYS y los logs del programador. El trabajo acme-renew se ejecuta diariamente y renueva los certificados que están dentro del umbral configurado.

Wildcard crown pro icon (PRO)

Compatibilidad con STREAM ❌

El plugin Wildcard permite que un único servicio de BunkerWeb responda a:

  • su nombre de host exacto
  • cualquier subdominio directo de ese nombre de host

Cuando está habilitado, el plugin toma la primera entrada de SERVER_NAME y añade un server_name comodín a la configuración NGINX generada.

Por ejemplo, si la primera entrada es example.com, el plugin añade:

server_name *.example.com;

Esto hace que el servicio responda a:

  • example.com
  • www.example.com
  • api.example.com

Este es un plugin mínimo, basado solo en configuración:

  • sin jobs
  • sin Lua
  • sin UI

Cómo funciona

El plugin obtiene el nombre de host comodín a partir del primer valor de SERVER_NAME e inyecta un nombre de servidor comodín estándar de NGINX durante la generación de la configuración.

No cambia la lógica de manejo de solicitudes más allá de la coincidencia de hostnames.

Los hosts comodín no son certificados comodín

Este plugin solo afecta al enrutamiento HTTP. Indica a NGINX qué hostnames debe aceptar el servicio.

No aprovisiona un certificado TLS comodín.

Para servir *.example.com por HTTPS, sigue necesitando un certificado comodín compatible, normalmente con una de estas opciones:

  • USE_LETS_ENCRYPT_WILDCARD=yes con el plugin integrado de Let's Encrypt
  • ACME_WILDCARD=yes con el plugin ACME PRO usando un desafío DNS-01

Funcionalidades

  • Activación simple: habilite el enrutamiento comodín con USE_WILDCARD=yes
  • Derivación automática: el host comodín se construye a partir de la primera entrada de SERVER_NAME
  • Semántica nativa de NGINX: la coincidencia sigue el comportamiento estándar de server_name
  • Compatible con multisite: cada servicio puede habilitar o deshabilitar el enrutamiento comodín de forma independiente

Configuración

Parámetro Valor predeterminado Contexto Múltiple Descripción
USE_WILDCARD no multisite no Habilita un server_name comodín para el servicio añadiendo *.domain para la primera entrada de SERVER_NAME.

Inicio rápido

  1. Coloque primero en SERVER_NAME el dominio que quiere convertir en comodín
  2. Establezca USE_WILDCARD=yes
  3. Haga que el registro DNS comodín apunte a BunkerWeb, normalmente con un registro comodín A o AAAA
  4. Si necesita HTTPS, aprovisione un certificado comodín por separado
  5. Recargue o reinicie BunkerWeb

Ejemplos

Single-site

SERVER_NAME: "example.com"
USE_WILDCARD: "yes"

Este servicio responderá a:

  • example.com
  • www.example.com
  • api.example.com
  • cualquier otro hostname *.example.com que resuelva hacia BunkerWeb

Multisite

MULTISITE: "yes"
SERVER_NAME: "app.example.com docs.example.org"

# Solo app.example.com obtiene enrutamiento comodín
app.example.com_USE_WILDCARD: "yes"

En esta configuración:

  • app.example.com y *.app.example.com van al primer servicio
  • docs.example.org conserva solo coincidencia exacta

Comportamiento importante

Solo el primer dominio se convierte en comodín

Si SERVER_NAME es:

SERVER_NAME: "example.com example.org"

solo se añade *.example.com.

Coloque primero el dominio que quiera usar como comodín.

Las entradas comodín existentes se conservan

Si el primer dominio ya empieza por *., por ejemplo:

SERVER_NAME: "*.example.com"

el plugin no emite nada.

La coincidencia comodín solo cubre una etiqueta

*.example.com coincide con foo.example.com, pero no con a.b.example.com.

Para subdominios más profundos, use una entrada explícita en SERVER_NAME o un servicio independiente.

Las coincidencias exactas tienen prioridad

Si otro servicio define explícitamente foo.example.com, NGINX enruta primero ese hostname a la coincidencia exacta.

Recomendado con certificados wildcard de Let's Encrypt

Si utiliza este plugin junto con USE_LETS_ENCRYPT_WILDCARD=yes, use este patrón:

SERVER_NAME: "<root_domain> <any_app>.<root_domain>"

El dominio raíz debe ir primero.

Ejemplo:

SERVER_NAME: "example.com app.example.com"
USE_WILDCARD: "yes"
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 YOUR_API_TOKEN"
USE_LETS_ENCRYPT_WILDCARD: "yes"

Por qué importa este patrón

  • Solo la primera entrada de SERVER_NAME se convierte en comodín

Si example.com va primero, el plugin genera *.example.com.

Si app.example.com va primero, genera *.app.example.com, lo que normalmente corresponde al nivel de comodín equivocado.

  • La segunda entrada ayuda a Let's Encrypt a detectar el dominio base correcto Con solo un dominio apex, la detección del certificado comodín puede fallar en algunos dominios de sufijo público como example.co.uk.

  • El segundo hostname no necesita un backend real Use cualquier valor estable como app.example.com o www.example.com.

Multisite con Let's Encrypt wildcard

MULTISITE: "yes"
SERVER_NAME: "example.com app.example.com"
example.com_USE_WILDCARD: "yes"
example.com_USE_LETS_ENCRYPT_WILDCARD: "yes"
example.com_LETS_ENCRYPT_CHALLENGE: "dns"
example.com_LETS_ENCRYPT_DNS_PROVIDER: "cloudflare"
example.com_LETS_ENCRYPT_DNS_CREDENTIAL_ITEM: "api_token YOUR_API_TOKEN"

Consejos de uso

  • Planifique TLS por separado El enrutamiento comodín no basta para HTTPS. Sigue necesitando cobertura de certificados para los subdominios.

  • Mantenga estable el orden de SERVER_NAME Reordenar las entradas cambia qué dominio se convierte en el objetivo del comodín.

  • Funciona bien con REVERSE_PROXY_HOST Es útil cuando muchos subdominios se enrutan a través de un upstream compartido, como un router de tenants.

  • Tenga cuidado con los servicios superpuestos NGINX siempre prefiere la coincidencia server_name más específica.