From bb182975e8fbfd20a86a5cb176ad9d76aa7f6581 Mon Sep 17 00:00:00 2001 From: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> Date: Mon, 2 Dec 2024 15:07:03 -0500 Subject: [PATCH] Add docs for running unprivileged agent as existing user/group (#1505) * Add docs for running unprivileged agent as existing user/group * fixup --- docs/en/ingest-management/commands.asciidoc | 38 ++++++++++++++++-- .../elastic-agent-unprivileged-mode.asciidoc | 39 +++++++++++++++++++ 2 files changed, 74 insertions(+), 3 deletions(-) diff --git a/docs/en/ingest-management/commands.asciidoc b/docs/en/ingest-management/commands.asciidoc index fe4486d32..a0a86f7d6 100644 --- a/docs/en/ingest-management/commands.asciidoc +++ b/docs/en/ingest-management/commands.asciidoc @@ -29,14 +29,14 @@ invoking the wrong binary. * <> * <> * <> [technical preview] -* <> [technical preview] +* <> * <> * <> * <> * <> * <> * <> -* <> [technical preview] +* <> * <> //* <> @@ -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 `:: {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" +---- + ++++
++++ 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 3c47aaca7..f4ebb351b 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 @@ -16,6 +16,7 @@ Refer to <> and <> for the * <> * <> * <> +* <> [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" +---- + +