Módulo core#

El módulo proporciona la funcionalidad esencial y las directivas de configuración necesarias para la operación básica del servidor, y gestiona tareas críticas como la gestión de procesos de trabajo, la configuración de modelos orientados a eventos y el procesamiento de conexiones y solicitudes entrantes. Incluye directivas clave para configurar el proceso principal, el registro de errores y el control del comportamiento del servidor a bajo nivel.

Ejemplo de configuración#

user www www;
worker_processes 2;

error_log /var/log/error.log info;

events {

    use kqueue; worker_connections 2048;
}

Directivas#

accept_mutex#

Sintaxis

accept_mutex on | off;

Predeterminado

accept_mutex off;

Contexto

events

Cuando accept_mutex está habilitado, los procesos de trabajo aceptarán nuevas conexiones por turno. Sin esta configuración, todos los procesos de trabajo son notificados de nuevas conexiones, lo que puede conducir a un uso ineficiente de los recursos del sistema si el volumen de nuevas conexiones es bajo.

Nota

No es necesario habilitar accept_mutex en sistemas que admiten la bandera EPOLLEXCLUSIVE o cuando se utiliza la directiva reuseport.

accept_mutex_delay#

Sintaxis

accept_mutex_delay tiempo;

Predeterminado

accept_mutex_delay 500ms;

Contexto

events

Si accept_mutex está habilitado, esta directiva especifica el tiempo máximo que un proceso de trabajo esperará para continuar aceptando nuevas conexiones mientras otro proceso de trabajo ya está manejando nuevas conexiones.

daemon#

Sintaxis

daemon on | off;

Predeterminado

daemon on;

Contexto

main

Determina si Angie debe ejecutarse como un demonio. Esto se utiliza principalmente durante el desarrollo.

debug_connection#

Sintaxis

debug_connection dirección | CIDR | unix:;

Predeterminado

—

Contexto

events

Habilita los registros de depuración para conexiones de clientes específicas. Otras conexiones utilizarán el nivel de registro establecido por la directiva error_log. Puede especificar conexiones por dirección IPv4 o IPv6, red o nombre de host. Para conexiones que utilicen sockets de dominio UNIX, utilice el parámetro unix: para habilitar los registros de depuración.

events {

    debug_connection 127.0.0.1;
    debug_connection localhost;
    debug_connection 192.0.2.0/24;
    debug_connection ::1;
    debug_connection 2001:0db8::/32;
    debug_connection unix:;
    #  ...
}

Nota

Para que esta directiva funcione, Angie debe estar compilada con el registro de depuración habilitado.

debug_points#

Sintaxis

debug_points abort | stop;

Predeterminado

—

Contexto

main

Esta directiva se utiliza para depuración.

Cuando ocurre un error interno, como una fuga de socket durante los reinicios del proceso de trabajo, habilitar debug_points creará un archivo core (abort) o detendrá el proceso (stop) para un análisis posterior con un depurador del sistema.

env#

Sintaxis

env variable[=valor];

Predeterminado

env TZ;

Contexto

main

Por defecto, Angie elimina todas las variables de entorno heredadas de su proceso padre excepto la variable TZ. Esta directiva le permite conservar algunas variables heredadas, modificar sus valores o crear nuevas variables de entorno.

Estas variables son entonces:

Tenga en cuenta que controlar las bibliotecas del sistema de esta manera puede no ser siempre efectivo, ya que las bibliotecas a menudo verifican las variables solo durante la inicialización, que ocurre antes de que esta directiva surta efecto. La variable TZ siempre se hereda y es accesible para el módulo Perl a menos que se configure explícitamente lo contrario.

Ejemplo:

env MALLOC_OPTIONS;
env PERL5LIB=/data/site/modules;
env OPENSSL_ALLOW_PROXY_CERTS=1;

Nota

La variable de entorno ANGIE se utiliza internamente por Angie y no debe ser establecida directamente por el usuario.

error_log#

Sintaxis

error_log archivo [nivel] [[filter=parte:patrón] ...] [rate=tasa] [format=formato];

Predeterminado

error_log logs/error.log error; (la ruta depende de la opción de compilación --error-log-path build option)

Contexto

main, http, mail, stream, server, location

Configura el registro, permitiendo especificar múltiples logs en el mismo nivel de configuración. Si no se define explícitamente un archivo de log en el nivel de configuración main, se utilizará el archivo predeterminado.

El primer parámetro especifica el archivo donde almacenar el log. El valor especial stderr selecciona la salida de error estándar. Para configurar el registro en syslog, utilice el prefijo "syslog:". Para registrar en un buffer cíclico de memoria, utilice el prefijo "memory:" seguido del tamaño del buffer; esto se utiliza típicamente para depuración.

El segundo parámetro establece el nivel de registro, que puede ser uno de los siguientes: debug, info, notice, warn, error, crit, alert, o emerg. Estos niveles están listados en orden de gravedad creciente. Establecer un nivel de log capturará mensajes de igual y mayor gravedad:

Configuración

Niveles Capturados

debug

debug, info, notice, warn, error, crit, alert, emerg

info

info, notice, warn, error, crit, alert, emerg

notice

notice, warn, error, crit, alert, emerg

warn

warn, error, crit, alert, emerg

error

error, crit, alert, emerg

crit

crit, alert, emerg

alert

alert, emerg

emerg

emerg

Si este parámetro se omite, se usa error como nivel de registro predeterminado.

El parámetro opcional filter=parte:patrón restringe qué mensajes se escriben en el log, de modo que un mismo destino pueda recoger solo los eventos de interés. Cada parámetro comprueba una parte del mensaje frente al patrón, donde parte es una de las siguientes:

  • logline — con format=default, el mensaje junto con el error del sistema y los detalles de contexto, si los hay, pero sin el prefijo de marca de tiempo, nivel, proceso, hilo y conexión; no coincide con las entradas con format=json;

  • message — con format=default, el texto del mensaje sin el error del sistema ni los detalles de contexto; con format=json, el fragmento serializado y escapado que contiene el miembro message, y no su valor sin procesar;

  • tag — una etiqueta asociada al mensaje, incluidas las añadidas por la directiva error_log_user_tag y por sus equivalentes de stream y mail;

  • sourcefile — el archivo fuente que emitió el mensaje; solo está disponible cuando Angie se compila con el log de depuración habilitado;

  • cualquier otro nombre — un campo del contexto del mensaje, como alguno de los campos que se muestran en el formato JSON más abajo.

De forma predeterminada, el patrón se busca como subcadena. Anteponga = para exigir una coincidencia exacta, o ~ para usar una expresión regular, lo que requiere una compilación con la biblioteca PCRE.

Con format=json, una coincidencia exacta de message debe abarcar todo el fragmento serializado, incluidos su sintaxis JSON y su escapado.

Una misma directiva admite varios parámetros filter=; un mensaje se escribe solo si cumple todos. Sin embargo, cada campo de contexto puede ser comprobado por un único parámetro filter= por directiva: un segundo parámetro sobre el mismo campo nunca coincide, por lo que ningún mensaje se escribe en el destino.

El parámetro opcional rate=tasa limita la frecuencia máxima de mensajes escritos en el log, en mensajes por segundo; el valor puede terminar con el sufijo m/s (por ejemplo, rate=2000m/s). De forma predeterminada se usa rate=1000 (1000 mensajes por segundo); con rate=0 se desactiva el límite.

El límite se aplica por separado a cada directiva error_log y de forma independiente en cada proceso de trabajo. Una avalancha de mensajes de baja gravedad (por ejemplo, info) no suprime los de mayor gravedad, como error, porque a los niveles más graves se les permite una ráfaga proporcionalmente mayor; lo contrario no se cumple. Los mensajes en exceso se descartan. Esto regula el log en lugar de silenciarlo: bajo una sobrecarga sostenida, los mensajes se siguen escribiendo aproximadamente a la frecuencia configurada.

Cuando un destino empieza a descartar mensajes, Angie escribe en él, en lugar del primer mensaje descartado, un aviso "too many log messages, limiting" del mismo nivel; el aviso puede repetirse durante una sobrecarga sostenida. El aviso no lleva detalles de contexto ni etiquetas y debe pasar los parámetros filter= del destino, por lo que un destino filtrado por tag o por un campo de contexto nunca lo recibe. Tampoco se escribe el aviso en el destino con el nivel más detallado entre las directivas error_log vigentes (el primero declarado, si varios comparten ese nivel), de modo que con un único destino no aparece ningún aviso.

La limitación de frecuencia no se aplica cuando rige el nivel de registro debug para un mensaje, ya sea porque el propio archivo de log usa el nivel debug, o porque los logs de depuración están habilitados para la conexión mediante debug_connection.

Nota

Para que el nivel de registro debug funcione, Angie debe estar compilada con el registro de depuración habilitado.

El parámetro opcional format=formato selecciona el formato de las entradas del log. El valor predeterminado, format=default, produce el formato tradicional de texto sin formato que se describe a continuación; format=json escribe cada entrada como un único objeto JSON en una sola línea.

En el formato predeterminado, cada entrada del log de errores tiene el siguiente formato:

timestamp [level] PID#TID: *connection_id message

Donde:

  • timestamp — fecha y hora local del evento

  • level — nivel de registro del evento

  • PID#TID — identificadores de proceso e hilo

  • *connection_id — número de serie de la conexión, compartido por todas las solicitudes de la misma conexión (si aplica)

  • message — texto del mensaje de error o evento

Con format=json, cada entrada se escribe en cambio como un único objeto JSON, que aquí se muestra con sangría para facilitar la lectura; en el archivo de log ocupa una sola línea:

{
    "time": "2026-02-14T09:23:10.874Z",
    "level": "error",
    "pid": 22738,
    "tid": 22738,
    "connection": 7,
    "message": "limiting requests, excess: 1.000 by zone \"one\"",
    "http": {
        "client": "127.0.0.1",
        "request": {
            "server": "localhost",
            "request_line": "GET /debug HTTP/1.1",
            "host": "localhost"
        }
    },
    "tags": [
        "http"
    ]
}

Donde:

  • time — fecha y hora del evento en UTC, en formato ISO 8601 con el sufijo Z; los milisegundos se incluyen salvo que sean cero

  • level — nivel de registro del evento

  • pid y tid — identificadores de proceso e hilo

  • connection — número de conexión (el mismo valor que se muestra como *connection_id en el formato de texto), presente cuando la entrada está asociada a una conexión

  • message — texto del mensaje de error o evento

  • error — presente cuando el mensaje está asociado a un error del sistema; un objeto con los campos code y message

  • http, stream o mail — un objeto con los detalles de contexto de la entrada, identificado por el nombre del módulo donde se originó (para los detalles de contexto ajenos a estos módulos se usa un objeto genérico context); el objeto solo aparece en las entradas que llevan tales detalles y se registran en un nivel distinto de debug. El objeto de cada módulo tiene su propio conjunto de campos; por ejemplo, dentro de http, un objeto anidado request contiene request_line, la línea de solicitud, junto con otros detalles de la solicitud

  • tags — lista de etiquetas asociadas a la entrada, presente cuando se aplica al menos una; incluye las etiquetas añadidas automáticamente por los módulos y por las directivas error_log_user_tag

  • truncated — true, presente solo cuando la entrada tuvo que truncarse para caber en el búfer del log de errores

events#

Sintaxis

events { ... };

Predeterminado

—

Contexto

main

Proporciona el contexto del archivo de configuración para directivas que afectan al procesamiento de conexiones.

include#

Sintaxis

include archivo | máscara;

Predeterminado

—

Contexto

any

Incluye otro archivo, o archivos que coincidan con la máscara especificada, en la configuración. Los archivos incluidos deben contener directivas y bloques sintácticamente correctos.

Ejemplo:

include mime.types;
include vhosts/*.conf;

load_module#

Sintaxis

load_module file;

Predeterminado

—

Contexto

main

Carga un módulo dinámico desde el archivo especificado. Si se proporciona una ruta relativa, se interpreta en función de la opción de compilación --prefix build option. Para verificar la ruta:

$ sudo angie -V

Ejemplo:

load_module modules/ngx_mail_module.so;

Si un módulo dinámico se compiló para una compilación de Angie diferente, la carga falla con un error como: "module "..." was built for "..." but you are running "Angie"".

lock_file#

Sintaxis

lock_file file;

Predeterminado

lock_file logs/angie.lock; (la ruta depende de la opción de compilación --lock-path)

Contexto

main

Angie utiliza un mecanismo de bloqueo para implementar accept_mutex y serializar el acceso a la memoria compartida. En la mayoría de los sistemas, los bloqueos se gestionan mediante operaciones atómicas, lo que hace innecesaria esta directiva. En ciertos sistemas, sin embargo, se utiliza un mecanismo alternativo de archivo de bloqueo. Esta directiva establece un prefijo para los nombres de archivos de bloqueo.

master_process#

Sintaxis

master_process on | off;

Predeterminado

master_process on;

Contexto

main

Determina si se inician procesos de trabajo. Esta directiva está destinada para desarrolladores de Angie.

multi_accept#

Sintaxis

multi_accept on | off;

Predeterminado

multi_accept off;

Contexto

events

on

Un proceso de trabajo aceptará todas las nuevas conexiones simultáneamente.

off

Un proceso de trabajo aceptará una nueva conexión a la vez.

Nota

Esta directiva se ignora si se utiliza el método de procesamiento de conexiones kqueue, ya que proporciona el número de nuevas conexiones listas para ser aceptadas.

pcre_jit#

Sintaxis

pcre_jit on | off;

Predeterminado

pcre_jit off;

Contexto

main

Habilita o deshabilita la "compilación just-in-time" (PCRE JIT) para expresiones regulares conocidas en el momento del análisis de la configuración.

La PCRE JIT puede acelerar significativamente el procesamiento de expresiones regulares.

Nota

JIT está disponible en las bibliotecas PCRE desde la versión 8.20, siempre que se hayan compilado con la opción de configuración --enable-jit. Cuando Angie se compila con la biblioteca PCRE (--with-pcre=), el soporte JIT se habilita mediante la opción --with-pcre-jit.

pid#

Sintaxis

pid file | off;

Predeterminado

pid logs/angie.pid; (la ruta depende de la opción de compilación --pid-path)

Contexto

main

Especifica el archivo que almacenará el ID del proceso principal de Angie. El archivo se crea atómicamente, lo que garantiza que su contenido siempre sea correcto. La opción off desactiva la creación de este archivo.

Nota

Si se modifica el valor de file durante la reconfiguración pero apunta a un enlace simbólico del archivo PID anterior, el archivo no se volverá a crear.

ssl_engine#

Sintaxis

ssl_engine motor;

Predeterminado

—

Contexto

main

Hace que OpenSSL use de forma predeterminada el motor con el nombre especificado para todos los algoritmos implementados por el motor. El motor también puede configurarse en el archivo de configuración de OpenSSL.

ssl_object_cache_inheritable#

Sintaxis

ssl_object_cache_inheritable on | off;

Predeterminado

ssl_object_cache_inheritable on;

Contexto

main

Si está habilitado, los objetos SSL (certificados SSL, claves secretas, certificados CA de confianza, listas CRL) se heredan a través de las recargas de configuración.

Los objetos SSL cargados desde archivos se heredan si su tiempo de modificación e índice de archivo no han cambiado desde la carga de configuración anterior. Las claves secretas especificadas con el prefijo engine: o store: nunca se heredan, mientras que los certificados y las claves especificados con el prefijo data: siempre se heredan. Las claves secretas protegidas por una frase de contraseña no se almacenan en caché y, por tanto, nunca se heredan.

Los objetos SSL cargados desde variables no pueden heredarse.

Ejemplo:

ssl_object_cache_inheritable on;

http {
    server {
        ssl_certificate     example.com.crt;
        ssl_certificate_key example.com.key;
    }
}

thread_pool#

Sintaxis

thread_pool name threads=number [max_queue=number];

Predeterminado

thread_pool default threads=32 max_queue=65536;

Contexto

main

Define el nombre y los parámetros de un grupo de hilos utilizado para la lectura y envío de archivos multihilo sin bloqueo de procesos de trabajo.

El parámetro threads define el número de hilos en el grupo.

Si todos los hilos del grupo están ocupados ejecutando tareas, las nuevas tareas esperan en una cola. El parámetro max_queue limita el número de tareas permitidas para esperar en la cola. Por defecto, hasta 65536 tareas pueden estar en la cola. Cuando la cola se desborda, la tarea se completa con un error.

timer_resolution#

Sintaxis

timer_resolution interval;

Predeterminado

—

Contexto

main

Reduce la resolución del temporizador en los procesos de trabajo, reduciendo así el número de llamadas al sistema gettimeofday(). Por defecto, gettimeofday() se llama cada vez que se recibe un evento del kernel. Con resolución reducida, gettimeofday() solo se llama una vez por intervalo especificado.

Ejemplo:

timer_resolution 100ms;

La implementación interna del intervalo depende del método utilizado:

  • el filtro EVFILT_TIMER si se usa kqueue;

  • timer_create() si se usa eventport;

  • setitimer() en otros casos.

use#

Sintaxis

use method;

Predeterminado

—

Contexto

events

Especifica el método a utilizar para el procesamiento de conexiones. Normalmente no hay necesidad de especificarlo explícitamente, porque Angie utilizará por defecto el método más eficiente.

user#

Sintaxis

user user [group];

Predeterminado

user <build parameter --user> <build parameter --group>;

Contexto

main

Define las credenciales de user y group utilizadas por los procesos de trabajo (ver también parámetros de compilación). Si se omite group, se utiliza un grupo cuyo nombre es igual al de user.

worker_aio_requests#

Sintaxis

worker_aio_requests number;

Predeterminado

worker_aio_requests 32;

Contexto

events

Al usar aio con el método de procesamiento de conexiones epoll, establece el número máximo de operaciones de E/S asíncronas pendientes para un único proceso de trabajo.

worker_connections#

Sintaxis

worker_connections number;

Predeterminado

worker_connections 512;

Contexto

events

Establece el número máximo de conexiones simultáneas que puede abrir un proceso de trabajo.

Debe tenerse en cuenta que este número incluye todas las conexiones (por ejemplo, conexiones con servidores proxy, entre otras), no solo conexiones con clientes. Otra consideración es que el número real de conexiones simultáneas no puede exceder el límite actual del número máximo de archivos abiertos, que puede cambiarse mediante worker_rlimit_nofile.

worker_cpu_affinity#

Sintaxis

worker_cpu_affinity cpumask ...;

worker_cpu_affinity auto [cpumask];

Predeterminado

—

Contexto

main

Vincula los procesos de trabajo a conjuntos de CPUs. Cada conjunto de CPU está representado por una máscara de bits de CPUs permitidas. Debe definirse un conjunto separado para cada uno de los procesos de trabajo. Por defecto, los procesos de trabajo no están vinculados a ninguna CPU específica.

Por ejemplo:

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

Esta configuración vincula cada proceso de trabajo a una CPU separada.

Alternativamente:

worker_processes    2;
worker_cpu_affinity 0101 1010;

Esto vincula el primer proceso de trabajo a CPU0 y CPU2, y el segundo proceso de trabajo a CPU1 y CPU3. Esta configuración es adecuada para hyper-threading.

El valor especial auto permite vincular automáticamente los procesos de trabajo a las CPUs disponibles:

worker_processes auto;
worker_cpu_affinity auto;

El parámetro opcional de máscara puede utilizarse para limitar las CPUs disponibles para la vinculación automática:

worker_cpu_affinity auto 01010101;

Nota

La directiva solo está disponible en FreeBSD y Linux.

worker_priority#

Sintaxis

worker_priority number;

Predeterminado

worker_priority 0;

Contexto

main

Define la prioridad de planificación para los procesos de trabajo, tal como lo hace el comando nice: un number negativo significa mayor prioridad. El rango permitido normalmente varía de -20 a 20.

Ejemplo:

worker_priority -10;

worker_processes#

Sintaxis

worker_processes number | auto;

Predeterminado

worker_processes 1;

Contexto

main

Define el número de procesos de trabajo.

El valor óptimo depende de muchos factores, incluyendo (pero no limitado a) el número de núcleos de CPU, el número de discos duros que almacenan datos, y el patrón de carga. En caso de duda, establecerlo al número de núcleos de CPU disponibles sería un buen inicio (el valor "auto" intentará detectarlo automáticamente).

worker_rlimit_core#

Sintaxis

worker_rlimit_core tamaño;

Predeterminado

—

Contexto

main

Cambia el límite del tamaño máximo de un archivo core (RLIMIT_CORE) para los procesos de trabajo. Se utiliza para aumentar el límite sin reiniciar el proceso principal.

worker_rlimit_nofile#

Sintaxis

worker_rlimit_nofile number;

Predeterminado

—

Contexto

main

Cambia el límite del número máximo de archivos abiertos (RLIMIT_NOFILE) para los procesos de trabajo. Se utiliza para aumentar el límite sin reiniciar el proceso principal.

worker_shutdown_timeout#

Sintaxis

worker_shutdown_timeout tiempo;

Predeterminado

—

Contexto

main

Configura un tiempo de espera para un apagado ordenado de los procesos de trabajo. Cuando el tiempo especificado expira, Angie intentará cerrar todas las conexiones actualmente abiertas para facilitar el apagado.

El apagado ordenado se inicia enviando una señal QUIT al proceso principal, que indica a los procesos de trabajo que dejen de aceptar nuevas conexiones y permite que las conexiones existentes se completen. Los procesos de trabajo continúan manejando las solicitudes activas hasta que finalicen, y luego se apagan de manera ordenada. Si las conexiones permanecen abiertas más tiempo que worker_shutdown_timeout, Angie cerrará forzosamente estas conexiones para completar el apagado. Además, las conexiones keep-alive del cliente se cierran solo si han estado inactivas durante al menos el tiempo especificado por lingering_timeout.

working_directory#

Sintaxis

working_directory directory;

Predeterminado

—

Contexto

main

Define el directorio de trabajo actual para un proceso de trabajo. Se utiliza principalmente al escribir un archivo core, en cuyo caso un proceso de trabajo debe tener permiso de escritura para el directorio especificado.