From 5f41f38691bd93f166675f418b0427657d3974ba Mon Sep 17 00:00:00 2001
From: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com>
Date: Fri, 9 Aug 2024 17:03:04 -0400
Subject: [PATCH] Add note to 'unprivleged' agent docs about elastic-agent-user
 (#1245)

* Add note to 'unprivleged' agent docs about elastic-agent-user

* Update command reference with beta tags

* Improve wording
---
 docs/en/ingest-management/commands.asciidoc   |  8 +++++--
 .../elastic-agent-unprivileged-mode.asciidoc  | 22 ++++++++++++++++---
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/docs/en/ingest-management/commands.asciidoc b/docs/en/ingest-management/commands.asciidoc
index cc61dc0f2..04994d337 100644
--- a/docs/en/ingest-management/commands.asciidoc
+++ b/docs/en/ingest-management/commands.asciidoc
@@ -28,14 +28,14 @@ invoking the wrong binary.
 * <<elastic-agent-help-command,help>>
 * <<elastic-agent-inspect-command,inspect>>
 * <<elastic-agent-install-command,install>>
-* <<elastic-agent-privileged-command,privileged>>
+* <<elastic-agent-privileged-command,privileged>> [technical preview]
 * <<elastic-agent-restart-command,restart>>
 * <<elastic-agent-run-command,run>>
 * <<elastic-agent-status-command,status>>
 * <<elastic-agent-uninstall-command,uninstall>>
 * <<elastic-agent-upgrade-command,upgrade>>
 * <<elastic-agent-logs-command,logs>>
-* <<elastic-agent-unprivileged-command,unprivileged>>
+* <<elastic-agent-unprivileged-command,unprivileged>> [technical preview]
 * <<elastic-agent-version-command,version>>
 //* <<elastic-agent-watch-command,watch>>
 
@@ -527,6 +527,8 @@ elastic-agent inspect components log-default
 [[elastic-agent-privileged-command]]
 == elastic-agent privileged
 
+preview::[]
+
 Run {agent} with full superuser privileges.
 This is the usual, default running mode for {agent}.
 The `privileged` command allows you to switch back to running an agent with full administrative privileges when you have been running it in `unprivileged` mode. 
@@ -1102,6 +1104,8 @@ elastic-agent uninstall
 [[elastic-agent-unprivileged-command]]
 == elastic-agent unprivileged
 
+preview::[]
+
 Run {agent} without full superuser privileges.
 This is useful in organizations that limit `root` access on Linux or macOS systems, or `admin` access on Windows systems.
 For details and limitations for running {agent} in this mode, refer to {fleet-guide}/elastic-agent-unprivileged.html[Run {agent} without administrative privileges].
diff --git a/docs/en/ingest-management/elastic-agent/elastic-agent-unprivileged-mode.asciidoc b/docs/en/ingest-management/elastic-agent/elastic-agent-unprivileged-mode.asciidoc
index 23f58177b..ee35d6973 100644
--- a/docs/en/ingest-management/elastic-agent/elastic-agent-unprivileged-mode.asciidoc
+++ b/docs/en/ingest-management/elastic-agent/elastic-agent-unprivileged-mode.asciidoc
@@ -33,9 +33,25 @@ elastic-agent install \
   --unprivileged
 ----
 
-IMPORTANT: On Linux systems, once {agent} has been installed with the `--unprivileged` flag, all {agent} commands that you run should not be prefixed with `sudo`.
-Including `sudo` in a command may result in <<agent-sudo-error,an error>> due to the agent not having the required privileges.
-The `sudo` option is still required for the `elastic-agent install` command.
+[IMPORTANT] 
+====
+Note the following current restrictions for running {agent} in `unprivileged` mode:
+
+* On Linux systems, after {agent} has been installed with the `--unprivileged` flag, all {agent} commands can be run without being the root user.
+** The `sudo` option is still required for the `elastic-agent install` command.
+Only `root` can install new services.
+The installed service will not run as the root user.
+* Using `sudo` without specifying an alternate non-root user with `sudo -u` in a command may result in <<agent-sudo-error,an error>> due to the agent not having the required privileges.
+* Using `sudo -u elastic-agent-user` will run commands as the user running the {agent} service and will always work.
+* For files that allow users in the `elastic-agent` group access, using an alternate user that has been added to that group will also work.
+There are still some commands that are only accessible to the `elastic-agent-user` that runs the service.
+** For example, `elastic-agent inspect` requires you to prefix the command with `sudo -u elastic-agent-user`.
++
+[source,shell]
+----
+sudo -u elastic-agent-user elastic-agent inspect
+----
+====
 
 [discrete]
 [[unprivileged-command-behaviors]]