HAPROXY(1)

💖 HAPROXY(1) — General Commands Manual 💖

okay bestie, sit down, we're doing the HAProxy manual page and honestly? it's giving legendary. this lives in the General Commands Manual section of your system, and it's the whole vibe of the tool. no cap.

✨ NAME ✨

HAProxy — fast and reliable http reverse proxy and load balancer 🦋

like. that's it. that's the whole name section. iconic, brief, slay.

🌸 SYNOPSIS 🌸

haproxy -f <configuration file|dir> [-L <name>] [-n maxconn]
[-N maxconn] [-C <dir>] [-v|-vv] [-d] [-D] [-W] [-Ws] [-q] [-V] [-c]
[-p <pidfile>] [-dk] [-ds] [-de] [-dp] [-db] [-dM[<byte>]] [-m <megs>]
[-x <unix_socket>] [{-sf|-st} pidlist...]

lowkey the whole energy is "give me a config file and I will handle literally everything else for you" 💅

👑 DESCRIPTION 👑

HAProxy is a TCP/HTTP reverse proxy and it's particularly suited for high availability environments. like, this is its whole personality. and it can, fr fr:

• route HTTP requests depending on statically assigned cookies ;
• spread the load among several servers while assuring server persistence through the use of HTTP cookies ;
• switch to backup servers in the event a main one fails ;
• accept connections to special ports dedicated to service monitoring ;
• stop accepting connections without breaking existing ones ;
• add/modify/delete HTTP headers both ways ;
• block requests matching a particular pattern ;
• hold clients to the right application server depending on application cookies
• report detailed status as HTML pages to authenticated users from an URI intercepted from the application.

and the way that it needs very little resource?? obsessed. its event-driven architecture lets it easily handle thousands of simultaneous connections across hundreds of instances without ever risking the system's stability. main character energy, honestly. 🫶

💅 OPTIONS 💅

bestie this is the part you actually came for. every single one, no skipping, we don't do that here ✨

• -f <configuration file|dir> — give it a config file or a directory path. if you hand it a directory, all the files it contains get added in lexical order (using LC_COLLATE=C), and here's the catch: only files (not dirs), only non hidden files, and only ones with the .cfg extension. gatekeeping the whole folder, as it should 💅
• -L <name> — set the local instance's peer name. peers are defined over in the peers configuration section and they're used for syncing stick tables between different instances. if you don't pass this, the local hostname becomes the peer name. this name gets exported in the $HAPROXY_LOCALPEER environment variable so you can use it in the config file. cute, right?
• -n <maxconn> — sets the high limit for the total number of simultaneous connections. that's the whole ceiling, bestie.
• -N <maxconn> — same energy but per-listener: the high limit for the per-listener number of simultaneous connections.
• -C <dir> — change directory to <dir> before loading any files. simple as.
• -v — display HAProxy's version. that's it. quick lil flex.
• -vv — display HAProxy's version and all build options. the full tea ☕
• -d — start in foreground with debugging mode enabled. when the proxy runs in this mode it dumps every connection, disconnection, timestamp, and HTTP header to stdout. and listen — this should NEVER be used in an init script because it will prevent the system from starting up. I said what I said. 💀
• -D — start in daemon mode.
• -W — start in master-worker mode. you can use it with either foreground or daemon mode, flexible queen.
• -Ws — start in master-worker mode with systemd notify support. it tells systemd when the process is ready. this mode forces foreground.
• -q — disable messages on output. shhh. 🤫
• -V — displays messages on output even when -q or 'quiet' are specified. some info about pollers and the config file gets shown during startup.
• -c — only checks the config file and exits with code 0 if no error was found, or exits with code 1 if a syntax error was found. vibe check for your config 💅
• -p <pidfile> — ask the process to write down each of its children's pids to this file in daemon mode, or ask the process to write down its master's pid to this file in master-worker mode.
• -dk — disable use of kqueue(2). kqueue(2) is available only on BSD systems.
• -dv — disable use of event ports. event ports are available only on SunOS systems derived from Solaris 10 and later (including illumos systems).
• -ds — disable use of speculative epoll(7). epoll(7) is available only on Linux 2.6 and some custom Linux 2.4 systems.
• -de — disable use of epoll(7). epoll(7) is available only on Linux 2.6 and some custom Linux 2.4 systems.
• -dp — disables use of poll(2). select(2) might be used instead.
• -dS — disables use of splice(2), which is broken on older kernels. noted, moving on.
• -db — disables background mode (stays in foreground, useful for debugging). for debugging, the '-db' option is very useful as it temporarily disables daemon mode and multi-process mode. the service can then be stopped by simply pressing Ctrl-C, without having to edit the config nor run full debug. so convenient, honestly.
• -dM[<byte>] — initializes all allocated memory areas with the given <byte>. this makes it easier to detect bugs resulting from uninitialized memory accesses, at the expense of touching all allocated memory once. if <byte> is not specified, it defaults to 0x50 (ASCII 'P'). cute default ngl.
• -m <megs> — enforce a memory usage limit to a maximum of <megs> megabytes. boundaries, we love to see them 🎀
• -sf <pidlist> — send FINISH signal to the pids in pidlist after startup. the processes which receive this signal will wait for all sessions to finish before exiting. this option must be specified last, followed by any number of PIDs. technically speaking, SIGTTOU and SIGUSR1 are sent.
• -st <pidlist> — send TERMINATE signal to the pids in pidlist after startup. the processes which receive this signal will terminate immediately, closing all active sessions. this option must be specified last, followed by any number of PIDs. technically speaking, SIGTTOU and SIGTERM are sent. no soft landing here 😭
• -x <unix_socket> — attempt to connect to the unix socket, and retrieve all the listening sockets from the old process. those sockets will then be used if possible instead of binding new ones.
• -S <bind>[,<bind options>...] — in master-worker mode, create a master CLI. this CLI enables access to the CLI of every worker. useful for debugging, it's a convenient way of accessing a leaving process.

🌈 LOGGING 🌈

so since HAProxy can run inside a chroot, it cannot reliably access /dev/log. for this reason it uses the UDP protocol to send its logs to the server, even if it's the local server. if you're experiencing trouble receiving logs, make sure your syslog daemon is actually listening on the UDP socket bestie. several Linux distributions that ship with syslogd from the sysklogd package have UDP disabled by default, and the -r option must be passed to the daemon in order to enable UDP.

🦋 SIGNALS 🦋

some signals have a special meaning for the haproxy daemon. generally they're used between daemons and you as the administrator don't need to touch them, iykyk.

• SIGUSR1 — tells the daemon to stop all proxies and exit once all sessions are closed. often referred to as the "soft-stop" signal. gentle queen 🌸
• SIGUSR2 — in master-worker mode, reloads the configuration and sends a soft-stop signal to old processes.
• SIGTTOU — tells the daemon to stop listening to all sockets. used internally by -sf and -st.
• SIGTTIN — tells the daemon to restart listening to all sockets after a SIGTTOU. used internally when there was a problem during hot reconfiguration.
• SIGINT and SIGTERM — both signals can be used to quickly stop the daemon. no ceremony 💀
• SIGHUP — dumps the status of all proxies and servers into the logs. mostly used for trouble-shooting purposes.
• SIGQUIT — dumps information about memory pools on stderr. mostly used for debugging purposes.
• SIGPIPE — this signal is intercepted and ignored on systems without MSG_NOSIGNAL. built different, fr.

👀 SEE ALSO 👀

a much better documentation can be found in configuration.txt. on Debian systems, you can find this file in /usr/share/doc/haproxy/configuration.txt.gz. go read it bestie, it's the real tea ✨

🎀 AUTHOR 🎀

HAProxy was written by Willy Tarreau. this man page was written by Arnaud Cornet and Willy Tarreau. legends only, honestly 👑

and that's the whole page, pookie 🫶 this version of the page comes from the HAPROXY(1) manual as of 17 August 2007. old but absolutely still iconic. periodt. 💖✨