diff --git a/docs/en/ingest-management/commands.asciidoc b/docs/en/ingest-management/commands.asciidoc index 5a69ecb71..cc61dc0f2 100644 --- a/docs/en/ingest-management/commands.asciidoc +++ b/docs/en/ingest-management/commands.asciidoc @@ -28,12 +28,14 @@ invoking the wrong binary. * <> * <> * <> +* <> * <> * <> * <> * <> * <> * <> +* <> * <> //* <> @@ -521,6 +523,28 @@ elastic-agent inspect components log-default
++++ +[discrete] +[[elastic-agent-privileged-command]] +== elastic-agent privileged + +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. + +Refer to {fleet-guide}/elastic-agent-unprivileged.html[Run {agent} without administrative privileges] for more detail. + +[discrete] +=== Examples + +[source,shell] +---- +elastic-agent privileged +---- + +++++ +
+++++ + [discrete] [[elastic-agent-install-command]] == elastic-agent install @@ -564,6 +588,7 @@ elastic-agent install --url [--help] [--insecure ] [--non-interactive] + [--privileged] [--proxy-disabled] [--proxy-header ] [--proxy-url ] @@ -607,6 +632,7 @@ elastic-agent install --fleet-server-es [--header ] [--help] [--non-interactive] + [--privileged] [--proxy-disabled] [--proxy-header ] [--proxy-url ] @@ -761,6 +787,13 @@ Install {agent} in a non-interactive mode. This flag is helpful when using automation software or scripted deployments. If {agent} is already installed on the host, the installation will terminate. +`--privileged`:: +Run {agent} with full superuser privileges. +This is the usual, default running mode for {agent}. +The `--privileged` option allows you to switch back to running an agent with full administrative privileges when you have been running it in `unprivileged`. + +See the `--unprivileged` option and {fleet-guide}/elastic-agent-unprivileged.html[Run {agent} without administrative privileges] for more detail. + `--proxy-disabled`:: Disable proxy support including environment variables. @@ -785,6 +818,8 @@ 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. + `--url `:: {fleet-server} URL to use to enroll the {agent} into {fleet}. @@ -845,7 +880,6 @@ elastic-agent install --url=https://fleet-server:8220 \ --certificate-authorities=/path/to/ca.crt ---- - ++++
++++ @@ -1064,6 +1098,28 @@ elastic-agent uninstall
++++ +[discrete] +[[elastic-agent-unprivileged-command]] +== elastic-agent unprivileged + +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]. + +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. + +[discrete] +=== Examples + +[source,shell] +---- +elastic-agent unprivileged +---- + +++++ +
+++++ + [discrete] [[elastic-agent-upgrade-command]] == elastic-agent upgrade 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 b91c9ffd5..3c3e8da5c 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 @@ -31,8 +31,9 @@ elastic-agent install \ --unprivileged ---- -IMPORTANT: On Linux systems, when you install {agent} using the `--unprivileged` flag, {agent} commands should not be run with `sudo`. -Doing so may result in <> due to the agent not having the required privileges. +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 <> due to the agent not having the required privileges. +The `sudo` option is still required for the `elastic-agent install` command. [discrete] [[unprivileged-command-behaviors]] @@ -149,7 +150,18 @@ Examples of integrations that require {agent} to have administrative privileges [[unprivileged-view-mode]] == Viewing an {agent} privilege mode -For any {agent} policy you can view the number of agents that are currently running in privileged or unprivileged mode: +The **Agent details** page shows you the privilege mode for any running {agent}. + +To view the status of an {agent}: + +. In {fleet}, open the **Agents** tab. +. Select an agent and click **View agent** in the actions menu. +. The **Agent details** tab shows whether the agent is running in `privileged` or `unprivileged` mode. ++ +[role="screenshot"] +image::images/agent-privilege-mode.png[Agent details tab showing the agent is running as non-root] + +As well, for any {agent} policy you can view the number of agents that are currently running in privileged or unprivileged mode: . In {fleet}, open the **Agent policies** tab. @@ -169,7 +181,25 @@ image::images/root-integration-and-unprivileged-agents.png[Agent policy tab show [[unprivileged-change-mode]] == Changing an {agent}'s privilege mode -If an agent doesn't have the right level of privilege to read a data source, you can adjust the agent's privileges by adding `elastic-agent-user` to the user group that has privileges to read the data source. +For any installed {agent} you can change the mode that it's running in by running the `privileged` or `unprivileged` subcommand. + +Change mode from privileged to unprivileged: + +[source,shell] +---- +sudo elastic-agent unprivileged +---- + +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. + +Change mode from unprivileged to privileged: + +[source,shell] +---- +sudo elastic-agent privileged +---- + +When an agent is running in `unprivileged` mode, if it doesn't have the right level of privilege to read a data source, you can also adjust the agent's privileges by adding `elastic-agent-user` to the user group that has privileges to read the data source. As background, when you run {agent} in `unprivileged` mode, one user and one group are created on the host. The same names are used for all operating systems: @@ -181,4 +211,3 @@ 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. - diff --git a/docs/en/ingest-management/images/agent-privilege-mode.png b/docs/en/ingest-management/images/agent-privilege-mode.png new file mode 100644 index 000000000..b6596cb51 Binary files /dev/null and b/docs/en/ingest-management/images/agent-privilege-mode.png differ