diff --git a/reference/fleet/elastic-agent-unprivileged.md b/reference/fleet/elastic-agent-unprivileged.md index bc275a6a88..b2512e5fd0 100644 --- a/reference/fleet/elastic-agent-unprivileged.md +++ b/reference/fleet/elastic-agent-unprivileged.md @@ -28,13 +28,37 @@ Refer to [Agent and dashboard behaviors in unprivileged mode](#unprivileged-comm To run {{agent}} without administrative privileges you use exactly the same commands that you use for {{agent}} otherwise, with one exception. When you run the [`elastic-agent install`](/reference/fleet/agent-command-reference.md#elastic-agent-install-command) command, add the `--unprivileged` flag. For example: +:::::{tab-set} +:group: os + +::::{tab-item} Linux/macOS +:sync: linux + ```shell -elastic-agent install \ +sudo elastic-agent install \ --url=https://cedd4e0e21e240b4s2bbbebdf1d6d52f.fleet.eu-west-1.aws.cld.elstc.co:443 \ --enrollment-token=NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ== \ --unprivileged ``` +:::: + +::::{tab-item} Windows +:sync: windows + +From PowerShell: + +```shell +elastic-agent install ` + --url=https://cedd4e0e21e240b4s2bbbebdf1d6d52f.fleet.eu-west-1.aws.cld.elstc.co:443 ` + --enrollment-token=NEFmVllaa0JLRXhKebVKVTR5TTI6N2JaVlJpSGpScmV0ZUVnZVlRUExFQQ== ` + --unprivileged +``` + +:::: + +::::: + ::::{important} Note the following current restrictions for running {{agent}} in `unprivileged` mode: @@ -153,18 +177,56 @@ For any installed {{agent}} you can change the mode that it’s running in by ru Change mode from privileged to unprivileged: +:::::{tab-set} +:group: os + +::::{tab-item} Linux/macOS +:sync: linux + ```shell sudo elastic-agent unprivileged ``` +:::: + +::::{tab-item} Windows +:sync: windows + +```shell +elastic-agent unprivileged +``` + +:::: + +::::: + 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: +:::::{tab-set} +:group: os + +::::{tab-item} Linux/macOS +:sync: linux + ```shell sudo elastic-agent privileged ``` +:::: + +::::{tab-item} Windows +:sync: windows + +```shell +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: @@ -188,24 +250,104 @@ This functionality is in technical preview and may be changed or removed in a fu 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: +::::{note} +On Windows, the `--password` parameter is required when specifying a custom user account. + +On Linux and macOS, the `--user` and `--group` parameters are optional: +* If you omit `--user`, {{agent}} uses (or creates) the default unprivileged user (`elastic-agent-user`). +* If you specify only `--group`, the agent runs unprivileged under its default user but with the requested group. +:::: + +To install {{agent}} in `unprivileged` mode as a specific user or group, use the following commands: + +:::::{tab-set} +:group: os + +::::{tab-item} Linux/macOS +:sync: linux + +To install with a specific user: ```shell -elastic-agent install --unprivileged --user="my.path\username" --password="mypassword" +sudo elastic-agent install --unprivileged --user="username" ``` -To install {{agent}} in `unprivileged` mode as part of a specific group, add the `--group` and `--password` parameters to the install command: +To install with a specific group: ```shell -elastic-agent install --unprivileged --group="my.path\groupname" --password="mypassword" +sudo elastic-agent install --unprivileged --group="groupname" ``` -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: +To install with both a specific user and group: ```shell -elastic-agent unprivileged --user="my.path\username" --password="mypassword" +sudo elastic-agent install --unprivileged --user="username" --group="groupname" ``` +:::: + +::::{tab-item} Windows +:sync: windows + +To install as a specific user: + +```shell +elastic-agent install --unprivileged --user="my.domain\username" --password="mypassword" +``` + +To install as part of a specific group: + +```shell +elastic-agent install --unprivileged --group="my.domain\groupname" +``` + +To install with both a specific user and group: + +```shell +elastic-agent install --unprivileged --user="my.domain\username" --password="mypassword" --group="my.domain\groupname" +``` + +:::: + +::::: + +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. + +:::::{tab-set} +:group: os + +::::{tab-item} Linux/macOS +:sync: linux + +To change to a specific user: + +```shell +sudo elastic-agent unprivileged --user="username" +``` + +To change to a specific group: + +```shell +sudo elastic-agent unprivileged --group="groupname" +``` + +:::: + +::::{tab-item} Windows +:sync: windows + +To change to a specific user: + +```shell +elastic-agent unprivileged --user="my.domain\username" --password="mypassword" +``` + +To change to a specific group: + ```shell -elastic-agent unprivileged --group="my.path\groupname" --password="mypassword" +elastic-agent unprivileged --group="my.domain\groupname" ``` + +:::: + +:::::