From 9677d1aaaea553e765ade8f709c866fab4614331 Mon Sep 17 00:00:00 2001
From: natasha-moore-elastic
 <137783811+natasha-moore-elastic@users.noreply.github.com>
Date: Fri, 8 Mar 2024 19:09:14 +0000
Subject: [PATCH] =?UTF-8?q?Adds=20Agent=E2=80=93Endpoint=20troubleshooting?=
 =?UTF-8?q?=20doc=20(#4870)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Adds Agent–Endpoint troubleshooting doc

* Removes attributes from log message

* Update docs/troubleshooting/management/ts-management.asciidoc

Co-authored-by: Joe Peeples <joe.peeples@elastic.co>

* Indents note

---------

Co-authored-by: Joe Peeples <joe.peeples@elastic.co>
(cherry picked from commit c1c9749d5c01455b4232df27df36bf1c386a50bf)
---
 .../management/ts-management.asciidoc         | 65 +++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/docs/troubleshooting/management/ts-management.asciidoc b/docs/troubleshooting/management/ts-management.asciidoc
index 46f2405c0a..7a3fd994c6 100644
--- a/docs/troubleshooting/management/ts-management.asciidoc
+++ b/docs/troubleshooting/management/ts-management.asciidoc
@@ -78,3 +78,68 @@ image::images/transforms-start.png[Transforms page with Start option selected]
 . On the confirmation message that displays, click *Start* to restart the transform.
 . The transform’s status changes to `started`. If it doesn't change, refresh the page.
 ====
+
+[discrete]
+[[ts-agent-connection]]
+.{agent} and Endpoint connection issues
+[%collapsible]
+====
+
+After {agent} installs Endpoint, Endpoint connects to {agent} over a local relay connection to report its health status and receive policy updates and response action requests. If that connection cannot be established, the {elastic-defend} integration will cause {agent} to be in an `Unhealthy` status, and Endpoint won't operate properly.
+
+[float]
+==== Identify if the issue is happening
+
+You can identify if this issue is happening in the following ways:
+
+* Run {agent}'s status command:
++
+--
+** `sudo /opt/Elastic/Agent/elastic-agent status` (Linux)
+** `sudo /Library/Elastic/Agent/elastic-agent status` (macOS)
+** `c:\Program Files\Elastic\Agent\elastic-agent.exe status` (Windows)
+--
++
+If the status result for `endpoint-security` says that Endpoint has missed check-ins or `localhost:6788` cannot be bound to, it might indicate this problem is occurring.
+
+* If the problem starts happening right after installing Endpoint, check the value of `fleet.agent.id` in the following file:
++
+--
+** `/opt/Elastic/Endpoint/elastic-endpoint.yaml` (Linux)
+** `/Library/Elastic/Endpoint/elastic-endpoint.yaml` (macOS)
+** `c:\Program Files\Elastic\Endpoint\elastic-endpoint.yaml` (Windows)
+--
++
+If the value of `fleet.agent.id` is `00000000-0000-0000-0000-000000000000`, this indicates this problem is occurring.
++
+NOTE: If this problem starts happening after Endpoint has already been installed and working properly, then this value will have changed even though the problem is happening.
+
+[float]
+==== Examine Endpoint logs
+
+If you've confirmed that the issue is happening, you can look at Endpoint log messages to identify the cause:
+
+* `Failed to find connection to validate. Is Agent listening on 127.0.0.1:6788?` or `Failed to validate connection. Is Agent running as root/admin?` means that Endpoint is not able to create an initial connection to {agent} over port `6788`.
+
+* `Unable to make GRPC connection in deadline(60s). Fetching connection info again` means that Endpoint's original connection to {agent} over port `6788` worked, but the connection over port `6789` is failing.
+
+[float]
+==== Resolve the issue
+
+To debug and resolve the issue, follow these steps:
+
+. Since 8.7.0, Endpoint diagnostics contain a file named `analysis.txt` that contains information about what may cause this issue. As of 8.11.2, {agent} diagnostics automatically include Endpoint diagnostics. For previous versions, you can gather Endpoint diagnostics by running:
+** `sudo /opt/Elastic/Endpoint/elastic-endpoint diagnostics` (Linux)
+** `sudo /Library/Elastic/Endpoint/elastic-endpoint diagnostics` (macOS)
+** `c:\Program Files\Elastic\Endpoint\elastic-endpoint.exe diagnostics` (Windows)
+
+. Make sure nothing else on your device is listening on ports `6788` or `6789` by running:
+** `sudo netstat -anp --tcp` (Linux)
+** `sudo netstat -an -f inet` (macOS)
+** `netstat -an` (Windows)
+
+. Make sure `localhost` can be resolved to `127.0.0.1` by running:
+** `ping -4 -c 1 localhost` (Linux)
+** `ping -c 1 localhost` (macOS)
+** `ping -4 localhost` (Windows)
+====
\ No newline at end of file