Consolidating requirements for the user account running the es service

[yetanothertw]

Summary

Fixes #1253 and adds a new page (PREVIEW) that includes the following Elasticsearch service user requirements:

• Don't run as root guidance supported by this page and also by this page through example of steps.

Furthermore, this snippet documents that the config directory is owned by root:elasticsearch, meaning the service user is expected to be a member of the elasticsearch group, not root itself.

This guidance supports the principle of least privilege (in security) and ensures that the elasticsearch user only needs access to its data, logs, and config directories.

• Use consistent user and group IDs across nodes, this guideline is supported on this page. This is also discussed in Add link to shared FS troubleshooting from system config page #1242 where it describes a scenario where nodes had the elasticsearch user with the same name but different numeric UIDs, causing silent NFS permission failures on shared file system snapshot repositories.

• Required system permissions. This information can be found in the same section, but scattered throughout various pages. I've added a table that consolidates all these recommendations per system-level permission and links to each page for details.

• File and directory ownership. This is supported by this snippet. Elasticsearch needs to read its configuration and write to data and log directories. Without correct ownership, Elasticsearch fails to start.

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

I've used claude 4.6 opus high to validate assumptions and find connections

[github-actions]

✅ Vale Linting Results

No issues found on modified lines!

---

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

[github-actions]

🔍 Preview links for changed docs

• deploy-manage/deploy/self-managed/elasticsearch-service-user.md
• deploy-manage/deploy/self-managed/important-system-configuration.md

[eedugon]

Looks great, adding this new page seems like a very good addition IMO, also linking it properly with the system configuration docs. I'm surprised we never had this doc.

One small comment besides the provided suggestions. Are we going to consider windows users here? Not sure if it would be useful, just for your consideration.

[shainaraskas]

couple of questions that are perhaps a little naive

re:

Furthermore, this snippet documents that the config directory is owned by root:elasticsearch, meaning the service user is expected to be a member of the elasticsearch group, not root itself.

does this mean that there is a group that needs to be created/joined?

wonder if this would be a good PR to get some support TL input on (e.g. kuni/stef) - they probably have a good understanding of where we run into user permission issues

[yetanothertw]

Thank you, Shaina and Edu for the excellent observations and suggestions!

does this mean that there is a group that needs to be created/joined?

I think there are quite a few questions that we can't confidently answer and I couldn't find in our docs where we mention creating the group or adding the user to it, so this is definitely a gap. There's an implicit group requirement that is never explicitly documented.

wonder if this would be a good PR to get some support TL input on (e.g. kuni/stef) - they probably have a good understanding of where we run into user permission issues

Yes, definitely!

@kunisen, @stefnestor, when you get the chance, would you please review this PR?

Our archive install guidance doesn't inlcude explicit groupadd/useradd instructions, but should it? The docs say "create the user manually" but we never mention creating the group or adding the user to it.

What specific group membership is required for archive installs vs package installs? What type of permission errors do you actually see in practice?

[stefnestor]

👋🏽 howdy, friends!

Sorry, I'm not actually a TL, we just hang out. And Kuni is TL for Cloud. Elasticsearch is handled by @Gunnerva and @\ppf2 . My best guess is that install requirements falls under "cluster formation" so tagging Ryan not Pius 🙂.

Also FWIW I'd claim this type of official recommendation needs Dev-not-Support sign off on word nuances. 🙃

Thanks!

[kunisen]

Thanks @yetanothertw for tagging me and thanks @stefnestor for connecting to Ryan.
++ on having Ryan's inputs as he's support tech lead in charge of Elasticsearch area. (and I am on cloud area)

Much appreciated your understanding and patience.

[yetanothertw]

Hi @Gunnerva, when you get the chance, could you please review this PR? 🙏
For context, we're trying to capture requirements for users running Elasticsearch and it would be good to validate the proposed guidance and add anything else that might be missing.

Some additional questions in this comment

[jozala]

It looks good. I've verified the RPM and Debian package specs regarding user creation and automatic permission logic and everything is aligned.

For Kernel resource limits I've done a high-level check against the linked docs. If we need a deep-dive validation of those specific configuration, it might be worth looping in ES Core/Infra for their expertise.

I've left one minor remark.

[jozala]

NIT: It says "Linux and MacOS only", but the document contains some info for Windows e.g., "Windows, do not run {{es}} as the Administrator user".
There is not much there about Windows so it might be fine, just wanted to highlight to make sure this was the intention.

[yetanothertw]

Thanks for catching that, I forgot to remove that reference when I added the Windows specific info. Fixed in a new commit.

[yetanothertw]

@jozala, thanks for looking through this. Re user creation, do you think we need to document how to manually create the user and group for .tar.gz or .zip installations? Or is this a typical sys admin task we'd expect the users to know how to perform?

[jozala]

I think that user/group creation is a typical sys admin task. Also, it might be a bit different depending on the Linux distribution so it would be hard to maintain.

[eedugon]

Reads really well! Great work