Skip to content

Commit a9af3b7

Browse files
mjuragamjuraga
committed
DOC/MAJOR: configuration: doc the configuration file options in full
1 parent a152b62 commit a9af3b7

File tree

3 files changed

+309
-9
lines changed

3 files changed

+309
-9
lines changed

‎configuration/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,10 @@
22

33
## HAProxy Data Plane API configuration file
44

5+
documentation can be seen at [doc](doc/README.md)
6+
57
example can be seen [yaml](examples/example-dataplaneapi.yaml)
8+
69
full examples of configuration also can be seen at [yaml](examples/example-full.yaml)
710

811
# IMPORTANT information regarding migration from 2.x to 3.0 version

‎configuration/doc/README.md

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
# HAProxy Data Plane API Configuration
2+
3+
## Overview
4+
5+
The primary configuration for the Data Plane API is managed through a YAML file. This file allows you to set various parameters that control the behavior of the API and its interaction with HAProxy.
6+
7+
## Top-Level Configuration Options
8+
9+
| Option | Type | Required | Description |
10+
|--------|------|----------|-------------|
11+
| `config_version` | integer | No | Configuration version |
12+
| `name` | string | No | Name |
13+
14+
## Structure
15+
16+
The configuration file is structured into several sections, each corresponding to a different aspect of the Data Plane API's functionality. Here's a breakdown of the main sections and their options:
17+
18+
### dataplaneapi Configuration Options
19+
20+
| Option | Type | Required | Description |
21+
|--------|------|----------|-------------|
22+
| `write_timeout` | string | No | Specifies the write timeout for API requests |
23+
| `graceful_timeout` | string | No | Sets the graceful shutdown timeout |
24+
| `show_system_info` | boolean | No | Enables or disables the display of system information on the info endpoint |
25+
| `max_header_size` | string | No | Defines the maximum header size for API requests |
26+
| `socket_path` | string | No | Specifies the path to the API's Unix socket |
27+
| `debug_socket_path` | string | No | Defines the path for the debugging command socket |
28+
| `host` | string | No | Sets the host address for the API |
29+
| `port` | integer | No | Defines the port number for the API |
30+
| `listen_limit` | integer | No | Sets the maximum number of connections the API can handle |
31+
| `disable_inotify` | boolean | No | Disables the inotify watcher for the configuration file |
32+
| `read_timeout` | string | No | Specifies the read timeout for API requests |
33+
| `advertised` | object | No | Contains settings for the advertised API address and port. [See advertised options](#dataplaneapiadvertised-configuration-options) |
34+
| `cleanup_timeout` | string | No | Sets the timeout for cleanup operations |
35+
| `keep_alive` | string | No | Defines the keep-alive timeout for connections |
36+
| `pid_file` | string | No | Specifies the path to the file where the API's PID will be written |
37+
| `uid` | integer | No | User id value to set on start |
38+
| `gid` | integer | No | Group id value to set on start |
39+
| `tls` | object | No | Contains settings for TLS encryption. [See TLS options](#dataplanapitls-configuration-options) |
40+
| `scheme` | array of strings | No | Enabled listeners |
41+
| `userlist` | object | No | Contains settings for userlist. [See userlist options](#dataplanapituserlist-configuration-options) |
42+
| `transaction` | object | No | Contains settings for transactions. [See transaction options](#dataplanapitransaction-configuration-options) |
43+
| `resources` | object | No | Contains settings for resources. [See resources options](#dataplaneapiresources-configuration-options) |
44+
| `user` | array of objects | No | List of users. [See user options](#dataplaneapiuser-configuration-options) |
45+
46+
### dataplaneapi.advertised Configuration Options
47+
48+
| Option | Type | Required | Description |
49+
|--------|------|----------|-------------|
50+
| `api_address` | string | No | The advertised API address |
51+
| `api_port` | integer | No | The advertised API port |
52+
53+
### dataplaneapi.tls Configuration Options
54+
55+
| Option | Type | Required | Description |
56+
|--------|------|----------|-------------|
57+
| `tls_host` | string | No | The host address for TLS connections |
58+
| `tls_port` | integer | No | The port number for TLS connections |
59+
| `tls_certificate` | string | No | Path to the TLS certificate file |
60+
| `tls_key` | string | No | Path to the TLS certificate key file |
61+
| `tls_ca` | string | No | Path to the TLS CA certificate file |
62+
| `tls_listen_limit` | integer | No | The maximum number of TLS connections |
63+
| `tls_keep_alive` | string | No | The keep-alive timeout for TLS connections |
64+
| `tls_read_timeout` | string | No | The read timeout for TLS connections |
65+
| `tls_write_timeout` | string | No | The write timeout for TLS connections |
66+
67+
### dataplaneapi.userlist Configuration Options
68+
69+
| Option | Type | Required | Description |
70+
|--------|------|----------|-------------|
71+
| `userlist` | string | No | Userlist in HAProxy configuration to use for API Basic Authentication |
72+
| `userlist_file` | string | No | Path to the dataplaneapi userlist file |
73+
74+
### dataplaneapi.transaction Configuration Options
75+
76+
| Option | Type | Required | Description |
77+
|--------|------|----------|-------------|
78+
| `transaction_dir` | string | No | Path to the transaction directory |
79+
| `backups_number` | integer | No | Number of backup configuration files to keep |
80+
| `backups_dir` | string | No | Path to directory in which to place backup files |
81+
| `max_open_transactions` | integer | No | Limit for active transaction in pending state |
82+
83+
### dataplaneapi.resources Configuration Options
84+
85+
| Option | Type | Required | Description |
86+
|--------|------|----------|-------------|
87+
| `maps_dir` | string | No | Path to directory of map files managed by dataplane |
88+
| `ssl_certs_dir` | string | No | Path to SSL certificates directory |
89+
| `general_storage_dir` | string | No | Path to general storage directory |
90+
| `dataplane_storage_dir` | string | No | Path to dataplane internal storage directory |
91+
| `update_map_files` | boolean | No | Flag used for syncing map files with runtime maps values |
92+
| `update_map_files_period` | integer | No | Elapsed time in seconds between two maps syncing operations |
93+
| `spoe_dir` | string | No | Path to SPOE directory |
94+
| `spoe_transaction_dir` | string | No | Path to the SPOE transaction directory |
95+
96+
### dataplaneapi.user Configuration Options
97+
98+
| Option | Type | Required | Description |
99+
|--------|------|----------|-------------|
100+
| `name` | string | Yes | User name |
101+
| `password` | string | Yes | Password |
102+
| `insecure` | boolean | No | Insecure password |
103+
104+
### haproxy Configuration Options
105+
106+
| Option | Type | Required | Description |
107+
|--------|------|----------|-------------|
108+
| `config_file` | string | No | Path to the HAProxy configuration file |
109+
| `haproxy_bin` | string | No | Path to the HAProxy binary file |
110+
| `master_runtime` | string | No | Path to the master Runtime API socket |
111+
| `fid` | string | No | Path to file that will dataplaneapi use to write its id |
112+
| `master_worker_mode` | boolean | No | Flag to enable helpers when running HAProxy in master worker mode |
113+
| `reload` | object | No | Contains settings for reloading HAProxy. [See reload options](#haproxyreload-configuration-options) |
114+
| `delayed_start_max` | string | No | Maximum duration to wait for the haproxy runtime socket to be ready |
115+
| `delayed_start_tick` | string | No | Duration between checks for the haproxy runtime socket to be ready |
116+
117+
### haproxy.reload Configuration Options
118+
119+
| Option | Type | Required | Description |
120+
|--------|------|----------|-------------|
121+
| `reload_delay` | integer | No | Minimum delay between two reloads (in s) |
122+
| `reload_cmd` | string | No | Reload command |
123+
| `restart_cmd` | string | No | Restart command |
124+
| `status_cmd` | string | No | Status command |
125+
| `service_name` | string | No | Name of the HAProxy service |
126+
| `reload_retention` | integer | No | Reload retention in days |
127+
| `reload_strategy` | string | No | Either systemd, s6 or custom |
128+
| `validate_cmd` | string | No | Executes a custom command to perform the HAProxy configuration check |
129+
130+
### log_targets Configuration Options
131+
132+
This section contains settings related to log targets.
133+
134+
- **`log_targets`**: (array of objects, optional) - List of log targets.
135+
136+
The `log_targets` option allows you to define multiple destinations for log messages. Each element in the `log_targets` array is an object that defines a specific log target. Each log target object can have the following properties:
137+
138+
| Option | Type | Required | Description |
139+
|--------|------|----------|-------------|
140+
| `log_to` | string | Yes | Type of log target: 'file', 'syslog', or 'stdout' |
141+
| `log_format` | string | No | Log format for this target: 'text', 'json', or 'apache_common'. Default is 'text' |
142+
| `log_level` | string | No | Log level: 'trace', 'debug', 'info', 'warning', 'error', or 'critical'. Default is 'info' |
143+
| `log_file` | string | No | If target is 'file', specifies the path to the log file |
144+
| `acl_format` | string | No | Apache Common Log Format to format the access log entries, default:\"%h %l %u %t \\\"%r\\\" %>s %b \\\"%{Referer}i\\\" \\\"%{User-agent}i\\\" %{us}T" |
145+
| `syslog_address` | string | No | If target is 'syslog', specifies the syslog server address |
146+
| `syslog_protocol` | string | No | If target is 'syslog', specifies the syslog protocol (e.g., 'udp', 'tcp') |
147+
| `syslog_tag` | string | No | If target is 'syslog', specifies the syslog tag |
148+
| `syslog_facility` | string | No | If target is 'syslog', define the Syslog facility number, allowed values: 'kern', 'user', 'mail', 'daemon', 'auth', 'syslog', 'lpr', 'news', 'uucp', 'cron', 'authpriv', 'ftp', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5', 'local6', 'local7' |
149+
| `syslog_level` | string | No | If target is 'syslog', define the required syslog messages level, allowed values: 'debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency' |
150+
| `log_types` | array of strings | No | Define which log types to log to this target, allowed values: 'app', 'access' |
151+
152+
**Example of `log_targets`:**
153+
154+
```yaml
155+
log_targets:
156+
- log_target: file
157+
log_file: /var/log/dataplaneapi.log
158+
log_format: json
159+
log_level: debug
160+
log_types:
161+
- access
162+
- app
163+
- log_target: syslog
164+
syslog_address: 127.0.0.1:514
165+
syslog_protocol: udp
166+
syslog_tag: dataplaneapi
167+
syslog_facility: local0
168+
log_level: info
169+
log_types:
170+
- access
171+
- log_target: stdout
172+
log_format: text
173+
log_level: warning
174+
log_types:
175+
- access
176+
- app
177+
```
178+
179+
## Command-Line Overrides
180+
181+
Many of the configuration options available in the YAML file can be overridden by command-line arguments when starting the Data Plane API. This allows for flexibility in deployment and testing.
182+
183+
### CLI Argument Precedence
184+
185+
When a configuration option is set both in the YAML file and via a command-line argument, the command-line argument takes precedence.
186+
187+
### Common CLI Flags
188+
189+
- `-c`, `--config-file`: Overrides the `haproxy.config_file` option.
190+
- `-b`, `--haproxy-bin`: Overrides the `haproxy.haproxy_bin` option.
191+
- `-m`, `--master-runtime`: Overrides the `haproxy.master_runtime` option.
192+
- `-u`, `--userlist`: Overrides the `dataplaneapi.userlist.userlist` option.
193+
- `-d`, `--reload-delay`: Overrides the `haproxy.reload.reload_delay` option.
194+
- `-r`, `--reload-cmd`: Overrides the `haproxy.reload.reload_cmd` option.
195+
- `-s`, `--restart-cmd`: Overrides the `haproxy.reload.restart_cmd` option.
196+
- `-t`, `--transaction-dir`: Overrides the `dataplaneapi.transaction.transaction_dir` option.
197+
- `-n`, `--backups-number`: Overrides the `dataplaneapi.transaction.backups_number` option.
198+
- `-p`, `--maps-dir`: Overrides the `dataplaneapi.resources.maps_dir` option.
199+
- `-i`, `--show-system-info`: Overrides the `dataplaneapi.show_system_info` option.
200+
- `--disable-inotify`: Overrides the `dataplaneapi.disable_inotify` option.
201+
- `--pid-file`: Overrides the `dataplaneapi.pid_file` option.
202+
- `--debug-socket-path`: Overrides the `dataplaneapi.debug_socket_path` option.
203+
- `--uid`: Overrides the `dataplaneapi.uid` option.
204+
- `--gid`: Overrides the `dataplaneapi.gid` option.
205+
- `--userlist-file`: Overrides the `dataplaneapi.userlist.userlist_file` option.
206+
- `--status-cmd`: Overrides the `haproxy.reload.status_cmd` option.
207+
- `--service`: Overrides the `haproxy.reload.service_name` option.
208+
- `--reload-retention`: Overrides the `haproxy.reload.reload_retention` option.
209+
- `--reload-strategy`: Overrides the `haproxy.reload.reload_strategy` option.
210+
- `--validate-cmd`: Overrides the `haproxy.reload.validate_cmd` option.
211+
- `--backups-dir`: Overrides the `dataplaneapi.transaction.backups_dir` option.
212+
- `--max-open-transactions`: Overrides the `dataplaneapi.transaction.max_open_transactions` option.
213+
- `--ssl-certs-dir`: Overrides the `dataplaneapi.resources.ssl_certs_dir` option.
214+
- `--general-storage-dir`: Overrides the `dataplaneapi.resources.general_storage_dir` option.
215+
- `--dataplane-storage-dir`: Overrides the `dataplaneapi.resources.dataplane_storage_dir` option.
216+
- `--update-map-files`: Overrides the `dataplaneapi.resources.update_map_files` option.
217+
- `--update-map-files-period`: Overrides the `dataplaneapi.resources.update_map_files_period` option.
218+
- `--spoe-dir`: Overrides the `dataplaneapi.resources.spoe_dir` option.
219+
- `--spoe-transaction-dir`: Overrides the `dataplaneapi.resources.spoe_transaction_dir` option.
220+
- `--api-address`: Overrides the `dataplaneapi.advertised.api_address` option.
221+
- `--api-port`: Overrides the `dataplaneapi.advertised.api_port` option.
222+
- `--syslog-address`: Overrides the `log.syslog.syslog_address` option.
223+
- `--syslog-protocol`: Overrides the `log.syslog.syslog_protocol` option.
224+
- `--syslog-tag`: Overrides the `log.syslog.syslog_tag` option.
225+
- `--syslog-level`: Overrides the `log.syslog.syslog_level` option.
226+
- `--syslog-facility`: Overrides the `log.syslog.syslog_facility` option.
227+
- `--log-to`: Overrides the `log.log_to` option.
228+
- `--log-file`: Overrides the `log.log_file` option.
229+
- `--log-level`: Overrides the `log.log_level` option.
230+
- `--log-format`: Overrides the `log.log_format` option.
231+
- `--apache-common-log-format`: Overrides the `log.apache_common_log_format` option.
232+
- `--master-worker-mode`: Overrides the `haproxy.master_worker_mode` option.
233+
- `--delayed-start-max`: Overrides the `haproxy.delayed_start_max` option.
234+
- `--delayed-start-tick`: Overrides the `haproxy.delayed_start_tick` option.
235+
- `--fid`: Overrides the `haproxy.fid` option.
236+
237+
## Example Configuration
238+
239+
```yaml
240+
config_version: 2
241+
name: haproxy-dataplaneapi
242+
dataplaneapi:
243+
host: 0.0.0.0
244+
port: 5555
245+
scheme:
246+
- http
247+
users:
248+
name: admin
249+
passowrd: adminpwd
250+
insecure: true
251+
transaction:
252+
transaction_dir: /etc/haproxy/transactions
253+
backups_number: 10
254+
backups_dir: /etc/haproxy/backups
255+
max_open_transactions: 10
256+
resources:
257+
maps_dir: /etc/haproxy/maps
258+
ssl_certs_dir: /etc/haproxy/ssl
259+
general_storage_dir: /etc/haproxy/general
260+
spoe_dir: /etc/haproxy/spoe
261+
dataplane_storage_dir: /etc/haproxy/dataplane
262+
haproxy:
263+
config_file: /etc/haproxy/haproxy.cfg
264+
haproxy_bin: /usr/sbin/haproxy
265+
master_worker_mode: true
266+
master_runtime: /var/run/haproxy/master.sock
267+
reload:
268+
reload_delay: 5
269+
service_name: haproxy
270+
reload_strategy: systemd
271+
log_targets:
272+
- log_to: file
273+
log_file: /var/log/haproxy-dataplaneapi.log
274+
log_level: info
275+
log_types:
276+
- access
277+
- app
278+
```

‎configuration/examples/example-dataplaneapi.yaml

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,38 @@
1-
name: famous_condor
1+
config_version: 2
2+
name: haproxy-dataplaneapi
23
dataplaneapi:
34
host: 0.0.0.0
4-
port: 8080
5-
user: # Deprecated
6-
- name: admin
5+
port: 5555
6+
scheme:
7+
- http
8+
user:
9+
name: admin
10+
passowrd: adminpwd
711
insecure: true
8-
password: adminpwd
12+
transaction:
13+
transaction_dir: /etc/haproxy/transactions
14+
backups_number: 10
15+
backups_dir: /etc/haproxy/backups
16+
max_open_transactions: 10
917
resources:
1018
maps_dir: /etc/haproxy/maps
1119
ssl_certs_dir: /etc/haproxy/ssl
20+
general_storage_dir: /etc/haproxy/general
1221
spoe_dir: /etc/haproxy/spoe
22+
dataplane_storage_dir: /etc/haproxy/dataplane
1323
haproxy:
1424
config_file: /etc/haproxy/haproxy.cfg
15-
haproxy_bin: /usr/local/sbin/haproxy
25+
haproxy_bin: /usr/sbin/haproxy
26+
master_worker_mode: true
27+
master_runtime: /var/run/haproxy/master.sock
1628
reload:
17-
reload_strategy: custom
18-
reload_cmd: kill -SIGUSR2 1
19-
restart_cmd: kill -SIGUSR2 1
29+
reload_delay: 5
30+
service_name: haproxy
31+
reload_strategy: systemd
32+
log_targets:
33+
- log_to: file
34+
log_file: /var/log/haproxy-dataplaneapi.log
35+
log_level: info
36+
log_types:
37+
- access
38+
- app

0 commit comments

Comments
 (0)