[8.x] Add docs for running unprivileged agent as existing user/group (backport #1505)

docs/en/ingest-management/commands.asciidoc

@@ -29,14 +29,14 @@ invoking the wrong binary.
 * <<elastic-agent-inspect-command,inspect>>
 * <<elastic-agent-install-command,install>>
 * <<elastic-agent-otel-command,otel>> [technical preview]
-* <<elastic-agent-privileged-command,privileged>> [technical preview]
+* <<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>> [technical preview]
+* <<elastic-agent-unprivileged-command,unprivileged>>
 * <<elastic-agent-version-command,version>>
 //* <<elastic-agent-watch-command,watch>>
 
@@ -823,8 +823,22 @@ tags, you must unenroll the {agent}, then re-enroll it using new tags.
 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.
++
+[technical preview] To run {agent} without superuser privileges as a pre-existing user or group, for instance under an Active Directory account, you can specify the user or group, and the password to use.
++
+For example:
++
+[source,shell]
+----
+elastic-agent install --unprivileged  --user="my.path\username" --password="mypassword"
+----
++
+[source,shell]
+----
+elastic-agent install --unprivileged  --group="my.path\groupname" --password="mypassword"
+----
 
 `--url <string>`::
 {fleet-server} URL to use to enroll the {agent} into {fleet}.
@@ -1177,14 +1191,32 @@ For details and limitations for running {agent} in this mode, refer to {fleet-gu
 
 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.
 
+[technical preview] To run {agent} without superuser privileges as a pre-existing user or group, for instance under an Active Directory account, add either a `--user` or `--group` parameter together with a `--password` parameter.
+
 [discrete]
 === Examples
 
+Run {agent} without administrative privileges:
+
 [source,shell]
 ----
 elastic-agent unprivileged
 ----
 
+Run {agent} without administrative privileges, as a pre-existing user: [technical preview]
+
+[source,shell]
+----
+elastic-agent unprivileged --user="my.pathl\username" --password="mypassword"
+----
+
+Run {agent} without administrative privileges, as a pre-existing group: [technical preview]
+
+[source,shell]
+----
+elastic-agent unprivileged --group="my.pathl\groupname" --password="mypassword"
+----
+
 ++++
 <hr>
 ++++

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

@@ -16,6 +16,7 @@ Refer to <<unprivileged-command-behaviors>> and <<unprivileged-running>> for the
 * <<unprivileged-integrations>>
 * <<unprivileged-view-mode>>
 * <<unprivileged-change-mode>>
+* <<unprivileged-preexisting-user>>
 
 [discrete]
 [[unprivileged-running]]
@@ -227,3 +228,41 @@ 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.
+
+[discrete]
+[[unprivileged-preexisting-user]]
+== Using `unprivileged` mode with a pre-existing user and group
+
+preview::[]
+
+In certain cases you may want to install {agent} in `unprivileged` mode, with the agent running as a pre-existing user or as part of a pre-existing group.
+For example, on a Windows system you may have a service account in Active Directory and you'd like {agent} to run under that account.
+
+To install {agent} in `unprivileged` mode as a specific user, add the `--user` and `--password` parameters to the install command:
+
+[source,shell]
+----
+elastic-agent install --unprivileged  --user="my.path\username" --password="mypassword"
+----
+
+To install {agent} in `unprivileged` mode as part of a specific group, add the `--group` and `--password` parameters to the install command:
+
+[source,shell]
+----
+elastic-agent install --unprivileged  --group="my.path\groupname" --password="mypassword"
+----
+
+Alternatively, if you have {agent} already installed with administrative privileges, you can change the agent to use `unprivileged` mode and to run as a specific user or in a specific group.
+For example:
+
+[source,shell]
+----
+elastic-agent unprivileged --user="my.path\username" --password="mypassword"
+----
+
+[source,shell]
+----
+elastic-agent unprivileged --group="my.path\groupname" --password="mypassword"
+----
+
+