Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[8.15] Add note to 'unprivleged' agent docs about elastic-agent-user (backport #1245) #1251

Merged
merged 1 commit into from
Aug 9, 2024
Merged

[8.15] Add note to 'unprivleged' agent docs about elastic-agent-user (backport #1245) #1251

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions docs/en/ingest-management/commands.asciidoc
View file
Open in desktop
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
22 changes: 19 additions & 3 deletions docs/en/ingest-management/elastic-agent/elastic-agent-unprivileged-mode.asciidoc
View file
Open in desktop
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