Fixes for 'unprivileged' agent docs (#1200) (#1204)

* Fixes for 'unprivileged' agent docs

* Add clause about required re-enroll

* fixup

* Improve warning about running sub-commands without sudo

* Add 'privileged' and 'unprivileged' as commands

* Note that sudo is still needed for install command

* fixup

* Fixup

(cherry picked from commit e409b9d)

Co-authored-by: David Kilfoyle <[email protected]>

docs/en/ingest-management/commands.asciidoc

@@ -28,12 +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-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-version-command,version>>
 //* <<elastic-agent-watch-command,watch>>
 
@@ -521,6 +523,28 @@ elastic-agent inspect components log-default
 <hr>
 ++++
 
+[discrete]
+[[elastic-agent-privileged-command]]
+== elastic-agent privileged
+
+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. 
+
+Refer to {fleet-guide}/elastic-agent-unprivileged.html[Run {agent} without administrative privileges] for more detail.
+
+[discrete]
+=== Examples
+
+[source,shell]
+----
+elastic-agent privileged
+----
+
+++++
+<hr>
+++++
+
 [discrete]
 [[elastic-agent-install-command]]
 == elastic-agent install
@@ -564,6 +588,7 @@ elastic-agent install --url <string>
                       [--help]
                       [--insecure ]
                       [--non-interactive]
+                      [--privileged]
                       [--proxy-disabled]
                       [--proxy-header <strings>]
                       [--proxy-url <string>]
@@ -607,6 +632,7 @@ elastic-agent install --fleet-server-es <string>
                       [--header <strings>]
                       [--help]
                       [--non-interactive]
+                      [--privileged]
                       [--proxy-disabled]
                       [--proxy-header <strings>]
                       [--proxy-url <string>]
@@ -761,6 +787,13 @@ Install {agent} in a non-interactive mode. This flag is helpful when
 using automation software or scripted deployments. If {agent} is
 already installed on the host, the installation will terminate.
 
+`--privileged`::
+Run {agent} with full superuser privileges.
+This is the usual, default running mode for {agent}.
+The `--privileged` option allows you to switch back to running an agent with full administrative privileges when you have been running it in `unprivileged`. 
+
+See the `--unprivileged` option and {fleet-guide}/elastic-agent-unprivileged.html[Run {agent} without administrative privileges] for more detail.
+
 `--proxy-disabled`::
 Disable proxy support including environment variables.
 
@@ -785,6 +818,8 @@ Run {agent} without full superuser privileges.
 This option 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].
 
+Note that changing to `unprivileged` mode is prevented if the agent is currently enrolled in a policy that includes an integration that requires administrative access, such as the {elastic-defend} integration.
+
 `--url <string>`::
 {fleet-server} URL to use to enroll the {agent} into {fleet}.
 
@@ -845,7 +880,6 @@ elastic-agent install --url=https://fleet-server:8220 \
   --certificate-authorities=/path/to/ca.crt
 ----
 
-
 ++++
 <hr>
 ++++
@@ -1064,6 +1098,28 @@ elastic-agent uninstall
 <hr>
 ++++
 
+[discrete]
+[[elastic-agent-unprivileged-command]]
+== elastic-agent unprivileged
+
+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].
+
+Note that changing a running {agent} to `unprivileged` mode is prevented if the agent is currently enrolled with a policy that contains the {elastic-defend} integration.
+
+[discrete]
+=== Examples
+
+[source,shell]
+----
+elastic-agent unprivileged
+----
+
+++++
+<hr>
+++++
+
 [discrete]
 [[elastic-agent-upgrade-command]]
 == elastic-agent upgrade

docs/en/ingest-management/elastic-agent/elastic-agent-unprivileged-mode.asciidoc

@@ -31,8 +31,9 @@ elastic-agent install \
   --unprivileged
 ----
 
-IMPORTANT: On Linux systems, when you install {agent} using the `--unprivileged` flag, {agent} commands should not be run with `sudo`.
-Doing so may result in <<agent-sudo-error,an error>> due to the agent not having the required privileges.
+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.
 
 [discrete]
 [[unprivileged-command-behaviors]]
@@ -149,7 +150,18 @@ Examples of integrations that require {agent} to have administrative privileges
 [[unprivileged-view-mode]]
 == Viewing an {agent} privilege mode
 
-For any {agent} policy you can view the number of agents that are currently running in privileged or unprivileged mode:
+The **Agent details** page shows you the privilege mode for any running {agent}.
+
+To view the status of an {agent}:
+
+. In {fleet}, open the **Agents** tab.
+. Select an agent and click **View agent** in the actions menu.
+. The **Agent details** tab shows whether the agent is running in `privileged` or `unprivileged` mode.
++
+[role="screenshot"]
+image::images/agent-privilege-mode.png[Agent details tab showing the agent is running as non-root]
+
+As well, for any {agent} policy you can view the number of agents that are currently running in privileged or unprivileged mode:
 
 . In {fleet}, open the **Agent policies** tab.
 
@@ -169,7 +181,25 @@ image::images/root-integration-and-unprivileged-agents.png[Agent policy tab show
 [[unprivileged-change-mode]]
 == Changing an {agent}'s privilege mode
 
-If an agent doesn't have the right level of privilege to read a data source, you can adjust the agent's privileges by adding `elastic-agent-user` to the user group that has privileges to read the data source.
+For any installed {agent} you can change the mode that it's running in by running the `privileged` or `unprivileged` subcommand.
+
+Change mode from privileged to unprivileged:
+
+[source,shell]
+----
+sudo elastic-agent unprivileged
+----
+
+Note that changing to `unprivileged` mode is prevented if the agent is currently enrolled in a policy that includes an integration that requires administrative access, such as the {elastic-defend} integration.
+
+Change mode from unprivileged to privileged:
+
+[source,shell]
+----
+sudo elastic-agent privileged
+----
+
+When an agent is running in `unprivileged` mode, if it doesn't have the right level of privilege to read a data source, you can also adjust the agent's privileges by adding `elastic-agent-user` to the user group that has privileges to read the data source.
 
 As background, when you run {agent} in `unprivileged` mode, one user and one group are created on the host. The same names are used for all operating systems:
 
@@ -181,4 +211,3 @@ For example:
 . When you install {agent} with the `--unprivileged` setting, the `elastic-agent-user` user and the `elastic-agent` group are created automatically.
 . If you then want your user `myuser` to be able to run an {agent} command such as `elastic-agent status`, add the `myuser` user to the `elastic-agent` group.
 . Then, once added to the group, the `elastic-agent status` command will work. Prior to that, the user `myuser` running the command will result in a permission error that indicates a problem communicating with the control socket.
-