diff --git a/docs/20_Checks/check_docker_io.md b/docs/20_Checks/check_docker_io.md new file mode 100644 index 0000000000000000000000000000000000000000..76b34f8e0cddf64f6b74288465c44a23e2d284e8 --- /dev/null +++ b/docs/20_Checks/check_docker_io.md @@ -0,0 +1,123 @@ +## CHECK_DOCKER_IO + +Script: `check_docker_io` + +**check_docker_stats** shows the docker net io total and for each container. +This check sends performance data. + +The first implemented measurement is the network io. + +This check starts the docker CLI and might be slow (a few seconds). + +## Requirements + +* `docker` Docker must be installed +* `jq` must be installed - commandline JSON processor +* `bc` must be installed - an arbitrary precision calculator language +* sudo permissions on docker command + +```txt +icingaclient ALL=(ALL) NOPASSWD:SETENV: /usr/bin/docker +``` + +## Standalone installation + +From this repository ypu need next to this script: + +* `inc_pluginfunctions` shared function for all IML checks written in bash +* `inc_dockerfunctions.sh` + +## Rootless docker + +It works with docker setups as root and can handle rootless docker instances. + +To bring it up and running with an unpriviledged icinga user it must be able to access docker. Copy the docker binary eg. from /home/dockeruser/bin/docker to /usr/bin/. Then use the parameter `-p /usr/bin`. + +If DOCKER_HOST is not set then the docker socket is detected from a running docker instance and will be fetched from the process list. + +## Syntax + +```txt +______________________________________________________________________ + +CHECK_DOCKER_IO +v0.1 + +(c) Institute for Medical Education - University of Bern +Licence: GNU GPL 3 + +https://os-docs.iml.unibe.ch/icinga-checks/Checks/check_docker_io.html +______________________________________________________________________ + +Show IO data of all docker containers + +USAGE: + check_docker_io [OPTIONS] + +OPTIONS: + + General: + -h, --help this help + + Connect to docker: + -p, --path Custom directory for docker binary + -t, --target Custom docker target; value for DOCKER_HOST + Needed only if Docker does not run on a unix socket or + multiple users run a rootless docker daemon. + + mode: + -m, --mode MODE Mode what kind of information to show. + The output of container list is sorted by the maximum + value first. + + netio sum of netio of all containers IN and OUT + +EXAMPLES: + check_docker_io -m netio + Show netio of all docker containers + +``` + +### Parameters + +None. + +## Examples + +### Network io + +`$ ./check_docker_io -m netio` + +```txt +OK: Docker Network I/O of all containers: 0.00 MB/s IN .. 0.00 MB/s OUT +portainer_agent.1cnjqw9p0nlmpaij393abu0ng.rwy5mv629o0yxonz5f6krasz5 5670551 36804 392 B/s 2 B/s +morpheus-live_morpheus-live.2.w1umgrc21kvinl6h2x2cqdkze 55671295 13944 0 B/s 0 B/s +morpheus-live_morpheus-live.1.10npyt2qnb1kzvta851i9mtvd 54929047 12883 0 B/s 0 B/s +morpheus-demo_morpheus-demo.1.nsf410w59q9g1an7iyf0j12lr 161951 1620 0 B/s 0 B/s +swarm_proxy_reverse-proxy.1.hw7snlg5i0sudyh58ydf02rtc 498606567 4208586 455 B/s 5 B/s +swarm_proxy_memcached.1.c8gimogel0k9iffffiyw3k9l4 11679831 167671 16 B/s 0 B/s +whoami_whoami.1.mguqldgk3pxuqsuw1ir0d5xjz 155845 2027 0 B/s 0 B/s +portainer_monitoring_se_node-exporter.1cnjqw9p0nlmpaij393abu0ng.ncfvhpy81tq5pp9i9o6qzs2ih 32668084 301076 34 B/s 0 B/s +portainer_monitoring_se_cadvisor.1cnjqw9p0nlmpaij393abu0ng.lr7xkpgdu43lkihcr0agj0vh6 88027743 1139668 93 B/s 1 B/s + |rx=990;; tx=10;; +``` + +## Troubleshooting + +### Missing environment + +```txt +sudo: sorry, you are not allowed to preserve the environment +UNKNOWN: No data. Unable to fetch Docker information. +``` + +Solution: you did not set SETENV in the sudoers config file + +icingaclient ALL=(ALL) NOPASSWD:**SETENV:** /usr/bin/docker + +### Docker not found + +If you get an error message that docker was not found then it is not reachable in ofe of the directories of $PATH. +This can happen especialy in rootless docker instances. + +Solution: Use the parameter `-p /usr/bin` to define a target. Copy the docker binary there.