# Connections, Sessions, Requests, Logs
## Connection processing mechanisms
Angie supports various connection processing methods. The availability of a
specific method depends on the platform being used. On platforms that support
multiple methods, Angie typically selects the most efficient method
automatically. However, if necessary, a connection processing method can be
explicitly chosen using the [use](https://en.angie.software//angie/docs/configuration/modules/core.md#use) directive.
The following connection processing methods are available:
| Method | Description |
|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `select` | A standard method. The supporting module is built automatically on
platforms that do not have more efficient methods. The
`--with-select_module` and `--without-select_module` build
options can be used to forcibly enable or disable the building of this
module. |
| `poll` | A standard method. The supporting module is built automatically on
platforms that do not have more efficient methods. The
`--with-poll_module` and `--without-poll_module` build
options can be used to forcibly enable or disable the building of this
module. |
| `kqueue` | An efficient method available on FreeBSD 4.1+, OpenBSD 2.9+, NetBSD 2.0,
and macOS. |
| `epoll` | An efficient method available on Linux 2.6+. |
| `/dev/poll` | An efficient method available on Solaris 7 11/99+, HP/UX 11.22+
(eventport), IRIX 6.5.15+, and Tru64 UNIX 5.1A+. |
| `eventport` | The `event ports` method is available on Solaris 10+. (Due to known
issues, using the `/dev/poll` method is recommended instead.) |
## HTTP request processing
An HTTP request goes through a series of phases, where a specific type of
processing is performed at each phase.
| `Post-read` | The initial phase. The [RealIP](https://en.angie.software//angie/docs/configuration/modules/http/http_realip.md#http-realip) module is
invoked during this phase. |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Server-rewrite` | The phase where directives from the [Rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#http-rewrite)
module, defined in a `server` block (but outside a `location`
block), are processed. |
| `Find-config` | A special phase where a [location](https://en.angie.software//angie/docs/configuration/modules/http/index.md#location) is selected based on the request
URI. |
| `Rewrite` | Similar to the `Server-rewrite` phase, but it applies to
[rewrite](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id4) rules defined within the location block selected in the
previous phase. |
| `Post-rewrite` | A special phase where the request is redirected to a new location, as in
the `Find-config` phase, if its URI was modified during the
`Rewrite` phase. |
| `Preaccess` | During this phase, standard Angie modules like [Limit Req](https://en.angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) register their handlers. |
| `Access` | The phase where the client's authorization to make the request is
verified, typically by invoking standard Angie modules such as
[Auth Basic](https://en.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic). |
| `Post-access` | A special phase where the [satisfy any](https://en.angie.software//angie/docs/configuration/modules/http/index.md#satisfy) directive is
processed. |
| `Precontent` | Standard module directives, such as [try_files](https://en.angie.software//angie/docs/configuration/modules/http/index.md#try-files) and
[mirror](https://en.angie.software//angie/docs/configuration/modules/http/http_mirror.md#id1), register their handlers during this phase. |
| `Content` | The phase where the response is usually generated.
Multiple standard Angie modules register their handlers at this stage,
including [Index](https://en.angie.software//angie/docs/configuration/modules/http/http_index.md#http-index).
The [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), [fastcgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass),
[uwsgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass), [scgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass) and [grpc_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-pass) directives
are also handled here.
Handlers are called sequentially
until one of them produces the output. |
| `Log` | The final phase, where request logging is performed. Currently, only the
[Log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#http-log) module registers its handler at this stage
for access logging. |
## TCP/UDP session processing
A TCP/UDP session from a client goes through a series of phases, where a
specific type of processing is performed at each phase:
| `Post-accept` | The initial phase after accepting a client connection. The [RealIP](https://en.angie.software//angie/docs/configuration/modules/stream/stream_realip.md#stream-realip) module is invoked at this phase. |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Pre-access` | A preliminary phase for checking access. The [Set](https://en.angie.software//angie/docs/configuration/modules/stream/stream_set.md#stream-set) modules are invoked during this phase. |
| `Access` | The phase for limiting client access before actual data processing. The
[Access](https://en.angie.software//angie/docs/configuration/modules/stream/stream_access.md#stream-access) module is invoked at this stage. |
| `SSL` | The phase where TLS/SSL termination occurs. The [SSL](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl.md#stream-ssl) module is invoked during this phase. |
| `Preread` | The phase for reading initial bytes of data into the [preread buffer](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-preread-buffer-size) to allow modules such as [SSL Preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#stream-ssl-preread) to analyze the data before processing. |
| `Content` | A mandatory phase where the data is actually processed, typically
involving the [Return](https://en.angie.software//angie/docs/configuration/modules/stream/stream_return.md#stream-return) module to send a
response to the client.
The [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) directive is also handled here. |
| `Log` | The final phase where the outcome of client session processing is
recorded. The [Log](https://en.angie.software//angie/docs/configuration/modules/stream/stream_log.md#stream-log) module is invoked at this
phase. |
## Processing requests
### Virtual server selection
Initially, a connection is created within the context of a default server. The
server name can then be determined in the following stages of request
processing, each of which is involved in the selection of server configuration:
- During the SSL handshake, in advance, according to the SNI.
- After processing the request line.
- After processing the `Host` header field.
If the server name is not determined after processing the request line or the
`Host` header field, Angie will use an empty name as the server name.
At each of these stages, different server configurations may be applied.
Therefore, certain directives should be specified with caution:
- In the case of the [ssl_protocols](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-protocols) directive, the protocol list is set by
the OpenSSL library before the server configuration is applied according to
the name requested through SNI. As a result, protocols should only be
specified for the default server.
- The [client_header_buffer_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#client-header-buffer-size) and [merge_slashes](https://en.angie.software//angie/docs/configuration/modules/http/index.md#merge-slashes) directives are
applied before reading the request line. Therefore, these directives use
either the default server configuration or the server configuration chosen by
SNI.
- In the case of the [ignore_invalid_headers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#ignore-invalid-headers),
[large_client_header_buffers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#large-client-header-buffers), and [underscores_in_headers](https://en.angie.software//angie/docs/configuration/modules/http/index.md#underscores-in-headers)
directives, which are involved in processing request header fields, the server
configuration additionally depends on whether it was updated according to the
request line or the `Host` header field.
- An error response is handled using the [error_page](https://en.angie.software//angie/docs/configuration/modules/http/index.md#error-page) directive in the
server that is currently processing the request.
### Name-based virtual servers
Angie first determines which server should handle the request. Consider a
simple configuration where all three virtual servers listen on port 80:
```nginx
server {
listen 80;
server_name example.org www.example.org;
# ...
}
server {
listen 80;
server_name example.net www.example.net;
# ...
}
server {
listen 80;
server_name example.com www.example.com;
# ...
}
```
In this configuration, Angie determines which server should handle the
request based solely on the `Host` header field. If the value of this
header does not match any server name or if the request does not contain this
header field, Angie will route the request to the default server for this
port. In the configuration above, the default server is the first one — which is
Angie's standard default behavior. It can also be explicitly specified which
server should be the default using the `default_server` parameter in the
[listen](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen) directive:
```nginx
server {
listen 80 default_server;
server_name example.net www.example.net;
# ...
}
```
#### NOTE
Note that the default server is a property of the listen socket, not of the
server name.
### Internationalized names
Internationalized domain names ([IDNs](https://en.wikipedia.org/wiki/Internationalized_domain_name)) should be
specified using an ASCII (Punycode) representation in the [server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name)
directive:
```nginx
server {
listen 80;
server_name xn--e1afmkfd.xn--80akhbyknj4f; # пример.испытание
# ...
}
```
### Preventing requests with undefined server names
If requests without the `Host` header field should not be allowed, a
server that simply drops such requests can be defined:
```nginx
server {
listen 80;
server_name "";
return 444;
}
```
In this configuration, the server name is set to an empty string, which matches
requests without the `Host` header field. A special non-standard code 444
is then returned, which closes the connection.
### Combining name-based and IP-based virtual servers
Let's examine a more complex configuration where some virtual servers listen on
different addresses:
```nginx
server {
listen 192.168.1.1:80;
server_name example.org www.example.org;
# ...
}
server {
listen 192.168.1.1:80;
server_name example.net www.example.net;
# ...
}
server {
listen 192.168.1.2:80;
server_name example.com www.example.com;
# ...
}
```
In this configuration, Angie first tests the IP address and port of the
request against the [listen](https://en.angie.software//angie/docs/configuration/modules/http/index.md#listen) directives of the [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) blocks. It
then tests the `Host` header field of the request against the
[server_name](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-name) entries of the [server](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server) blocks that matched the IP
address and port. If the server name is not found, the request will be processed
by the default server. For example, a request for `www.example.com`
received on port 192.168.1.1:80 will be handled by the default server for that
port — i.e., by the first server — since `www.example.com` is not defined
for this port.
As previously mentioned, a default server is a property of the listen port, and
different default servers may be defined for different ports:
```nginx
server {
listen 192.168.1.1:80;
server_name example.org www.example.org;
# ...
}
server {
listen 192.168.1.1:80 default_server;
server_name example.net www.example.net;
# ...
}
server {
listen 192.168.1.2:80 default_server;
server_name example.com www.example.com;
# ...
}
```
### Choosing locations
Consider a simple PHP website configuration:
```nginx
server {
listen 80;
server_name example.org www.example.org;
root /data/www;
location / {
index index.html index.php;
}
location ~* \.(gif|jpg|png)$ {
expires 30d;
}
location ~ \.php$ {
fastcgi_pass localhost:9000;
fastcgi_param SCRIPT_FILENAME
$document_root$fastcgi_script_name;
include fastcgi_params;
}
}
```
Angie first searches for the most specific prefix `location` given by
literal strings, regardless of their listed order. In the configuration above,
the only prefix location is `location /`, which matches any request and
will be used as a last resort. Angie then checks locations defined by
regular expressions in the order they appear in the configuration file. The
first matching expression stops the search, and Angie will use that
`location`. If no regular expression matches a request, Angie will use
the most specific prefix `location` found earlier.
#### NOTE
Locations of all types test only the URI part of the request line, excluding
arguments. This is because arguments in the query string can be specified in
various ways, for example:
- `/index.php?user=john&page=1`
- `/index.php?page=1&user=john`
Additionally, query strings may contain any number of parameters:
- `/index.php?page=1&something+else&user=john`
Now let's look at how requests would be processed in the configuration above:
- The request `/logo.gif` is first matched by the prefix `location
/` and then by the regular expression `.(gif|jpg|png)$`. Therefore, it
is handled by the latter location. Using the directive `root /data/www`,
the request is mapped to the file `/data/www/logo.gif`, and the file is
sent to the client.
- The request `/index.php` is also initially matched by the prefix
`location /` and then by the regular expression `.(php)$`.
Consequently, it is handled by the latter location, and the request is passed
to a FastCGI server listening on `localhost:9000`. The
[fastcgi_param](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-param) directive sets the FastCGI parameter
`SCRIPT_FILENAME` to `/data/www/index.php`, and the FastCGI server
executes the file. The variable [$document_root](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-document-root) is set to the value of
the `root` directive, and the variable [$fastcgi_script_name](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#v-fastcgi-script-name) is
set to the request URI, i.e., `/index.php`.
- The request `/about.html` is matched only by the prefix `location
/`, so it is handled in this location. Using the directive `root
/data/www`, the request is mapped to the file `/data/www/about.html`,
and the file is sent to the client.
Handling the request `/` is more complex. It is matched only by the prefix
`location /`, so it is handled by this location. The [index](https://en.angie.software//angie/docs/configuration/modules/http/http_index.md#id1) directive then
tests for the existence of index files according to its parameters and the
`root /data/www` directive. If the file `/data/www/index.html` does
not exist but the file `/data/www/index.php` does, the directive performs
an internal redirect to `/index.php`, and Angie searches the locations
again as if the request had been sent by a client. As previously mentioned, the
redirected request will eventually be handled by the FastCGI server.
## Proxying and Load Balancing
One common use of Angie is to set it up as a proxy server. In this role,
Angie receives requests, forwards them to the proxied servers, retrieves
responses from those servers, and sends the responses back to the clients.
A simple proxy server:
```nginx
server {
location / {
proxy_pass http://backend:8080;
}
```
The [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) directive instructs Angie to pass client requests to
the backend `backend:8080` (the proxied server). There are many additional
[directives](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) available for further configuring a proxy
connection.
### FastCGI Proxying
Angie can be used to route requests to FastCGI servers that run applications
built with various frameworks and programming languages, such as PHP.
The most basic Angie configuration for working with a FastCGI server
involves using the [fastcgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass) directive instead of the
[proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) directive, along with [fastcgi_param](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-param) directives to set
parameters passed to the FastCGI server. Suppose the FastCGI server is
accessible on `localhost:9000`. In PHP, the `SCRIPT_FILENAME`
parameter is used to determine the script name, and the `QUERY_STRING`
parameter is used to pass request parameters. The resulting configuration would
be:
```nginx
server {
location / {
fastcgi_pass localhost:9000;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param QUERY_STRING $query_string;
}
location ~ \.(gif|jpg|png)$ {
root /data/images;
}
}
```
This configuration sets up a server that routes all requests, except those for
static images, to the proxied server operating on `localhost:9000` via the
FastCGI protocol.
### WebSocket Proxying
To upgrade a connection from HTTP/1.1 to WebSocket, the [protocol switch](https://datatracker.ietf.org/doc/html/rfc2616#section-14.42) mechanism
available in HTTP/1.1 is used.
However, there is a subtlety: since the `Upgrade` header is a [hop-by-hop
header](https://datatracker.ietf.org/doc/html/rfc2616#section-13.5.1), it is
not passed from the client to the proxied server. With forward proxying, clients
may use the CONNECT method to circumvent this issue. This approach does not work
with reverse proxying, as clients are unaware of any proxy servers, and special
processing on the proxy server is required.
Angie implements a special mode of operation that allows setting up a tunnel
between a client and a proxied server if the proxied server returns a response
with code 101 (Switching Protocols), and the client requests a protocol switch
via the `Upgrade` header in the request.
As mentioned, hop-by-hop headers, including `Upgrade` and
`Connection`, are not passed from the client to the proxied server.
Therefore, for the proxied server to be aware of the client's intention to
switch to the WebSocket protocol, these headers must be explicitly passed:
```nginx
location /chat/ {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
```
A more sophisticated example demonstrates how the value of the
`Connection` header field in a request to the proxied server depends on
the presence of the `Upgrade` field in the client request header:
```nginx
http {
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
...
location /chat/ {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
}
```
By default, the connection will be closed if the proxied server does not
transmit any data within 60 seconds. This timeout can be increased using the
[proxy_read_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-read-timeout) directive. Alternatively, the proxied server can be
configured to periodically send WebSocket ping frames to reset the timeout and
check if the connection is still active.
### Load Balancing
Load balancing across multiple application instances is a widely used technique
to optimize resource utilization, maximize throughput, reduce latency, and
ensure fault-tolerant configurations.
Angie can be used as a highly efficient HTTP load balancer to distribute
traffic to multiple application servers, thereby enhancing the performance,
scalability, and reliability of web applications.
The simplest configuration for load balancing with Angie might look like
this:
```nginx
http {
upstream myapp1 {
server srv1.example.com;
server srv2.example.com;
server srv3.example.com;
}
server {
listen 80;
location / {
proxy_pass http://myapp1;
}
}
}
```
In the example above, three instances of the same application are running on
`srv1` through `srv3`. When a load balancing method is not
explicitly configured, it defaults to round-robin. Other supported load
balancing mechanisms include: [weight](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server), [least_conn](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-least-conn), and
[ip_hash](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-ip-hash). The reverse proxy implementation in Angie also supports
in-band (or passive) server health probes. These are configured using the
[max_fails](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) and [fail_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#fail-timeout) directives
within the [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) block in the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) context.
## Logging
#### NOTE
In addition to the options listed here,
you can also enable the [debugging log](https://en.angie.software//angie/docs/troubleshooting.md#debug-logging).
### Syslog
The [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) and [access_log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) directives support logging to
`syslog`. The following parameters are used to configure logging to
`syslog`:
| `server=`address | Specifies the address of a `syslog` server. The address can be a
domain name or an IP address, with an optional port, or a UNIX domain
socket path specified after the `"unix:"` prefix. If the port is
not specified, UDP port 514 is used. If a domain name resolves to
multiple IP addresses, the first resolved address is used. |
|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `facility=`string | Sets the facility for `syslog` messages, as defined in [RFC 3164](https://datatracker.ietf.org/doc/html/rfc3164.html). Possible
facilities include: `"kern"`, `"user"`, `"mail"`,
`"daemon"`, `"auth"`, `"intern"`, `"lpr"`,
`"news"`, `"uucp"`, `"clock"`, `"authpriv"`,
`"ftp"`, `"ntp"`, `"audit"`, `"alert"`,
`"cron"`, `"local0".."local7"`. The default is
`"local7"`. |
| `severity=`string | Defines the severity level of `syslog` messages for
[access_log](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#access-log), as specified in [RFC 3164](https://datatracker.ietf.org/doc/html/rfc3164.html). Possible values
are the same as those for the second parameter (level) of the
[error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive. The default is `"info"`. The severity
of error messages is determined by Angie, so this parameter is
ignored in the [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log) directive. |
| `tag=`string | Sets the tag for `syslog` messages. The default tag is
`"angie"`. |
| `nohostname` | Disables the addition of the `hostname` field in the `syslog`
message header. |
Example syslog configuration:
```nginx
error_log syslog:server=192.168.1.1 debug;
access_log syslog:server=unix:/var/log/angie.sock,nohostname;
access_log syslog:server=[2001:db8::1]:12345,facility=local7,tag=angie,severity=info combined;
```