mirror of
http://git.haproxy.org/git/haproxy.git/
synced 2024-12-14 23:44:41 +00:00
494 lines
22 KiB
Plaintext
494 lines
22 KiB
Plaintext
----------------------
|
||
HAProxy how-to
|
||
----------------------
|
||
version 1.7
|
||
willy tarreau
|
||
2015/10/13
|
||
|
||
|
||
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 4.8. 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 10 (others untested)
|
||
- netbsd for NetBSD
|
||
- osx for Mac OS/X
|
||
- openbsd for OpenBSD 3.1 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.
|
||
|
||
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.
|
||
|
||
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 and 1.0.2 at the time of
|
||
writing). Branch 1.0.2 is recommended for the richest features.
|
||
|
||
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-independant, 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) DeviceAtlas Device Detection
|
||
---------------------------------
|
||
|
||
In order to add DeviceAtlas Device Detection support, you would need to download
|
||
the API source code from https://deviceatlas.com/deviceatlas-haproxy-module and
|
||
once extracted :
|
||
|
||
$ make TARGET=<target> USE_PCRE=1 USE_DEVICEATLAS=1 DEVICEATLAS_SRC=<path to the API root folder>
|
||
|
||
Optionally DEVICEATLAS_INC and DEVICEATLAS_LIB may be set to override the path
|
||
to the include files and libraries respectively if they're not in the source
|
||
directory.
|
||
|
||
These are supported DeviceAtlas directives (see doc/configuration.txt) :
|
||
- deviceatlas-json-file <path to the DeviceAtlas JSON data file>.
|
||
- deviceatlas-log-level <number> (0 to 3, level of information returned by
|
||
the API, 0 by default).
|
||
- deviceatlas-property-separator <character> (character used to separate the
|
||
properties produced by the API, | by default).
|
||
|
||
Sample configuration :
|
||
|
||
global
|
||
deviceatlas-json-file <path to json file>
|
||
|
||
...
|
||
frontend
|
||
bind *:8881
|
||
default_backend servers
|
||
|
||
There are two distinct methods available, one which leverages all HTTP headers
|
||
and one which uses only a single HTTP header for the detection. The former
|
||
method is highly recommended and more accurate. There are several possible use
|
||
cases.
|
||
|
||
# To transmit the DeviceAtlas data downstream to the target application
|
||
|
||
All HTTP headers via the sample / fetch
|
||
|
||
http-request set-header X-DeviceAtlas-Data %[da-csv-fetch(primaryHardwareType,osName,osVersion,browserName,browserVersion)]
|
||
|
||
Single HTTP header (e.g. User-Agent) via the convertor
|
||
|
||
http-request set-header X-DeviceAtlas-Data %[req.fhdr(User-Agent),da-csv-conv(primaryHardwareType,osName,osVersion,browserName,browserVersion)]
|
||
|
||
# Mobile content switching with ACL
|
||
|
||
All HTTP headers
|
||
|
||
acl is_mobile da-csv-fetch(mobileDevice) 1
|
||
|
||
Single HTTP header
|
||
|
||
acl device_type_tablet req.fhdr(User-Agent),da-csv-conv(primaryHardwareType) "Tablet"
|
||
|
||
|
||
Please find more information about DeviceAtlas and the detection methods at https://deviceatlas.com/resources .
|
||
|
||
|
||
1.2) 51Degrees Device Detection
|
||
-------------------------------
|
||
|
||
You can also include 51Degrees for inbuilt device detection enabling attributes
|
||
such as screen size (physical & pixels), supported input methods, release date,
|
||
hardware vendor and model, browser information, and device price among many
|
||
others. Such information can be used to improve the user experience of a web
|
||
site by tailoring the page content, layout and business processes to the
|
||
precise characteristics of the device. Such customisations improve profit by
|
||
making it easier for customers to get to the information or services they
|
||
need. Attributes of the device making a web request can be added to HTTP
|
||
headers as configurable parameters.
|
||
|
||
In order to enable 51Degrees download the 51Degrees source code from the
|
||
official github repository :
|
||
|
||
git clone https://github.com/51Degrees/Device-Detection
|
||
|
||
then run 'make' with USE_51DEGREES and 51DEGREES_SRC set. Both 51DEGREES_INC
|
||
and 51DEGREES_LIB may additionally be used to force specific different paths
|
||
for .o and .h, but will default to 51DEGREES_SRC. Make sure to replace
|
||
'51D_REPO_PATH' with the path to the 51Degrees repository.
|
||
|
||
51Degrees provide 2 different detection algorithms:
|
||
|
||
1. Pattern - balances main memory usage and CPU.
|
||
2. Trie - a very high performance detection solution which uses more main
|
||
memory than Pattern.
|
||
|
||
To make with 51Degrees Pattern algorithm use the following command line.
|
||
|
||
$ make TARGET=linux26 USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/pattern
|
||
|
||
To use the 51Degrees Trie algorithm use the following command line.
|
||
|
||
$ make TARGET=linux26 USE_51DEGREES=1 51DEGREES_SRC='51D_REPO_PATH'/src/trie
|
||
|
||
A data file containing information about devices, browsers, operating systems
|
||
and their associated signatures is then needed. 51Degrees provide a free
|
||
database with Github repo for this purpose. These free data files are located
|
||
in '51D_REPO_PATH'/data with the extensions .dat for Pattern data and .trie for
|
||
Trie data.
|
||
|
||
The configuration file needs to set the following parameters:
|
||
|
||
51degrees-data-file path to the Pattern or Trie data file
|
||
51degrees-property-name-list list of 51Degrees properties to detect
|
||
51degrees-property-separator separator to use between values
|
||
51degrees-cache-size LRU-based cache size (disabled by default)
|
||
|
||
The following is an example of the settings for Pattern.
|
||
|
||
51degrees-data-file '51D_REPO_PATH'/data/51Degrees-LiteV3.2.dat
|
||
51degrees-property-name-list IsTablet DeviceType IsMobile
|
||
51degrees-property-separator ,
|
||
51degrees-cache-size 10000
|
||
|
||
HAProxy needs a way to pass device information to the backend servers. This is
|
||
done by using the 51d converter or fetch method, which intercepts the HTTP
|
||
headers and creates some new headers. This is controlled in the frontend
|
||
http-in section.
|
||
|
||
The following is an example which adds two new HTTP headers prefixed X-51D-
|
||
|
||
frontend http-in
|
||
bind *:8081
|
||
default_backend servers
|
||
http-request set-header X-51D-DeviceTypeMobileTablet %[51d.all(DeviceType,IsMobile,IsTablet)]
|
||
http-request set-header X-51D-Tablet %[51d.all(IsTablet)]
|
||
|
||
Here, two headers are created with 51Degrees data, X-51D-DeviceTypeMobileTablet
|
||
and X-51D-Tablet. Any number of headers can be created this way and can be
|
||
named anything. 51d.all( ) invokes the 51degrees fetch. It can be passed up to
|
||
five property names of values to return. Values will be returned in the same
|
||
order, seperated by the 51-degrees-property-separator configured earlier. If a
|
||
property name can't be found the value 'NoData' is returned instead.
|
||
|
||
In addition to the device properties three additional properties related to the
|
||
validity of the result can be returned when used with the Pattern method. The
|
||
following example shows how Method, Difference and Rank could be included as one
|
||
new HTTP header X-51D-Stats.
|
||
|
||
http-request set-header X-51D-Stats %[51d.all(Method,Difference,Rank)]
|
||
|
||
These values indicate how confident 51Degrees is in the result that that was
|
||
returned. More information is available on the 51Degrees web site at:
|
||
|
||
https://51degrees.com/support/documentation/pattern
|
||
|
||
The above 51d.all fetch method uses all available HTTP headers for detection. A
|
||
modest performance improvement can be obtained by only passing one HTTP header
|
||
to the detection method with the 51d.single converter. The following example
|
||
uses the User-Agent HTTP header only for detection.
|
||
|
||
http-request set-header X-51D-DeviceTypeMobileTablet %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)]
|
||
|
||
Any HTTP header could be used inplace of User-Agent by changing the parameter
|
||
provided to req.fhdr.
|
||
|
||
When compiled to use the Trie detection method the trie format data file needs
|
||
to be provided. Changing the extension of the data file from dat to trie will
|
||
use the correct data.
|
||
|
||
51degrees-data-file '51D_REPO_PATH'/data/51Degrees-LiteV3.2.trie
|
||
|
||
When used with Trie the Method, Difference and Rank properties are not
|
||
available.
|
||
|
||
The free Lite data file contains information about screen size in pixels and
|
||
whether the device is a mobile. A full list of available properties is located
|
||
on the 51Degrees web site at:
|
||
|
||
https://51degrees.com/resources/property-dictionary
|
||
|
||
Some properties are only available in the paid for Premium and Enterprise
|
||
versions of 51Degrees. These data sets not only contain more properties but
|
||
are updated weekly and daily and contain signatures for 100,000s of different
|
||
device combinations. For more information see the data options comparison web
|
||
page:
|
||
|
||
https://51degrees.com/compare-data-options
|
||
|
||
|
||
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<6E>'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
|