diff options
Diffstat (limited to 'INSTALL')
| -rw-r--r-- | INSTALL | 352 |
1 files changed, 234 insertions, 118 deletions
@@ -1,14 +1,19 @@ 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 +HAProxy 3.0 is a long-term supported version, which means that it will get +fixes for bugs as they are discovered till around Q2 2029 and will not receive +new features. This version is suitable for general deployment as it is expected +to receive less frequent updates than regular stable branches which have an odd +digit in the minor version number. New users are encouraged to use long-term +supported versions such as the ones provided by their software vendor, Linux +distribution, or by a trusted package maintainer. Experienced users who manage +a fleet of load balancers are encouraged to deploy at least one node with the +latest weekly development version to get familiar with upcoming changes and +possibly detect unwelcome changes or bugs before the release. This is also a +great way to get new features implemented exactly as desired. + +If for any reason you would prefer 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/. @@ -33,18 +38,26 @@ 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 + USE_OPENSSL=1 USE_QUIC=1 USE_QUIC_OPENSSL_COMPAT=1 \ + USE_LUA=1 USE_PCRE2=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 + - FreeBSD + OpenSSL, build with all options : + $ gmake -j $(sysctl -n hw.ncpu) TARGET=freebsd \ + USE_OPENSSL=1 USE_QUIC=1 USE_QUIC_OPENSSL_COMPAT=1 \ + USE_LUA=1 USE_PCRE2=1 + + - OpenBSD + LibreSSL, build with all options : + $ gmake -j $(sysctl -n hw.ncpu) TARGET=openbsd \ + USE_OPENSSL=1 USE_QUIC=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 + CC=/opt/cross/gcc730-arm/bin/gcc CFLAGS="-mthumb" ADDLIB=-latomic - Build with static PCRE on Solaris / UltraSPARC : - $ make TARGET=solaris CPU=ultrasparc USE_STATIC_PCRE2=1 + $ make -j $(/usr/sbin/psrinfo -p) TARGET=solaris \ + CPU_CFLAGS="-mcpu=v9" USE_STATIC_PCRE2=1 For more advanced build options or if a command above reports an error, please read the following sections. @@ -72,10 +85,10 @@ 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 : +and are disabled by "USE_<feature>=" (with no value) or "USE_<feature>=0". 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= @@ -226,7 +239,7 @@ to forcefully enable it using "USE_LIBCRYPT=1". ----------------- 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 +1.0.0, 1.0.1, 1.0.2, 1.1.0, 1.1.1, and 3.0 to 3.3. 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 @@ -280,11 +293,11 @@ SSL library files using SSL_LIB. Example : 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 +least WolfSSL 5.6.6 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/ + $ ./configure --enable-haproxy --enable-quic --prefix=/opt/wolfssl-5.6.6/ $ make -j $(nproc) $ make install @@ -292,12 +305,24 @@ 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. +When running wolfSSL in chroot, either mount /dev/[u]random devices into the +chroot: + + $ mkdir -p /path/to/chrootdir/dev/ + $ mknod -m 444 /path/to/chrootdir/dev/random c 1 8 + $ mknod -m 444 /path/to/chrootdir/dev/urandom c 1 9 + +Or, if your OS supports it, enable the getrandom() syscall by appending the +following argument to the wolfSSL configure command: + + EXTRA_CFLAGS=-DWOLFSSL_GETRANDOM=1 + 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 + SSL_INC=/opt/wolfssl-5.6.6/include SSL_LIB=/opt/wolfssl-5.6.6/lib To use HAProxy with AWS-LC you must have version v1.13.0 or newer of AWS-LC built and installed locally. @@ -524,7 +549,11 @@ bindings must be explicitly enabled with a specific QUIC tuning parameter. This section assumes that you have already read section 2 (basic principles) and section 3 (build environment). It often refers to section 4 (dependencies). +It goes into more details with the main options. + +5.1) Configuring the TARGET +--------------------------- To build haproxy, you have to choose your target OS amongst the following ones and assign it to the TARGET variable : @@ -545,29 +574,64 @@ and assign it to the TARGET variable : - 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. +Example: + $ make -j $(nproc) TARGET=linux-glibc + +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 +ARCH_FLAGS. + +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 or a zero. For +example : + + $ gmake TARGET=tiny USE_POLL="" USE_SLZ=0 TARGET_CFLAGS=-fomit-frame-pointer + + +5.2) Adding extra CFLAGS for compiling +-------------------------------------- +A generic CFLAGS variable may be set to append any option to pass to the C +compiler. These flags are passed last so the variable may be used to override +other options such as warnings, optimization levels, include paths etc. + +A default optimization level of -O2 is set by variable OPT_CFLAGS which may be +overridden if desired. It's used early in the list of CFLAGS so that any other +set of CFLAGS providing a different value may easily override it. + +Some platforms may benefit from some CPU-specific options that will enable +certain instruction sets, word size or endianness for example. One of them is +the common "-march=native" that indicates to modern compilers that they need to +optimize for the machine the compiler is running on. Such options may be either +passed in the CPU_CFLAGS or in the CFLAGS variable, either will work though +one may be more convenient for certain methods of packaging and the other one +for other methods. Among the many possible options, the following ones are +known for having successfully been used: + + - "-march=native" for a native build + - "-march=armv8-a+crc" for older ARM Cortex A53/A72/A73 (such as RPi 3B/4B) + - "-march=armv8.1-a" for modern ARM Cortex A55/A76, Graviton2+, RPi 5 + - "-march=armv8-a+crc -moutline-atomics" to support older ARM with better + support of modern cores with gcc-10+ + - "-mavx", "-mavx2", "-mavx512", to enable certain x86 SIMD instruction sets + - "-march=i586" to support almost all 32-bit x86 systems + - "-march=i686" to support only the latest 32-bit x86 systems + - "-march=i386" to support even the oldest 32-bit x86 systems + - "-mlittle-endian -march=armv5te" for some little-endian ARMv5 systems + - "-mcpu=v9 -mtune=ultrasparc -m64" for a 64-bit Solaris SPARC build + - "-march=1004kc -mtune=1004kc" for some multi-core 32-bit MIPS 1004Kc + - "-march=24kc -mtune=24kc" for some single-core 32-bit MIPS 24Kc 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 @@ -585,20 +649,49 @@ flags are passed to the compiler nor what compiler is involved. Simply append 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 +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" + +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 + + +5.3) Adding extra LDFLAGS for linking +------------------------------------- +If a particular target requires specific link-time flags, these can be passed +via the LDFLAGS variable. This variable is passed to the linker immediately +after ARCH_FLAGS. One of the common use cases is to add some run time search +paths for a dynamic library that's not part of the default system search path: + + $ make -j $(nproc) TARGET=generic USE_OPENSSL_AWSLC=1 USE_QUIC=1 \ + SSL_INC=/opt/aws-lc/include SSL_LIB=/opt/aws-lc/lib \ + LDFLAGS="-Wl,-rpath,/opt/aws-lc/lib" + +Some options require to be consistent between the compilation stage and the +linking stage. This is the case for options which enable debugging (e.g. "-g"), +profiling ("-pg"), link-time optimization ("-flto"), endianness ("-EB", "-EL"), +bit width ("-m32", "-m64"), or code analyzers ("-fsanitize=address"). These +options can be passed via the ARCH_FLAGS variable, which will be used at both +stages during the build process, thus avoiding the risk of inconsistencies. By +default, ARCH_FLAGS only contains "-g" to enable the generation of debug +symbols. 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 + $ make TARGET=linux-glibc ARCH_FLAGS="-m32 -g" USE_OPENSSL=1 ADDLIB=-lz + +and building with the address sanitizer (ASAN) simply requires: + $ make TARGET=linux-glibc ARCH_FLAGS="-fsanitize=address -g" + + +5.4) Other common OS-specific options +------------------------------------- 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, @@ -625,16 +718,63 @@ 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 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. + -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. +5.5) Adjusting the build error / warning behavior +------------------------------------------------- +If the ERR variable is set to any non-empty value other than "0", 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. Similarly, for developers, another +variable, FAILFAST enables -Wfatal-errors when set to non-empty except 0, and +makes the compiler stop at the first error instead of scrolling pages. It's +essentially a matter of taste. + +Packagers who want to achieve the cleanest warning-free builds may be +interested in knowing that all enabled warnings are normally placed into +the WARN_CFLAGS variable. The variable contains a list of pre-established +warnings and a list of some that are dynamically detected on the compiler. +If the build environment or toolchain doesn't even support some of the basic +ones, it is then possible to just redefine them by passing the main ones in +WARN_CFLAGS (e.g. at the very least -W -Wall). Similarly, it may sometimes +be desirable not to disable certain warnings when porting to new platforms +or during code audits, or simply because the toolchain doesn't support some +of the most basic -Wno options. In this case, the list of automatic -Wno +variables is specified by variable NOWARN_CFLAGS, which is passed after +WARN_CFLAGS (i.e. it can undo some of the WARN_CFLAGS settings). Be careful +with it, as clearing this list can yield many warnings depending on the +compiler and options. +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. + +Examples: + # silence strict-aliasing warnings with old gcc-4.4: + $ make -j$(nproc) TARGET=linux-glibc CC=gcc-44 CFLAGS=-fno-strict-aliasing + + # disable all warning options: + $ make -j$(nproc) TARGET=linux-glibc CC=mycc WARN_CFLAGS= NOWARN_CFLAGS= + + # enable -Werror and -Wfatal-errors to immediately stop on error + $ make -j$(nproc) TARGET=linux-glibc ERR=1 FAILFAST=1 + + # try to restart the build where it was after hacking an include file, to + # check if that was sufficient or not: + $ make -j$(nproc) TARGET=linux-glibc ERR=1 DEP= + + +5.6) Enabling a DEBUG build +--------------------------- 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 @@ -645,8 +785,8 @@ these options should not be changed. Among the usable ones are: 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 + on. The option knows 3 values: 0 (disable all such assertions, not + recommended), 1 (enable all inexpensive assertions, the default), 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. @@ -678,7 +818,7 @@ these options should not be changed. Among the usable ones are: 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. + options and may be disabled with -DDEBUG_MEMORY_POOLS=0. - -DDEBUG_DONT_SHARE_POOLS: this will keep separate pools for same-sized objects of different types. Using this increases the memory usage a little @@ -698,58 +838,34 @@ these options should not be changed. Among the usable ones are: 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 +As such, "-DDEBUG_STRICT -DDEBUG_MEMORY_POOLS" is implicit and recommended for +production. For security sensitive environments, it is recommended to use +"-DDEBUG_STRICT_ACTION=2 -DDEBUG_DONT_SHARE_POOLS". When testing new versions +or trying to nail a bug down, use "-DDEBUG_STRICT=2 -DDEBUG_STRICT_ACTION=2 \ +-DDEBUG_DONT_SHARE_POOLS -DDEBUG_POOL_INTEGRITY". Finally in order to minimize +memory usage by disabling these integrity features, it is also possible to use +"-DDEBUG_STRICT=0 -DDEBUG_MEMORY_POOLS=0". + + +5.7) Summary of the Makefile's main variables +--------------------------------------------- + +The following variables are commonly used: + - TARGET platform name, empty by default, see help + - CC path to the C compiler, defaults to "cc" + - LD path to the linker, defaults to "$CC" + - CFLAGS CFLAGS to append at the end, empty by default + - LDFLAGS LDFLAGS to append at the end, empty by default + - ARCH_FLAGS flags common to CC and LD (-fsanitize, etc). Defaults to "-g" + - OPT_CFLAGS C compiler optimization level. Defaults to "-O2" + - WARN_CFLAGS list of autodetected C compiler warnings to enable + - NOWARN_CFLAGS list of autodetected C compiler warnings to disable + - ADDINC include directives to append at the end, empty by default + - ADDLIB lib directives to append at the end, empty by default + - DEFINE extra macros definitions for compiler, empty by default + - DEBUG extra DEBUG options for compiler, empty by default + - ERR enables -Werror if non-zero, empty by default + - FAILFAST enables -Wfatal-error if non-zero, empty by default 6) How to install HAProxy |