| 1 | # Running Netdata behind Apache's mod_proxy |
| 2 | |
| 3 | Below, you can find instructions for configuring an apache server to: |
| 4 | |
| 5 | 1. Proxy a single Netdata via an HTTP and HTTPS virtual host. |
| 6 | 2. Dynamically proxy any number of Netdata servers. |
| 7 | 3. Add user authentication. |
| 8 | 4. Adjust Netdata settings to get optimal results. |
| 9 | |
| 10 | ## Requirements |
| 11 | |
| 12 | Make sure your apache has `mod_proxy` and `mod_proxy_http` installed and enabled. |
| 13 | |
| 14 | On Debian/Ubuntu systems, install apache, which already includes the two modules, using: |
| 15 | |
| 16 | ```sh |
| 17 | sudo apt-get install apache2 |
| 18 | ``` |
| 19 | |
| 20 | Enable them: |
| 21 | |
| 22 | ```sh |
| 23 | sudo a2enmod proxy |
| 24 | sudo a2enmod proxy_http |
| 25 | ``` |
| 26 | |
| 27 | Also, enable the rewrite module: |
| 28 | |
| 29 | ```sh |
| 30 | sudo a2enmod rewrite |
| 31 | ``` |
| 32 | |
| 33 | ## Netdata on an existing virtual host |
| 34 | |
| 35 | On any **existing** and already **working** apache virtual host, you can redirect requests for URL `/netdata/` to one or more Netdata servers. |
| 36 | |
| 37 | ### Proxy one Netdata, running on the same server apache runs |
| 38 | |
| 39 | Add the following on top of any existing virtual host. It will allow you to access Netdata as `http://virtual.host/netdata/`. |
| 40 | |
| 41 | ```text |
| 42 | <VirtualHost *:80> |
| 43 | |
| 44 | RewriteEngine On |
| 45 | ProxyRequests Off |
| 46 | ProxyPreserveHost On |
| 47 | |
| 48 | <Proxy *> |
| 49 | Require all granted |
| 50 | </Proxy> |
| 51 | |
| 52 | # Local Netdata server accessed with '/netdata/', at localhost:19999 |
| 53 | ProxyPass "/netdata/" "http://localhost:19999/" connectiontimeout=5 timeout=30 keepalive=on |
| 54 | ProxyPassReverse "/netdata/" "http://localhost:19999/" |
| 55 | |
| 56 | # if the user did not give the trailing /, add it |
| 57 | # for HTTP (if the virtualhost is HTTP, use this) |
| 58 | RewriteRule ^/netdata$ http://%{HTTP_HOST}/netdata/ [L,R=301] |
| 59 | # for HTTPS (if the virtualhost is HTTPS, use this) |
| 60 | #RewriteRule ^/netdata$ https://%{HTTP_HOST}/netdata/ [L,R=301] |
| 61 | |
| 62 | # rest of virtual host config here |
| 63 | |
| 64 | </VirtualHost> |
| 65 | ``` |
| 66 | |
| 67 | ### Proxy multiple Netdata running on multiple servers |
| 68 | |
| 69 | Add the following on top of any existing virtual host. It will allow you to access multiple Netdata as `http://virtual.host/netdata/HOSTNAME/`, where `HOSTNAME` is the hostname of any other Netdata server you have (to access the `localhost` Netdata, use `http://virtual.host/netdata/localhost/`). |
| 70 | |
| 71 | ```text |
| 72 | <VirtualHost *:80> |
| 73 | |
| 74 | RewriteEngine On |
| 75 | ProxyRequests Off |
| 76 | ProxyPreserveHost On |
| 77 | |
| 78 | <Proxy *> |
| 79 | Require all granted |
| 80 | </Proxy> |
| 81 | |
| 82 | # proxy any host, on port 19999 |
| 83 | ProxyPassMatch "^/netdata/([A-Za-z0-9\._-]+)/(.*)" "http://$1:19999/$2" connectiontimeout=5 timeout=30 keepalive=on |
| 84 | |
| 85 | # make sure the user did not forget to add a trailing / |
| 86 | # for HTTP (if the virtualhost is HTTP, use this) |
| 87 | RewriteRule "^/netdata/([A-Za-z0-9\._-]+)$" http://%{HTTP_HOST}/netdata/$1/ [L,R=301] |
| 88 | # for HTTPS (if the virtualhost is HTTPS, use this) |
| 89 | RewriteRule "^/netdata/([A-Za-z0-9\._-]+)$" https://%{HTTP_HOST}/netdata/$1/ [L,R=301] |
| 90 | |
| 91 | # rest of virtual host config here |
| 92 | |
| 93 | </VirtualHost> |
| 94 | ``` |
| 95 | |
| 96 | > IMPORTANT<br/> |
| 97 | > The above config allows your apache users to connect to port 19999 on any server on your network. |
| 98 | |
| 99 | If you want to control the servers your users can connect to, replace the `ProxyPassMatch` line with the following. This allows only `server1`, `server2`, `server3` and `server4`. |
| 100 | |
| 101 | ```text |
| 102 | ProxyPassMatch "^/netdata/(server1|server2|server3|server4)/(.*)" "http://$1:19999/$2" connectiontimeout=5 timeout=30 keepalive=on |
| 103 | ``` |
| 104 | |
| 105 | ## Netdata on a dedicated virtual host |
| 106 | |
| 107 | You can proxy Netdata through apache, using a dedicated apache virtual host. |
| 108 | |
| 109 | Create a new apache site: |
| 110 | |
| 111 | ```sh |
| 112 | nano /etc/apache2/sites-available/netdata.conf |
| 113 | ``` |
| 114 | |
| 115 | with this content: |
| 116 | |
| 117 | ```text |
| 118 | <VirtualHost *:80> |
| 119 | |
| 120 | ProxyRequests Off |
| 121 | ProxyPreserveHost On |
| 122 | |
| 123 | ServerName netdata.domain.tld |
| 124 | |
| 125 | <Proxy *> |
| 126 | Require all granted |
| 127 | </Proxy> |
| 128 | |
| 129 | ProxyPass "/" "http://localhost:19999/" connectiontimeout=5 timeout=30 keepalive=on |
| 130 | ProxyPassReverse "/" "http://localhost:19999/" |
| 131 | |
| 132 | ErrorLog ${APACHE_LOG_DIR}/netdata-error.log |
| 133 | CustomLog ${APACHE_LOG_DIR}/netdata-access.log combined |
| 134 | |
| 135 | </VirtualHost> |
| 136 | ``` |
| 137 | |
| 138 | Enable the VirtualHost: |
| 139 | |
| 140 | ```sh |
| 141 | sudo a2ensite netdata.conf && service apache2 reload |
| 142 | ``` |
| 143 | |
| 144 | ## Netdata proxy in Plesk |
| 145 | |
| 146 | _Assuming the main goal is to make Netdata running in HTTPS._ |
| 147 | |
| 148 | 1. Make a subdomain for Netdata on which you enable and force HTTPS - You can use a free Let's Encrypt certificate |
| 149 | 2. Go to "Apache & nginx Settings", and in the following section, add: |
| 150 | |
| 151 | ```text |
| 152 | RewriteEngine on |
| 153 | RewriteRule (.*) http://localhost:19999/$1 [P,L] |
| 154 | ``` |
| 155 | |
| 156 | 3. Optional: If your server is remote, then replace "localhost" with your actual hostname or IP, it just works. |
| 157 | |
| 158 | Repeat the operation for as many servers as you need. |
| 159 | |
| 160 | ## Enable Basic Auth |
| 161 | |
| 162 | :::tip Simpler Alternative |
| 163 | |
| 164 | If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no htpasswd files or Apache auth configuration needed. |
| 165 | |
| 166 | ::: |
| 167 | |
| 168 | If you wish to add an authentication (user/password) to access your Netdata, do these: |
| 169 | |
| 170 | Install the package `apache2-utils`. On Debian/Ubuntu run `sudo apt-get install apache2-utils`. |
| 171 | |
| 172 | Then, generate password for user `netdata`, using `htpasswd -c /etc/apache2/.htpasswd netdata` |
| 173 | |
| 174 | **Apache 2.2 Example:**\ |
| 175 | Modify the virtual host with these: |
| 176 | |
| 177 | ```text |
| 178 | # replace the <Proxy *> section |
| 179 | <Proxy *> |
| 180 | Order deny,allow |
| 181 | Allow from all |
| 182 | </Proxy> |
| 183 | |
| 184 | # add a <Location /netdata/> section |
| 185 | <Location /netdata/> |
| 186 | AuthType Basic |
| 187 | AuthName "Protected site" |
| 188 | AuthUserFile /etc/apache2/.htpasswd |
| 189 | Require valid-user |
| 190 | Order deny,allow |
| 191 | Allow from all |
| 192 | </Location> |
| 193 | ``` |
| 194 | |
| 195 | Specify `Location /` if Netdata is running on dedicated virtual host. |
| 196 | |
| 197 | **Apache 2.4 (dedicated virtual host) Example:** |
| 198 | |
| 199 | ```text |
| 200 | <VirtualHost *:80> |
| 201 | RewriteEngine On |
| 202 | ProxyRequests Off |
| 203 | ProxyPreserveHost On |
| 204 | |
| 205 | ServerName netdata.domain.tld |
| 206 | |
| 207 | <Proxy *> |
| 208 | AllowOverride None |
| 209 | AuthType Basic |
| 210 | AuthName "Protected site" |
| 211 | AuthUserFile /etc/apache2/.htpasswd |
| 212 | Require valid-user |
| 213 | </Proxy> |
| 214 | |
| 215 | ProxyPass "/" "http://localhost:19999/" connectiontimeout=5 timeout=30 keepalive=on |
| 216 | ProxyPassReverse "/" "http://localhost:19999/" |
| 217 | |
| 218 | ErrorLog ${APACHE_LOG_DIR}/netdata-error.log |
| 219 | CustomLog ${APACHE_LOG_DIR}/netdata-access.log combined |
| 220 | </VirtualHost> |
| 221 | ``` |
| 222 | |
| 223 | Note: Changes are applied by reloading or restarting Apache. |
| 224 | |
| 225 | ## Configuration of Content Security Policy |
| 226 | |
| 227 | If you want to enable CSP within your Apache, you should consider some special requirements for the headers. Modify your configuration like that: |
| 228 | |
| 229 | ```text |
| 230 | Header always set Content-Security-Policy "default-src http: 'unsafe-inline' 'self' 'unsafe-eval'; script-src http: 'unsafe-inline' 'self' 'unsafe-eval'; style-src http: 'self' 'unsafe-inline'" |
| 231 | ``` |
| 232 | |
| 233 | Note: Changes are applied by reloading or restarting Apache. |
| 234 | |
| 235 | ## Using Netdata with Apache's `mod_evasive` module |
| 236 | |
| 237 | The `mod_evasive` Apache module helps system administrators protect their web server from brute force and distributed |
| 238 | denial-of-service attack (DDoS) attacks. |
| 239 | |
| 240 | Because Netdata sends a request to the web server for every chart update, it's normal to create 20–30 requests per |
| 241 | second, per client. If you're using `mod_evasive` on your Apache web server, this volume of requests will trigger the |
| 242 | module's protection, and your dashboard will become unresponsive. You may even begin to see 403 errors. |
| 243 | |
| 244 | To mitigate this issue, you will need to change the value of the `DOSPageCount` option in your `mod_evasive.conf` file, |
| 245 | which can typically be found at `/etc/httpd/conf.d/mod_evasive.conf` or `/etc/apache2/mods-enabled/evasive.conf`. |
| 246 | |
| 247 | The `DOSPageCount` option sets the limit of the number of requests from a single IP address for the same page per page |
| 248 | interval, which is usually 1 second. The default value is `2` requests per second. Netdata's typical usage will |
| 249 | exceed that threshold, and `mod_evasive` will add your IP address to a blocklist. |
| 250 | |
| 251 | Our users have found success by setting `DOSPageCount` to `30`. Try this and raise the value if you continue to see 403 |
| 252 | errors while accessing the dashboard. |
| 253 | |
| 254 | ```text |
| 255 | DOSPageCount 30 |
| 256 | ``` |
| 257 | |
| 258 | Restart Apache with `sudo systemctl restart apache2`, or the appropriate method to restart services on your system, to |
| 259 | reload its configuration with your new values. |
| 260 | |
| 261 | ### Virtual host |
| 262 | |
| 263 | To adjust the `DOSPageCount` for a specific virtual host, open your virtual host config, which can be found at |
| 264 | `/etc/httpd/conf/sites-available/my-domain.conf` or `/etc/apache2/sites-available/my-domain.conf` and add the |
| 265 | following: |
| 266 | |
| 267 | ```text |
| 268 | <VirtualHost *:80> |
| 269 | ... |
| 270 | # Increase the DOSPageCount to prevent 403 errors and IP addresses being blocked. |
| 271 | <IfModule mod_evasive20.c> |
| 272 | DOSPageCount 30 |
| 273 | </IfModule> |
| 274 | </VirtualHost> |
| 275 | ``` |
| 276 | |
| 277 | See issues [#2011](https://github.com/netdata/netdata/issues/2011) and |
| 278 | [#7658](https://github.com/netdata/netdata/issues/7568) for more information. |
| 279 | |
| 280 | ## Netdata configuration |
| 281 | |
| 282 | You might edit `/etc/netdata/netdata.conf` to optimize your setup a bit. For applying these changes, you need to restart Netdata. |
| 283 | |
| 284 | ### Response compression |
| 285 | |
| 286 | If you plan to use Netdata exclusively via apache, you can gain some performance by preventing double compression of its output (Netdata compresses its response, apache re-compresses it) by editing `/etc/netdata/netdata.conf` and setting: |
| 287 | |
| 288 | ```text |
| 289 | [web] |
| 290 | enable gzip compression = no |
| 291 | ``` |
| 292 | |
| 293 | Once you disable compression at Netdata (and restart it), please verify you receive compressed responses from apache (it is important to receive compressed responses - the charts will be more snappy). |
| 294 | |
| 295 | ### Limit direct access to Netdata |
| 296 | |
| 297 | You would also need to instruct Netdata to listen only on `localhost`, `127.0.0.1` or `::1`. |
| 298 | |
| 299 | ```text |
| 300 | [web] |
| 301 | bind to = localhost |
| 302 | ``` |
| 303 | |
| 304 | or |
| 305 | |
| 306 | ```text |
| 307 | [web] |
| 308 | bind to = 127.0.0.1 |
| 309 | ``` |
| 310 | |
| 311 | or |
| 312 | |
| 313 | ```text |
| 314 | [web] |
| 315 | bind to = ::1 |
| 316 | ``` |
| 317 | |
| 318 | You can also use a unix domain socket. This will also provide a faster route between apache and Netdata: |
| 319 | |
| 320 | ```text |
| 321 | [web] |
| 322 | bind to = unix:/tmp/netdata.sock |
| 323 | ``` |
| 324 | |
| 325 | Apache 2.4.24+ can’t read from `/tmp` so create your socket in `/var/run/netdata` |
| 326 | |
| 327 | ```text |
| 328 | [web] |
| 329 | bind to = unix:/var/run/netdata/netdata.sock |
| 330 | ``` |
| 331 | |
| 332 | At the apache side, prepend the second argument to `ProxyPass` with `unix:/tmp/netdata.sock|`, like this: |
| 333 | |
| 334 | ```text |
| 335 | ProxyPass "/netdata/" "unix:/tmp/netdata.sock|http://localhost:19999/" connectiontimeout=5 timeout=30 keepalive=on |
| 336 | ``` |
| 337 | |
| 338 | If your apache server is not on localhost, you can set: |
| 339 | |
| 340 | ```text |
| 341 | [web] |
| 342 | bind to = * |
| 343 | allow connections from = IP_OF_APACHE_SERVER |
| 344 | ``` |
| 345 | |
| 346 | `allow connections from` accepts [Netdata simple patterns](/src/libnetdata/simple_pattern/README.md) to match against the connection IP address. |
| 347 | |
| 348 | ## Prevent the double access.log |
| 349 | |
| 350 | Apache logs accesses and Netdata logs them too. You can prevent Netdata from generating its access log, by setting this in `/etc/netdata/netdata.conf`: |
| 351 | |
| 352 | ```text |
| 353 | [logs] |
| 354 | access = off |
| 355 | ``` |
| 356 | |
| 357 | ## Troubleshooting mod_proxy |
| 358 | |
| 359 | Make sure the requests reach Netdata, by examining `/var/log/netdata/access.log`. |
| 360 | |
| 361 | 1. if the requests don’t reach Netdata, your apache doesn’t forward them. |
| 362 | 2. if the requests reach Netdata but the URLs are wrong, you haven’t re-written them properly. |