@cryptotaxi247 / netdata-1 / commits / 97552e309

Add document explaining how to proxy Netdata via H2O (#13266)

* Add document explaining how to proxy Netdata via H2O * Fix typos. * Update Running-behind-h2o.md Co-authored-by: DShreve2 <david@netdata.cloud>

Austin S. Hemmelgarn committed Jul 12, 2022 at 21:04 UTC 97552e30963e034dac51ac2c233426dc32a64790
1 file changed +183
docs/Running-behind-h2o.md new
+183
@@ -0,0 +1,183 @@
1 +<!--
2 +title: "Running Netdata behind H2O"
3 +custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/Running-behind-h2o.md
4 +-->
5 +
6 +# Running Netdata behind H2O
7 +
8 +[H2O](https://h2o.examp1e.net/) is a new generation HTTP server that provides quicker response to users with less CPU utilization when compared to older generation of web servers.
9 +
10 +It is notable for having much simpler configuration than many popular HTTP servers, low resource requirements, and integrated native support for many things that other HTTP servers may need special setup to use.
11 +
12 +## Why H2O
13 +
14 +- Sane configuration defaults mean that typical configurations are very minimalistic and easy to work with.
15 +
16 +- Native support for HTTP/2 provides improved performance when accessing the Netdata dashboard remotely.
17 +
18 +- Password protect access to the Netdata dashboard without requiring Netdata Cloud.
19 +
20 +## H2O configuration file.
21 +
22 +On most systems, the H2O configuration is found under `/etc/h2o`. H2O uses [YAML 1.1](https://yaml.org/spec/1.1/), with a few special extensions, for it’s configuration files, with the main configuration file being `/etc/h2o/h2o.conf`.
23 +
24 +You can edit the H2O configuration file with Nano, Vim or any other text editors with which you are comfortable.
25 +
26 +After making changes to the configuration files, perform the following:
27 +
28 +- Test the configuration with `h2o -m test -c /etc/h2o/h2o.conf`
29 +
30 +- Restart H2O to apply tha changes with `/etc/init.d/h2o restart` or `service h2o restart`
31 +
32 +## Ways to access Netdata via H2O
33 +
34 +### As a virtual host
35 +
36 +With this method instead of `SERVER_IP_ADDRESS:19999`, the Netdata dashboard can be accessed via a human-readable URL such as `netdata.example.com` used in the configuration below.
37 +
38 +```yaml
39 +hosts:
40 + netdata.example.com:
41 + listen:
42 + port: 80
43 + paths:
44 + /:
45 + proxy.preserve-host: ON
46 + proxy.reverse.url: http://127.0.0.1:19999
47 +```
48 +
49 +### As a subfolder of an existing virtual host
50 +
51 +This method is recommended when Netdata is to be served from a subfolder (or directory).
52 +In this case, the virtual host `netdata.example.com` already exists and Netdata has to be accessed via `netdata.example.com/netdata/`.
53 +
54 +```yaml
55 +hosts:
56 + netdata.example.com:
57 + listen:
58 + port: 80
59 + paths:
60 + /netdata:
61 + redirect:
62 + status: 301
63 + url: /netdata/
64 + /netdata/:
65 + proxy.preserve-host: ON
66 + proxy.reverse.url: http://127.0.0.1:19999
67 +```
68 +
69 +### As a subfolder for multiple Netdata servers, via one H2O instance
70 +
71 +This is the recommended configuration when one H2O instance will be used to manage multiple Netdata servers via subfolders.
72 +
73 +```yaml
74 +hosts:
75 + netdata.example.com:
76 + listen:
77 + port: 80
78 + paths:
79 + /netdata/server1:
80 + redirect:
81 + status: 301
82 + url: /netdata/server1/
83 + /netdata/server1/:
84 + proxy.preserve-host: ON
85 + proxy.reverse.url: http://198.51.100.1:19999
86 + /netdata/server2:
87 + redirect:
88 + status: 301
89 + url: /netdata/server2/
90 + /netdata/server2/:
91 + proxy.preserve-host: ON
92 + proxy.reverse.url: http://198.51.100.2:19999
93 +```
94 +
95 +Of course you can add as many backend servers as you like.
96 +
97 +Using the above, you access Netdata on the backend servers, like this:
98 +
99 +- `http://netdata.example.com/netdata/server1/` to reach Netdata on `198.51.100.1:19999`
100 +- `http://netdata.example.com/netdata/server2/` to reach Netdata on `198.51.100.2:19999`
101 +
102 +### Encrypt the communication between H2O and Netdata
103 +
104 +In case Netdata's web server has been [configured to use TLS](/web/server/README.md#enabling-tls-support), it is
105 +necessary to specify inside the H2O configuration that the final destination is using TLS. To do this, change the
106 +`http://` on the `proxy.reverse.url` line in your H2O configuration with `https://`
107 +
108 +### Enable authentication
109 +
110 +Create an authentication file to enable basic authentication via H2O, this secures your Netdata dashboard.
111 +
112 +If you don't have an authentication file, you can use the following command:
113 +
114 +```sh
115 +printf "yourusername:$(openssl passwd -apr1)" > /etc/h2o/passwords
116 +```
117 +
118 +And then add a basic authentication handler to each path definition:
119 +
120 +```yaml
121 +hosts:
122 + netdata.example.com:
123 + listen:
124 + port: 80
125 + paths:
126 + /:
127 + mruby.handler: |
128 + require "htpasswd.rb"
129 + Htpasswd.new("/etc/h2o/passwords", "netdata.example.com")
130 + proxy.preserve-host: ON
131 + proxy.reverse.url: http://127.0.0.1:19999
132 +```
133 +
134 +For more information on using basic authentication with H2O, see [their official documentation](https://h2o.examp1e.net/configure/basic_auth.html).
135 +
136 +## Limit direct access to Netdata
137 +
138 +If your H2O server is on `localhost`, you can use this to ensure external access is only possible through H2O:
139 +
140 +```
141 +[web]
142 + bind to = 127.0.0.1 ::1
143 +```
144 +
145 +---
146 +
147 +You can also use a unix domain socket. This will provide faster communication between H2O and Netdata as well:
148 +
149 +```
150 +[web]
151 + bind to = unix:/run/netdata/netdata.sock
152 +```
153 +
154 +In the H2O configuration, use a line like the following to connect to Netdata via the unix socket:
155 +
156 +```yaml
157 +proxy.reverse.url http://[unix:/run/netdata/netdata.sock]
158 +```
159 +
160 +---
161 +
162 +If your H2O server is not on localhost, you can set:
163 +
164 +```
165 +[web]
166 + bind to = *
167 + allow connections from = IP_OF_H2O_SERVER
168 +```
169 +
170 +*note: Netdata v1.9+ support `allow connections from`*
171 +
172 +`allow connections from` accepts [Netdata simple patterns](/libnetdata/simple_pattern/README.md) to match against
173 +the connection IP address.
174 +
175 +## Prevent the double access.log
176 +
177 +H2O logs accesses and Netdata logs them too. You can prevent Netdata from generating its access log, by setting
178 +this in `/etc/netdata/netdata.conf`:
179 +
180 +```
181 +[global]
182 + access log = none
183 +```