Document pre-requisites for running Elastic Agent in unprivileged mode

[ycombinator]

Background

Traditionally, privileged users (e.g. root on Linux) run Elastic Agent on a host. However, with #3598, #4362, #4264, and other follow-up PRs, it is now possible to run Elastic Agent with an unprivileged user.

Problem statement

Running Agent as an unprivileged user has consequences. Not only does the Agent itself run as an unprivileged user, but so do the process components it orchestrates, e.g. the various Beats. Consequently, any integrations being handled by such components, e.g. system, might not have the necessary access on the host to collect all the data they can when running as a privileged user. The result is that users do not see data they might be expecting in these integrations' dashboards. Some examples of this situation are:

• system.security dataset is not generated for Windows agent installed with unprivileged flag. #4647
• Windows Agent gets unhealthy on adding Windows Integration when installed with --unprivileged flag, #4653
• No obvious permissions error when system.syslog not available for mac agent installed with unprivileged flag. #4675

Similarly, users might encounter other issues related to the installing or running of Elastic Agent in privileged mode. Some examples of this situation are:

• Unable to install mac agent at custom path using --base-path and --unprivilege command. #4690
• Inspect command failed for mac agent installed at custom path using --base-path and --unprivileged flags. #4703

Definition of done

Let's use this issue to collect any pre-requisites a user must perform to install and run Elastic Agent in unprivileged mode, as well as any other gotchas they might run into when using the system integration with an Elastic Agent running in unprivileged mode.

For each pre-requisite let's capture the following information:

1. What steps does the user need to take as a prerequisite to running Elastic Agent in unprivileged mode?
2. What would the impact be if these prerequisite steps were not taken? Or, put differently, what functionality is enabled as a result of taking these prerequisite steps?
3. What symptoms (e.g. errors) will the user observe and where if these prerequisite steps were not taken?

MacOS

Beta Give feedback

1. Try installing Elastic Agent in unprivileged mode.
2. Try running various Elastic Agent subcommands (e.g. inspect, status, etc.).
3. Try installing the system integration on an Elastic Agent in unprivileged mode and viewing its dashboards. Compare the results with installing the system integration on Elastic Agent in privileged mode.

Linux

Beta Give feedback

1. Try installing Elastic Agent in unprivileged mode.
2. Try running various Elastic Agent subcommands (e.g. inspect, status, etc.).
3. Try installing the system integration on an Elastic Agent in unprivileged mode and viewing its dashboards. Compare the results with installing the system integration on Elastic Agent in privileged mode.

Windows

Beta Give feedback

1. Try installing Elastic Agent in unprivileged mode.
2. Try running various Elastic Agent subcommands (e.g. inspect, status, etc.).
3. Try installing the system integration on an Elastic Agent in unprivileged mode and viewing its dashboards. Compare the results with installing the system integration on Elastic Agent in privileged mode.

[elasticmachine]

Pinging @elastic/elastic-agent-control-plane (Team:Elastic-Agent-Control-Plane)

[ycombinator]

cc: @kilfoyle

[kilfoyle]

Thanks for opening this @ycombinator! I like the organization. Once we have all the pre-requisites info I can add a table into the docs mapping each function to the pre-requisite(s) associated with using it in unprivileged mode.

I'm thinking that we can also have a troubleshooting section with something like:

• a list of possible error messages
• for each message, a brief explanation of what it indicates: i.e., that the prerequisite for running Function X in unprivileged mode isn't satisfied
• a link back to the "function to pre-requisites" table mentioned above

And thanks @kaanyalti for taking this one on!

[ycombinator]

In #4125 (comment), @kilfoyle said:

@kaanyalti I think the "pre-requisites and gotchas" could go in tables like these, but we can update the format once the list becomes more clear.