Skip to content

Commit

Permalink
Add docs for running unprivileged agent as existing user/group
Browse files Browse the repository at this point in the history
  • Loading branch information
kilfoyle committed Nov 27, 2024
1 parent 6d3fdf5 commit a652d08
Show file tree
Hide file tree
Showing 2 changed files with 74 additions and 3 deletions.
38 changes: 35 additions & 3 deletions docs/en/ingest-management/commands.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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>>

Expand Down Expand Up @@ -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}.
Expand Down Expand Up @@ -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 the `--user` and `--password` parameters.

[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>
++++
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down Expand Up @@ -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"
----


0 comments on commit a652d08

Please sign in to comment.