diff options
Diffstat (limited to '')
| -rw-r--r-- | INSTALL | 766 |
1 files changed, 766 insertions, 0 deletions
@@ -0,0 +1,766 @@ +Installation instructions for HAProxy +===================================== + +HAProxy 2.9 is a stable version, which means that it will get fixes for bugs as +they are discovered till around Q1 2025 and should not receive new features. +This version is mostly suited at experienced users who are willing to quickly +follow updates. New users are encouraged to use long term supported versions +such as the ones provided by their software vendor or Linux distribution, as +such versions require far less common updates. + +If for any reason you'd prefer to use a different version than the one packaged +for your system, you want to be certain to have all the fixes or to get some +commercial support, other choices are available at http://www.haproxy.com/. + + +Areas covered in this document +============================== + +1) Quick build & install +2) Basic principles +3) Build environment +4) Dependencies +5) Advanced build options +6) How to install HAProxy + + +1) Quick build & install +======================== + +If you've already built HAProxy and are just looking for a quick reminder, here +are a few build examples : + + - recent Linux system with all options, make and install : + $ make clean + $ make -j $(nproc) TARGET=linux-glibc \ + USE_OPENSSL=1 USE_LUA=1 USE_PCRE2=1 USE_SYSTEMD=1 + $ sudo make install + + - FreeBSD and OpenBSD, build with all options : + $ gmake -j 4 TARGET=freebsd USE_OPENSSL=1 USE_LUA=1 USE_PCRE2=1 + + - embedded Linux, build using a cross-compiler : + $ make -j $(nproc) TARGET=linux-glibc USE_OPENSSL=1 USE_PCRE2=1 \ + CC=/opt/cross/gcc730-arm/bin/gcc ADDLIB=-latomic + + - Build with static PCRE on Solaris / UltraSPARC : + $ make TARGET=solaris CPU=ultrasparc USE_STATIC_PCRE2=1 + +For more advanced build options or if a command above reports an error, please +read the following sections. + + +2) Basic principles +=================== + +HAProxy uses a single GNU Makefile which supports options on the command line, +so that there is no need to hack a "configure" file to work on your system. The +makefile totally supports parallel build using "make -j <jobs>" where <jobs> +matches the number of usable processors, which on some platforms is returned by +the "nproc" utility. The explanations below may occasionally refer to some +options, usually in the form "name=value", which have to be passed to the +command line. This means that the option has to be passed after the "make" +command. For example : + + $ make -j $(nproc) TARGET=generic USE_GZIP=1 + +One required option is TARGET, it must be set to a target platform name, which +provides a number of presets. The list of known platforms is displayed when no +target is specified. It is not strictly required to use the exact target, you +can use a relatively similar one and adjust specific variables by hand. + +Most configuration variables are in fact booleans. Some options are detected and +enabled by default if available on the target platform. This is the case for all +those named "USE_<feature>". These booleans are enabled by "USE_<feature>=1" +and are disabled by "USE_<feature>=" (with no value). An exhaustive list of the +supported USE_* features is located at the top of the main Makefile. The last +occurrence of such an option on the command line overrides any previous one. +Example : + + $ make TARGET=generic USE_THREAD= + +In case of error or missing TARGET, a help screen is displayed. It is also +possible to display a list of all known options using "make help". + +Some optional components which may depend on third-party libraries, are used +with popular tools which are not necessarily standard implementations, or are +maintained at slower pace than the core of the project, are located in the +"addons/" directory. These ones may disappear in a future version if the +product they depend on disappears or if their maintainers do not assign enough +resources to maintain them any more. For this reason they are not built by +default, but some USE_* options are usually provided for them, and their build +is routinely tested anyway. + + +3) Build environment +==================== + +HAProxy requires a working GCC or Clang toolchain and GNU make : + + - GNU make >= 3.80. Note that neither Solaris nor OpenBSD's make work with + the GNU Makefile. If you get many syntax errors when running "make", you + may want to retry with "gmake" which is the name commonly used for GNU make + on BSD systems. + + - GCC >= 4.2 (up to 13 tested). Older versions can be made to work with a + few minor adaptations if really needed. Newer versions may sometimes break + due to compiler regressions or behaviour changes. The version shipped with + your operating system is very likely to work with no trouble. Clang >= 3.0 + is also known to work as an alternative solution. Recent versions may emit + a bit more warnings that are worth reporting as they may reveal real bugs. + TCC (https://repo.or.cz/tinycc.git) is also usable for developers but will + not support threading and was found at least once to produce bad code in + some rare corner cases (since fixed). But it builds extremely quickly + (typically half a second for the whole project) and is very convenient to + run quick tests during API changes or code refactoring. + + - GNU ld (binutils package), with no particular version. Other linkers might + work but were not tested. + +On debian or Ubuntu systems and their derivatives, you may get all these tools +at once by issuing the two following commands : + + $ sudo apt-get update + $ sudo apt-get install build-essential + +On Fedora, CentOS, RHEL and derivatives, you may get the equivalent packages +with the following command : + + $ sudo yum groupinstall "Development Tools" + +Please refer to your operating system's documentation for other systems. + +It is also possible to build HAProxy for another system or platform using a +cross-compiler but in this case you probably already have installed these +tools. + +Building HAProxy may require between 60 and 80 MB of free space in the +directory where the sources have been extracted, depending on the debugging +options involved. + + +4) Dependencies +=============== + +HAProxy in its basic form does not depend on anything beyond a working libc. +However a number of options are enabled by default, or are highly recommended, +and these options will typically involve some external components or libraries, +depending on the targeted platform. + +Optional dependencies may be split into several categories : + + - memory allocation + - regular expressions + - multi-threading + - password encryption + - cryptography + - compression + - lua + - device detection + - miscellaneous + + +4.1) Memory allocation +---------------------- +By default, HAProxy uses the standard malloc() call provided by the libc. It +may also be built to use jemalloc, which is fast and thread-safe. In order to +use it, please add "-ljemalloc" to the ADDLIB variable. You may possibly also +need to append "-lpthread" and/or "-ldl" depending on the operating system. + + +4.2) Regular expressions +------------------------ +HAProxy may make use regular expressions (regex) to match certain patterns. The +regex engine is provided by default in the libc. On some operating systems, it +might happen that the original regex library provided by the libc is too slow, +too limited or even bogus. For example, on older Solaris versions up to 8, the +default regex used not to properly extract group references, without reporting +compilation errors. Also, some early versions of the GNU libc used to include a +regex engine which could be slow or even crash on certain patterns. + +If you plan on importing a particularly heavy configuration involving a lot of +regex, you may benefit from using some alternative regex implementations such as +PCRE. HAProxy natively supports PCRE and PCRE2 (recommended), both in standard +and JIT flavors (Just In Time). The following options are available depending on +the library version provided on your system : + + - "USE_PCRE=1" : enable PCRE version 1, dynamic linking + - "USE_STATIC_PCRE=1" : enable PCRE version 1, static linking + - "USE_PCRE_JIT=1" : enable PCRE version 1 in JIT mode + - "USE_PCRE2=1" : enable PCRE version 2, dynamic linking + - "USE_STATIC_PCRE2=1" : enable PCRE version 2, static linking + - "USE_PCRE2_JIT=1" : enable PCRE version 2 in JIT mode + +Both of these libraries may be downloaded from https://www.pcre.org/. + +By default, the include and library paths are figured from the "pcre-config" +and "pcre2-config" utilities. If these ones are not installed or inaccurate +(for example when cross-compiling), it is possible to force the path to include +files using "PCRE_INC" and "PCRE2_INC" respectively, and the path to library +files using "PCRE_LIB" and "PCRE2_LIB" respectively. For example : + + $ make TARGET=generic \ + USE_PCRE2_JIT=1 PCRE2_INC=/opt/cross/include PCRE2_LIB=/opt/cross/lib + + +4.3) Multi-threading +-------------------- +On some systems for which positive feedback was reported, multi-threading will +be enabled by default. When multi-threading is used, the libpthread library +(POSIX threading) will be used. If the target system doesn't contain such a +library, it is possible to forcefully disable multi-threading by adding +"USE_THREAD=" on the command line. + + +4.4) Password encryption +------------------------ +Many systems provide password encryption functions used for authentication. On +some systems these functions are part of the libc. On others, they're part of a +separate library called "libcrypt". The default targets are pre-configured +based on which system needs the library. It is possible to forcefully disable +the linkage against libcrypt by adding "USE_LIBCRYPT=" on the command line, or +to forcefully enable it using "USE_LIBCRYPT=1". + + +4.5) Cryptography +----------------- +For SSL/TLS, it is necessary to use a cryptography library. HAProxy currently +supports the OpenSSL library, and is known to build and work with branches +1.0.0, 1.0.1, 1.0.2, 1.1.0, 1.1.1, 3.0, 3.1 and 3.2. It is recommended to use +at least OpenSSL 1.1.1 to have support for all SSL keywords and configuration +in HAProxy. OpenSSL follows a long-term support cycle similar to HAProxy's, +and each of the branches above receives its own fixes, without forcing you to +upgrade to another branch. There is no excuse for staying vulnerable by not +applying a fix available for your version. There is always a small risk of +regression when jumping from one branch to another one, especially when it's +very new, so it's preferable to observe for a while if you use a different +version than your system's defaults. Specifically, it has been well established +that OpenSSL 3.0 can be 2 to 20 times slower than earlier versions on +multiprocessor systems due to design issues that cannot be fixed without a +major redesign, so in this case upgrading should be carefully thought about +(please see https://github.com/openssl/openssl/issues/20286 and +https://github.com/openssl/openssl/issues/17627). If a migration to 3.x is +mandated by support reasons, at least 3.1 recovers a small fraction of this +important loss. + +Four OpenSSL derivatives called LibreSSL, BoringSSL, QUICTLS, and AWS-LC are +reported to work as well. While there are some efforts from the community to +ensure they work well, OpenSSL remains the primary target and this means that +in case of conflicting choices, OpenSSL support will be favored over other +options. Note that QUIC is not fully supported when haproxy is built with +OpenSSL. In this case, QUICTLS is the preferred alternative. As of writing +this, the QuicTLS project follows OpenSSL very closely and provides update +simultaneously, but being a volunteer-driven project, its long-term future does +not look certain enough to convince operating systems to package it, so it +needs to be build locally. See the section about QUIC in this document. + +A fifth option is wolfSSL (https://github.com/wolfSSL/wolfssl). It is the only +supported alternative stack not based on OpenSSL, yet which implements almost +all of its API and natively supports QUIC. At the time of writing, the vast +majority of SSL features are well supported by wolfSSL though not everything is +exposed in haproxy yet, advanced users might notice tiny differences that the +wolfSSL and HAProxy teams are working on together to address in the wolfSSL +code base. Features like ecdsa/rsa dual stack, crt-list and client auth might +not work as expected. As of November 2023, wolfSSL support is considered +experimental. This stack is not affected by OpenSSL's design issue regarding +multi-processor systems and is viewed by the HAProxy team as the most promising +mid-term solution for general deployments and QUIC deployments. + +In order to enable SSL/TLS support, simply pass "USE_OPENSSL=1" on the command +line and the default library present on your system will be used : + + $ make TARGET=generic USE_OPENSSL=1 + +If you want to use a different version from the one provided by your system +(which is not recommended due to the risk of missing security fixes), it is +possible to indicate the path to the SSL include files using SSL_INC, and the +SSL library files using SSL_LIB. Example : + + $ make TARGET=generic \ + USE_OPENSSL=1 SSL_INC=/opt/ssl-1.1.1/include SSL_LIB=/opt/ssl-1.1.1/lib + +To use HAProxy with WolfSSL, WolfSSL must be built with haproxy support, at +least WolfSSL 5.6.4 is needed, but a development version might be needed for +some of the features: + + $ cd ~/build/wolfssl + $ ./configure --enable-haproxy --enable-quic --prefix=/opt/wolfssl-5.6.4/ + $ make -j $(nproc) + $ make install + +Please also note that wolfSSL supports many platform-specific features that may +affect performance, and that for production uses it might be a good idea to +check them using "./configure --help". Please refer to the lib's documentation. + +Building HAProxy with wolfSSL requires to specify the API variant on the "make" +command line, for example: + + $ cd ~/build/haproxy + $ make -j $(nproc) TARGET=generic USE_OPENSSL_WOLFSSL=1 USE_QUIC=1 \ + SSL_INC=/opt/wolfssl-5.6.4/include SSL_LIB=/opt/wolfssl-5.6.4/lib + +To use HAProxy with AWS-LC you must have version v1.13.0 or newer of AWS-LC +built and installed locally. + $ cd ~/build/aws-lc + $ cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/opt/aws-lc + $ make -j $(nproc) + $ make install + +Building HAProxy with AWS-LC requires you to enable AWS-LC support, and specify +the path it was installed to when running make for HAPRoxy. + + $ cd ~/build/haproxy + $ make -j $(nproc) TARGET=generic USE_OPENSSL_AWSLC=1 \ + SSL_INC=/opt/aws-lc/include SSL_LIB=/opt/aws-lc/lib + +In order to link OpenSSL statically against HAProxy, first download OpenSSL +from https://www.openssl.org/ then build it with the "no-shared" keyword and +install it to a local directory, so your system is not affected : + + $ export STATICLIBSSL=/tmp/staticlibssl + $ ./config --prefix=$STATICLIBSSL no-shared + $ make && make install_sw + +Then when building haproxy, pass that path via SSL_INC and SSL_LIB : + + $ make TARGET=generic \ + USE_OPENSSL=1 SSL_INC=$STATICLIBSSL/include SSL_LIB=$STATICLIBSSL/lib + +When building with OpenSSL on some systems, you may also need to enable support +for the "libz" library, which is visible if the linker complains about function +"deflateInit()" not being found. In this case, simply append "ADDLIB=-lz" to +the command line. + +It is worth mentioning that asynchronous cryptography engines are supported on +OpenSSL 1.1.0 and above. Such engines are used to access hardware cryptography +acceleration that might be present on your system. Due to API changes that +appeared with OpenSSL 3.0 and cause lots of build warnings, engines are not +enabled by default anymore in HAProxy 2.6. It is required to pass USE_ENGINE=1 +if they are desired. + +If for any reason you are forced to use OpenSSL 3.x and the performance is not +acceptable at all, you may want to try replacing the pthread locks that OpenSSL +uses with HAProxy's much lighter locks that are able to emulate them: + + $ make TARGET=generic \ + USE_OPENSSL=1 USE_PTHREAD_EMULATION=1 + +On large multi-processor systems, this may result in a performance increase of +50 to 100% on OpenSSL 3.0 depending on the level of contention, but this will +of course not recover everything. It should not be used by distro packagers as +it is a bit less observable. + + +4.6) Compression +---------------- +HAProxy can compress HTTP responses before delivering them to clients, in order +to save network bandwidth. Two compression options are available. The first one +relies on the libslz library (http://libslz.org) that is embedded in haproxy. +It is enabled by default as it is very fast and does not keep a copy of the +contents in memory. It is possible to disable it, for example for very small +systems, by passing "USE_SLZ=" to the "make" command. + +Please note that SLZ will benefit from some CPU-specific instructions like the +availability of the CRC32 extension on some ARM processors. Thus it can further +improve its performance to build with "CPU=native" on the target system, or +"CPU=armv81" (modern systems such as Graviton2 or A55/A75 and beyond), +"CPU=a72" (e.g. for RPi4, or AWS Graviton), "CPU=a53" (e.g. for RPi3), or +"CPU=armv8-auto" (automatic detection with minor runtime penalty). + +A second option involves the widely known zlib library, which is very likely +installed on your system. In order to use zlib, simply pass "USE_ZLIB=1" to the +"make" command line, which will also automatically disable SLZ. If the library +is not installed in your default system's path, it is possible to specify the +path to the include files using ZLIB_INC, and the path to the library files +using ZLIB_LIB : + + $ make TARGET=generic \ + USE_ZLIB=1 ZLIB_INC=/opt/zlib-1.2.11/include ZLIB_LIB=/opt/zlib-1.2.11/lib + +Zlib is commonly found on most systems, otherwise updates can be retrieved from +http://www.zlib.net/. It is easy and fast to build, and new versions sometimes +provide better performance so it might be worth using an up-to-date one. + +Zlib compresses a bit better than libslz but at the expense of more CPU usage +(about 3.5 times more minimum), and a huge memory usage (~260 kB per compressed +stream). The only valid reason for uzing Zlib instead of SLZ here usually is to +deal with a very limited internet bandwidth while CPU and RAM are abundant so +that the last few percent of compression ratio are worth the invested hardware. + + +4.7) Lua +-------- +Lua is an embedded programming language supported by HAProxy to provide more +advanced scripting capabilities. Only versions 5.3 and above are supported. +In order to enable Lua support, please specify "USE_LUA=1" on the command line. +Some systems provide this library under various names to avoid conflicts with +previous versions. By default, HAProxy looks for "lua5.4", "lua54", "lua5.3", +"lua53", "lua". If your system uses a different naming, you may need to set the +library name in the "LUA_LIB_NAME" variable. + +If Lua is not provided on your system, it can be very simply built locally. It +can be downloaded from https://www.lua.org/, extracted and built, for example : + + $ cd /opt/lua-5.4.6 + $ make linux + +The path to the include files and library files may be set using "LUA_INC" and +"LUA_LIB" respectively. For example : + + $ make TARGET=generic \ + USE_LUA=1 LUA_INC=/opt/lua-5.4.6/src LUA_LIB=/opt/lua-5.4.6/src + + +4.8) Device detection +--------------------- +HAProxy supports several device detection modules relying on third party +products. Some of them may provide free code, others free libs, others free +evaluation licenses. Please read about their respective details in the +following files : + + doc/DeviceAtlas-device-detection.txt for DeviceAtlas + doc/51Degrees-device-detection.txt for 51Degrees + doc/WURFL-device-detection.txt for Scientiamobile WURFL + + +4.9) Miscellaneous +------------------ +Some systems have specificities. Usually these specificities are known and/or +detected and properly set for you. If you need to adjust the behaviour, here +are the extra libraries that may be referenced at build time : + + - USE_RT=1 build with librt, which is sometimes needed on some systems + when using threads. It is set by default on Linux platforms, + and may be disabled using "USE_RT=" if your system doesn't + have one. You may have to set it as well if you face an error + indicating that clock_gettime() was not found. + + - USE_DL=1 build with libdl, which is usually needed for Lua and OpenSSL + on Linux. It is automatically detected and may be disabled + using "USE_DL=", though it should never harm. + + - USE_SYSTEMD=1 enables support for the sdnotify features of systemd, + allowing better integration with systemd on Linux systems + which come with it. It is never enabled by default so there + is no need to disable it. + + +4.10) Common errors +------------------- +Some build errors may happen depending on the options combinations or the +selected target. When facing build errors, if you know that your system is a +bit special or particularly old, start from TARGET=generic, it is easier to +start from there and fix the remaining issues than trying to degrade another +target. Common issues may include: + + - clock_gettime() not found + => your system needs USE_RT=1 + + - many __sync_<something> errors in many files + => your gcc is too old, build without threads. + + - many openssl errors + => your OpenSSL version really is too old, do not enable OpenSSL + + - quic_conn-t.h: field 'level' has incomplete type + => you tried to build QUIC with the legacy OpenSSL library, which does + not support QUIC. Either disable QUIC with "USE_QUIC=" or use any + other supported compatible library. + + - many "dereferencing pointer 'sa.985' does break strict-aliasing rules" + => these warnings happen on old compilers (typically gcc-4.4), and may + safely be ignored; newer ones are better on these. + + +4.11) QUIC +---------- +QUIC is the new transport layer protocol and is required for HTTP/3. This +protocol stack is currently supported as an experimental feature in haproxy on +the frontend side. In order to enable it, use "USE_QUIC=1 USE_OPENSSL=1". + +Note that QUIC is not fully supported by the OpenSSL library. Indeed QUIC 0-RTT +cannot be supported by OpenSSL contrary to others libraries with full QUIC +support. The preferred option is to use QUICTLS. This is a fork of OpenSSL with +a QUIC-compatible API. Its repository is available at this location: + + https://github.com/quictls/openssl + +You can use the following instruction to build a functional QUICTLS. + + $ ./config --libdir=lib [--prefix=/opt/quictls] + $ make + $ make install + +On a development environment, use SSL_INC and SSL_LIB when building haproxy to +point to the correct cryptographic library. It may be useful to specify QUICTLS +location via rpath for haproxy execution. Example : + + $ make -j $(nproc) TARGET=generic \ + USE_QUIC=1 \ + USE_OPENSSL=1 SSL_INC=/opt/quictls/include SSL_LIB=/opt/quictls/lib \ + LDFLAGS="-Wl,-rpath,/opt/quictls/lib" + +Alternately, building against wolfSSL is supported as well, for example this +way assuming that wolfSSL was installed in /opt/wolfssl-5.6.0 as shown in 4.5: + + $ make -j $(nproc) TARGET=generic \ + USE_QUIC=1 \ + USE_OPENSSL_WOLFSSL=1 \ + SSL_INC=/opt/wolfssl-5.6.0/include SSL_LIB=/opt/wolfssl-5.6.0/lib + LDFLAGS="-Wl,-rpath,/opt/wolfssl-5.6.0/lib" + +As last resort, haproxy may be compiled against OpenSSL as follows: + + $ make TARGET=generic USE_OPENSSL=1 USE_QUIC=1 USE_QUIC_OPENSSL_COMPAT=1 + +Note that QUIC 0-RTT is not supported by haproxy QUIC stack when built against +OpenSSL. In addition to this compilation requirements, the QUIC listener +bindings must be explicitly enabled with a specific QUIC tuning parameter. +(see "limited-quic" global parameter of haproxy Configuration Manual). + + +5) How to build HAProxy +======================= + +This section assumes that you have already read section 2 (basic principles) +and section 3 (build environment). It often refers to section 4 (dependencies). + +To build haproxy, you have to choose your target OS amongst the following ones +and assign it to the TARGET variable : + + - linux-glibc for Linux kernel 2.6.28 and above + - linux-glibc-legacy for Linux kernel 2.6.28 and above without new features + - linux-musl for Linux kernel 2.6.28 and above with musl libc + - solaris for Solaris 10 and above + - freebsd for FreeBSD 10 and above + - dragonfly for DragonFlyBSD 4.3 and above + - netbsd for NetBSD 8 and above + - osx for Mac OS/X + - openbsd for OpenBSD 6.3 and above + - aix51 for AIX 5.1 + - aix52 for AIX 5.2 + - aix72-gcc for AIX 7.2 (using gcc) + - cygwin for Cygwin + - haiku for Haiku + - generic for any other OS or version. + - custom to manually adjust every setting + +You may also choose your CPU to benefit from some optimizations. This is +particularly important on UltraSparc machines. For this, you can assign +one of the following choices to the CPU variable : + + - i686 for intel PentiumPro, Pentium 2 and above, AMD Athlon (32 bits) + - i586 for intel Pentium, AMD K6, VIA C3. + - ultrasparc : Sun UltraSparc I/II/III/IV processor + - power8 : IBM POWER8 processor + - power9 : IBM POWER9 processor + - armv81 : modern ARM cores (Cortex A55/A75/A76/A78/X1, Neoverse, Graviton2) + - a72 : ARM Cortex-A72 or A73 (e.g. RPi4, Odroid N2, AWS Graviton) + - a53 : ARM Cortex-A53 or any of its successors in 64-bit mode (e.g. RPi3) + - armv8-auto : support both older and newer armv8 cores with a minor penalty, + thanks to gcc 10's outline atomics (default with gcc 10.2). + - native : use the build machine's specific processor optimizations. Use with + extreme care, and never in virtualized environments (known to break). + - generic : any other processor or no CPU-specific optimization. (default) + +Alternatively, you may just set the CPU_CFLAGS value to the optimal GCC options +for your platform. A second variable named SMALL_OPTS also supports passing a +number of defines and compiler options usually for small systems. For better +clarity it's recommended to pass the options which result in a smaller binary +(like memory limits or -Os) into this variable. + +If you are building for a different system than the one you're building on, +this is called "cross-compiling". HAProxy supports cross-compilation pretty +well and tries to ease it by letting you adjust paths to all libraries (please +read section 4 on dependencies for more details). When cross-compiling, you +just need to pass the path to your compiler in the "CC" variable, and the path +to the linker in the "LD" variable. Most of the time, setting the CC variable +is enough since LD points to it by default. + +By default the build process runs in quiet mode and hide the details of the +commands that are executed. This allows to more easily catch build warnings +and see what is happening. However it is not convenient at all to observe what +flags are passed to the compiler nor what compiler is involved. Simply append +"V=1" to the "make" command line to switch to verbose mode and display the +details again. It is recommended to use this option when cross-compiling to +verify that the paths are correct and that /usr/include is never involved. + +You may want to build specific target binaries which do not match your native +compiler's target. This is particularly true on 64-bit systems when you want +to build a 32-bit binary. Use the ARCH variable for this purpose. Right now +it only knows about a few x86 variants (i386,i486,i586,i686,x86_64), two +generic ones (32,64) and sets -m32/-m64 as well as -march=<arch> accordingly. +This variable is only used to set ARCH_FLAGS to preset values, so if you know +the arch-specific flags that your system needs, you may prefer to set +ARCH_FLAGS instead. Note that these flags are passed both to the compiler and +to the linker. For example, in order to build a 32-bit binary on an x86_64 +Linux system with SSL support without support for compression but when OpenSSL +requires ZLIB anyway : + + $ make TARGET=linux-glibc ARCH=i386 USE_OPENSSL=1 ADDLIB=-lz + +Recent systems can resolve IPv6 host names using getaddrinfo(). This primitive +is not present in all libcs and does not work in all of them either. Support in +glibc was broken before 2.3. Some embedded libs may not properly work either, +thus, support is disabled by default, meaning that some host names which only +resolve as IPv6 addresses will not resolve and configs might emit an error +during parsing. If you know that your OS libc has reliable support for +getaddrinfo(), you can add USE_GETADDRINFO=1 on the make command line to enable +it. This is the recommended option for most Linux distro packagers since it's +working fine on all recent mainstream distros. It is automatically enabled on +Solaris 8 and above, as it's known to work. + +If your system supports PCRE (Perl Compatible Regular Expressions), then you +really should build with libpcre which is between 2 and 10 times faster than +other libc implementations. Regex are used for header processing (deletion, +rewriting, allow, deny). Please see section 4 about dependencies to figure +how to build with PCRE support. + +It is possible to add native support for SSL, by passing "USE_OPENSSL=1" on the +make command line. The libssl and libcrypto will automatically be linked with +HAProxy. Some systems also require libz, so if the build fails due to missing +symbols such as deflateInit(), then try again with "ADDLIB=-lz". Please check +section 4 about dependencies for more information on how to build with OpenSSL. + +HAProxy can compress HTTP responses to save bandwidth. Please see section 4 +about dependencies to see the available libraries and associated options. + +By default, the DEBUG_CFLAGS variable is set to '-g' to enable debug symbols. +It is not wise to disable it on uncommon systems, because it's often the only +way to get a usable core when you need one. Otherwise, you can set DEBUG to +'-s' to strip the binary. + +If the ERR variable is set to any non-empty value, then -Werror will be added +to the compiler so that any build warning will trigger an error. This is the +recommended way to build when developing, and it is expected that contributed +patches were tested with ERR=1. + +The DEBUG variable is used to extend the CFLAGS and is preset to a list of +build-time options that are known for providing significant reliability +improvements and a barely perceptible performance cost. Unless instructed to do +so by some project developers, or trying to save the last ounce of performance, +these options should not be changed. Among the usable ones are: + - -DDEBUG_STRICT: enable some runtime assertions at key places in the code. + The goal is to emit a warning or stop the program if certain expected + conditions are not met, and whose violation will result in a misbehaving + process due to memory corruption or other significant trouble, possibly + caused by an attempt to exploit a bug in the program or a library it relies + on. The option knows 3 values: 0 (disable all such assertions, the default + when the option is not set), 1 (enable all inexpensive assertions), and + 2 (enable all assertions even in fast paths). Setting the option with no + value corresponds to 1, which is the recommended value for production. + + - -DDEBUG_STRICT_ACTION: indicates how to react to a check violation. There + are 3 types of checks: BUG (condition that is known to have serious + consequences), WARN (warning about a highly suspicious condition which the + process may recover from, but whose unknown cause may also have serious + consequences), CHECK (verification whether a condition that developers now + consider impossible still happens). The variable takes a value from 0 to 3, + that adjusts the behavior on these 3 violations: + + BUG WARN CHECK + 0 warn warn warn + 1 stop warn warn + 2 stop stop warn + 3 stop stop stop + + The default value is 1, which is the best balance for production in that it + will do its best to prevent a known bogus process from running away, but + will let it run if it believes it can recover. Users running the process in + sensitive environments (finance etc) may prefer to run at level 2 to make + sure to stop any detected anomaly before it may have an impact. Level 3 + should only be used at the request of developers. In any case, any emitted + warning should be reported to developers. + + - -DDEBUG_MEMORY_POOLS: this enables by default extra controls around memory + allocation that will help detect coding errors such as double-frees and + freeing a bad memory location. It will also detect earlier risks of memory + overflows, which may have security implications. The cost is extremely low + (less than 1% increase in memory footprint). This is equivalent to adding + "-dMtag" on the command line. This option is enabled in the default build + options. + + - -DDEBUG_DONT_SHARE_POOLS: this will keep separate pools for same-sized + objects of different types. Using this increases the memory usage a little + bit but further reduces the risk of memory management related bugs and will + lead to more accurate traces in case of error. It is equivalent to adding + "-dMno-merge" on the command line. It is not enabled in the default build + options. + + - -DDEBUG_POOL_INTEGRITY: this will enable runtime detection and stopping of + a class of bugs known as "use after free", which consists in modifying a + memory area after freeing it while it was reused for something else. This + option is quite powerful but such bugs are fortunately extremely rare, and + it will cause a measurable performance degradation (a few percent). This is + equivalent to adding "-dMcold-first,integrity" on the command line. This + option is not enabled by default but users running development versions on + moderate performance sites in order to participate to reliability testing + are encouraged to use it, in combination with -DDEBUG_DONT_SHARE_POOLS and + -DDEBUG_MEMORY_POOLS, as this could catch dangerous regressions. + +As such, for regular production, "-DDEBUG_STRICT -DDEBUG_MEMORY_POOLS" is +recommended. For security sensitive environments, it is recommended to use +"-DDEBUG_STRICT -DDEBUG_STRICT_ACTION=2 -DDEBUG_MEMORY_POOLS \ +-DDEBUG_DONT_SHARE_POOLS". For deployments dedicated to testing new versions or +when trying to nail a bug down, use "-DDEBUG_STRICT=2 -DDEBUG_STRICT_ACTION=2 \ +-DDEBUG_MEMORY_POOLS -DDEBUG_DONT_SHARE_POOLS -DDEBUG_POOL_INTEGRITY". + +The DEP variable is automatically set to the list of include files and also +designates a file that contains the last build options used. It is used during +the build process to compute dependencies and decide whether or not to rebuild +everything (we do rebuild everything when .h files are touched or when build +options change). Sometimes when performing fast build iterations on inline +functions it may be desirable to avoid a full rebuild. Forcing this variable +to be empty will be sufficient to achieve this. This variable must never be +forced to produce final binaries, and must not be used during bisect sessions, +as it will often lead to the wrong commit. + +If you need to pass other defines, includes, libraries, etc... then please +check the Makefile to see which ones will be available in your case, and +use/override the USE_* variables from the Makefile. + +AIX 5.3 is known to work with the generic target. However, for the binary to +also run on 5.2 or earlier, you need to build with DEFINE="-D_MSGQSUPPORT", +otherwise __fd_select() will be used while not being present in the libc, but +this is easily addressed using the "aix52" target. If you get build errors +because of strange symbols or section mismatches, simply remove -g from +DEBUG_CFLAGS. + +Building on AIX 7.2 works fine using the "aix72-gcc" TARGET. It adds two +special CFLAGS to prevent the loading of AIX's xmem.h and var.h. This is done +by defining the corresponding include-guards _H_XMEM and _H_VAR. Without +excluding those header-files the build fails because of redefinition errors. +Furthermore, the atomic library is added to the LDFLAGS to allow for +multithreading via USE_THREAD. + +You can easily define your own target with the GNU Makefile. Unknown targets +are processed with no default option except USE_POLL=default. So you can very +well use that property to define your own set of options. USE_POLL and USE_SLZ +can even be disabled by setting them to an empty string. For example : + + $ gmake TARGET=tiny USE_POLL="" USE_SLZ="" TARGET_CFLAGS=-fomit-frame-pointer + +If you need to pass some defines to the preprocessor or compiler, you may pass +them all in the DEFINE variable. Example: + + $ make TARGET=generic DEFINE="-DDEBUG_DONT_SHARE_POOLS -DDEBUG_MEMORY_POOLS" + +The ADDINC variable may be used to add some extra include paths; this is +sometimes needed when cross-compiling. Similarly the ADDLIB variable may be +used to specify extra paths to library files. Example : + + $ make TARGET=generic ADDINC=-I/opt/cross/include ADDLIB=-L/opt/cross/lib64 + + +6) How to install HAProxy +========================= + +To install haproxy, you can either copy the single resulting binary to the +place you want, or run : + + $ sudo make install + +If you're packaging it for another system, you can specify its root directory +in the usual DESTDIR variable. + +-- end |