Building Angie from Source#

We recommend installing Angie from official pre-built packages. However, if you still need your own build, make sure the prerequisites are in place first.

Note

Building Angie requires a C compiler (gcc or clang) and make, plus the PCRE2, zlib, and OpenSSL libraries. Install the development packages provided by your distribution. On Debian and Ubuntu:

$ sudo apt install build-essential libpcre2-dev zlib1g-dev libssl-dev

On RHEL, Fedora, and derivatives:

$ sudo dnf install gcc make pcre2-devel zlib-devel openssl-devel

Alternatively, build these libraries statically together with Angie using the --with-pcre=, --with-zlib=, and --with-openssl= options shown in the Examples.

To build Angie from source:

  1. Download the .tar.gz archive from our website:

    $ curl -O https://download.angie.software/files/angie-1.12.1.tar.gz

  2. Unpack the archive and navigate to the source directory:

    $ tar -xpf angie-1.12.1.tar.gz
$ cd angie-1.12.1

  3. To prepare the build, use the ./configure script, which determines the specific characteristics of the OS where the build occurs, particularly the methods that Angie can use to handle connections. After a successful run, the script creates a Makefile.

    With the prerequisites installed, a minimal build needs no options:

    $ ./configure

    Otherwise, review and set the required build options for the modules and libraries you need (see the Examples):

    $ ./configure <OPTIONS>

  4. When the Makefile is ready, build and install Angie:

    $ make
$ make install

Build Options#

General#

Option

Description

Default

--help

Prints a help message.

--user=name

Sets the name of an unprivileged user whose credentials will be used by worker processes. After installation, the name can always be changed in the angie.conf configuration file using the user directive.

nobody

--group=name

Sets the name of a group whose credentials will be used by worker processes. After installation, the name can always be changed in the angie.conf configuration file using the user directive.

--user setting

--build=name

Sets an optional name for the build.

--builddir=path

Sets the build directory.

objs

--feature-cache=path

Specifies the directory for caching build artifacts.

If set without a path, --builddir setting is used

Paths#

Option

Description

Default

--prefix=path

Defines the directory that will store server files. This same directory will also be used for all relative paths set by ./configure (except for paths to library sources) and in the angie.conf configuration file.

/usr/local/angie

--sbin-path=path

Sets the name of the Angie executable. This name is used only during installation.

<prefix>/sbin/angie

--modules-path=path

Defines the directory where dynamic modules will be installed.

<prefix>/modules

--conf-path=path

Sets the name of the angie.conf configuration file. If needed, you can always start Angie with a different configuration file using the -c command-line option.

<prefix>/conf/angie.conf

--error-log-path=path

Sets the name of the primary error, warning, and diagnostic log file. After installation, the file name can always be changed in the angie.conf configuration file using the error_log directive.

<prefix>/logs/error.log

--pid-path=path

Sets the name of the angie.pid file that will store the process ID of the main process. After installation, the file name can always be changed in the angie.conf configuration file using the pid directive.

<prefix>/logs/angie.pid

--lock-path=path

Sets the prefix for lock file names. After installation, the value can always be changed in the angie.conf configuration file using the lock_file directive.

<prefix>/logs/angie.lock

--http-acme-client-path=path

Sets the directory to store certificates and keys for server blocks that have acme directives defined.

<prefix>/acme_client

--http-log-path=path

Sets the name of the primary request log file for the HTTP server. After installation, the file name can always be changed in the angie.conf configuration file using the access_log directive.

<prefix>/logs/access.log

--http-client-body-temp-path=path

Defines the directory for storing temporary files that hold client request bodies. After installation, the directory can always be changed in the angie.conf configuration file using the client_body_temp_path directive.

<prefix>/client_body_temp

--http-proxy-temp-path=path

Defines the directory for storing temporary files with data received from proxied servers. After installation, the directory can always be changed in the angie.conf configuration file using the proxy_temp_path directive.

<prefix>/proxy_temp

--http-fastcgi-temp-path=path

Defines the directory for storing temporary files with data received from FastCGI servers. After installation, the directory can always be changed in the angie.conf configuration file using the fastcgi_temp_path directive.

<prefix>/fastcgi_temp

--http-uwsgi-temp-path=path

Defines the directory for storing temporary files with data received from uWSGI servers. After installation, the directory can always be changed in the angie.conf configuration file using the uwsgi_temp_path directive.

<prefix>/uwsgi_temp

--http-scgi-temp-path=path

Defines the directory for storing temporary files with data received from SCGI servers. After installation, the directory can always be changed in the angie.conf configuration file using the scgi_temp_path directive.

<prefix>/scgi_temp

Features and dependencies#

--with-select_module, --without-select_module

Enables or disables building a module that allows the server to work with the select() method. This module is built automatically if the platform does not appear to support more appropriate methods such as kqueue, epoll, or /dev/poll.

--with-poll_module, --without-poll_module

Enables or disables building a module that allows the server to work with the poll() method. This module is built automatically if the platform does not appear to support more appropriate methods such as kqueue, epoll, or /dev/poll.

--with-threads

Enables the use of thread pools (aio threads mode).

--with-file-aio

Enables the use of asynchronous file I/O (AIO) on FreeBSD and Linux (aio on mode).

--with-debug

Enables the debugging log.

--without-http-cache

Disables the HTTP cache.

--with-pcre, --with-pcre=path

Enables the use of the PCRE library.

The optional parameter sets the path to the sources of the PCRE library. The library distribution needs to be downloaded from the PCRE site and extracted. The rest is done by Angie's ./configure and make commands.

The library is required for regular expression support in the location directive and for the Rewrite module.

--with-pcre-opt=parameters

Sets additional build parameters for PCRE.

--with-pcre-jit

Builds the PCRE library with JIT compilation support (the pcre_jit directive).

--without-pcre

Disables the use of the PCRE library.

--without-pcre2

Disables the use of the PCRE2 library instead of the original PCRE library.

--with-libatomic, --with-libatomic=path

Enables building with the libatomic_ops library. The optional parameter sets the path to the library sources.

--with-openssl=path

Enables static building and sets the path to the OpenSSL library sources. AWS-LC can be used as an OpenSSL-compatible library.

--with-openssl-opt=parameters

Sets additional build parameters for OpenSSL.

--with-ntls

Enables NTLS support in the HTTP module (server-side, client-side) and stream module (server-side, client-side) when building with an SSL library that supports NTLS.

--with-zlib=path

Sets the path to the sources of the zlib library. The library distribution (version 1.1.3 or later) needs to be downloaded from the zlib site and extracted; releases older than the current one are archived under zlib fossils. The rest is done by Angie's ./configure and make commands.

The library is required for the GZip module.

--with-zlib-opt=parameters

Sets additional build parameters for zlib.

--with-zlib-asm=cpu

Enables the use of assembly optimizations for building zlib, optimized for one of the following processors: pentium, pentiumpro.

Enabling and Disabling Modules#

You can disable modules that are enabled by default, or enable modules that are available but disabled by default.

HTTP#

Enabling additional modules:

--with-http_acme_module

Enables building the ACME module, which enables the ACME protocol.

--with-http_addition_module

Enables building the Addition module that allows adding text before and after a response.

--with-http_auth_request_module

Enables building the Auth Request module that provides client authorization capability based on the result of a subrequest.

--with-http_dav_module

Enables building the DAV module intended for automating file management tasks on the server via the WebDAV protocol.

--with-http_degradation_module

Enables building the Degradation module that allows returning HTTP status codes 204 or 444 for certain location blocks.

This module can only be used in cases where sbrk(0) shows the actual amount of memory allocated to the process. In other words, the module works on FreeBSD up to version 7.0 by default. Starting from version 7.0, it works only if MALLOC_OPTIONS=Dm is set. On Linux it does not work.

--with-http_flv_module

Enables building the FLV module that provides server-side pseudo-streaming support for Flash Video (FLV) files.

--with-http_geoip_module, --with-http_geoip_module=dynamic

Enables building the GeoIP module that creates variables whose values are determined based on the client's IP address and ready-made MaxMind databases.

--with-http_gunzip_module

Enables building the GunZIP module that allows decompressing responses with Content-Encoding: gzip for clients that do not support the gzip compression method.

--with-http_gzip_static_module

Enables building the Gzip Static module that allows serving a precompressed file with the same name and the .gz extension instead of a regular file.

--with-http_image_filter_module, --with-http_image_filter_module=dynamic

Enables building the Image Filter module that allows transforming images in JPEG, GIF, PNG, and WebP formats.

--with-http_mp4_module

Enables building the MP4 module that provides server-side pseudo-streaming support for MP4 format files.

--with-http_perl_module, --with-http_perl_module=dynamic

Enables building the Perl module.

--with-perl_modules_path=path

Sets the directory where Perl module files will be located.

--with-perl=path

Sets the name of the Perl executable file.

--with-http_random_index_module

Enables building the Random Index module that serves requests ending with a slash (/) and returns a random file as the directory's index file.

--with-http_realip_module

Enables building the RealIP module that allows changing the client address to the one passed in the specified header field.

--with-http_secure_link_module

Enables building the Secure Link module.

--with-http_slice_module

Enables building the Slice module that allows splitting a request into subrequests, each returning a specific range of the response. The module provides efficient caching of large responses.

--with-http_ssl_module

Enables SSL support for the HTTP server.

The OpenSSL library is required for this module.

--with-http_stub_status_module

Enables building the Stub Status module that provides access to basic server status information.

--with-http_sub_module

Enables building the Sub module that allows modifying one specified string in the response to another.

--with-http_v2_module

Enables the HTTP/2 module.

--with-http_v3_module

Enables the HTTP/3 module.

Note

For building, it is strongly recommended to use an SSL library that supports the QUIC protocol:

Building with BoringSSL:

$ ./configure \
      --with-debug \
      --with-http_v3_module \
      --with-cc-opt="-I../boringssl/include" \
      --with-ld-opt="-L../boringssl/build/ssl -L../boringssl/build/crypto"

Without this, the OpenSSL library will be used in compatibility mode, where early data sending is not supported and other features are missing, such as session reuse. Such a build will be able to interact only with clients and servers using OpenSSL in the same mode.

This fallback is silent: if the configured SSL library is missing or unusable, ./configure uses the system OpenSSL instead of reporting an error. After it finishes, check the Configuration summary: a line reading + using system OpenSSL library means the intended QUIC-capable library was not picked up.

--with-http_xslt_module, --with-http_xslt_module=dynamic

Enables building the XSLT module that allows transforming XML responses using XSLT stylesheets.

The libxml2 and libxslt libraries are required for this module.

--with-google_perftools_module

Enables building the Google PerfTools module that provides support for profiling Angie worker processes using Google Performance Tools. The module is intended for Angie developers.

Disabling standard modules:

--without-http

Disables the HTTP server.

--without-http_access_module

Disables building the Access module that allows limiting access to certain client addresses.

--without-http_api_module

Disables building the API module that provides a RESTful HTTP interface for accessing JSON-based information about the web server instance.

--without-http_metric_module

Disables building the Metric module.

--without-http_auth_basic_module

Disables building the Auth Basic module that allows limiting access to resources by validating the user name and password using the HTTP Basic Authentication protocol.

--without-http_autoindex_module

Disables building the AutoIndex module that processes requests ending with the slash character (/) and produces a directory listing in case the Index module cannot find an index file.

--without-http_browser_module

Disables building the Browser module that creates variables whose values depend on the value of the User-Agent request header field.

--without-http_charset_module

Disables building the Charset module that adds the specified charset to the Content-Type response header field and can additionally convert data from one charset to another.

--without-http_doh_module

Disables building the DoH module that implements a DNS over HTTPS server.

--without-http_empty_gif_module

Disables building the module that emits a single-pixel transparent GIF.

--without-http_fastcgi_module

Disables building the FastCGI module that passes requests to a FastCGI server.

--without-http_geo_module

Disables building the Geo module that creates variables with values depending on the client IP address.

--without-http_gzip_module

Disables building the module that compresses the HTTP server responses.

The zlib library is required for this module.

--without-http_grpc_module

Disables building the gRPC module that passes requests to a gRPC server.

--without-http_limit_conn_module

Disables building the Limit Conn module that limits the number of connections per key, for example, the number of connections from a single IP address.

--without-http_limit_req_module

Disables building the Limit Req module that limits the request processing rate per key, for example, the processing rate of requests coming from a single IP address.

--without-http_map_module

Disables building the Map module that creates variables with values depending on the values of other variables.

--without-http_memcached_module

Disables building the Memcached module that obtains responses from a memcached server.

--without-http_mirror_module

Disables building the Mirror module that implements mirroring of an original request by creating background mirror subrequests.

--without-http_prometheus_module

Disables building the Prometheus module for the HTTP server.

--without-http_proxy_module

Disables building the Proxy module for the HTTP server.

--without-http_referer_module

Disables building the Referer module that can block access to a site for requests with invalid values in the Referer header field.

--without-http_rewrite_module

Disables building the Rewrite module that allows the HTTP server to redirect requests and change their URIs.

The PCRE library is required for this module.

--without-http_scgi_module

Disables building the SCGI module that passes requests to an SCGI server.

--without-http_split_clients_module

Disables building the Split Clients module that creates variables for A/B testing.

--without-http_ssi_module

Disables building the SSI module that processes SSI (Server Side Includes) commands in responses passing through it.

--without-http_upstream_hash_module

Disables building the module that implements the hash load balancing method.

--without-http_upstream_ip_hash_module

Disables building the module that implements the ip_hash load balancing method.

--without-http_upstream_keepalive_module

Disables building the module that provides connection caching to upstream servers.

--without-http_upstream_least_conn_module

Disables building the module that implements the least_conn load balancing method.

--without-http_upstream_least_time_module

Disables building the module that implements the least_time load balancing method.

--without-http_upstream_random_module

Disables building the module that implements the random load balancing method.

--without-http_upstream_sticky_module

Disables building the module that implements session persistence, ensuring all requests in the client session are passed to the same server in the upstream.

--without-http_upstream_zone_module

Disables building the module that allows storing the run-time state of an upstream in a shared memory zone.

--without-http_userid_module

Disables building the UserID module that sets cookies suitable for client identification.

--without-http_uwsgi_module

Disables building the uWSGI module that passes requests to a uWSGI server.

Stream modules#

Enabling additional modules:

* - --with-stream, --with-stream=dynamic - Enables the core Stream module for generic TCP/UDP proxying and load balancing.#

--with-stream_acme_module

Enables building the ACME module, which enables the ACME protocol.

--with-stream_geoip_module, --with-stream_geoip_module=dynamic

Enables the GeoIP module that creates variables depending on the client IP address and the precompiled MaxMind databases.

--with-stream_mqtt_preread_module

Enables the MQTT Preread module that allows extracting client IDs and usernames from CONNECT packets in MQTT versions 3.1.1 and 5.0.

--with-stream_rdp_preread_module

Enables the RDP Preread module that allows extracting cookies from RDP sessions.

--with-stream_realip_module

Enables the RealIP module that changes the client address to the address sent in the PROXY protocol header.

--with-stream_ssl_module

Enables SSL support for the Stream server.

The OpenSSL library is required to build and run this module.

--with-stream_ssl_preread_module

Enables the SSL Preread module that allows extracting information from ClientHello messages without terminating SSL/TLS.

--with-stream_upstream_probe_icmp (PRO)

Enables ICMP echo probes for the upstream_probe (PRO) directive. Requires OS ICMP support.

Disabling standard modules:

* - --without-stream_access_module - Disables the Access module that allows limiting access to certain client addresses.#

--without-stream_geo_module

Disables the Geo module that creates variables with values depending on the client IP address.

--without-stream_limit_conn_module

Disables the Limit Conn module that limits the number of connections per key, for example, the number of connections from a single IP address.

--without-stream_map_module

Disables the Map module that creates variables with values depending on values of other variables.

--without-stream_return_module

Disables the Return module that sends the specified value to the client and then closes the connection.

--without-stream_set_module

Disables the Set module that sets a value for a variable.

--without-stream_split_clients_module

Disables the Split Clients module that creates variables for A/B testing.

--without-stream_upstream_hash_module

Disables the module that implements the hash load balancing method.

--without-stream_upstream_least_conn_module

Disables the module that implements the least_conn load balancing method.

--without-stream_upstream_least_time_module

Disables the module that implements the least_time load balancing method.

--without-stream_upstream_random_module

Disables the module that implements the random load balancing method.

--without-stream_upstream_zone_module

Disables the module that enables storing the run-time state of an upstream in a shared memory zone.

Mail#

Enabling additional modules:

* - --with-mail, --with-mail=dynamic - Enables the core Mail module that supports POP3, IMAP4, and SMTP.#

--with-mail_ssl_module

Enables SSL support for the Mail server.

The OpenSSL library is required to build and run this module.

Disabling standard modules:

* - --without-mail_imap_module - Disables the IMAP protocol in the Mail server.#

--without-mail_pop3_module

Disables the POP3 protocol in the Mail server.

--without-mail_smtp_module

Disables the SMTP protocol in the Mail server.

Other options#

* - --with-cpp_test_module - Enables the CPP Test module. It's used primarily for development and testing purposes and isn't intended for production use.#

--add-module=path

Enables building an external module at the specified path.

--add-dynamic-module=path

Enables building an external dynamic module at the specified path.

--with-compat

Enables dynamic module compatibility mode. When enabled, Angie can load and use dynamic modules that were built for the same Angie version, even if these modules were built with different options. Angie PRO can load only modules built for Angie PRO; Angie (OSS) modules are rejected due to a different module signature.

--with-cc=path

Sets the compiler to be used during the build.

--with-cpp=path

Sets the preprocessor to be used during the build.

--with-cc-opt=parameters

Sets additional parameters that will be added to the CFLAGS variable. When using the system PCRE library under FreeBSD, --with-cc-opt="-I /usr/local/include" should be specified. If the number of files supported by select() needs to be increased, it can also be specified here, such as --with-cc-opt="-D FD_SETSIZE=2048".

--with-ld-opt=parameters

Sets additional parameters that will be used during linking. When using the system PCRE library under FreeBSD, --with-ld-opt="-L /usr/local/lib" should be specified.

--with-cpu-opt=cpu

Enables builds optimized for one of the following processors: pentium, pentiumpro, pentium3, pentium4, athlon, opteron, sparc32, sparc64, ppc64.

Examples#

Simple HTTPS-Enabled Build. This basic configuration enables HTTPS support using SSL/TLS, with the necessary dependencies (PCRE for regular expressions, zlib for compression, and OpenSSL for SSL/TLS):

$ ./configure \
    --sbin-path=/usr/sbin/angie \
    --conf-path=/etc/angie/angie.conf \
    --pid-path=/run/angie.pid \
    --with-http_ssl_module \
    --with-pcre=../pcre2-10.40 \
    --with-zlib=../zlib-1.3 \
    --with-openssl=../openssl-3.0.8

Performance-Optimized Build. This configuration is optimized for performance, including HTTP/2 support, gzip static compression, JIT for PCRE, and asynchronous I/O; thread pools are also enabled for efficient handling of high loads:

$ ./configure \
    --sbin-path=/usr/sbin/angie \
    --conf-path=/etc/angie/angie.conf \
    --pid-path=/run/angie.pid \
    --with-http_ssl_module \
    --with-http_v2_module \
    --with-http_gzip_static_module \
    --with-pcre=../pcre2-10.40 \
    --with-pcre-jit \
    --with-zlib=../zlib-1.3 \
    --with-threads \
    --with-file-aio

Load Balancer with TCP/UDP Proxying. This configuration sets up a load balancer for both HTTP and non-HTTP services:

$ ./configure \
    --sbin-path=/usr/sbin/angie \
    --conf-path=/etc/angie/angie.conf \
    --pid-path=/run/angie.pid \
    --with-stream \
    --with-stream_ssl_module \
    --with-pcre=../pcre2-10.40 \
    --with-zlib=../zlib-1.3

Specialized Build. This configuration includes HTTPS, HTTP/2, compression, enhanced security and performance, along with additional modules for Brotli compression and cache management, optimized for both HTTP and TCP/UDP proxying:

$ ./configure \
    --prefix=/usr/local/angie \
    --sbin-path=/usr/sbin/angie \
    --conf-path=/etc/angie/angie.conf \
    --pid-path=/run/angie.pid \
    --lock-path=/var/lock/angie.lock \
    --error-log-path=/var/log/angie/error.log \
    --http-log-path=/var/log/angie/access.log \
    --with-http_ssl_module \
    --with-http_v2_module \
    --with-http_realip_module \
    --with-http_gzip_static_module \
    --with-http_stub_status_module \
    --with-threads \
    --with-file-aio \
    --with-stream \
    --with-stream_ssl_module \
    --with-pcre=../pcre2-10.40 \
    --with-pcre-jit \
    --with-zlib=../zlib-1.3 \
    --with-openssl=../openssl-3.0.8 \
    --with-openssl-opt="enable-ec_nistp_64_gcc_128" \
    --add-module=../ngx_brotli \
    --add-dynamic-module=../ngx_cache_purge

The --add-module and --add-dynamic-module options above reference third-party module sources that you download separately. For example, clone them next to the Angie source tree:

$ git clone --recurse-submodules https://github.com/google/ngx_brotli
$ git clone https://github.com/nginx-modules/ngx_cache_purge

See Third-Party Modules for the modules Angie packages and their sources.