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.
Related guides
Migrating from nginx: changes the include, pid, and error_log paths.
Config Files: the
mainand events contexts; the include directive.Runtime Control: signals via the pid file; the
-goption.Connection Handling: the methods the use directive selects from.
Configuring SSL: one worker process per CPU core for SSL.
Configuration Example#
user www www;
worker_processes 2;
error_log /var/log/error.log info;
events {
use kqueue; worker_connections 2048;
}
Directives#
accept_mutex#
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#
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#
Determines whether Angie should run as a daemon. This is primarily used during development.
debug_connection#
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:;
# ...
}
Note
For this directive to work, Angie must be built with debugging log enabled.
debug_points#
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#
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:
inherited during a live upgrade of an executable file
used by the Perl module
available to worker processes
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#
| |
Default |
|
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If this parameter is omitted,
error is used as the default logging level.
Optional filter=part:match parameters restrict which messages
are written to the log, so a single destination can collect only the events
of interest. Each parameter tests one part of the message against the
match pattern, where part is one of:
logline— withformat=default, the message together with any system error and context details, but without the timestamp, level, process, thread, and connection prefix; it does not match entries withformat=json;message— withformat=default, the message text without system error or context details; withformat=json, the escaped, serialized fragment containing themessagemember rather than its raw value;tag— a tag attached to the message, including tags added by the error_log_user_tag directive and its stream and mail counterparts;sourcefile— the source file that emitted the message; available only when Angie is built with the debugging log enabled;any other name — a field of the message context, such as one of the fields shown in the JSON format below.
By default the match pattern is matched as a substring. Prefix it with
= to require an exact match, or with ~ to match a regular
expression, which requires a build with the PCRE library.
With format=json, an exact message match must cover the entire
serialized fragment, including its JSON syntax and escaping.
Several filter= parameters may be given for one directive; a message
is written only when it matches all of them. Each context field, however, can
be tested by only one filter= parameter per directive: a second
parameter on the same field never matches, so no message is written to the
destination.
Optional rate=rate parameter limits the maximum rate of messages
written to the log, in messages per second; the value may end
with the m/s suffix (for example, rate=2000m/s). By default,
rate=1000 (1000 messages per second) is used; set rate=0
to disable the limit.
The limit is applied separately to each error_log directive
and independently in each worker process. A flood of low-severity messages
(for example info) does not suppress higher-severity ones such as
error, because more severe levels are allowed a proportionally
larger burst; the reverse is not true. Excess messages are dropped. This
throttles the log rather than muting it: under sustained overload, messages
are still written at approximately the configured rate.
When a destination starts dropping messages, Angie writes a "too many log
messages, limiting" notice of the same level to that destination in place of
the first dropped message; the notice can recur during sustained overload. The
notice carries no context details or tags and must pass the destination's
filter= parameters, so a destination filtered by tag or by a
context field never receives it. Nor is the notice written to the destination
with the most verbose level among the error_log directives in effect
(the first one declared, if several share that level), so with a single
destination no notice appears.
Rate limiting doesn't apply when the debug logging level is in
effect for a message — either because the log file itself uses the
debug level, or because debugging logs are enabled for the
connection via debug_connection.
Note
For the debug logging level to work,
Angie must be built with debugging log enabled.
Optional format=format parameter selects the format used for log
entries. The default, format=default, produces the traditional
plain-text format described below; format=json writes each entry as
a single JSON object on one line.
In the default format, each entry in the error log has the following format:
timestamp [level] PID#TID: *connection_id message
Where:
timestamp— local date and time of the eventlevel— logging level of the eventPID#TID— process and thread identifiers*connection_id— connection serial number, shared by all requests on the same connection (if applicable)message— error or event message text
With format=json, each entry is instead written as a single JSON
object, shown here pretty-printed for readability; in the log file it
occupies a single line:
{
"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"
]
}
Where:
time— date and time of the event in UTC, in ISO 8601 format with theZsuffix; milliseconds are included unless they are zerolevel— logging level of the eventpidandtid— process and thread identifiersconnection— connection number (the same value shown as*connection_idin the plain-text format), present when the entry is associated with a connectionmessage— error or event message texterror— present when the message is associated with a system error; an object withcodeandmessagefieldshttp,stream, ormail— an object with the entry's context details, keyed by the name of the module where the entry originated (a genericcontextobject is used for context details outside these modules); the object only appears for entries that carry such details and are logged at a level other thandebug. Each module's object has its own set of fields; for example, underhttpa nestedrequestobject holdsrequest_line, the request line, along with other request detailstags— list of tags attached to the entry, present when at least one tag applies; includes tags added automatically by modules and by error_log_user_tag directivestruncated—true, present only when the entry had to be truncated to fit the error log buffer
events#
Provides the configuration file context for directives that affect connection processing.
include#
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#
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;
If a dynamic module was built for a different Angie build, loading fails with an error like: "module "..." was built for "..." but you are running "Angie"".
lock_file#
| |
Default |
|
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#
Determines whether worker processes are started. This directive is intended for Angie developers.
multi_accept#
| A worker process will accept all new connections simultaneously. |
| 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#
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.
Note
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#
| |
Default |
|
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#
Makes OpenSSL use the engine with the specified name by default for all algorithms the engine implements. The engine can also be set in the OpenSSL configuration file.
ssl_object_cache_inheritable#
If enabled, SSL objects (SSL certificates, secret keys, trusted CA certificates, CRL lists) are inherited across configuration reloads.
SSL objects loaded from files are inherited if their modification time and file
index have not changed since the previous configuration load. Secret keys
specified with the engine: or store: prefix are never
inherited, while certificates and keys specified with the data: prefix
are always inherited. Secret keys protected by a passphrase are not cached and
therefore never inherited.
SSL objects loaded from variables cannot be inherited.
Example:
ssl_object_cache_inheritable on;
http {
server {
ssl_certificate example.com.crt;
ssl_certificate_key example.com.key;
}
}
thread_pool#
| |
Default |
|
main |
Defines the name and parameters of a thread pool used for multi-threaded reading and sending of files without blocking worker processes.
The threads parameter defines the number of threads in the pool.
If all threads in the pool are busy executing tasks, new tasks wait in a queue.
The max_queue parameter limits the number of tasks
allowed to be waiting in the queue.
By default, up to 65536 tasks can be in the queue.
When the queue overflows, the task is completed with an error.
timer_resolution#
Reduces timer resolution in worker processes,
thus reducing the number of gettimeofday() system calls.
By default, gettimeofday() is called each time a kernel event is received.
With reduced resolution, gettimeofday() is only called once per specified interval.
Example:
timer_resolution 100ms;
Internal implementation of the interval depends on the method used:
use#
Specifies the method to use for connection processing. There is normally no need to specify it explicitly, because Angie will by default use the most efficient method.
user#
Defines user and group credentials used by worker processes (see also build parameters). If group is omitted, a group whose name equals that of user is used.
worker_aio_requests#
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#
Sets the maximum number of simultaneous connections that can be opened by a worker process.
It should be kept in mind that this number includes all connections (e.g. connections with proxied servers, among others), not only connections with clients. Another consideration is that the actual number of simultaneous connections cannot exceed the current limit on the maximum number of open files, which can be changed by worker_rlimit_nofile.
worker_cpu_affinity#
Binds worker processes to the sets of CPUs. Each CPU set is represented by a bitmask of allowed CPUs. There should be a separate set defined for each of the worker processes. 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 binding worker processes automatically 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;
Note
The directive is only available on FreeBSD and Linux.
worker_priority#
Defines the scheduling priority for worker processes like it is done by the nice command: a negative number means higher priority. Allowed range normally varies from -20 to 20.
Example:
worker_priority -10;
worker_processes#
Defines the number of worker processes.
The optimal value depends on many factors including (but not limited to)
the number of CPU cores, the number of hard disk drives that store data,
and load pattern.
When one is in doubt, setting it to the number of available CPU cores
would be a good start (the value "auto" will try to autodetect it).
worker_rlimit_core#
Changes the limit on the largest size of a core file (RLIMIT_CORE)
for worker processes.
Used to increase the limit without restarting the main process.
worker_rlimit_nofile#
Changes the limit on the maximum number of open files (RLIMIT_NOFILE)
for worker processes.
Used to increase the limit without restarting the main process.
worker_shutdown_timeout#
Configures a timeout for a graceful shutdown of worker processes. When the specified time expires, Angie will try to close all the connections currently open to facilitate shutdown.
Graceful shutdown is initiated by sending a QUIT signal to the main process, which instructs worker processes
to stop accepting new connections and allows existing connections to complete.
Worker processes continue to handle active requests until they finish,
then shut down gracefully. If connections remain open
longer than worker_shutdown_timeout, Angie will forcibly close these
connections to complete the shutdown.
Also, client keep-alive connections are closed only if they have been
idle for at least the time specified by lingering_timeout.
working_directory#
Defines the current working directory for a worker process. It is primarily used when writing a core file, in which case a worker process should have write permission for the specified directory.
Content