Run-Time Control#

To start Angie, use systemd with the following command:

$ sudo service angie start

It is recommended to check the configuration syntax beforehand. Here is how:

$ sudo angie -t && sudo service angie start

To reload the configuration:

$ sudo angie -t && sudo service angie reload

To stop Angie:

$ sudo service angie stop

After installation, run the following command to ensure that Angie is up and running:

$ curl localhost:80

Note

The methods for running the open-source version of Angie may vary depending on the installation method.

Angie has one master process and several worker processes. The master process is responsible for reading and evaluating the configuration and maintaining the worker processes. Worker processes handle the actual request processing. Angie uses an event-based model and OS-dependent mechanisms to efficiently distribute requests among the worker processes. The number of worker processes is defined in the configuration file and may be either fixed for a given configuration or automatically adjusted based on the number of available CPU cores (see worker_processes).

Using Signals#

Angie can also be controlled using signals. By default, the process ID of the master process is written to the file /var/run/angie.pid. This filename can be changed at configuration time or in angie.conf using the pid directive. The master process supports the following signals:

`TERM`, `INT`	Fast shutdown
`QUIT`	Graceful shutdown
`HUP`	Reload configuration, update time zone (only for FreeBSD and Linux), start new worker processes with the updated configuration, gracefully shut down old worker processes
`USR1`	Reopen log files
`USR2`	Upgrade the executable file
`WINCH`	Graceful shutdown of worker processes

Individual worker processes can also be controlled using signals, although this is optional. The supported signals are:

`TERM`, `INT`	Fast shutdown
`QUIT`	Graceful shutdown
`USR1`	Reopen log files
`WINCH`	Abnormal termination for debugging (requires debug_points to be enabled)

Changing Configuration#

In order for Angie to re-read the configuration file, a HUP signal should be sent to the master process. The master process first checks the syntax validity and then attempts to apply the new configuration, which includes opening new log files and listen sockets. If applying the new configuration fails, the master process rolls back the changes and continues operating with the old configuration. If the application succeeds, the master process starts new worker processes and sends messages to the old worker processes, requesting them to shut down gracefully. The old worker processes close their listen sockets and continue to service existing clients. After all clients have been served, the old worker processes are shut down.

Angie tracks configuration changes for each process. Generation numbers start at 1 when the server is first started. These numbers are incremented with each configuration reload and are visible in the process titles:

$ sudo angie
$ ps aux | grep angie

    angie: master process v1.7.0 #1 [angie]
    angie: worker process #1

After a successful configuration reload (regardless of whether there are actual changes), Angie increments the generation number for processes that received the new configuration:

$ sudo angie -s reload
$ ps aux | grep angie

    angie: master process v1.7.0 #2 [angie]
    angie: worker process #2

If any worker processes from previous generations continue to operate, they will become immediately visible:

$ ps aux | grep angie

    angie: worker process #1
    angie: worker process #2

Note

Do not confuse the configuration generation number with a 'process number'; Angie does not use continuous process numbering for practical purposes.

Rotating Log Files#

To rotate log files, first rename the files. Then, send a USR1 signal to the master process. The master process will re-open all currently open log files and assign them to an unprivileged user under which the worker processes are running. After successfully re-opening the files, the master process closes all open files and notifies the worker processes to re-open their log files. Worker processes will also open the new files and close the old ones immediately. As a result, the old files become available for post-processing, such as compression, almost immediately.

On-the-fly Executable Upgrade#

To upgrade the server executable, first replace the old executable file with the new one. Then, send a USR2 signal to the master process. The master process will rename its current file with the process ID to a new file with the .oldbin suffix, e.g., /usr/local/angie/logs/angie.pid.oldbin, and then start the new executable, which in turn starts new worker processes.

Note that the old master process does not close its listen sockets and can be managed to restart its worker processes if necessary. If the new executable does not perform as expected, you can take one of the following actions:

Send the HUP signal to the old master process. This will start new worker processes without re-reading the configuration. You can then shut down all new processes gracefully by sending the QUIT signal to the new master process.
Send the TERM signal to the new master process. It will send a message to its worker processes, requesting them to exit immediately. If any processes do not exit, send the KILL signal to force them to exit. When the new master process exits, the old master process will automatically start new worker processes.

If the new master process exits, the old master process will remove the .oldbin suffix from the file name with the process ID.

If the upgrade is successful, send the QUIT signal to the old master process, and only the new processes will remain.

Command-Line Options#

`-h`, `-?`	Display help for command-line parameters, then exit.
`--build-env`	Display auxiliary information about the build environment, then exit.
`-c` file	Use file as the configuration file instead of the default file.
`-e` file	Use file as the error log file instead of the default file. The special value `stderr` specifies the standard error output.
`-g` directives	Apply additional global configuration directives, for example: angie -g "pid /var/run/angie.pid; worker_processes `sysctl -n hw.ncpu`;".
`-m`, `-M`	Display a list of built-in (`-m`) or built-in and loaded (`-M`) modules, then exit.
`-p` prefix	Specify the prefix path for `angie` (the directory where server files are located; the default is `/usr/local/angie/`).
`-q`	Only display error messages if `-t` or `-T` is set; otherwise, do nothing.
`-s` signal	Send a signal to the master process, such as `stop`, `quit`, `reopen`, `reload`, and so on.
`-t`	Test the configuration file, then exit. Angie checks the configuration syntax and recursively includes any files mentioned in it.
`-T`	Same as `-t`, but also outputs the summary configuration to standard output after recursively including all files mentioned in the configuration.
`-v`	Display the Angie version, then exit.
`-V`	Display the Angie version, the compiler version, and the build parameters used, then exit.