HAProxy

https://docs.haproxy.org/
Admin
HAProxy is a high-performance, open-source load balancer and proxy server that provides reliable,...
Tokens:90,140
Snippets:705
Trust Score:9.9
Update:7 months ago
Show doc for...
Tokens:
Raw
### HAProxy Master CLI Command Sequence Example

Source: https://docs.haproxy.org/3.3/management.html

An example demonstrating the sequence of enabling expert, experimental, and debug modes in the HAProxy master CLI, followed by executing a command and observing the prompt changes.

```bash
$ socat /var/run/haproxy-master.sock -
prompt
master> expert-mode on
master(e)> experimental-mode on
master(xe)> mcli-debug-mode on
master(xed)> @1
95191(xed)>
```

--------------------------------

### HAProxy Startup with Dynamic Configuration Files

Source: https://docs.haproxy.org/3.3/management.html

This example illustrates loading an unknown number of customer-specific configuration files. It recommends naming them with a fixed-size sequence number and using '--' to load them, potentially after default configurations.

```bash
haproxy -f /etc/haproxy/global.cfg -f /etc/haproxy/stats.cfg \
        --
```

--------------------------------

### HAProxy Startup with Multiple Configuration Files

Source: https://docs.haproxy.org/3.3/management.html

This example shows how to load HAProxy configuration from multiple files, which is recommended when the configuration is split into logical parts (e.g., TCP vs. HTTP). It also includes daemon mode, PID file management, and graceful shutdown of older processes.

```bash
haproxy -f /etc/haproxy/global.cfg -f /etc/haproxy/stats.cfg \
        -f /etc/haproxy/default-tcp.cfg -f /etc/haproxy/tcp.cfg \
        -f /etc/haproxy/default-http.cfg -f /etc/haproxy/http.cfg \
        -D -p /var/run/haproxy.pid -sf $(cat /var/run/haproxy.pid)
```

--------------------------------

### HAProxy Startup with Daemon Mode, PID File, and Graceful Shutdown

Source: https://docs.haproxy.org/3.3/management.html

This example demonstrates a safe HAProxy startup sequence from an init file. It forces daemon mode (-D), stores PIDs in a file (-p), and notifies older processes to finish gracefully (-sf) using the PIDs from the file.

```bash
haproxy -f /etc/haproxy.cfg \
        -D -p /var/run/haproxy.pid -sf $(cat /var/run/haproxy.pid)
```

--------------------------------

### Master CLI Configuration with HAProxy

Source: https://docs.haproxy.org/3.3/management.html

Shows how to configure and start HAProxy with the master CLI using the -S option. The -S option accepts bind options separated by commas, allowing for various configurations like IP address, port, user/group IDs, and access levels.

```bash
# haproxy -W -S 127.0.0.1:1234 -f test1.cfg
# haproxy -Ws -S /tmp/master-socket,uid,1000,gid,1000,mode,600 -f test1.cfg
# haproxy -W -S /tmp/master-socket,level,user -f test1.cfg
```

--------------------------------

### Show Backend List in HAProxy

Source: https://docs.haproxy.org/3.3/management.html

Dumps a list of all backends currently configured and running within the HAProxy process. This is useful for getting an overview of the load balancing setup.

```haproxy-cli
**show backend**
```

--------------------------------

### HAProxy Strace Example

Source: https://docs.haproxy.org/3.3/management.html

Demonstrates how HAProxy's internal clock and timeout enforcement are visible through strace. It shows periodic calls to gettimeofday and epoll_wait, indicating how HAProxy manages time without blocking.

```text
16:35:40.002320 gettimeofday({1442759740, 2605}, NULL) = 0
16:35:40.002942 epoll_wait(0, {}, 200, 1000) = 0
16:35:41.007542 gettimeofday({1442759741, 7641}, NULL) = 0
16:35:41.007998 gettimeofday({1442759741, 8114}, NULL) = 0
16:35:41.008391 epoll_wait(0, {}, 200, 1000) = 0
16:35:42.011313 gettimeofday({1442759742, 11411}, NULL) = 0
```

--------------------------------

### HAProxy CLI Level Example

Source: https://docs.haproxy.org/3.3/management.html

Demonstrates how to change and check the CLI level in HAProxy using 'operator' and 'user' commands, along with 'show cli level'. Shows permission denied for unauthorized level changes.

```bash
$ socat /tmp/sock1 readline
prompt
> operator
> show cli level
operator
> user
> show cli level
user
> operator
Permission denied

```

--------------------------------

### Synchronous HAProxy Reload with Socat

Source: https://docs.haproxy.org/3.3/management.html

Demonstrates performing a synchronous reload of the HAProxy master process using 'socat' with a specified timeout. It shows examples of both successful and failed reloads, including configuration parsing errors.

```bash
echo "reload" | socat -t300 /var/run/haproxy-master.sock stdin
```

--------------------------------

### Initiate ACME Certificate Generation

Source: https://docs.haproxy.org/3.3/management.html

Starts an ACME certificate generation task for a specified certificate name. The certificate must be configured within an ACME section in HAProxy.

```cli
acme renew <certificate>
```

--------------------------------

### Get Process Variable

Source: https://docs.haproxy.org/3.3/management.html

Shows the existence, type, and contents of a process-wide variable. Only variables starting with 'proc.' are readable and require 'operator' or 'admin' privileges.

```APIDOC
## Get Process Variable

### Description
Retrieves the existence, type, and content of a specified process-wide variable. The variable name must start with 'proc.' to be accessible.

### Method
GET

### Endpoint
get var <name>

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the process-wide variable (must start with 'proc.').

### Permissions
Requires 'operator' or 'admin' level privileges.

### Response
#### Success Response (200)
- **variable details** (string) - Information about the variable's existence, type, and content.

### Response Example
```
proc.loadavg: { type=table, value={ 1m=0.5, 5m=0.6, 15m=0.7 } }
```
```

--------------------------------

### Get HAProxy Version

Source: https://docs.haproxy.org/3.3/management.html

Retrieves the version of the HAProxy instance by sending the 'show version' command to the master socket. This is useful for checking the installed HAProxy version.

```bash
$ echo "show version" | socat /var/run/haproxy-master.sock stdio
2.5.0
```

--------------------------------

### Example: Clear Specific Entry from HAProxy Stick-Table

Source: https://docs.haproxy.org/3.3/management.html

This example demonstrates how to clear a specific entry (key 127.0.0.1) from the 'http_proxy' stick-table using socat. It first shows the table contents, then executes the clear command, and finally shows the updated table contents.

```bash
    $ echo "show table http_proxy" | socat stdio /tmp/sock1
>>> # table: http_proxy, type: ip, size:204800, used:2
>>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \
      bytes_out_rate(60000)=187
>>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
      bytes_out_rate(60000)=191
>>> 0x80e6b40: key=127.0.0.3 use=0 exp=3594743 gpc0=2 conn_rate(30000)=10 \
      bytes_out_rate(60000)=200

    $ echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1

    $ echo "show table http_proxy" | socat stdio /tmp/sock1
>>> # table: http_proxy, type: ip, size:204800, used:1
>>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \
>>> 0x80e6b40: key=127.0.0.3 use=0 exp=3594743 gpc0=2 conn_rate(30000)=10 \
      bytes_out_rate(60000)=200
      bytes_out_rate(60000)=191
```

--------------------------------

### Get Map or ACL Value

Source: https://docs.haproxy.org/3.3/management.html

Looks up a value within a specified map or ACL.

```APIDOC
## Get Map or ACL Value

### Description
Lookup the value in the map or in the ACL.

### Method
N/A (CLI Command)

### Endpoint
N/A (CLI Command)

### Parameters
#### Path Parameters
- **map** (string) - Required - The name of the map to query.
- **acl** (string) - Required - The name of the ACL to query.
- **value** (string) - Required - The value to look up.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
get map mymap some_key
get acl myacl some_value
```

### Response
#### Success Response (200)
Returns the result of the lookup (e.g., the value associated with the key in the map, or a boolean indicating if the value is in the ACL).

#### Response Example
```
value_from_map
1
```
```

--------------------------------

### View HAProxy Startup Logs via CLI

Source: https://docs.haproxy.org/3.3/management.html

The 'show startup-logs' command retrieves HAProxy's startup messages, including those from failed reloads. This feature requires HAProxy to be compiled with USE_SHM_OPEN=1 for full visibility. The logs are also available via the 'reload' command.

```bash
# Requires HAProxy compiled with USE_SHM_OPEN=1
# Example usage (conceptual, actual command might vary based on socket path)
# echo 'show startup-logs' | socat /var/run/haproxy-master.sock -
```

--------------------------------

### Show Startup Logs

Source: https://docs.haproxy.org/3.3/management.html

Dumps all messages emitted during the startup of the current HAProxy process. Each startup-logs buffer is unique to its HAProxy worker. This command also exists on the master CLI, showing the latest startup or reload tentative.

```APIDOC
## GET /haproxy/startup-logs

### Description
Retrieves all messages emitted during the startup of the current HAProxy process. Each buffer is unique to its HAProxy worker. This command can also be used on the master CLI to view the latest startup or reload tentative.

### Method
GET

### Endpoint
/haproxy/startup-logs

### Parameters
None

### Request Example
```bash
$ echo "show startup-logs" | socat stdio /tmp/sock1
```

### Response
#### Success Response (200)
- **logs** (string) - A string containing the startup logs.

#### Response Example
```json
{
  "logs": "<startup log messages>"
}
```
```

--------------------------------

### Report HAProxy Version

Source: https://docs.haproxy.org/3.3/management.html

The -v option displays the HAProxy version and build date. This is a simple command to check the installed HAProxy version.

```bash
haproxy -v
```

--------------------------------

### Get Server Weight

Source: https://docs.haproxy.org/3.3/management.html

Reports the current and initial weight of a specific server within a backend. Weights are normally equal unless the current weight has been modified.

```APIDOC
## Get Server Weight

### Description
Reports the current and initial weight of a specified server within a backend. The initial weight is read from the configuration file.

### Method
GET

### Endpoint
get weight <backend>/<server>

### Parameters
#### Path Parameters
- **backend** (string) - Required - The name or ID of the backend.
- **server** (string) - Required - The name or ID of the server within the backend.

### Response
#### Success Response (200)
- **current weight** (integer) - The current weight of the server.
- **initial weight** (integer) - The initial weight of the server as defined in the configuration.

### Response Example
```
Server 'web01' in backend 'webservers': current weight = 10, initial weight = 10
```
```

--------------------------------

### Specify HAProxy PID File

Source: https://docs.haproxy.org/3.3/management.html

The -p <file> option writes all process PIDs to the specified <file> during startup, similar to the 'pidfile' global keyword. The file is opened before chroot and after chdir. Each PID is written on a new line.

```bash
haproxy -p /var/run/haproxy.pid
```

--------------------------------

### Show HAProxy Startup Logs

Source: https://docs.haproxy.org/3.3/management.html

Dumps all messages emitted during the startup of the current HAProxy process. Each startup-logs buffer is unique to its HAProxy worker. This command is also available on the master CLI to show the latest startup or reload tentative.

```bash
# Example usage:
# echo "show startup-logs" | socat stdio /tmp/sock
```

--------------------------------

### Add Server Help

Source: https://docs.haproxy.org/3.3/management.html

Lists the keywords supported for dynamic servers by the current HAProxy version. Keyword syntax is similar to the server line from the configuration file.

```APIDOC
## ADD SERVER HELP

### Description
List the keywords supported for dynamic servers by the current haproxy version. Keyword syntax is similar to the server line from the configuration file, please refer to their individual documentation for details.

### Method
GET

### Endpoint
/websites/haproxy

### Parameters
None

### Request Example
```
add server help
```

### Response
#### Success Response (200)
- **supported_keywords** (array of strings) - A list of keywords supported for dynamic servers.

#### Response Example
```json
{
  "supported_keywords": [
    "check",
    "track",
    "agent-check",
    "init-addr"
  ]
}
```
```

--------------------------------

### Set SSL Certificate using socat

Source: https://docs.haproxy.org/3.3/management.html

Commands to set SSL certificates, including basic sanitization and complete examples with commit. Uses 'socat' to interact with the HAProxy stats socket.

```bash
echo -e "set ssl cert localhost.pem <<\n$(sed -n '/^$/d;/-BEGIN/,/-END/p' 127.0.0.1.pem)\n" | \
 socat /var/run/haproxy.stat -

echo -e "set ssl cert localhost.pem <<\n$(cat 127.0.0.1.pem)\n" | \
 socat /var/run/haproxy.stat -
 echo -e \
 "set ssl cert localhost.pem.issuer <<\n $(cat 127.0.0.1.pem.issuer)\n" | \
 socat /var/run/haproxy.stat -
 echo -e \
 "set ssl cert localhost.pem.ocsp <<\n$(base64 -w 1000 127.0.0.1.pem.ocsp)\n" | \
 socat /var/run/haproxy.stat -
 echo "commit ssl cert localhost.pem" | socat /var/run/haproxy.stat -
```

--------------------------------

### Add Server

Source: https://docs.haproxy.org/3.3/management.html

Instantiates a new server attached to a specified backend. The backend must use a dynamic load-balancing algorithm. Server configuration keywords are supported, and health checks can be enabled.

```APIDOC
## ADD SERVER

### Description
Instantiate a new server attached to the backend <backend>.

The <server> name must not be already used in the backend. A special restriction is put on the backend which must used a dynamic load-balancing algorithm. A subset of keywords from the server config file statement can be used to configure the server behavior (see "add server help" to list them). Also note that no settings will be reused from an hypothetical 'default-server' statement in the same backend.

Currently a dynamic server is statically initialized with the "none" init-addr method. This means that no resolution will be undertaken if a FQDN is specified as an address, even if the server creation will be validated.

To support the reload operations, it is expected that the server created via the CLI is also manually inserted in the relevant haproxy configuration file. A dynamic server not present in the configuration won't be restored after a reload operation.

A dynamic server may use the "track" keyword to follow the check status of another server from the configuration. However, it is not possible to track another dynamic server. This is to ensure that the tracking chain is kept consistent even in the case of dynamic servers deletion.

Use the "check" keyword to enable health-check support. Note that the health-check is disabled by default and must be enabled independently from the server using the "enable health" command. For agent checks, use the "agent-check" keyword and the "enable agent" command. Note that in this case the server may be activated via the agent depending on the status reported, without an explicit "enable server" command. This also means that extra care is required when removing a dynamic server with agent check. The agent should be first deactivated via "disable agent" to be able to put the server in the required maintenance mode before removal.

It may be possible to reach the fd limit when using a large number of dynamic servers. Please refer to the "u-limit" global keyword documentation in this case.

### Method
POST

### Endpoint
/websites/haproxy

### Parameters
#### Path Parameters
- **backend** (string) - Required - The name of the backend to which the server will be added.
- **server** (string) - Required - The name of the new server.

#### Query Parameters
- **args** (string) - Optional - Keywords from the server config file statement to configure the server behavior.

### Request Example
```
add server <backend>/<server> [args]*
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the server was added successfully.

#### Response Example
```json
{
  "message": "Server <server> added to backend <backend>"
}
```
```

--------------------------------

### List Supported Keywords for Dynamic Servers

Source: https://docs.haproxy.org/3.3/management.html

Displays a list of keywords that can be used when adding dynamic servers in the current HAProxy version. The syntax for these keywords mirrors that of the server line in the configuration file.

```bash
add server help
```

--------------------------------

### Prepare HAProxy Chroot Directory

Source: https://docs.haproxy.org/3.3/management.html

This command prepares an empty directory for HAProxy's chroot environment. It creates the directory and sets its permissions to 0, ensuring no access. This is a crucial step for isolating HAProxy.

```bash
# mkdir /var/empty && chmod 0 /var/empty || echo "Failed"
```

--------------------------------

### List HAProxy Trace Sources

Source: https://docs.haproxy.org/3.3/management.html

Lists all available trace sources, their current status, and brief descriptions. This command serves as an entry point to explore and configure more detailed tracing options.

```bash
trace
```

--------------------------------

### Signal Older HAProxy Processes to Finish

Source: https://docs.haproxy.org/3.3/management.html

The -sf <pid>* option sends SIGUSR1 to older processes after boot, instructing them to finish current tasks and exit. <pid> is a list of PIDs, terminated by any option starting with '-'. An empty list is permissible.

```bash
haproxy -sf $(cat /var/run/haproxy.pid)
```

--------------------------------

### Enable Frontend

Source: https://docs.haproxy.org/3.3/management.html

Resumes a frontend that was temporarily stopped. It may not be possible to bind listening ports if another process has taken them.

```APIDOC
## Enable Frontend

### Description
Resume a frontend which was temporarily stopped. It is possible that some of the listening ports won't be able to bind anymore (eg: if another process took them since the 'disable frontend' operation). If this happens, an error is displayed. Some operating systems might not be able to resume a frontend which was disabled.

The frontend may be specified either by its name or by its numeric ID, prefixed with a sharp ('#').

### Method
N/A (CLI Command)

### Endpoint
N/A (CLI Command)

### Parameters
#### Path Parameters
- **frontend** (string) - Required - The frontend to resume, specified by name or numeric ID (prefixed with '#').

#### Query Parameters
None

#### Request Body
None

### Request Example
N/A (CLI command execution)

### Response
#### Success Response (200)
The frontend is resumed.

#### Response Example
N/A
```

--------------------------------

### Terminate Older HAProxy Processes Immediately

Source: https://docs.haproxy.org/3.3/management.html

The -st <pid>* option sends SIGTERM to older processes after boot, terminating them immediately without finishing ongoing tasks. <pid> is a list of PIDs, terminated by any option starting with '-'. An empty list is permissible.

```bash
haproxy -st $(pidof haproxy)
```

--------------------------------

### Extract Abusing IP Addresses using HAProxy Socket

Source: https://docs.haproxy.org/3.3/management.html

This example demonstrates how to extract IP addresses of clients that are abusing the service by exceeding a certain threshold. It uses `socat` to communicate with the HAProxy socket and `fgrep`/`cut` or `awk` to parse the output and save the IPs to a file.

```bash
$ echo "show table http_proxy data.gpc0 gt 0" \
  | socat stdio /tmp/sock1 \
  | fgrep 'key=' | cut -d' ' -f2 | cut -d= -f2 > abusers-ip.txt
  ( or | awk '/key/{ print a[split($2,a,"=")]; }')
```

--------------------------------

### Enable Server

Source: https://docs.haproxy.org/3.3/management.html

Marks a server as UP and re-enables checks if it was previously marked DOWN for maintenance.

```APIDOC
## Enable Server

### Description
If the server was previously marked as DOWN for maintenance, this marks the server UP and checks are re-enabled.

Both the backend and the server may be specified either by their name or by their numeric ID, prefixed with a sharp ('#').

### Method
N/A (CLI Command)

### Endpoint
N/A (CLI Command)

### Parameters
#### Path Parameters
- **backend>/<server>** (string) - Required - The backend and server to enable.

#### Query Parameters
None

#### Request Body
None

### Request Example
N/A (CLI command execution)

### Response
#### Success Response (200)
The server is marked UP and checks are re-enabled.

#### Response Example
N/A
```

--------------------------------

### Display HAProxy ECH Keys

Source: https://docs.haproxy.org/3.3/management.html

The 'show ssl ech' command displays the list of Encrypted Client Hello (ECH) keys loaded in the HAProxy process. It can display keys for a specific bind line using a format like <frontend>/@<filename>:<linenum> or <frontend>/<name>. The 'age' indicates how long the key has been loaded. This command requires an OpenSSL version supporting ECH, HAProxy compiled with USE_ECH=1, and experimental mode enabled.

```bash
echo "experimental-mode on; show ssl ech" | socat /tmp/haproxy.sock -
```

```bash
echo "experimental-mode on; show ssl ech frontend1/@haproxy.conf:19" | socat /tmp/haproxy.sock -
```

--------------------------------

### Help Command

Source: https://docs.haproxy.org/3.3/management.html

Displays a list of available keywords and their basic usage, or provides information about a specific command if provided.

```APIDOC
## Help

### Description
Provides a list of all available commands and their basic usage, or detailed information for a specific command if one is provided.

### Method
GET (Implicit)

### Endpoint
help [<command>]

### Parameters
#### Path Parameters
- **command** (string) - Optional - The name of the command to get help for.

### Response
#### Success Response (200)
- **help text** (string) - A list of commands or detailed help for a specific command.

### Response Example
```
Available commands: help, get var, get weight, httpclient, ...

help httpclient:
  Launch an HTTP client request and print the response on the CLI.
  Only supported on a CLI connection running in expert mode...
```
```

--------------------------------

### Manage HAProxy Configuration with Environment Variables

Source: https://docs.haproxy.org/3.3/management.html

HAProxy configurations can incorporate environment variables, starting from version 1.5 for addresses and expanded in 1.6 for all arguments within double quotes. This allows for shared configuration files across multiple nodes, differing only by environment-specific variables, simplifying management and reducing divergence.

```ini
global
    log "${LOGGER}:514" local0

defaults
    mode http
    timeout client "${TIMEOUT}"
    timeout server "${TIMEOUT}"
    timeout connect 5s

frontend public
    bind "${LISTEN}:80"
    http-request reject if { src -f "${ABUSERS}" }
    stats uri /stats
    stats auth "${STATSLP}"
    use_backend cache if { path_end .jpg .css .ico }
    default_backend server

backend cache
    server cache1 "${CACHE_PFX}.1:18080" check
    server cache2 "${CACHE_PFX}.2:18080" check

backend server
    server cache1 "${SERVER_PFX}.1:8080" check
    server cache2 "${SERVER_PFX}.2:8080" check
```

```bash
# Example environment variable definitions
LISTEN=192.168.1.1
CACHE_PFX=192.168.11
SERVER_PFX=192.168.22
LOGGER=192.168.33.1
STATSLP=admin:pa$$w0rd
ABUSERS=/etc/haproxy/abuse.lst
TIMEOUT=10s
```

--------------------------------

### Generate HAProxy Stats-file for Preloading Counters

Source: https://docs.haproxy.org/3.3/management.html

The 'dump stats-file' CLI command generates a stats-file used to preload internal HAProxy counters on process startup. This is primarily for preserving statistics for worker processes across reloads, supporting proxy counters for frontends, backends, servers, and listeners with non-empty GUIDs.

```bash
# Example usage (conceptual, actual command might vary based on socket path)
# echo 'dump stats-file' | socat /var/run/haproxy-master.sock -
```

--------------------------------

### Display Detailed HAProxy Version and Build Info

Source: https://docs.haproxy.org/3.3/management.html

The -vv option provides comprehensive details including version, build options, library versions, and usable pollers. This output is typically requested when reporting bugs.

```bash
haproxy -vv
```

--------------------------------

### Set SSL ECH using socat and OpenSSL

Source: https://docs.haproxy.org/3.3/management.html

Commands to set TLS Encrypted Client Hello (ECH) keys for a bind line. Requires OpenSSL with ECH support and HAProxy compiled with USE_ECH=1, running in experimental mode.

```bash
openssl ech -public_name foobar.com -out foobar3.com.ech
echo -e "experimental-mode on;
             set ssl ech frontend1/@haproxy.conf:19 <<%EOF%
$(cat foobar3.com.ech)
%EOF%
" | \
    socat /tmp/haproxy.sock -
```
Tokens:
Raw