Willy Tarreau | b1a34b6 | 2010-05-09 22:37:12 +0200 | [diff] [blame] | 1 | ---------------------- |
| 2 | HAProxy how-to |
| 3 | ---------------------- |
Willy Tarreau | 068c344 | 2016-04-13 00:05:35 +0200 | [diff] [blame] | 4 | version 1.5 |
Willy Tarreau | b1a34b6 | 2010-05-09 22:37:12 +0200 | [diff] [blame] | 5 | willy tarreau |
Willy Tarreau | c5cca45 | 2016-05-10 15:43:41 +0200 | [diff] [blame^] | 6 | 2016/05/10 |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 7 | |
| 8 | |
Willy Tarreau | b1a34b6 | 2010-05-09 22:37:12 +0200 | [diff] [blame] | 9 | 1) How to build it |
| 10 | ------------------ |
| 11 | |
Willy Tarreau | 869f351 | 2014-06-19 15:26:32 +0200 | [diff] [blame] | 12 | First, please note that this version is a stable version, so in general if you |
| 13 | are not used to build from sources, it is recommended that instead you follow |
| 14 | the packaged updates provided by your software vendor or Linux distribution. |
| 15 | Most of them are taking this task seriously and are doing a good job. If for |
| 16 | any reason you'd prefer a different version than the one packaged for your |
| 17 | system, or to get some commercial support, other choices are available at : |
| 18 | |
| 19 | http://www.haproxy.com/ |
| 20 | |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 21 | To build haproxy, you will need : |
Willy Tarreau | b1a34b6 | 2010-05-09 22:37:12 +0200 | [diff] [blame] | 22 | - GNU make. Neither Solaris nor OpenBSD's make work with the GNU Makefile. |
Willy Tarreau | 3543cdb | 2014-05-10 09:12:46 +0200 | [diff] [blame] | 23 | If you get many syntax errors when running "make", you may want to retry |
| 24 | with "gmake" which is the name commonly used for GNU make on BSD systems. |
Willy Tarreau | 869f351 | 2014-06-19 15:26:32 +0200 | [diff] [blame] | 25 | - GCC between 2.95 and 4.8. Others may work, but not tested. |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 26 | - GNU ld |
| 27 | |
| 28 | Also, you might want to build with libpcre support, which will provide a very |
Willy Tarreau | b1a34b6 | 2010-05-09 22:37:12 +0200 | [diff] [blame] | 29 | efficient regex implementation and will also fix some badness on Solaris' one. |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 30 | |
| 31 | To build haproxy, you have to choose your target OS amongst the following ones |
| 32 | and assign it to the TARGET variable : |
| 33 | |
Willy Tarreau | 83b30c1 | 2008-05-25 10:32:50 +0200 | [diff] [blame] | 34 | - linux22 for Linux 2.2 |
| 35 | - linux24 for Linux 2.4 and above (default) |
| 36 | - linux24e for Linux 2.4 with support for a working epoll (> 0.21) |
Willy Tarreau | 83b30c1 | 2008-05-25 10:32:50 +0200 | [diff] [blame] | 37 | - linux26 for Linux 2.6 and above |
Willy Tarreau | 869f351 | 2014-06-19 15:26:32 +0200 | [diff] [blame] | 38 | - linux2628 for Linux 2.6.28, 3.x, and above (enables splice and tproxy) |
Willy Tarreau | 83b30c1 | 2008-05-25 10:32:50 +0200 | [diff] [blame] | 39 | - solaris for Solaris 8 or 10 (others untested) |
Willy Tarreau | 869f351 | 2014-06-19 15:26:32 +0200 | [diff] [blame] | 40 | - freebsd for FreeBSD 5 to 10 (others untested) |
Willy Tarreau | 8624cab | 2013-04-02 08:17:43 +0200 | [diff] [blame] | 41 | - osx for Mac OS/X |
Daniel Jakots | e4766ba | 2015-07-29 08:03:08 +0200 | [diff] [blame] | 42 | - openbsd for OpenBSD 3.1 and above |
Willy Tarreau | 50abe30 | 2014-04-02 20:44:43 +0200 | [diff] [blame] | 43 | - aix51 for AIX 5.1 |
Willy Tarreau | 7dec965 | 2012-06-06 16:15:03 +0200 | [diff] [blame] | 44 | - aix52 for AIX 5.2 |
Yitzhak Sapir | 3208731 | 2009-06-14 18:27:54 +0200 | [diff] [blame] | 45 | - cygwin for Cygwin |
Willy Tarreau | 869f351 | 2014-06-19 15:26:32 +0200 | [diff] [blame] | 46 | - generic for any other OS or version. |
Willy Tarreau | 83b30c1 | 2008-05-25 10:32:50 +0200 | [diff] [blame] | 47 | - custom to manually adjust every setting |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 48 | |
| 49 | You may also choose your CPU to benefit from some optimizations. This is |
| 50 | particularly important on UltraSparc machines. For this, you can assign |
| 51 | one of the following choices to the CPU variable : |
| 52 | |
| 53 | - i686 for intel PentiumPro, Pentium 2 and above, AMD Athlon |
| 54 | - i586 for intel Pentium, AMD K6, VIA C3. |
| 55 | - ultrasparc : Sun UltraSparc I/II/III/IV processor |
Willy Tarreau | 94fb38f | 2014-07-10 20:24:25 +0200 | [diff] [blame] | 56 | - native : use the build machine's specific processor optimizations. Use with |
| 57 | extreme care, and never in virtualized environments (known to break). |
| 58 | - generic : any other processor or no CPU-specific optimization. (default) |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 59 | |
Willy Tarreau | 83b30c1 | 2008-05-25 10:32:50 +0200 | [diff] [blame] | 60 | Alternatively, you may just set the CPU_CFLAGS value to the optimal GCC options |
| 61 | for your platform. |
| 62 | |
Willy Tarreau | ef7341d | 2009-04-11 19:45:50 +0200 | [diff] [blame] | 63 | You may want to build specific target binaries which do not match your native |
| 64 | compiler's target. This is particularly true on 64-bit systems when you want |
| 65 | to build a 32-bit binary. Use the ARCH variable for this purpose. Right now |
Willy Tarreau | a5899aa | 2010-11-28 07:41:00 +0100 | [diff] [blame] | 66 | it only knows about a few x86 variants (i386,i486,i586,i686,x86_64), two |
| 67 | generic ones (32,64) and sets -m32/-m64 as well as -march=<arch> accordingly. |
Willy Tarreau | ef7341d | 2009-04-11 19:45:50 +0200 | [diff] [blame] | 68 | |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 69 | If your system supports PCRE (Perl Compatible Regular Expressions), then you |
| 70 | really should build with libpcre which is between 2 and 10 times faster than |
| 71 | other libc implementations. Regex are used for header processing (deletion, |
| 72 | rewriting, allow, deny). The only inconvenient of libpcre is that it is not |
| 73 | yet widely spread, so if you build for other systems, you might get into |
| 74 | trouble if they don't have the dynamic library. In this situation, you should |
| 75 | statically link libpcre into haproxy so that it will not be necessary to |
Willy Tarreau | 83b30c1 | 2008-05-25 10:32:50 +0200 | [diff] [blame] | 76 | install it on target systems. Available build options for PCRE are : |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 77 | |
Willy Tarreau | 83b30c1 | 2008-05-25 10:32:50 +0200 | [diff] [blame] | 78 | - USE_PCRE=1 to use libpcre, in whatever form is available on your system |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 79 | (shared or static) |
| 80 | |
Willy Tarreau | 83b30c1 | 2008-05-25 10:32:50 +0200 | [diff] [blame] | 81 | - USE_STATIC_PCRE=1 to use a static version of libpcre even if the dynamic |
| 82 | one is available. This will enhance portability. |
| 83 | |
Willy Tarreau | 663148c | 2012-12-12 00:38:22 +0100 | [diff] [blame] | 84 | - with no option, use your OS libc's standard regex implementation (default). |
Willy Tarreau | 83b30c1 | 2008-05-25 10:32:50 +0200 | [diff] [blame] | 85 | Warning! group references on Solaris seem broken. Use static-pcre whenever |
| 86 | possible. |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 87 | |
Willy Tarreau | 64bc40b | 2011-03-23 20:00:53 +0100 | [diff] [blame] | 88 | Recent systems can resolve IPv6 host names using getaddrinfo(). This primitive |
| 89 | is not present in all libcs and does not work in all of them either. Support in |
| 90 | glibc was broken before 2.3. Some embedded libs may not properly work either, |
| 91 | thus, support is disabled by default, meaning that some host names which only |
| 92 | resolve as IPv6 addresses will not resolve and configs might emit an error |
| 93 | during parsing. If you know that your OS libc has reliable support for |
| 94 | getaddrinfo(), you can add USE_GETADDRINFO=1 on the make command line to enable |
| 95 | it. This is the recommended option for most Linux distro packagers since it's |
| 96 | working fine on all recent mainstream distros. It is automatically enabled on |
| 97 | Solaris 8 and above, as it's known to work. |
| 98 | |
Willy Tarreau | 3543cdb | 2014-05-10 09:12:46 +0200 | [diff] [blame] | 99 | It is possible to add native support for SSL using the GNU makefile, by passing |
| 100 | "USE_OPENSSL=1" on the make command line. The libssl and libcrypto will |
| 101 | automatically be linked with haproxy. Some systems also require libz, so if the |
| 102 | build fails due to missing symbols such as deflateInit(), then try again with |
| 103 | "ADDLIB=-lz". |
Willy Tarreau | d450881 | 2012-09-10 09:07:41 +0200 | [diff] [blame] | 104 | |
Lukas Tribus | 3fe9f1e | 2013-05-19 16:28:17 +0200 | [diff] [blame] | 105 | To link OpenSSL statically against haproxy, build OpenSSL with the no-shared |
| 106 | keyword and install it to a local directory, so your system is not affected : |
| 107 | |
| 108 | $ export STATICLIBSSL=/tmp/staticlibssl |
| 109 | $ ./config --prefix=$STATICLIBSSL no-shared |
| 110 | $ make && make install_sw |
| 111 | |
Lukas Tribus | 130ddf7 | 2013-10-01 00:28:03 +0200 | [diff] [blame] | 112 | When building haproxy, pass that path via SSL_INC and SSL_LIB to make and |
| 113 | include additional libs with ADDLIB if needed (in this case for example libdl): |
Willy Tarreau | 3543cdb | 2014-05-10 09:12:46 +0200 | [diff] [blame] | 114 | |
Lukas Tribus | 130ddf7 | 2013-10-01 00:28:03 +0200 | [diff] [blame] | 115 | $ make TARGET=linux26 USE_OPENSSL=1 SSL_INC=$STATICLIBSSL/include SSL_LIB=$STATICLIBSSL/lib ADDLIB=-ldl |
Lukas Tribus | 3fe9f1e | 2013-05-19 16:28:17 +0200 | [diff] [blame] | 116 | |
William Lallemand | 82fe75c | 2012-10-23 10:25:10 +0200 | [diff] [blame] | 117 | It is also possible to include native support for ZLIB to benefit from HTTP |
| 118 | compression. For this, pass "USE_ZLIB=1" on the "make" command line and ensure |
| 119 | that zlib is present on the system. |
| 120 | |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 121 | By default, the DEBUG variable is set to '-g' to enable debug symbols. It is |
| 122 | not wise to disable it on uncommon systems, because it's often the only way to |
| 123 | get a complete core when you need one. Otherwise, you can set DEBUG to '-s' to |
| 124 | strip the binary. |
| 125 | |
| 126 | For example, I use this to build for Solaris 8 : |
| 127 | |
Willy Tarreau | 83b30c1 | 2008-05-25 10:32:50 +0200 | [diff] [blame] | 128 | $ make TARGET=solaris CPU=ultrasparc USE_STATIC_PCRE=1 |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 129 | |
Willy Tarreau | 83b30c1 | 2008-05-25 10:32:50 +0200 | [diff] [blame] | 130 | And I build it this way on OpenBSD or FreeBSD : |
willy tarreau | d38e72d | 2006-03-19 20:56:52 +0100 | [diff] [blame] | 131 | |
Willy Tarreau | 3543cdb | 2014-05-10 09:12:46 +0200 | [diff] [blame] | 132 | $ gmake TARGET=freebsd USE_PCRE=1 USE_OPENSSL=1 USE_ZLIB=1 |
willy tarreau | d38e72d | 2006-03-19 20:56:52 +0100 | [diff] [blame] | 133 | |
Willy Tarreau | 663148c | 2012-12-12 00:38:22 +0100 | [diff] [blame] | 134 | And on a classic Linux with SSL and ZLIB support (eg: Red Hat 5.x) : |
| 135 | |
Willy Tarreau | 94fb38f | 2014-07-10 20:24:25 +0200 | [diff] [blame] | 136 | $ make TARGET=linux26 USE_PCRE=1 USE_OPENSSL=1 USE_ZLIB=1 |
Willy Tarreau | 663148c | 2012-12-12 00:38:22 +0100 | [diff] [blame] | 137 | |
| 138 | And on a recent Linux >= 2.6.28 with SSL and ZLIB support : |
Willy Tarreau | d450881 | 2012-09-10 09:07:41 +0200 | [diff] [blame] | 139 | |
Willy Tarreau | 94fb38f | 2014-07-10 20:24:25 +0200 | [diff] [blame] | 140 | $ make TARGET=linux2628 USE_PCRE=1 USE_OPENSSL=1 USE_ZLIB=1 |
Willy Tarreau | d450881 | 2012-09-10 09:07:41 +0200 | [diff] [blame] | 141 | |
William Lallemand | 82fe75c | 2012-10-23 10:25:10 +0200 | [diff] [blame] | 142 | In order to build a 32-bit binary on an x86_64 Linux system with SSL support |
| 143 | without support for compression but when OpenSSL requires ZLIB anyway : |
Willy Tarreau | ef7341d | 2009-04-11 19:45:50 +0200 | [diff] [blame] | 144 | |
Willy Tarreau | d450881 | 2012-09-10 09:07:41 +0200 | [diff] [blame] | 145 | $ make TARGET=linux26 ARCH=i386 USE_OPENSSL=1 ADDLIB=-lz |
Willy Tarreau | ef7341d | 2009-04-11 19:45:50 +0200 | [diff] [blame] | 146 | |
Willy Tarreau | b1efede | 2014-05-09 00:44:48 +0200 | [diff] [blame] | 147 | The SSL stack supports session cache synchronization between all running |
| 148 | processes. This involves some atomic operations and synchronization operations |
| 149 | which come in multiple flavors depending on the system and architecture : |
| 150 | |
| 151 | Atomic operations : |
| 152 | - internal assembler versions for x86/x86_64 architectures |
| 153 | |
| 154 | - gcc builtins for other architectures. Some architectures might not |
| 155 | be fully supported or might require a more recent version of gcc. |
| 156 | If your architecture is not supported, you willy have to either use |
| 157 | pthread if supported, or to disable the shared cache. |
| 158 | |
| 159 | - pthread (posix threads). Pthreads are very common but inter-process |
| 160 | support is not that common, and some older operating systems did not |
| 161 | report an error when enabling multi-process mode, so they used to |
| 162 | silently fail, possibly causing crashes. Linux's implementation is |
| 163 | fine. OpenBSD doesn't support them and doesn't build. FreeBSD 9 builds |
| 164 | and reports an error at runtime, while certain older versions might |
| 165 | silently fail. Pthreads are enabled using USE_PTHREAD_PSHARED=1. |
| 166 | |
| 167 | Synchronization operations : |
| 168 | - internal spinlock : this mode is OS-independant, light but will not |
| 169 | scale well to many processes. However, accesses to the session cache |
| 170 | are rare enough that this mode could certainly always be used. This |
| 171 | is the default mode. |
| 172 | |
| 173 | - Futexes, which are Linux-specific highly scalable light weight mutexes |
| 174 | implemented in user-space with some limited assistance from the kernel. |
| 175 | This is the default on Linux 2.6 and above and is enabled by passing |
| 176 | USE_FUTEX=1 |
| 177 | |
| 178 | - pthread (posix threads). See above. |
| 179 | |
| 180 | If none of these mechanisms is supported by your platform, you may need to |
| 181 | build with USE_PRIVATE_CACHE=1 to totally disable SSL cache sharing. Then |
| 182 | it is better not to run SSL on multiple processes. |
| 183 | |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 184 | If you need to pass other defines, includes, libraries, etc... then please |
| 185 | check the Makefile to see which ones will be available in your case, and |
Willy Tarreau | 3543cdb | 2014-05-10 09:12:46 +0200 | [diff] [blame] | 186 | use the USE_* variables in the Makefile. |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 187 | |
Willy Tarreau | 97ec969 | 2010-01-28 20:52:05 +0100 | [diff] [blame] | 188 | AIX 5.3 is known to work with the generic target. However, for the binary to |
| 189 | also run on 5.2 or earlier, you need to build with DEFINE="-D_MSGQSUPPORT", |
Willy Tarreau | 869f351 | 2014-06-19 15:26:32 +0200 | [diff] [blame] | 190 | otherwise __fd_select() will be used while not being present in the libc, but |
| 191 | this is easily addressed using the "aix52" target. If you get build errors |
| 192 | because of strange symbols or section mismatches, simply remove -g from |
| 193 | DEBUG_CFLAGS. |
Willy Tarreau | 97ec969 | 2010-01-28 20:52:05 +0100 | [diff] [blame] | 194 | |
Willy Tarreau | 32e65ef | 2013-04-02 08:14:29 +0200 | [diff] [blame] | 195 | You can easily define your own target with the GNU Makefile. Unknown targets |
| 196 | are processed with no default option except USE_POLL=default. So you can very |
| 197 | well use that property to define your own set of options. USE_POLL can even be |
| 198 | disabled by setting USE_POLL="". For example : |
| 199 | |
| 200 | $ gmake TARGET=tiny USE_POLL="" TARGET_CFLAGS=-fomit-frame-pointer |
| 201 | |
Willy Tarreau | b1a34b6 | 2010-05-09 22:37:12 +0200 | [diff] [blame] | 202 | |
| 203 | 2) How to install it |
| 204 | -------------------- |
| 205 | |
| 206 | To install haproxy, you can either copy the single resulting binary to the |
| 207 | place you want, or run : |
| 208 | |
| 209 | $ sudo make install |
| 210 | |
| 211 | If you're packaging it for another system, you can specify its root directory |
| 212 | in the usual DESTDIR variable. |
| 213 | |
| 214 | |
| 215 | 3) How to set it up |
| 216 | ------------------- |
| 217 | |
| 218 | There is some documentation in the doc/ directory : |
| 219 | |
| 220 | - architecture.txt : this is the architecture manual. It is quite old and |
| 221 | does not tell about the nice new features, but it's still a good starting |
| 222 | point when you know what you want but don't know how to do it. |
| 223 | |
| 224 | - configuration.txt : this is the configuration manual. It recalls a few |
| 225 | essential HTTP basic concepts, and details all the configuration file |
| 226 | syntax (keywords, units). It also describes the log and stats format. It |
| 227 | is normally always up to date. If you see that something is missing from |
Willy Tarreau | 74774c0 | 2014-04-23 00:57:08 +0200 | [diff] [blame] | 228 | it, please report it as this is a bug. Please note that this file is |
| 229 | huge and that it's generally more convenient to review Cyril Bonté's |
| 230 | HTML translation online here : |
| 231 | |
| 232 | http://cbonte.github.io/haproxy-dconv/configuration-1.5.html |
Willy Tarreau | b1a34b6 | 2010-05-09 22:37:12 +0200 | [diff] [blame] | 233 | |
| 234 | - haproxy-en.txt / haproxy-fr.txt : these are the old outdated docs. You |
| 235 | should never need them. If you do, then please report what you didn't |
| 236 | find in the other ones. |
| 237 | |
| 238 | - gpl.txt / lgpl.txt : the copy of the licenses covering the software. See |
| 239 | the 'LICENSE' file at the top for more information. |
| 240 | |
| 241 | - the rest is mainly for developers. |
| 242 | |
| 243 | There are also a number of nice configuration examples in the "examples" |
| 244 | directory as well as on several sites and articles on the net which are linked |
| 245 | to from the haproxy web site. |
| 246 | |
| 247 | |
| 248 | 4) How to report a bug |
| 249 | ---------------------- |
| 250 | |
| 251 | It is possible that from time to time you'll find a bug. A bug is a case where |
| 252 | what you see is not what is documented. Otherwise it can be a misdesign. If you |
| 253 | find that something is stupidly design, please discuss it on the list (see the |
| 254 | "how to contribute" section below). If you feel like you're proceeding right |
| 255 | and haproxy doesn't obey, then first ask yourself if it is possible that nobody |
| 256 | before you has even encountered this issue. If it's unlikely, the you probably |
| 257 | have an issue in your setup. Just in case of doubt, please consult the mailing |
| 258 | list archives : |
| 259 | |
Willy Tarreau | b1a34b6 | 2010-05-09 22:37:12 +0200 | [diff] [blame] | 260 | http://marc.info/?l=haproxy |
| 261 | |
| 262 | Otherwise, please try to gather the maximum amount of information to help |
| 263 | reproduce the issue and send that to the mailing list : |
| 264 | |
| 265 | haproxy@formilux.org |
| 266 | |
| 267 | Please include your configuration and logs. You can mask your IP addresses and |
| 268 | passwords, we don't need them. But it's essential that you post your config if |
| 269 | you want people to guess what is happening. |
| 270 | |
| 271 | Also, keep in mind that haproxy is designed to NEVER CRASH. If you see it die |
| 272 | without any reason, then it definitely is a critical bug that must be reported |
| 273 | and urgently fixed. It has happened a couple of times in the past, essentially |
| 274 | on development versions running on new architectures. If you think your setup |
| 275 | is fairly common, then it is possible that the issue is totally unrelated. |
| 276 | Anyway, if that happens, feel free to contact me directly, as I will give you |
| 277 | instructions on how to collect a usable core file, and will probably ask for |
| 278 | other captures that you'll not want to share with the list. |
| 279 | |
| 280 | |
| 281 | 5) How to contribute |
| 282 | -------------------- |
| 283 | |
Willy Tarreau | 5052928 | 2015-09-20 22:31:42 +0200 | [diff] [blame] | 284 | Please carefully read the CONTRIBUTING file that comes with the sources. It is |
| 285 | mandatory. |
Willy Tarreau | b1a34b6 | 2010-05-09 22:37:12 +0200 | [diff] [blame] | 286 | |
willy tarreau | 7834533 | 2005-12-18 01:33:16 +0100 | [diff] [blame] | 287 | -- end |