Starting and loading the configuration 10
| Command | What it does |
|---|---|
-f <CFGFILE|CFGDIR> | Load a configuration fileA directory adds only its non-hidden .cfg files, in lexical order; repeat -f once per file or directory. |
-- <CFGFILE> ... | Load every file that followsOne -- covers a whole shell-expanded list; each file has to begin with a section keyword such as global or backend. |
-C <DIR> | Change directory before loadingHandy with relative paths; wildcards after -- are expanded by the shell before the change takes place. |
-D | Daemon modeDetaches after forking, so later errors no longer reach the terminal; the guide advises forcing it in init scripts. |
-W | Master-worker modeA master process monitors the workers and reloads them on SIGUSR2; works in foreground or daemon mode. |
-Ws | Master-worker for systemdUse this variant instead of -W when the systemd unit declares the notify service type. |
-p <FILE> | Write a PID fileEquivalent to the global pidfile keyword; every process ID is written on a separate line. |
-L <NAME> | Set the local peer nameOnly used by peers replication; it defaults to the hostname and is readable as $HAPROXY_LOCALPEER. |
haproxy -f /etc/haproxy.cfg -D -p /var/run/haproxy.pid -sf $(cat /var/run/haproxy.pid) | Start from an init scriptRuns as a daemon, records the new PIDs and tells the processes in the old PID file to finish and leave. |
haproxy -Ws -f $CONFIG -f $CFGDIR -p $PIDFILE $EXTRAOPTS | Systemd unit start lineDefaults: CONFIG is /etc/haproxy/haproxy.cfg, CFGDIR is /etc/haproxy/conf.d, EXTRAOPTS adds a master CLI socket. |
Checking the configuration and version 11
| Command | What it does |
|---|---|
haproxy | Print the help pageStarting the binary with no option shows a reminder of the options, which vary a little by operating system. |
haproxy -f configuration.conf -c | Validate configThe form the manual prints; reload scripts run the same check before starting a new process. |
-c | Check modeExit status 0 means valid; warnings are printed, but a success message only appears when -V is added. |
-V | Verbose modeCancels -q or the quiet keyword; together with -c it confirms a valid file in words. |
-q | Quiet modeWith -c nothing is printed, so only the exit status tells whether the files are valid. |
-dW | Refuse to start on warningsZero-warning mode; combined with -c, a configuration that only produces warnings fails the check too. |
-dD | Diagnostic modeAdds warnings about suspicious statements but never blocks startup or alters the exit code. |
-dr | Ignore address resolution failuresLets a configuration be tested away from production, where its server names may not resolve. |
-dC | Dump the parsed configurationPrinted after tokenizing, so comments are gone; a non-zero key truncates and hashes sensitive fields. |
haproxy -v | Show versionTells which build is running; a development version shows dev after the branch number. |
haproxy -vv | Show build options and librariesAlso lists the target system and library versions; bug reports always ask for this output. |
Reloading, stopping and signals 10
SIGTTOU and SIGTTIN are not sent by hand: a starting process sends them to the PIDs given with -sf or -st when a port it needs is still taken.
| Command | What it does |
|---|---|
-sf <PID> ... | Finish old processes gracefullyOnce started, the new process sends SIGUSR1 to the listed PIDs; an empty list, for example from pidof, is fine. |
-st <PID> ... | Terminate old processesThe listed PIDs get SIGTERM after startup and stop at once, abandoning the work in progress. |
-x <UNIX_SOCKET> | Take over listening socketsNeeds expose-fd listeners on the stats socket, except in master-worker mode where the master handles it. |
SIGTERM | Hard stopThe process exits at once and closes every established connection; service stop and restart actions use it. |
SIGUSR1 | Graceful stopListening ports are released while open connections are served; the process exits after the last one ends. |
SIGUSR2 | Reload the master processIn master-worker mode the master re-executes itself with -sf and the worker PIDs, then forks new workers. |
SIGTTOU | Pause old listenersSent by a new process that cannot bind: the old ones stop listening but keep their current connections. |
SIGTTIN | Resume old listenersSent when binding still fails, so the old processes listen again as if nothing had happened. |
haproxy -Ws -f $CONFIG -f $CFGDIR -c $EXTRAOPTS | Systemd unit reload checkFirst ExecReload step of the unit: the files are checked before the master is signalled. |
/bin/kill -USR2 $MAINPID | Systemd unit reload signalSecond ExecReload step: SIGUSR2 to the master, which then starts workers with the new configuration. |
Limits and debugging 7
| Command | What it does |
|---|---|
-d | Debug modeStays in the foreground and prints incoming and outgoing events; not for init scripts. |
-db | Stay in the foregroundCtrl-C then stops the process; meant for development and quick tests, never for init scripts. |
-m <LIMIT> | Cap memory in megabytesReaching the cap can refuse connections or slow things down; each forked process gets its own limit. |
-n <LIMIT> | Set the process maxconnTakes precedence over the global maxconn keyword, a quick way to force a lower limit. |
-N <LIMIT> | Set the default proxy maxconnReplaces the built-in default, usually 2000; the guide calls it a debugging aid. |
SIGQUIT | Flush memory poolsReleases unused pooled objects, as the process does by itself when a memory allocation fails. |
show pools | Show memory pool usageLike SIGQUIT in the foreground but without flushing; byusage sorts by total use and hides empty pools. |
Connecting to the runtime API 13
The stats socket is off by default. One stats socket line in the global section turns it on; the guide's example also sets level admin, which commands that change state require.
| Command | What it does |
|---|---|
socat /var/run/haproxy.sock stdio | Connect for scriptsJoins stdin and stdout to the stats socket, so a script can send commands and read the replies. |
socat /var/run/haproxy.sock readline | Connect interactivelyReadline adds line editing and history, handy when repeating commands by hand. |
echo "show version" | socat /var/run/haproxy.sock stdio | Send one command from the shellThe usual one-shot form: the connection closes as soon as the answer has been printed. |
echo "show info;show stat;show table" | socat /var/run/haproxy stdio | Send several commands at onceSeparate commands with semicolons; a semicolon or backslash inside a value needs a backslash before it. |
prompt | Switch to prompt modeSend it first on a new connection, otherwise the default single-command mode closes after the next line. |
prompt timed | Show uptime in the promptThe prompt then starts with the process uptime as d:hh:mm:ss. |
help [<COMMAND>] | List runtime commandsWith a command name only matching entries are printed; an unknown command shows the same screen. |
quit | Close the sessionNeeded in interactive mode only; in the default mode the connection ends after each reply. |
set timeout cli <DELAY> | Extend the CLI timeoutValue in seconds, for this connection only; useful in long debugging sessions. |
show cli level | Show the session levelThe answer is admin, operator or user; the operator and user commands lower it. |
operator | Drop to operator levelA session level can only be lowered; expert and experimental modes are switched off as well. |
user | Drop to user levelSame rule as operator: the level stays lowered for the rest of the connection. |
show cli sockets | List CLI socketsEach line gives the socket address, its level and the processes it is bound to. |
Process information 9
| Command | What it does |
|---|---|
show info | Show infoProcess-wide fields as name: value pairs; typed or json give machine-readable output. |
echo "show info json" | socat /var/run/haproxy.sock stdio | python -m json.tool | Pretty-print info as JSONThe JSON form carries no extra whitespace, so it is piped through a pretty printer for reading. |
echo "show info" | socat - /var/run/haproxy.sock | grep ^Idle | Check the idle percentageIdle near 100% while traffic is slow means HAProxy is waiting for data, not short of CPU. |
show version | Show the running versionAnswers on the master CLI as well as on each worker's socket. |
show env [<NAME>] | Show environment variablesWithout a name every variable is listed in the name=value form of the env utility. |
show errors | Show recent protocol errorsCovers HTTP/1.x errors seen by frontends and backends; a proxy name and request or response narrow it. |
show startup-logs | Show startup messagesOn the master CLI it reports the most recent start or reload attempt instead. |
show sess | List active streamsOutput can be huge, so avoid it over slow links; needs an operator or admin socket. |
shutdown session <ID> | Kill one streamTakes the identifier from the first field of show sess; the stream is logged with a K flag. |
Statistics and server state 10
| Command | What it does |
|---|---|
show stat | Show statsCSV by default; typed or json change the format, and a proxy, type and server ID narrow the dump. |
echo "show stat json" | socat /var/run/haproxy.sock stdio | python -m json.tool | Pretty-print stats as JSONSame pretty-printing trick as for show info, applied to the per-proxy statistics. |
show schema json | Show the JSON schemaDescribes the fields that the json forms of show info and show stat emit. |
show servers state [<BACKEND>] | Server stateThe dump starts with a format version and a header line; a backend name limits it to that backend. |
socat /tmp/socket - <<< "show servers state" > /tmp/server_state | Save server states to a fileWith server-state-file and load-server-state-from-file set, the next process reapplies these states at startup. |
show servers conn [<BACKEND>] | Show server connectionsCurrent and idle connections per server; the last columns are per thread, so read the header line. |
show backend | List backends |
clear counters | Reset maximum countersOnly the max values are cleared; accumulated traffic counters stay, giving clean peaks after an incident. |
clear counters all | Reset all countersNeeds an admin-level socket; for the statistics it amounts to a restart. |
show resolvers | Show DNS resolver statisticsCounters per name server, such as requests sent and valid answers; a section ID narrows it to one resolvers section. |
Server maintenance 17
| Command | What it does |
|---|---|
disable server <BACKEND>/<SERVER> | Disable serverMaintenance mode: no traffic and no checks, shown as MAINT on the stats page; needs an admin socket. |
enable server <BACKEND>/<SERVER> | Enable serverTakes the server out of maintenance and turns its health checks back on. |
set server <BACKEND>/<SERVER> state ready | Return server to readyNormal mode again, the same as enable server. |
set server <BACKEND>/<SERVER> state drain | Drain a serverOut of load balancing but still checked, and it keeps accepting new persistent connections. |
set server <BACKEND>/<SERVER> state maint | Put server in maintenanceStops all traffic and health checks, the same as disable server. |
shutdown sessions server <BACKEND>/<SERVER> | Close a server's streamsEnds long-running streams after the server is put into maintenance, instead of waiting for them. |
set weight <BACKEND>/<SERVER> <WEIGHT>[%] | Change server weightA trailing % is relative to the configured weight; setting 0, then 100% after an update, pauses a server. |
get weight <BACKEND>/<SERVER> | Show server weightPrints the current and the configured weight; they differ after a runtime change. |
set server <BACKEND>/<SERVER> health [ up | stopping | down ] | Force a health stateOverrides the check result at once, for example when checks are slow; tracking servers follow. |
set server <BACKEND>/<SERVER> addr <ADDRESS> [port <PORT>] | Change server addressSwaps the server's IP address while running; the same command can also set a new port. |
disable health <BACKEND>/<SERVER> | Pause health checksThe last result is ignored and the server counts as UP unless an agent check marks it down. |
enable health <BACKEND>/<SERVER> | Resume health checksStarts sending the primary checks again after disable health. |
disable agent <BACKEND>/<SERVER> | Pause the agent checkStops the auxiliary agent check that a server's agent-check parameter sets up. |
enable agent <BACKEND>/<SERVER> | Resume the agent checkUndoes disable agent so the auxiliary agent check runs again. |
set maxconn server <BACKEND/SERVER> <VALUE> | Change server maxconnZero is allowed; values above the global maxconn have little point. |
add server <BACKEND>/<SERVER> [ARGS] ... | Add a server at run timeThe backend needs a dynamic balancing algorithm, and the server is lost on reload unless added to the configuration. |
del server <BACKEND>/<SERVER> | Remove a serverOnly for a server already in maintenance, without connections and not referenced elsewhere. |
Frontends and global limits 6
| Command | What it does |
|---|---|
disable frontend <FRONTEND> | Stop a frontend temporarilyThe frontend releases its ports as in a soft restart; some non-Linux systems cannot resume it. |
enable frontend <FRONTEND> | Resume a frontendReports an error if another process has taken one of its ports in the meantime. |
shutdown frontend <FRONTEND> | Delete a frontendReleases its ports for good; unlike disable frontend, it cannot be brought back. |
set maxconn frontend <FRONTEND> <VALUE> | Change frontend maxconnRaising it accepts pending connections at once; lowering it below the current count delays new ones. |
set maxconn global <MAXCONN> | Change global maxconnOnly within the configured global maxconn; 0 brings back the value set at startup. |
set rate-limit connections global <VALUE> | Change connection rate limitConnections per second across all frontends, applied immediately; 0 removes the limit. |
Stick tables 5
| Command | What it does |
|---|---|
show table | List stick tablesGives each table's name, type, size and how many entries are used. |
show table <NAME> | Dump a stick tablePrints the table header, then every entry; a data filter or key limits the output. |
echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1 | Filter entries by a counterLists only the http_proxy entries whose gpc0 counter is above zero. |
clear table <TABLE> key <KEY> | Remove a table entryTypically used to unblock a client that a stick-table rule has wrongly denied. |
echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1 | Clear one client addressRemoves the entry for 127.0.0.1 from the http_proxy table. |
Maps and ACLs 8
| Command | What it does |
|---|---|
show map | List mapsAdd a map name or #ID to dump its entries instead of the list. |
get map <MAP> <VALUE> | Look up a map valueReturns every matching pattern, which helps when debugging map and ACL behaviour. |
add map <MAP> <KEY> <VALUE> | Add a map entryExisting keys are not checked, so a duplicate entry can be created. |
set map <MAP> [<KEY>|#<REF>] <VALUE> | Change a map valueUpdates every entry for that key, or only one entry when a #reference is given. |
del map <MAP> [<KEY>|#<REF>] | Delete map entriesRemoves every entry for the key; with #REF only that one listed entry goes. |
show acl | List ACLsName an ACL or give its #ID to dump its patterns. |
add acl <ACL> <PATTERN> | Add an ACL patternThe entry goes into the current version unless a version prepared with prepare acl is named. |
del acl <ACL> [<KEY>|#<REF>] | Delete ACL entriesIf a map uses the same name, the matching entry is deleted from the map too. |
TLS certificates 9
| Command | What it does |
|---|---|
show ssl cert | List loaded certificatesUncommitted transactions carry an asterisk; name a file to see its details. |
new ssl cert <FILENAME> | Create an empty certificateFill it with set ssl cert, then attach it with add ssl crt-list. |
set ssl cert <FILENAME> <PAYLOAD> | Stage a certificate updateOpens a transaction on any certificate listed by show ssl cert; nothing changes until commit. |
commit ssl cert <FILENAME> | Apply a certificate updateBuilds the new SSL contexts and SNIs and swaps them in for the previous certificate. |
abort ssl cert <FILENAME> | Cancel a certificate updateThrows away the uncommitted transaction opened by set ssl cert. |
show ssl crt-list [-n] [<FILENAME>] | List crt-listsName a crt-list to dump its lines; -n adds line numbers for del ssl crt-list but breaks the file format. |
add ssl crt-list <CRTLIST> <CERTIFICATE> | Add a certificate to a crt-listLoads it on every bind line that uses the list; SSL options or filters need the payload form instead. |
echo -e "set ssl cert localhost.pem <<\n$(cat 127.0.0.1.pem)\n" | socat /var/run/haproxy.stat - | Upload a certificate from a fileThe payload starts after the marker at the end of the first line and ends at an empty line. |
echo "commit ssl cert localhost.pem" | socat /var/run/haproxy.stat - | Commit from the shellLast step of the guide's example, after the certificate and its issuer and OCSP parts are set. |
Master CLI 9
The master CLI exists only in master-worker mode and only when -S is given on the command line; it can reach every worker, including ones still finishing after a reload.
| Command | What it does |
|---|---|
-S <BIND>[,BIND_OPTIONS...] | Bind the master CLITakes the options of a bind line joined by commas; a local UNIX socket is the safer choice. |
haproxy -W -S 127.0.0.1:1234 -f test1.cfg | Start with a master CLIMaster-worker mode with the master CLI on a TCP address, as in the guide's first example. |
socat /var/run/haproxy-master.sock readline | Open the master CLIAfter prompt, the master> prompt accepts @ prefixes that send commands to each process. |
show proc | List master and workersShows each process with its type, reload count, uptime and version, including old workers still running. |
@1 | Switch to process 1Later commands run in that process until another @ prefix; @ alone goes back to the master. |
echo '@!1271 show info; @!1272 show info' | socat /var/run/haproxy-master.sock - | Run show info by PIDAn @! prefix picks a process by PID, the only way to reach a worker that is leaving. |
reload | Reload from the master CLISame effect as SIGUSR2 to the master, but synchronous: a status comes back once the new worker is forked. |
echo "reload" | socat -t300 /var/run/haproxy-master.sock stdin | Scripted reload with statusThe long -t300 timeout matters, because socat's default of 0.5 s can quit before the status arrives. |
hard-reload | Reload with a hard stopLike reload, but the previous processes are stopped with -st, so their connections are closed. |
No row on this page matches that filter.
Notes
Validate before you reload
-c parses the configuration and exits before binding any port: the exit status is zero when the files are valid, -V adds a success message and -dW makes warnings fail the check as well. The systemd unit in the source tree reloads in two steps, haproxy -Ws -f $CONFIG -f $CFGDIR -c $EXTRAOPTS and then /bin/kill -USR2 $MAINPID, so the master is only signalled once the files pass. On SIGUSR2 the master re-executes itself with -sf and the worker PIDs: new workers start with the new configuration while the old ones stop listening and finish their connections.
Reading the runtime state
Send one command per connection with echo "show version" | socat /var/run/haproxy.sock stdio, or open socat /var/run/haproxy.sock readline and type prompt first to keep the session open. show info prints process-wide fields such as Uptime_sec and Maxconn, show stat returns per-frontend, backend and server statistics as CSV unless typed or json is added, and show servers state [<BACKEND>] dumps each server's state with a header line, the first thing to read when a backend looks wrong.
Draining a server without a reload
set server <BACKEND>/<SERVER> state drain removes a server from load balancing while it is still checked and still takes persistent connections. disable server <BACKEND>/<SERVER>, the same as state maint, stops all traffic and checks, and shutdown sessions server <BACKEND>/<SERVER> ends the streams that remain; enable server <BACKEND>/<SERVER> brings it back. To keep such states across a reload, write show servers state into the file named by server-state-file before reloading, as in socat /tmp/socket - <<< "show servers state" > /tmp/server_state; with load-server-state-from-file set, the new process applies them at startup.
Questions
How do I reload HAProxy without dropping connections?
In master-worker mode, signal the master with SIGUSR2 (the shipped systemd unit runs /bin/kill -USR2 $MAINPID) or type reload on the master CLI. New workers start with the new configuration and the old ones finish their connections; the master also hands the listening sockets to the new worker itself. Without master-worker mode, start a new process with -sf <PID> ... listing the old PIDs.
What is the difference between -sf and -st?
Both are passed to the new process together with the PIDs of the old ones. -sf <PID> ... sends SIGUSR1 after startup, so the old processes release their ports and finish their current connections; -st <PID> ... sends SIGTERM, which stops them at once and closes their connections. On the master CLI, reload and hard-reload make the same choice.
Why does the reload command on the master CLI print nothing when sent through socat?
The status only comes back after the configuration has been parsed and the new worker forked, and socat gives up after 0.5 seconds by default. Give it a longer timeout: echo "reload" | socat -t300 /var/run/haproxy-master.sock stdin.
Which socket level do runtime commands need?
Each stats socket line can set a level of user, operator (the default) or admin. Commands that change state, such as disable server <BACKEND>/<SERVER> or clear counters all, are restricted to admin, and show sess needs operator or admin. show cli level shows the level of the current session, and operator or user lowers it for the rest of the connection.
How can I tell which HAProxy version and build options are running?
haproxy -v prints the version string, haproxy -vv adds the build options, target system and library versions that bug reports ask for, and show version asks a running process over its socket.
Sources and checks
- HAProxy 3.4 Management Guide (doc/management.txt, release v3.4.6) Command-line options, signals, stopping and reloading, the runtime API (stats socket) and the master CLI
- HAProxy 3.4.6 source tree: admin/systemd/haproxy.service.in The systemd unit shipped with HAProxy: its start and reload command lines
- HAProxy 3.4 Starter Guide (doc/intro.txt, release v3.4.6) haproxy -v and how to read the version string
- HAProxy 3.4 Configuration Manual (doc/configuration.txt, release v3.4.6) The configuration check command and saving server states for the next start
Every row on this page was matched to a line in the documentation above on . A binding that could not be found there is not listed.
2 rows from the earlier version of this page were removed in that check: duplicates, and bindings the documentation does not list or lists differently.
Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.