summaryrefslogtreecommitdiffstats
path: root/packaging/docker/README.md
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2019-08-04 08:56:44 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2019-08-04 08:56:44 +0000
commit34f488f41ee820371159111bf621f11d0f54f669 (patch)
tree13eea1c3aa3d905ec929691bbf23d8b90bef1dcb /packaging/docker/README.md
parentAdding upstream version 1.16.0. (diff)
downloadnetdata-34f488f41ee820371159111bf621f11d0f54f669.tar.xz
netdata-34f488f41ee820371159111bf621f11d0f54f669.zip
Adding upstream version 1.16.1.upstream/1.16.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'packaging/docker/README.md')
-rw-r--r--packaging/docker/README.md69
1 files changed, 47 insertions, 22 deletions
diff --git a/packaging/docker/README.md b/packaging/docker/README.md
index 0bf416cd4..4e21918ec 100644
--- a/packaging/docker/README.md
+++ b/packaging/docker/README.md
@@ -24,9 +24,10 @@ This is good for an internal network or to quickly analyse a host.
```bash
docker run -d --name=netdata \
-p 19999:19999 \
+ -v /etc/passwd:/host/etc/passwd:ro \
+ -v /etc/group:/host/etc/group:ro \
-v /proc:/host/proc:ro \
-v /sys:/host/sys:ro \
- -v /var/run/docker.sock:/var/run/docker.sock:ro \
--cap-add SYS_PTRACE \
--security-opt apparmor=unconfined \
netdata/netdata
@@ -47,35 +48,57 @@ services:
security_opt:
- apparmor:unconfined
volumes:
+ - /etc/passwd:/host/etc/passwd:ro
+ - /etc/group:/host/etc/group:ro
- /proc:/host/proc:ro
- /sys:/host/sys:ro
- - /var/run/docker.sock:/var/run/docker.sock:ro
```
+If you don't want to use the apps.plugin functionality, you can remove the mounts of `/etc/passwd` and `/etc/group` (they are used to get proper user and group names for the monitored host) to get slightly better security.
+
### Docker container names resolution
-If you want to have your container names resolved by netdata, you need to do two things:
-1) Make netdata user be part of the group that owns the socket.
- To achieve that just add environment variable `PGID=[GROUP NUMBER]` to the netdata container,
- where `[GROUP NUMBER]` is practically the group id of the group assigned to the docker socket, on your host.
- This group number can be found by running the following (if socket group ownership is docker):
- ```bash
- grep docker /etc/group | cut -d ':' -f 3
- ```
-
-2) Change docker socket access level to read/write like so:
- from
- ```
- /var/run/docker.sock:/var/run/docker.sock:ro
- ```
-
- change to
- ```
- /var/run/docker.sock:/var/run/docker.sock:rw
- ```
+There are a few options for resolving container names within netdata. Some methods of doing so will allow root access to your machine from within the container. Please read the following carefully.
+
+#### Docker Socket Proxy (Safest Option)
+
+Deploy a Docker socket proxy that accepts and filter out requests using something like [HAProxy](https://docs.netdata.cloud/docs/running-behind-haproxy/) so that it restricts connections to read-only access to the CONTAINERS endpoint.
+
+The reason it's safer to expose the socket to the proxy is because netdata has a TCP port exposed outside the Docker network. Access to the proxy container is limited to only within the network.
+
+#### Giving group access to Docker Socket (Less safe)
**Important Note**: You should seriously consider the necessity of activating this option,
-as it grants to the netdata user access to the privileged socket connection of docker service
+as it grants to the netdata user access to the privileged socket connection of docker service and therefore your whole machine.
+
+If you want to have your container names resolved by Netdata, make the `netdata` user be part of the group that owns the socket.
+
+To achieve that just add environment variable `PGID=[GROUP NUMBER]` to the Netdata container,
+where `[GROUP NUMBER]` is practically the group id of the group assigned to the docker socket, on your host.
+
+This group number can be found by running the following (if socket group ownership is docker):
+
+```bash
+grep docker /etc/group | cut -d ':' -f 3
+```
+
+#### Running as root (Unsafe)
+
+**Important Note**: You should seriously consider the necessity of activating this option,
+as it grants to the netdata user access to the privileged socket connection of docker service and therefore your whole machine.
+
+```yaml
+version: '3'
+services:
+ netdata:
+ image: netdata/netdata
+ # ... rest of your config ...
+ volumes:
+ # ... other volumes ...
+ - /var/run/docker.sock:/var/run/docker.sock:ro
+ environment:
+ - DOCKER_USR=root
+```
### Pass command line options to Netdata
@@ -132,6 +155,8 @@ services:
security_opt:
- apparmor:unconfined
volumes:
+ - /etc/passwd:/host/etc/passwd:ro
+ - /etc/group:/host/etc/group:ro
- /proc:/host/proc:ro
- /sys:/host/sys:ro
- /var/run/docker.sock:/var/run/docker.sock:ro