Add netdata haproxy documentation page (#6454)
#### Summary Add a documentation page for running netdata via HAproxy. The example includes: A simple configuration over http A more complex example over https Instructions on how to use HTTP authentication A full configuration example Component Name docs #### Additional Information Fixes #6446
John committed
Jul 22, 2019 at 23:56 UTC
1e7b913d4c97b19a5d95988e1f36a47e12a7adf1
2 files changed
+281
docs/Running-behind-haproxy.md
new
+280
@@ -0,0 +1,280 @@
1
+# Netdata via HAProxy
2
+
3
+> HAProxy is a free, very fast and reliable solution offering high availability, load balancing, and proxying for TCP and HTTP-based applications. It is particularly suited for very high traffic web sites and powers quite a number of the world's most visited ones.
4
+
5
+If Netdata is running on a host running HAProxy, rather than connecting to Netdata from a port number, a domain name can be pointed at HAProxy, and HAProxy can redirect connections to the Netdata port. This can make it possible to connect to Netdata at https://example.com or https://example.com/netdata/, which is a much nicer experience then http://example.com:19999.
6
+
7
+To proxy requests from [HAProxy](https://github.com/haproxy/haproxy) to Netdata, the following configuration can be used:
8
+
9
+## Default Configuration
10
+
11
+For all examples, set the mode to `http`
12
+
13
+```
14
+defaults
15
+ mode http
16
+```
17
+
18
+## Simple Configuration
19
+
20
+A simple example where the base URL, say http://example.com, is used with no subpath:
21
+
22
+### Frontend
23
+
24
+Create a frontend to recieve the request.
25
+
26
+```
27
+frontend http_frontend
28
+ ## HTTP ipv4 and ipv6 on all ips ##
29
+ bind :::80 v4v6
30
+
31
+ default_backend netdata_backend
32
+```
33
+
34
+### Backend
35
+
36
+Create the Netdata backend which will send requests to port `19999`.
37
+
38
+```
39
+backend netdata_backend
40
+ option forwardfor
41
+ server netdata_local 127.0.0.1:19999
42
+
43
+ http-request set-header Host %[src]
44
+ http-request set-header X-Forwarded-For %[src]
45
+ http-request set-header X-Forwarded-Port %[dst_port]
46
+ http-request set-header Connection "keep-alive"
47
+```
48
+
49
+## Configuration with subpath
50
+
51
+A example where the base URL is used with a subpath `/netdata/`:
52
+
53
+### Frontend
54
+
55
+To use a subpath, create an ACL, which will set a variable based on the subpath.
56
+
57
+```
58
+frontend http_frontend
59
+ ## HTTP ipv4 and ipv6 on all ips ##
60
+ bind :::80 v4v6
61
+
62
+ # URL begins with /netdata
63
+ acl is_netdata url_beg /netdata
64
+
65
+ # if trailing slash is missing, redirect to /netdata/
66
+ http-request redirect scheme https drop-query append-slash if is_netdata ! { path_beg /netdata/ }
67
+
68
+ ## Backends ##
69
+ use_backend netdata_backend if is_netdata
70
+
71
+ # Other requests go here (optional)
72
+ # put netdata_backend here if no others are used
73
+ default_backend www_backend
74
+```
75
+
76
+### Backend
77
+
78
+Same as simple example, expept remove `/netdata/` with regex.
79
+
80
+```
81
+backend netdata_backend
82
+ option forwardfor
83
+ server netdata_local 127.0.0.1:19999
84
+
85
+ http-request set-path %[path,regsub(^/netdata/,/)]
86
+
87
+ http-request set-header Host %[src]
88
+ http-request set-header X-Forwarded-For %[src]
89
+ http-request set-header X-Forwarded-Port %[dst_port]
90
+ http-request set-header Connection "keep-alive"
91
+```
92
+
93
+## Using TLS communication
94
+
95
+TLS can be used by adding port `443` and a cert to the frontend. This example will only use Netdata if host matches example.com (replace with your domain).
96
+
97
+### Frontend
98
+
99
+This frontend uses a certificate list.
100
+
101
+```
102
+frontend https_frontend
103
+ ## HTTP ##
104
+ bind :::80 v4v6
105
+ # Redirect all HTTP traffic to HTTPS with 301 redirect
106
+ redirect scheme https code 301 if !{ ssl_fc }
107
+
108
+ ## HTTPS ##
109
+ # Bind to all v4/v6 addresses, use a list of certs in file
110
+ bind :::443 v4v6 ssl crt-list /etc/letsencrypt/certslist.txt
111
+
112
+ ## ACL ##
113
+ # Optionally check host for Netdata
114
+ acl is_example_host hdr_sub(host) -i example.com
115
+
116
+ ## Backends ##
117
+ use_backend netdata_backend if is_example_host
118
+ # Other requests go here (optional)
119
+ default_backend www_backend
120
+```
121
+
122
+In the cert list file place a mapping from a certificate file to the domain used:
123
+
124
+`/etc/letsencrypt/certslist.txt`:
125
+
126
+```
127
+example.com /etc/letsencrypt/live/example.com/example.com.pem
128
+```
129
+
130
+The file `/etc/letsencrypt/live/example.com/example.com.pem` should contain the key and certificate (in that order) concatenated into a `.pem` file.:
131
+
132
+```
133
+$ cat /etc/letsencrypt/live/example.com/fullchain.pem \
134
+ /etc/letsencrypt/live/example.com/privkey.pem > \
135
+ /etc/letsencrypt/live/example.com/example.com.pem
136
+```
137
+
138
+### Backend
139
+
140
+Same as simple, except set protocol `https`.
141
+
142
+```
143
+backend netdata_backend
144
+ option forwardfor
145
+ server netdata_local 127.0.0.1:19999
146
+
147
+ http-request add-header X-Forwarded-Proto https
148
+ http-request set-header Host %[src]
149
+ http-request set-header X-Forwarded-For %[src]
150
+ http-request set-header X-Forwarded-Port %[dst_port]
151
+ http-request set-header Connection "keep-alive"
152
+```
153
+
154
+## Enable authentication
155
+
156
+To use basic HTTP Authentication, create a authentication list:
157
+
158
+```
159
+# HTTP Auth
160
+userlist basic-auth-list
161
+ group is-admin
162
+ # Plaintext password
163
+ user admin password passwordhere groups is-admin
164
+```
165
+
166
+You can create a hashed password using the `mkpassword` utility.
167
+
168
+```
169
+$ printf "passwordhere" | mkpasswd --stdin --method=sha-256
170
+$5$l7Gk0VPIpKO$f5iEcxvjfdF11khw.utzSKqP7W.0oq8wX9nJwPLwzy1
171
+```
172
+
173
+Replace `passwordhere` with hash:
174
+
175
+```
176
+user admin password $5$l7Gk0VPIpKO$f5iEcxvjfdF11khw.utzSKqP7W.0oq8wX9nJwPLwzy1 groups is-admin
177
+```
178
+
179
+Now add at the top of the backend:
180
+
181
+```
182
+acl devops-auth http_auth_group(basic-auth-list) is-admin
183
+http-request auth realm netdata_local unless devops-auth
184
+```
185
+
186
+## Full Example
187
+
188
+Full example configuration with HTTP auth over TLS with subpath:
189
+
190
+```
191
+global
192
+ maxconn 20000
193
+
194
+ log /dev/log local0
195
+ log /dev/log local1 notice
196
+ user haproxy
197
+ group haproxy
198
+ pidfile /run/haproxy.pid
199
+
200
+ stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
201
+ stats timeout 30s
202
+ daemon
203
+
204
+ tune.ssl.default-dh-param 4096 # Max size of DHE key
205
+
206
+ # Default ciphers to use on SSL-enabled listening sockets.
207
+ ssl-default-bind-ciphers ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:RSA+AESGCM:RSA+AES:!aNULL:!MD5:!DSS
208
+ ssl-default-bind-options no-sslv3
209
+
210
+defaults
211
+ log global
212
+ mode http
213
+ option httplog
214
+ option dontlognull
215
+ timeout connect 5000
216
+ timeout client 50000
217
+ timeout server 50000
218
+ errorfile 400 /etc/haproxy/errors/400.http
219
+ errorfile 403 /etc/haproxy/errors/403.http
220
+ errorfile 408 /etc/haproxy/errors/408.http
221
+ errorfile 500 /etc/haproxy/errors/500.http
222
+ errorfile 502 /etc/haproxy/errors/502.http
223
+ errorfile 503 /etc/haproxy/errors/503.http
224
+ errorfile 504 /etc/haproxy/errors/504.http
225
+
226
+frontend https_frontend
227
+ ## HTTP ##
228
+ bind :::80 v4v6
229
+ # Redirect all HTTP traffic to HTTPS with 301 redirect
230
+ redirect scheme https code 301 if !{ ssl_fc }
231
+
232
+ ## HTTPS ##
233
+ # Bind to all v4/v6 addresses, use a list of certs in file
234
+ bind :::443 v4v6 ssl crt-list /etc/letsencrypt/certslist.txt
235
+
236
+ ## ACL ##
237
+ # Optionally check host for Netdata
238
+ acl is_example_host hdr_sub(host) -i example.com
239
+ acl is_netdata url_beg /netdata
240
+
241
+ http-request redirect scheme https drop-query append-slash if is_netdata ! { path_beg /netdata/ }
242
+
243
+ ## Backends ##
244
+ use_backend netdata_backend if is_example_host is_netdata
245
+ default_backend www_backend
246
+
247
+# HTTP Auth
248
+userlist basic-auth-list
249
+ group is-admin
250
+ # Hashed password
251
+ user admin password $5$l7Gk0VPIpKO$f5iEcxvjfdF11khw.utzSKqP7W.0oq8wX9nJwPLwzy1 groups is-admin
252
+
253
+## Default server(s) (optional)##
254
+backend www_backend
255
+ mode http
256
+ balance roundrobin
257
+ timeout connect 5s
258
+ timeout server 30s
259
+ timeout queue 30s
260
+
261
+ http-request add-header 'X-Forwarded-Proto: https'
262
+ server other_server 111.111.111.111:80 check
263
+
264
+backend netdata_backend
265
+ acl devops-auth http_auth_group(basic-auth-list) is-admin
266
+ http-request auth realm netdata_local unless devops-auth
267
+
268
+ option forwardfor
269
+ server netdata_local 127.0.0.1:19999
270
+
271
+ http-request set-path %[path,regsub(^/netdata/,/)]
272
+
273
+ http-request add-header X-Forwarded-Proto https
274
+ http-request set-header Host %[src]
275
+ http-request set-header X-Forwarded-For %[src]
276
+ http-request set-header X-Forwarded-Port %[dst_port]
277
+ http-request set-header Connection "keep-alive"
278
+```
279
+
280
+[]()
docs/generator/buildyaml.sh
+1
@@ -163,6 +163,7 @@ echo -ne " - Running behind another web server:
163
- 'docs/Running-behind-apache.md'
164
- 'docs/Running-behind-lighttpd.md'
165
- 'docs/Running-behind-caddy.md'
166
+ - 'docs/Running-behind-haproxy.md'
167
"
168
#navpart 2 system
169
navpart 2 database