Building Angie from Source#

We recommend installing Angie from official pre-built packages. However, if you still need your own build:

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

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

  2. Unpack the sources and browse to the source code:

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

  3. To prepare the build, use the ./configure script to determine 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.

    Before running ./configure, browse and set the build options:

    $ ./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 an unprivileged 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 Angie 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 name of the angie.lock lock file. 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 obtained for server blocks that have the 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 run using poll(). The module is built automatically if the platform doesn't support more suitable methods such as kqueue, epoll, or /dev/poll.

--with-threads

Enables the use of thread pools.

--with-file-aio

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

--with-debug

Enables the debugging log.

--without-http-cache

Disables the HTTP cache.

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

Enables the PCRE library.

The optional setting is 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 options 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

Forces the usage of the libatomic_ops library. The optional setting is the path to the library sources.

--with-openssl=path

Enables and sets the path to the OpenSSL library sources.

--with-openssl-opt=parameters

Sets additional build options for OpenSSL.

--with-ntls

Enables server-side and client-side NTLS support in the HTTP and Streaming modules (server-side, client-side) when linked with an NTLS-enabled SSL library.

--with-zlib=path

Sets the path to the sources of the zlib library. The library distribution (version 1.1.3 — 1.2.11) needs to be downloaded from the zlib site and extracted. 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 options for zlib.

--with-zlib-asm=cpu

Enables building zlib with assembly sources optimized for one of these CPUs: pentium, pentiumpro.

Enabling and Disabling Modules#

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

HTTP#

Enabling additional modules:

--with-http_acme_module

Enables the ACME module that supports the ACME protocol.

--with-http_addition_module

Enables the Addition module that adds text before and after a response.

--with-http_auth_request_module

Enables the Auth Request module that implements client authorization based on the result of a subrequest.

--with-http_dav_module

Enables the DAV module that provides file management automation via the WebDAV protocol.

--with-http_degradation_module

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

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

--with-http_flv_module

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

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

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

--with-http_gunzip_module

Enables the GunZIP module that decompresses responses with Content-Encoding: gzip for clients that do not support the gzip encoding method.

--with-http_gzip_static_module

Enables the GZip Static module that allows sending precompressed files with the .gz filename extension instead of regular files.

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

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

--with-http_mp4_module

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

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

Enables the Perl module.

--with-perl_modules_path=path

Defines the directory that will store Perl modules.

--with-perl=path

Sets the path to the Perl executable.

--with-http_random_index_module

Enables the Random Index module that processes requests ending with the slash character (/) and picks a random file in a directory to serve as an index file.

--with-http_realip_module

Enables the RealIP module that changes the client address to the address sent in the specified header field.

--with-http_secure_link_module

Enables the Secure Link module.

--with-http_slice_module

Enables the Slice module that splits a request into subrequests, each returning a certain range of the response. The module provides effective caching of large responses.

--with-http_ssl_module

Enables SSL support for the HTTP server.

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

--with-http_stub_status_module

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

--with-http_sub_module

Enables the Sub module that modifies a response by replacing one specified string with another.

--with-http_v2_module

Enables the HTTP/2 module.

--with-http_v3_module

Enables the HTTP/3 module.

Note

It's highly recommended to build the HTTP/3 module with an SSL library that fully supports QUIC:

Using 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"

Otherwise, the OpenSSL library will use a compatibility layer that doesn't support early data and some other features, such as session reuse. The resulting build will only interoperate with clients and servers that use the same OpenSSL compatibility layer.

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

Enables the XSLT module that transforms XML responses using one or more XSLT stylesheets.

The libxml2 and libxslt libraries are required to build and run this module.

--with-google_perftools_module

Enables the Google PerfTools module that allows 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 the Access module that allows limiting access to certain client addresses.

--without-http_api_module

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

--without-http_auth_basic_module

Disables 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 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 the Browser module that creates variables whose values depend on the value of the User-Agent request header field.

--without-http_charset_module

Disables 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_empty_gif_module

Disables the :ref:` module <http_empty_gif>` that emits a single-pixel transparent GIF.

--without-http_fastcgi_module

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

--without-http_geo_module

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

--without-http_gzip_module

Disables the module that compresses the HTTP server responses.

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

--without-http_grpc_module

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

--without-http_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-http_limit_req_module

Disables 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 the Map module that creates variables with values depending on the values of other variables.

--without-http_memcached_module

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

--without-http_mirror_module

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

--without-http_proxy_module

Disables the Proxy module of the HTTP server.

--without-http_prometheus_module

Disables the Prometheus module of the HTTP server.

--without-http_referer_module

Disables 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 the Rewrite module that allows the HTTP server to redirect requests and change their URIs.

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

--without-http_scgi_module

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

--without-http_split_clients_module

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

--without-http_ssi_module

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

--without-http_upstream_hash_module

Disables the module that implements the hash load balancing method.

--without-http_upstream_ip_hash_module

Disables the module that implements the ip_hash load balancing method.

--without-http_upstream_keepalive_module

Disables the module that provides connection caching to upstream servers.

--without-http_upstream_least_conn_module

Disables the module that implements the least_conn load balancing method.

--without-http_upstream_random_module

Disables the module that implements the random load balancing method.

--without-http_upstream_sticky_module

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

--without-http_upstream_zone_module

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

--without-http_userid_module

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

--without-http_uwsgi_module

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

Streaming#

Enabling additional modules:

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

--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 Streaming 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.

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_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 an external module at the specified path.

--add-dynamic-module=path

Enables an external dynamic module at the specified path.

--with-compat

Enables dynamic module compatibility; 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.

--with-cc=path

Sets the name of the C compiler.

--with-cpp=path

Sets the name of the C preprocessor.

--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 a specific CPU: 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 regex, 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 by enabling HTTP/2, gzip static compression, JIT for PCRE, and asynchronous I/O; thread pools are also enabled to handle high loads efficiently:

$ ./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 configures 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

Custom build: This configures 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 \                        # Sets the installation directory for Angie
    --sbin-path=/usr/sbin/angie \                      # Path to the Angie binary
    --conf-path=/etc/angie/angie.conf \                # Path to the main configuration file
    --pid-path=/run/angie.pid \                        # Path to the PID file
    --lock-path=/var/lock/angie.lock \                 # Path to the lock file
    --error-log-path=/var/log/angie/error.log \        # Path to the error log
    --http-log-path=/var/log/angie/access.log \        # Path to the access log
    --with-http_ssl_module \                           # Enables SSL module for HTTPS
    --with-http_v2_module \                            # Enables HTTP/2 support for improved performance
    --with-http_realip_module \                        # Allows Angie to correctly handle X-Real-IP and X-Forwarded-For headers
    --with-http_gzip_static_module \                   # Serves pre-compressed .gz files to reduce CPU load
    --with-http_stub_status_module \                   # Provides a status page
    --with-threads \                                   # Enables thread pools to improve performance under heavy load
    --with-file-aio \                                  # Enables asynchronous I/O
    --with-stream \                                    # Enables TCP/UDP proxy functionality
    --with-stream_ssl_module \                         # Adds SSL/TLS support for stream (TCP/UDP) proxy
    --with-pcre=../pcre2-10.40 \                       # Specifies the path to PCRE library for regex support
    --with-pcre-jit \                                  # Enables just-in-time compilation for PCRE
    --with-zlib=../zlib-1.3 \                          # Specifies the path to the zlib library for compression
    --with-openssl=../openssl-3.0.8 \                  # Specifies the path to the OpenSSL library for SSL/TLS
    --with-openssl-opt="enable-ec_nistp_64_gcc_128" \  # Optimizes OpenSSL for 64-bit NIST curves
    --add-module=../ngx_brotli \                       # Adds third-party ngx_brotli module for Brotli compression support
    --add-dynamic-module=../ngx_cache_purge            # Adds third-party ngx_cache_purge module for cache management