Skip to content

Commit

Permalink
Add note to 'unprivleged' agent docs about elastic-agent-user (#1245)
Browse files Browse the repository at this point in the history
* Add note to 'unprivleged' agent docs about elastic-agent-user

* Update command reference with beta tags

* Improve wording
  • Loading branch information
kilfoyle authored Aug 9, 2024
1 parent b9ad65e commit 5f41f38
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 5 deletions.
8 changes: 6 additions & 2 deletions docs/en/ingest-management/commands.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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>>

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

0 comments on commit 5f41f38

Please sign in to comment.