From 0a4674da2e19a5dc0f8e149839329d27ddeaf632 Mon Sep 17 00:00:00 2001 From: Andrew Cholakian Date: Thu, 19 Dec 2019 10:47:28 -0600 Subject: [PATCH] [Heartbeat] Add docs for rootless pings (#15194) We missed adding these docs in #13795 (cherry picked from commit 2c94e7205233c2a4dbfb25b4d0c7feb7eaa5181a) --- heartbeat/docs/heartbeat-options.asciidoc | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/heartbeat/docs/heartbeat-options.asciidoc b/heartbeat/docs/heartbeat-options.asciidoc index 7f631bd47d3..221af5c0502 100644 --- a/heartbeat/docs/heartbeat-options.asciidoc +++ b/heartbeat/docs/heartbeat-options.asciidoc @@ -87,7 +87,7 @@ options that are specific to that monitor type. The type of monitor to run. One of: * `icmp`: Uses an ICMP (v4 and v6) Echo Request to ping the configured hosts. -Requires root access. See <>. +Requires special permissions or root access. See <>. * `tcp`: Connects via TCP and optionally verifies the endpoint by sending and/or receiving a custom payload. See <>. * `http`: Connects via HTTP and optionally verifies that the host returns the @@ -224,7 +224,15 @@ the output document. By default, `keep_null` is set to `false`. These options configure {beatname_uc} to use ICMP (v4 and v6) Echo Requests to check the configured hosts. These options are valid when the <> is -`icmp`. +`icmp`. Please note that on most platforms you must execute Heartbeat with elevated permissions +to perform ICMP pings. + +On Linux, regular users may perform pings if the right file capabilities are set. Run +`sudo setcap cap_net_raw+eip /path/to/heartbeat` to grant {beatname_uc} ping capabilities on Linux. +Alternatively, one may grant ping permissions to the user {beatname_uc} runs as. To grant ping permissions +in this way, run `sudo sysctl -w net.ipv4.ping_group_range='myuserid myuserid'`. + +Other platforms may require {beatname_uc} to run as root or administrator to execute pings. [float] [[monitor-icmp-hosts]] @@ -678,5 +686,3 @@ the following JSON objects in `dynamic.json`: restarts it with a schedule of 15 seconds between checks. <2> {beatname_uc} starts a new monitor that uses a TLS-based connection with a custom CA certificate. - -