From 7f3327390f08ab73c73f8c4c33ca2143250b28dd Mon Sep 17 00:00:00 2001 From: Willy Tarreau Date: Sun, 16 Dec 2018 22:27:15 +0100 Subject: [PATCH] DOC: split the README into README + INSTALL The README was barely usable after all the additions having accumulated over the years. This patch introduces a new INSTALL file explaining how to build and install haproxy with various levels of details. The README is now mostly an index to the list of useful documentations. --- .gitignore | 1 + INSTALL | 535 +++++++++++++++++++++++++++++++++++++++++ README | 356 ++------------------------- scripts/create-release | 6 +- 4 files changed, 560 insertions(+), 338 deletions(-) create mode 100644 INSTALL diff --git a/.gitignore b/.gitignore index 32a8a84d24..8a38c4ffb6 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ !/LICENSE !/Makefile !/README +!/INSTALL !/CONTRIBUTING !/MAINTAINERS !/ROADMAP diff --git a/INSTALL b/INSTALL new file mode 100644 index 0000000000..8086d15485 --- /dev/null +++ b/INSTALL @@ -0,0 +1,535 @@ +Installation instructions for HAProxy +===================================== + +This is a development version, so it is expected to break from time to time, +to add and remove features without prior notification and it should not be used +in production. If you are not used to build from sources or if you are not used +to follow updates then it is recommended that instead you use the packages +provided by your software vendor or Linux distribution. Most of them are taking +this task seriously and are doing a good job at backporting important fixes. 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 4 TARGET=linux2628 USE_NS=1 USE_TFO=1 \ + USE_OPENSSL=1 USE_ZLIB=1 USE_LUA=1 USE_PCRE=1 USE_SYSTEMD=1 + $ sudo make install + + - FreeBSD and OpenBSD, build with all options : + $ gmake -j 4 TARGET=freebsd USE_OPENSSL=1 USE_ZLIB=1 USE_LUA=1 USE_PCRE=1 + + - embedded Linux, build using a cross-compiler : + $ make -j 4 TARGET=linux2628 USE_NS=1 USE_OPENSSL=1 USE_SLZ=1 USE_PCRE=1 \ + CC=/opt/cross/gcc730-arm/bin/gcc + + - Build with static PCRE on Solaris / UltraSPARC : + $ make TARGET=solaris CPU=ultrasparc USE_STATIC_PCRE=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 " where +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_". These booleans are enabled by "USE_=1" +and are disabled by "USE_=" (with no value). The last occurrence 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". + + +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 >= 3.4 (up to 8.1 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. + + - 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 10 and 40 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 targetted 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 be built to use dlmalloc instead. In this case, "USE_DLMALLOC=1" needs to +be appended to the build options, and "DLMALLOC_SRC" needs to point to the +absolute path to "dlmalloc.c". Doing this is not safe when using threads. +HAProxy 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 sur as +PCRE. HAProxy natively supports PCRE and PCRE2, 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 ant work with branches +0.9.8, 1.0.0, 1.0.1, 1.0.2, 1.1.0 and 1.1.1. 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. + +Two OpenSSL derivatives called LibreSSL and BoringSSL 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. + +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 + +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. + + +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 +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 command line. 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 + +However, zlib maintains an in-memory context for each compressed stream, which +is not always welcome when dealing with large sites. An alternative solution is +to use libslz instead, which doesn't consume memory, which is much faster, but +compresses slightly less efficiently. For this, please use "USE_SLZ=1", and +optionally make "SLZ_INC" and "SLZ_LIB" point to the library's include and +library paths, respectively. + +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. Libslz +can be downloaded http://libslz.org/ and is even easier to build. + + +4.7) Lua +-------- +Lua is an embedded programming langage 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.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.3.5 + $ 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.3.5/src LUA_LIB=/opt/lua-5.3.5/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. + + - 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. + + +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 : + + - linux22 for Linux 2.2 + - linux24 for Linux 2.4 and above (default) + - linux24e for Linux 2.4 with support for a working epoll (> 0.21) + - linux26 for Linux 2.6 and above + - linux2628 for Linux 2.6.28, 3.x, and above (enables splice and tproxy) + - solaris for Solaris 8 or 10 (others untested) + - freebsd for FreeBSD 5 to 12 (others untested) + - netbsd for NetBSD + - osx for Mac OS/X + - openbsd for OpenBSD 5.7 and above + - aix51 for AIX 5.1 + - aix52 for AIX 5.2 + - 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 + - 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 invovled. + +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= 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=linux2628 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 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 SSL stack supports session cache synchronization between all running +processes. This involves some atomic operations and synchronization operations +which come in multiple flavors depending on the system and architecture : + + Atomic operations : + - internal assembler versions for x86/x86_64 architectures + + - gcc builtins for other architectures. Some architectures might not + be fully supported or might require a more recent version of gcc. + If your architecture is not supported, you willy have to either use + pthread if supported, or to disable the shared cache. + + - pthread (posix threads). Pthreads are very common but inter-process + support is not that common, and some older operating systems did not + report an error when enabling multi-process mode, so they used to + silently fail, possibly causing crashes. Linux's implementation is + fine. OpenBSD doesn't support them and doesn't build. FreeBSD 9 builds + and reports an error at runtime, while certain older versions might + silently fail. Pthreads are enabled using USE_PTHREAD_PSHARED=1. + + Synchronization operations : + - internal spinlock : this mode is OS-independent, light but will not + scale well to many processes. However, accesses to the session cache + are rare enough that this mode could certainly always be used. This + is the default mode. + + - Futexes, which are Linux-specific highly scalable light weight mutexes + implemented in user-space with some limited assistance from the kernel. + This is the default on Linux 2.6 and above and is enabled by passing + USE_FUTEX=1 + + - pthread (posix threads). See above. + +If none of these mechanisms is supported by your platform, you may need to +build with USE_PRIVATE_CACHE=1 to totally disable SSL cache sharing. Then it +is better not to run SSL on multiple processes. Note that you don't need these +features if you only intend to use multi-threading and never multi-process. + +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. + +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 can even be +disabled by setting USE_POLL="". For example : + + $ gmake TARGET=tiny USE_POLL="" 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 specifify 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 diff --git a/README b/README index 81ca06b6cf..915e038282 100644 --- a/README +++ b/README @@ -1,335 +1,21 @@ - ---------------------- - HAProxy how-to - ---------------------- - version 1.9 - willy tarreau - 2018/12/08 - - -1) How to build it ------------------- - -This is a development version, so it is expected to break from time to time, -to add and remove features without prior notification and it should not be used -in production. If you are not used to build from sources or if you are not used -to follow updates then it is recommended that instead you use the packages provided -by your software vendor or Linux distribution. Most of them are taking this task -seriously and are doing a good job at backporting important fixes. If for any -reason you'd 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/ - -To build haproxy, you will need : - - GNU make. 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 between 2.95 and 8.1. Others may work, but not tested. - - GNU ld - -Also, you might want to build with libpcre support, which will provide a very -efficient regex implementation and will also fix some badness on Solaris' one. - -To build haproxy, you have to choose your target OS amongst the following ones -and assign it to the TARGET variable : - - - linux22 for Linux 2.2 - - linux24 for Linux 2.4 and above (default) - - linux24e for Linux 2.4 with support for a working epoll (> 0.21) - - linux26 for Linux 2.6 and above - - linux2628 for Linux 2.6.28, 3.x, and above (enables splice and tproxy) - - solaris for Solaris 8 or 10 (others untested) - - freebsd for FreeBSD 5 to 12 (others untested) - - netbsd for NetBSD - - osx for Mac OS/X - - openbsd for OpenBSD 5.7 and above - - aix51 for AIX 5.1 - - aix52 for AIX 5.2 - - 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 - - i586 for intel Pentium, AMD K6, VIA C3. - - ultrasparc : Sun UltraSparc I/II/III/IV processor - - 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. - -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. - -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= accordingly. - -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). The only inconvenient of libpcre is that it is not -yet widely spread, so if you build for other systems, you might get into -trouble if they don't have the dynamic library. In this situation, you should -statically link libpcre into haproxy so that it will not be necessary to -install it on target systems. Available build options for PCRE are : - - - USE_PCRE=1 to use libpcre, in whatever form is available on your system - (shared or static) - - - USE_STATIC_PCRE=1 to use a static version of libpcre even if the dynamic - one is available. This will enhance portability. - - - with no option, use your OS libc's standard regex implementation (default). - Warning! group references on Solaris seem broken. Use static-pcre whenever - possible. - -If your system doesn't provide PCRE, you are encouraged to download it from -http://www.pcre.org/ and build it yourself, it's fast and easy. - -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. - -It is possible to add native support for SSL using the GNU makefile, 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". - -Your are strongly encouraged to always use an up-to-date version of OpenSSL, as -found on https://www.openssl.org/ as vulnerabilities are occasionally found and -you don't want them on your systems. HAProxy is known to build correctly on all -currently supported branches (0.9.8, 1.0.0, 1.0.1, 1.0.2 and 1.1.0 at the time -of writing). Branch 1.0.2 is currently recommended for the best combination of -features and stability. Asynchronous engines require OpenSSL 1.1.0 though. It's -worth mentioning that some OpenSSL derivatives are also reported to work but -may occasionally break. Patches to fix them are welcome but please read the -CONTRIBUTING file first. - -To link OpenSSL statically against haproxy, build OpenSSL 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 - -When building haproxy, pass that path via SSL_INC and SSL_LIB to make and -include additional libs with ADDLIB if needed (in this case for example libdl): - - $ make TARGET=linux26 USE_OPENSSL=1 SSL_INC=$STATICLIBSSL/include SSL_LIB=$STATICLIBSSL/lib ADDLIB=-ldl - -It is also possible to include native support for zlib to benefit from HTTP -compression. For this, pass "USE_ZLIB=1" on the "make" command line and ensure -that zlib is present on the system. Alternatively it is possible to use libslz -for a faster, memory less, but slightly less efficient compression, by passing -"USE_SLZ=1". - -Zlib is commonly found on most systems, otherwise updates can be retrieved from -http://www.zlib.net/. It is easy and fast to build. Libslz can be downloaded -from http://1wt.eu/projects/libslz/ and is even easier to build. - -By default, the DEBUG 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 complete core when you need one. Otherwise, you can set DEBUG to '-s' to -strip the binary. - -For example, I use this to build for Solaris 8 : - - $ make TARGET=solaris CPU=ultrasparc USE_STATIC_PCRE=1 - -And I build it this way on OpenBSD or FreeBSD : - - $ gmake TARGET=freebsd USE_PCRE=1 USE_OPENSSL=1 USE_ZLIB=1 - -And on a classic Linux with SSL and ZLIB support (eg: Red Hat 5.x) : - - $ make TARGET=linux26 USE_PCRE=1 USE_OPENSSL=1 USE_ZLIB=1 - -And on a recent Linux >= 2.6.28 with SSL and ZLIB support : - - $ make TARGET=linux2628 USE_PCRE=1 USE_OPENSSL=1 USE_ZLIB=1 - -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=linux26 ARCH=i386 USE_OPENSSL=1 ADDLIB=-lz - -The SSL stack supports session cache synchronization between all running -processes. This involves some atomic operations and synchronization operations -which come in multiple flavors depending on the system and architecture : - - Atomic operations : - - internal assembler versions for x86/x86_64 architectures - - - gcc builtins for other architectures. Some architectures might not - be fully supported or might require a more recent version of gcc. - If your architecture is not supported, you willy have to either use - pthread if supported, or to disable the shared cache. - - - pthread (posix threads). Pthreads are very common but inter-process - support is not that common, and some older operating systems did not - report an error when enabling multi-process mode, so they used to - silently fail, possibly causing crashes. Linux's implementation is - fine. OpenBSD doesn't support them and doesn't build. FreeBSD 9 builds - and reports an error at runtime, while certain older versions might - silently fail. Pthreads are enabled using USE_PTHREAD_PSHARED=1. - - Synchronization operations : - - internal spinlock : this mode is OS-independent, light but will not - scale well to many processes. However, accesses to the session cache - are rare enough that this mode could certainly always be used. This - is the default mode. - - - Futexes, which are Linux-specific highly scalable light weight mutexes - implemented in user-space with some limited assistance from the kernel. - This is the default on Linux 2.6 and above and is enabled by passing - USE_FUTEX=1 - - - pthread (posix threads). See above. - -If none of these mechanisms is supported by your platform, you may need to -build with USE_PRIVATE_CACHE=1 to totally disable SSL cache sharing. Then -it is better not to run SSL on multiple processes. - -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 the USE_* variables in 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. - -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 can even be -disabled by setting USE_POLL="". For example : - - $ gmake TARGET=tiny USE_POLL="" TARGET_CFLAGS=-fomit-frame-pointer - - -1.1) 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 - - -2) How to install it --------------------- - -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. - - -3) How to set it up -------------------- - -There is some documentation in the doc/ directory : - - - intro.txt : this is an introduction to haproxy, it explains what it is - what it is not. Useful for beginners or to re-discover it when planning - for an upgrade. - - - architecture.txt : this is the architecture manual. It is quite old and - does not tell about the nice new features, but it's still a good starting - point when you know what you want but don't know how to do it. - - - configuration.txt : this is the configuration manual. It recalls a few - essential HTTP basic concepts, and details all the configuration file - syntax (keywords, units). It also describes the log and stats format. It - is normally always up to date. If you see that something is missing from - it, please report it as this is a bug. Please note that this file is - huge and that it's generally more convenient to review Cyril Bonté's - HTML translation online here : - - http://cbonte.github.io/haproxy-dconv/configuration-1.6.html - - - management.txt : it explains how to start haproxy, how to manage it at - runtime, how to manage it on multiple nodes, how to proceed with seamless - upgrades. - - - gpl.txt / lgpl.txt : the copy of the licenses covering the software. See - the 'LICENSE' file at the top for more information. - - - the rest is mainly for developers. - -There are also a number of nice configuration examples in the "examples" -directory as well as on several sites and articles on the net which are linked -to from the haproxy web site. - - -4) How to report a bug ----------------------- - -It is possible that from time to time you'll find a bug. A bug is a case where -what you see is not what is documented. Otherwise it can be a misdesign. If you -find that something is stupidly design, please discuss it on the list (see the -"how to contribute" section below). If you feel like you're proceeding right -and haproxy doesn't obey, then first ask yourself if it is possible that nobody -before you has even encountered this issue. If it's unlikely, the you probably -have an issue in your setup. Just in case of doubt, please consult the mailing -list archives : - - http://marc.info/?l=haproxy - -Otherwise, please try to gather the maximum amount of information to help -reproduce the issue and send that to the mailing list : - - haproxy@formilux.org - -Please include your configuration and logs. You can mask your IP addresses and -passwords, we don't need them. But it's essential that you post your config if -you want people to guess what is happening. - -Also, keep in mind that haproxy is designed to NEVER CRASH. If you see it die -without any reason, then it definitely is a critical bug that must be reported -and urgently fixed. It has happened a couple of times in the past, essentially -on development versions running on new architectures. If you think your setup -is fairly common, then it is possible that the issue is totally unrelated. -Anyway, if that happens, feel free to contact me directly, as I will give you -instructions on how to collect a usable core file, and will probably ask for -other captures that you'll not want to share with the list. - - -5) How to contribute --------------------- - -Please carefully read the CONTRIBUTING file that comes with the sources. It is -mandatory. - --- end +The HAProxy documentation has been split into a number of different files for +ease of use. + +Please refer to the following files depending on what you're looking for : + + - INSTALL for instructions on how to build and install HAProxy + - LICENSE for the project's license + - CONTRIBUTING for the process to follow to submit contributions + +The more detailed documentation is located into the doc/ directory : + + - doc/intro.txt for a quick introduction on HAProxy + - doc/configuration.txt for the configuration's reference manual + - doc/lua.txt for the Lua's reference manual + - doc/SPOE.txt for how to use the SPOE engine + - doc/network-namespaces.txt for how to use network namespaces under Linux + - doc/management.txt for the management guide + - doc/regression-testing.txt for how to use the regression testing suite + - doc/peers.txt for the peers protocol reference + - doc/coding-style.txt for how to adopt HAProxy's coding style + - doc/internals for developer-specific documentation (not all up to date) diff --git a/scripts/create-release b/scripts/create-release index afd6e56d61..68781b2c23 100755 --- a/scripts/create-release +++ b/scripts/create-release @@ -188,8 +188,8 @@ sed -e "s/^Version: .*/Version: $NEW/" < examples/haproxy.spec >examples/haproxy sed -ne '0,/^%changelog/d;p' < examples/haproxy.spec >>examples/haproxy.spec- mv examples/haproxy.spec- examples/haproxy.spec -# updating branch and date in README and all modified doc files except the outdated architecture.txt -for file in README doc/intro.txt doc/configuration.txt doc/management.txt $(git diff --name-only v${OLD}.. -- doc); do +# updating branch and date in all modified doc files except the outdated architecture.txt +for file in doc/intro.txt doc/configuration.txt doc/management.txt $(git diff --name-only v${OLD}.. -- doc); do if [ ! -e "$file" ]; then continue; fi if [ "$file" = doc/architecture.txt ]; then continue; fi echo "Updating $file ..." @@ -208,7 +208,7 @@ sed -e "s:^\(#define\s*PRODUCT_BRANCH\s*\)\"[^\"]*\":\1\"$BRANCH\":" \ if [ -n "$INTERACTIVE" ]; then vi CHANGELOG VERSION VERDATE examples/haproxy*.spec \ - src/haproxy.c README doc/configuration.txt \ + src/haproxy.c doc/configuration.txt \ $(git diff --name-only v${OLD}.. -- doc) fi