Core Module#

The module provides essential functionality and configuration directives necessary for the basic operation of the server, and handles critical tasks such as managing worker processes, configuring event-driven models, and processing incoming connections and requests. It includes key directives for setting up the main process, error logging, and controlling the behavior of the server at a low level.

Configuration Example#

user www www;
worker_processes 2;

error_log /var/log/error.log info;

events {

    use kqueue; worker_connections 2048;
}

Directives#

accept_mutex#

Syntax

accept_mutex on | off;

Default

accept_mutex off;

Context

events

When accept_mutex is enabled, worker processes will accept new connections in turn. Without this setting, all worker processes are notified of new connections, which can lead to inefficient use of system resources if the volume of new connections is low.

Note

There is no need to enable accept_mutex on systems that support the EPOLLEXCLUSIVE flag or when using the reuseport directive.

accept_mutex_delay#

Syntax

accept_mutex_delay time;

Default

accept_mutex_delay 500ms;

Context

events

If accept_mutex is enabled, this directive specifies the maximum time a worker process will wait to continue accepting new connections while another worker process is already handling new connections.

daemon#

Syntax

daemon on | off;

Default

daemon on;

Context

main

Determines whether Angie should run as a daemon. This is primarily used during development.

debug_connection#

Syntax

debug_connection address | CIDR | unix:;

Default

Context

events

Enables debugging logs for specific client connections. Other connections will use the logging level set by the error_log directive. You can specify connections by IPv4 or IPv6 address, network, or hostname. For connections using UNIX domain sockets, use the unix: parameter to enable debugging logs.

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:;
    #  ...
}

Important

For this directive to work, Angie must be built with debugging log enabled.

debug_points#

Syntax

debug_points abort | stop;

Default

Context

main

This directive is used for debugging.

When an internal error occurs, such as a socket leak during worker process restarts, enabling debug_points will either create a core file (abort) or stop the process (stop) for further analysis with a system debugger.

env#

Syntax

env variable[=value];

Default

env TZ;

Context

main

By default, Angie removes all environment variables inherited from its parent process except for the TZ variable. This directive allows you to preserve some inherited variables, modify their values, or create new environment variables.

These variables are then:

Note that controlling system libraries in this way may not always be effective, as libraries often check variables only during initialization, which occurs before this directive takes effect. The TZ variable is always inherited and accessible to the Perl module unless explicitly configured otherwise.

Example:

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

Note

The ANGIE environment variable is used internally by Angie and should not be set directly by the user.

error_log#

Syntax

error_log file [level];

Default

error_log logs/error.log error;

Context

main, http, mail, stream, server, location

Configures logging, allowing multiple logs to be specified at the same configuration level. If a log file is not explicitly defined at the main configuration level, the default file will be used.

The first parameter specifies the file to store the log. The special value stderr selects the standard error stream. To configure logging to syslog, use the "syslog:" prefix. To log to a cyclic memory buffer, use the "memory:" prefix followed by the buffer size; this is typically used for debugging.

The second parameter sets the logging level, which can be one of the following: debug, info, notice, warn, error, crit, alert, or emerg. These levels are listed in order of increasing severity. Setting a log level will capture messages of equal and higher severity:

Setting

Levels Captured

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

If this parameter is omitted, error is used as the default logging level.

Important

For the debug logging level to work, Angie must be built with debugging log enabled.

events#

Syntax

events { ... };

Default

Context

main

Provides the configuration file context for directives that affect connection processing.

include#

Syntax

include file | mask;

Default

Context

any

Includes another file, or files that match the specified mask, into the configuration. The included files must contain syntactically correct directives and blocks.

Example:

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

load_module#

Syntax

load_module file;

Default

Context

main

Loads a dynamic module from the specified file. If a relative path is provided, it is interpreted based on the --prefix build option. To verify the path:

$ sudo angie -V

Example:

load_module modules/ngx_mail_module.so;

lock_file#

Syntax

lock_file file;

Default

lock_file logs/angie.lock;

Context

main

Angie uses a locking mechanism to implement accept_mutex and serialize access to shared memory. On most systems, locks are managed using atomic operations, making this directive unnecessary. On certain systems, however, an alternative lock file mechanism is used. This directive sets a prefix for lock file names.

master_process#

Syntax

master_process on | off;

Default

master_process on;

Context

main

Determines whether worker processes are started. This directive is intended for Angie developers.

multi_accept#

Syntax

multi_accept on | off;

Default

multi_accept off;

Context

events

on

A worker process will accept all new connections simultaneously.

off

A worker process will accept one new connection at a time.

Note

This directive is ignored if the kqueue connection processing method is used, as it provides the number of new connections ready to be accepted.

pcre_jit#

Syntax

pcre_jit on | off;

Default

pcre_jit off;

Context

main

Enables or disables "just-in-time compilation" (PCRE JIT) for regular expressions known at the time of configuration parsing.

PCRE JIT can significantly accelerate regular expression processing.

Important

JIT is available in PCRE libraries from version 8.20, provided they are built with the --enable-jit configuration option. When Angie is built with the PCRE library (--with-pcre=), JIT support is enabled using the --with-pcre-jit option.

pid#

Syntax

pid file | off;

Default

pid logs/angie.pid;

Context

main

Specifies the file that will store the ID of the Angie main process. The file is created atomically, which ensures its contents are always correct. The off setting disables the creation of this file.

Note

If the file setting is modified during reconfiguration but points to a symlink of the previous PID file, the file will not be recreated.

ssl_engine#

Syntax

ssl_engine device;

Default

Context

main

Specifies the name of the hardware SSL accelerator.

thread_pool#

Syntax

thread_pool name threads=number [max_queue=number];

Default

thread_pool default threads=32 max_queue=65536;

Context

main

Defines the name and parameters of a thread pool used for multi-threaded file reading and sending, without blocking worker processes.

The threads parameter specifies the number of threads in the pool.

If all threads are busy, new tasks will wait in the queue. The max_queue parameter limits the number of tasks that can wait in the queue. By default, the queue can hold up to 65536 tasks. When the queue overflows, new tasks are completed with an error.

timer_resolution#

Syntax

timer_resolution interval;

Default

Context

main

Reduces timer resolution in worker processes, thereby decreasing the frequency of gettimeofday() system calls. By default, gettimeofday() is called each time kernel events are queried. With reduced resolution, it is called only once per the specified interval.

Example:

timer_resolution 100ms;

The internal implementation of the interval depends on the method used:

  • The EVFILT_TIMER filter if kqueue is used.

  • The timer_create() function if eventport is used.

  • The setitimer() function otherwise.

use#

Syntax

use method;

Default

Context

events

Specifies the connection processing method to use. Typically, there is no need to specify it explicitly, as Angie defaults to the most efficient method.

user#

Syntax

user user [group];

Default

user <--user build option> <--group build option>;

Context

main

Defines the user and group credentials for worker processes (see also the build options). If only the user is set, the specified user name is also used for the group.

worker_aio_requests#

Syntax

worker_aio_requests number;

Default

worker_aio_requests 32;

Context

events

When using aio with the epoll connection processing method, sets the maximum number of outstanding asynchronous I/O operations for a single worker process.

worker_connections#

Syntax

worker_connections number;

Default

worker_connections 512;

Context

events

Sets the maximum number of simultaneous connections a worker process can open.

Note that this number includes all connections, such as those with proxied servers, not just client connections. Additionally, the actual number of simultaneous connections cannot exceed the system's limit on open files, which can be adjusted using worker_rlimit_nofile.

worker_cpu_affinity#

Syntax

worker_cpu_affinity cpumask ...;

worker_cpu_affinity auto [cpumask];

Default

Context

main

Binds worker processes to specific sets of CPUs. Each CPU set is represented by a bitmask indicating allowed CPUs. A separate set should be defined for each worker process. By default, worker processes are not bound to any specific CPUs.

For example:

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

This configuration binds each worker process to a separate CPU.

Alternatively:

worker_processes    2;
worker_cpu_affinity 0101 1010;

This binds the first worker process to CPU0 and CPU2, and the second worker process to CPU1 and CPU3. This setup is suitable for hyper-threading.

The special value auto allows automatic binding of worker processes to available CPUs:

worker_processes auto;
worker_cpu_affinity auto;

The optional mask parameter can be used to limit the CPUs available for automatic binding:

worker_cpu_affinity auto 01010101;

Important

This directive is only available on FreeBSD and Linux.

worker_priority#

Syntax

worker_priority number;

Default

worker_priority 0;

Context

main

Defines the scheduling priority for worker processes, similar to the nice command: a negative number indicates higher priority. The allowed range typically varies from -20 to 20.

Example:

worker_priority -10;

worker_processes#

Syntax

worker_processes number | auto;

Default

worker_processes 1;

Context

main

Defines the number of worker processes.

The optimal value depends on various factors, including the number of CPU cores, the number of hard disk drives, and the load pattern. If unsure, starting with the number of available CPU cores is recommended. The value auto attempts to autodetect the optimal worker process number.

worker_rlimit_core#

Syntax

worker_rlimit_core size;

Default

Context

main

Changes the limit on the maximum size of a core file (RLIMIT_CORE) for worker processes. This allows increasing the limit without restarting the main process.

worker_rlimit_nofile#

Syntax

worker_rlimit_nofile number;

Default

Context

main

Changes the limit on the maximum number of open files (RLIMIT_NOFILE) for worker processes. This allows increasing the limit without restarting the main process.

worker_shutdown_timeout#

Syntax

worker_shutdown_timeout time;

Default

Context

main

Configures a timeout for the graceful shutdown of worker processes. Once the time expires, Angie will attempt to close all active connections to complete the shutdown process.

A graceful shutdown is initiated by sending a QUIT signal to the master process, which tells the worker processes to stop accepting new connections while allowing existing connections to complete. Workers continue to process active requests until they finish, after which they exit cleanly. If the connections remain open beyond worker_shutdown_timeout, Angie will forcefully close those connections to finalize the shutdown.

working_directory#

Syntax

working_directory directory;

Default

Context

main

Defines the current working directory for a worker process. This is primarily used for writing core files, so the worker process must have write permissions for the specified directory.