# Runtime Control To start Angie, use **systemd** with the following command: ```console $ sudo service angie start ``` It is recommended to check the configuration syntax beforehand. Here is how: ```console $ sudo angie -t && sudo service angie start ``` To reload the configuration: ```console $ sudo angie -t && sudo service angie reload ``` To stop Angie: ```console $ sudo service angie stop ``` After installation, run the following command to ensure that Angie is up and running: ```console $ 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](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes)). When configured, Angie will also flush certain shared memory zones (currently, the `keys_zone` in [proxy_cache_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path)) to disk before exiting, so the new master process can restore them and thereby improve performance. If the restore fails due to a change in zone size, binary version incompatibility, or other reasons, Angie will log a warning (`failed to restore zone at address`) and will not use the zone restore mechanism. ## Using Signals Angie can also be controlled using signals. By default, the process ID of the master process is written to the file `/run/angie.pid`. This filename can be changed at configuration time or in `angie.conf` using the [pid](https://en.angie.software//angie/docs/configuration/modules/core.md#pid) directive. The master process supports the following signals: | `TERM`, `INT` | Fast shutdown | |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `QUIT` | [Graceful](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout) shutdown | | `HUP` | Reload configuration, update time zone (only for FreeBSD and Linux),
start new worker processes with the updated configuration,
[gracefully](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout) shut down old worker
processes | | `USR1` | Reopen log files | | `USR2` | Upgrade the executable file | | `WINCH` | [Graceful](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout) shutdown of worker processes | You can send signals using **kill**: ```console $ sudo kill -QUIT $(cat /run/angie.pid) ``` Individual worker processes can also be controlled using signals, although this is optional. The supported signals are: | `TERM`, `INT` | Fast shutdown | |-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `QUIT` | [Graceful](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout) shutdown | | `USR1` | Reopen log files | | `WINCH` | Abnormal termination for debugging (requires [debug_points](https://en.angie.software//angie/docs/configuration/modules/core.md#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](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout). 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: ```console $ sudo angie $ ps aux | grep angie angie: master process v|version| #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: ```console $ sudo kill -HUP $(cat /run/angie.pid) $ ps aux | grep angie angie: master process v|version| #2 [angie] angie: worker process #2 ``` If any worker processes from previous generations continue to operate, they will become immediately visible: ```console $ 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](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-shutdown-timeout) 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. When configured, Angie will also flush certain shared memory zones (currently, the `keys_zone` in [proxy_cache_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path)) to disk before upgrading, so the new master process can restore them and thereby improve performance. If the restore fails due to a change in zone size, binary version incompatibility, or other reasons, Angie will log a warning (`failed to restore zone at address`) and will not use the zone restore mechanism. ## 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](https://en.angie.software//angie/docs/configuration/configfile.md#configfile). | | `-e` file | Use file as the error log file instead of the [default file](https://en.angie.software//angie/docs/configuration/processing.md#logging). The special value `stderr` specifies the standard error
output. | | `-g` directives | Set [global configuration directives](https://en.angie.software//angie/docs/configuration/modules/core.md#core),
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 | Use the specified prefix path for `angie` (the directory where server
files are located; the default is `/usr/local/angie/`). | | `-q` | Display only error messages if `-t` or `-T` is set;
otherwise, has no effect. | | `-s` signal | Send a [signal](#control-signals) to the master process:
`stop`, `quit`, `reopen`, `reload`, and so on. | | `-t` | Test the configuration file, then exit. Angie checks the
configuration syntax, recursively including 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, compiler version, build time
and the [build parameters](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure) used, then exit. |