<!-- review: finished -->

<a id="configfile"></a>

# Configuration Files

Angie uses a text-based configuration file. By default, this file is named
`angie.conf` and is located according to the [--conf-path](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths)
build parameter, typically in the `/etc/angie` directory.

A configuration file generally consists of the following contexts:

- [events](https://en.angie.software//angie/docs/configuration/modules/core.md#events) – General connection processing
- [http](https://en.angie.software//angie/docs/configuration/modules/http/index.md#d-http) – HTTP traffic
- [mail](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#m-mail) – Mail traffic
- [stream](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-stream) – TCP and UDP traffic
- [wasm_modules](https://en.angie.software//angie/docs/configuration/modules/wasm/index.md#wasm-modules) – WASM runtime

Directives that are placed outside of these contexts are considered to be in the
`main` context:

```nginx
user angie; # a directive in the 'main' context

events {

    # configuration of connection processing
}

http {

    # Configuration specific to HTTP and affecting all virtual servers

    server {

        # configuration of HTTP virtual server 1
        location /one {

            # configuration for processing URIs starting with '/one'
        }
        location /two {

            # configuration for processing URIs starting with '/two'
        }
    }

    server {

        # configuration of HTTP virtual server 2
    }
}

stream {

    # Configuration specific to TCP/UDP and affecting all virtual servers
    server {

        # configuration of TCP virtual server 1
    }
}
```

To simplify configuration management, we recommend using the [include](https://en.angie.software//angie/docs/configuration/modules/core.md#include)
directive in the main `angie.conf` file to reference the contents of
feature-specific files:

```nginx
include /etc/angie/http.d/*.conf;
include /etc/angie/stream.d/*.conf;
```

<a id="inheritance"></a>

## Inheritance

In general, a child context (one that is contained within another context, which
is considered its parent) inherits the settings of directives defined at the
parent level. Some directives can appear in multiple contexts; in such cases,
you can override the settings inherited from the parent by including the
directive in the child context.

<a id="syntax"></a>

## Syntax

<a id="measurement-units"></a>

### Measurement Units

You can specify sizes using the following units:

| No suffix   | Bytes     |
|-------------|-----------|
| `k`, `K`    | Kilobytes |
| `m`, `M`    | Megabytes |
| `g`, `G`    | Gigabytes |

For example: `1024`, `8k`, `1m`, `16g`.

Time intervals can be specified in milliseconds, seconds, minutes, hours, days,
and so on, using the following suffixes:

| `ms`   | Milliseconds                      |
|--------|-----------------------------------|
| `s`    | Seconds                           |
| `m`    | Minutes                           |
| `h`    | Hours                             |
| `d`    | Days                              |
| `w`    | Weeks                             |
| `M`    | Months (assumed equal to 30 days) |
| `y`    | Years (assumed equal to 365 days) |

Multiple units can be combined in a single value by specifying them in order
from the most significant to the least significant, optionally separated by
whitespace. For example, `"1h 30m"` specifies the same duration as
`"90m"` or `"5400s"`. A value without a suffix is interpreted as
seconds. It is recommended to always specify a suffix.

Some time intervals can only be specified with second-level resolution.

<a id="directives"></a>

### Directives

Each directive consists of a name and a set of parameters.
If any part of a directive needs to contain spaces,
it should be enclosed in quotes or escape the spaces:

```nginx
add_header X-MyHeader "foo bar";
add_header X-MyHeader foo\ bar;
```

If a named parameter needs spaces and you use quotes,
its name must be enclosed in quotes as well:

```nginx
server example.com "sid=server 1";
```

<a id="configure-hashes"></a>

## Setting up Hashes

To efficiently process static sets of data, such as server names, the [map](https://en.angie.software//angie/docs/configuration/modules/http/http_map.md#id1)
directive values, MIME types, and request header names, Angie utilizes hash
tables. During startup and each reconfiguration, Angie determines the
optimal size for these hash tables to ensure that the bucket size, which stores
keys with identical hash values, does not exceed the configured parameter (hash
bucket size). The table size is measured in buckets and is adjusted until it
exceeds the hash max size parameter. Most hash tables have corresponding
directives to adjust these parameters, such as [server_names_hash_max_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-names-hash-max-size)
and [server_names_hash_bucket_size](https://en.angie.software//angie/docs/configuration/modules/http/index.md#server-names-hash-bucket-size) for server names.

The hash bucket size parameter is aligned to a multiple of the processor's
cache line size. This alignment enhances key search efficiency on modern
processors by reducing the number of memory accesses. If the hash bucket size
is equal to one cache line size, the maximum number of memory accesses during a
key search will be two: one to compute the bucket address and another to search
inside the bucket. Therefore, if Angie indicates that either the hash max
size or hash bucket size should be increased, start by increasing the hash
max size.

<a id="configfile-reloading"></a>

### Reloading Configuration

To apply changes to the configuration file, it must be reloaded. You can either
restart the Angie process with a configuration syntax check beforehand:

```console
$ sudo angie -t && sudo service angie restart
```

Alternatively, you can reload the service to apply the new configuration without
interrupting the processing of current requests:

```console
$ sudo angie -t && sudo service angie reload
```