Fix code examples in doc for running Elastic Agent unprivileged #4070

Copilot · 2025-11-25T09:10:45Z

Summary

Resolves #2808

The use of the --password parameter in the documentation was incorrect—it's only required on Windows, not Linux/macOS. The existing examples incorrectly showed --password for all platforms.

Changes:

Added note clarifying that on Windows, the --password parameter is required when specifying a custom user account
Clarified that on Linux/macOS, the --user and --group parameters are optional—if --user is omitted, the default elastic-agent-user is used; if only --group is specified, the agent runs unprivileged with the requested group using the default user
Split all examples into platform-specific tabs (Linux/macOS vs Windows) with synchronized tab groups using :group: os and :sync: options
Corrected Linux/macOS examples to use only --user/--group without --password
Added sudo prefix to Linux/macOS commands
Updated elastic-agent install, elastic-agent unprivileged, and elastic-agent privileged command examples with tabs
Added tabs to the initial install example in the "Run {{agent}} in unprivileged mode" section
Fixed nested bullet point formatting in the important note section—converted nested bullets to paragraphs under their respective list items

Before (incorrect):

elastic-agent install --unprivileged --user="my.path\username" --password="mypassword"

After (Linux/macOS):

sudo elastic-agent install --unprivileged --user="username" --group="groupname"

After (Windows, from PowerShell):

elastic-agent install --unprivileged --user="my.domain\username" --password="mypassword" --group="my.domain\groupname"

Generative AI disclosure

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

Yes
No

Tool(s) and model(s) used: GitHub Copilot (Claude)

Preview

reference/fleet/elastic-agent-unprivileged.md

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

- Add note explaining --password is only required on Windows - Add tabs to display separate examples for Windows vs Linux/macOS - Correct Linux/macOS examples to use --user/--group without --password - Add sudo prefix to Linux/macOS commands - Use .exe extension for Windows examples Fixes elastic/docs-content#5298 Co-authored-by: vishaangelova <[email protected]>

vishaangelova · 2025-11-25T09:30:18Z

@copilot the changes should be made to the elastic-agent unprivileged command as well. Also, on Linux/macOS, --user is optional when you install or switch to unprivileged mode.
If you omit --user, Elastic Agent will use (or create) the default unprivileged user.
If you specify only a group, the agent will still run unprivileged under its default user but with the group that was requested. Make changes to the examples and text accordingly.

- Update note to explain --user and --group are optional on Linux/macOS - Clarify that if --user is omitted, default elastic-agent-user is used - Clarify that if only --group is specified, agent runs under default user - Update example text in both install and unprivileged command tabs Co-authored-by: vishaangelova <[email protected]>

Copilot · 2025-11-25T09:33:13Z

@copilot the changes should be made to the elastic-agent unprivileged command as well. Also, on Linux/macOS, --user is optional when you install or switch to unprivileged mode.
If you omit `--use...

Updated in f35413c. The documentation now clarifies that on Linux/macOS, --user and --group are optional—if --user is omitted, the default elastic-agent-user is used, and if only --group is specified, the agent runs under its default user with the requested group. Both the elastic-agent install and elastic-agent unprivileged command examples have been updated with this context.

vishaangelova · 2025-11-25T10:18:06Z

@copilot Update the two other examples in the doc (sudo elastic-agent unprivileged and sudo elastic-agent privileged) with tabs that show the command example separately for Windows and Linux/macOS. Use a a group and sync option for all tabs to synchronize the tabs across the page. Remove the .exe extension from the Windows example. Remove the "(the agent runs under its default user with the specified group)” and "(optional—if omitted, the default elastic-agent-user is used)” parts from your changes. Include an example for installing Agent with a specific user and group for Windows as well.

- Add tabs to `elastic-agent unprivileged` and `elastic-agent privileged` commands - Add `:group: os` and `:sync:` options to synchronize tabs across page - Remove `.exe` extension from Windows examples - Remove extra clarifying text from example descriptions - Add Windows example for user+group installation Co-authored-by: vishaangelova <[email protected]>

Copilot · 2025-11-25T10:22:52Z

@copilot Update the two other examples in the doc (sudo elastic-agent unprivileged and sudo elastic-agent privileged) with tabs that show the command example separately for Windows and Linux/macOS...

Updated in 9cdf6d9:

Added tabs with :group: os and :sync: linux/:sync: windows to synchronize tabs across the page
Added tabs for elastic-agent unprivileged and elastic-agent privileged commands
Removed .exe extension from Windows examples
Removed the extra clarifying text from example descriptions
Added Windows example for installing with both user and group

vishaangelova · 2025-11-25T10:37:48Z

@copilot update the code example in line 31-36 and use tabs to show an example command for the different operating systems. Synchronize the tabs with the rest.

- Add synchronized tabs for Linux/macOS and Windows install commands - Add sudo prefix to Linux/macOS example (required for service installation) - Use PowerShell backtick line continuation for Windows example Co-authored-by: vishaangelova <[email protected]>

Copilot · 2025-11-25T10:41:47Z

@copilot update the code example in line 31-36 and use tabs to show an example command for the different operating systems. Synchronize the tabs with the rest.

Updated in 534d8e7. Added tabs with :group: os and :sync: linux/:sync: windows to the initial install example, synchronizing it with the rest of the page.

reference/fleet/elastic-agent-unprivileged.md

Co-authored-by: vishaangelova <[email protected]>

reference/fleet/elastic-agent-unprivileged.md

vishaangelova · 2025-11-25T11:21:56Z

@copilot Continue but with the following changes:

In the note, fix the formatting to: On Windows, the --password parameter is required when specifying a custom user account.

Co-authored-by: vishaangelova <[email protected]>

Copilot · 2025-11-25T11:23:51Z

@copilot Continue but with the following changes:

In the note, fix the formatting to: On Windows, the --password parameter is required when specifying a custom user account.

Fixed the note formatting in cfee58d. The text now reads: "On Windows, the --password parameter is required when specifying a custom user account."

github-actions · 2025-11-25T11:31:22Z

🔍 Preview links for changed docs

reference/fleet/elastic-agent-unprivileged.md

vishaangelova · 2025-11-25T13:30:31Z

@blakerouse, as Eric’s on PTO this week, and I’m not sure whom to ask for a review -- could you take a look at this PR, or maybe direct me to someone else from your team?

alexandra5000 · 2025-11-28T12:15:18Z

reference/fleet/elastic-agent-unprivileged.md


 * 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.


Is there a reason this is indented? Seems random to me 🤔

Hmm, this was in the original text, and I hadn’t noticed it. It’s currently an unonrdered list in the unordered list, but I think it should just be a separate paragraph as part of the unordered list item.

@copilot on line 67 and 73, remove the * to format those paragraphs as new paragraphs under their respective unordered list item.

Removed the * from lines 67 and 73, formatting them as paragraphs under their respective list items in f9da888.

reference/fleet/elastic-agent-unprivileged.md

github-actions · 2025-11-28T13:46:45Z

Vale Linting Results

Summary: 1 suggestion found

💡 Suggestions (1)

File	Line	Rule	Message
reference/fleet/elastic-agent-unprivileged.md	67	Elastic.FutureTense	'will not' might be in future tense. Write in the present tense to describe the state of the product as it is now.

- Changed lines 67 and 73 from nested bullet points (*) to regular paragraphs indented under their respective list items Co-authored-by: vishaangelova <[email protected]>

michel-laterman

lgtm

reference/fleet/elastic-agent-unprivileged.md

Initial plan

93a26b7

Copilot AI assigned Copilot and vishaangelova Nov 25, 2025

Copilot started work on behalf of vishaangelova November 25, 2025 09:11 View session

Copilot AI changed the title ~~[WIP] Fix documentation for unprivileged mode command~~ Fix documentation for unprivileged mode with pre-existing user and group Nov 25, 2025

Copilot AI requested a review from vishaangelova November 25, 2025 09:18

Copilot finished work on behalf of vishaangelova November 25, 2025 09:18

Copilot started work on behalf of vishaangelova November 25, 2025 09:30 View session

Copilot finished work on behalf of vishaangelova November 25, 2025 09:37

Copilot started work on behalf of vishaangelova November 25, 2025 10:18 View session

Copilot finished work on behalf of vishaangelova November 25, 2025 10:24

Copilot started work on behalf of vishaangelova November 25, 2025 10:39 View session

Copilot finished work on behalf of vishaangelova November 25, 2025 10:43

vishaangelova reviewed Nov 25, 2025

View reviewed changes

reference/fleet/elastic-agent-unprivileged.md Show resolved Hide resolved

Copilot started work on behalf of vishaangelova November 25, 2025 10:49 View session

Specify PowerShell before Windows install example

cf0133d

Co-authored-by: vishaangelova <[email protected]>

Copilot AI requested a review from vishaangelova November 25, 2025 10:52

Copilot finished work on behalf of vishaangelova November 25, 2025 10:52

vishaangelova reviewed Nov 25, 2025

View reviewed changes

reference/fleet/elastic-agent-unprivileged.md Show resolved Hide resolved

Copilot started work on behalf of vishaangelova November 25, 2025 11:08 View session

Copilot started work on behalf of vishaangelova November 25, 2025 11:22 View session

Fix note formatting: proper backtick around --password parameter

cfee58d

Co-authored-by: vishaangelova <[email protected]>

Copilot finished work on behalf of vishaangelova November 25, 2025 11:25

vishaangelova marked this pull request as ready for review November 25, 2025 11:29

vishaangelova requested a review from a team as a code owner November 25, 2025 11:29

github-actions bot deployed to docs-preview November 25, 2025 11:30 View deployment

vishaangelova changed the title ~~Fix documentation for unprivileged mode with pre-existing user and group~~ Fix code examples in doc for running Elastic Agent unprivileged Nov 25, 2025

vishaangelova requested a review from blakerouse November 25, 2025 13:27

alexandra5000 reviewed Nov 28, 2025

View reviewed changes

Copilot started work on behalf of vishaangelova November 28, 2025 13:45 View session

Update reference/fleet/elastic-agent-unprivileged.md

1241718

github-actions bot deployed to docs-preview November 28, 2025 13:46 View deployment

Remove nested bullet points, format as paragraphs under list items

f9da888

- Changed lines 67 and 73 from nested bullet points (*) to regular paragraphs indented under their respective list items Co-authored-by: vishaangelova <[email protected]>

Copilot finished work on behalf of vishaangelova November 28, 2025 13:49

github-actions bot deployed to docs-preview November 28, 2025 13:52 View deployment

Merge branch 'main' into copilot/fix-docs-unprivileged-mode

74d4523

github-actions bot deployed to docs-preview November 28, 2025 14:18 View deployment

michel-laterman approved these changes Nov 28, 2025

View reviewed changes

vishaangelova requested review from a team and alexandra5000 November 28, 2025 19:25

vishaangelova reviewed Nov 28, 2025

View reviewed changes

reference/fleet/elastic-agent-unprivileged.md Outdated Show resolved Hide resolved

Update reference/fleet/elastic-agent-unprivileged.md

072e1f4

vishaangelova self-requested a review November 28, 2025 19:31

github-actions bot deployed to docs-preview November 28, 2025 19:31 View deployment

vishaangelova requested a review from a team November 28, 2025 19:42


		* 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.

Fix code examples in doc for running Elastic Agent unprivileged #4070

Are you sure you want to change the base?

Fix code examples in doc for running Elastic Agent unprivileged #4070

Conversation

Copilot AI commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Generative AI disclosure

Preview

Uh oh!

vishaangelova commented Nov 25, 2025

Uh oh!

Copilot AI commented Nov 25, 2025

Uh oh!

vishaangelova commented Nov 25, 2025

Uh oh!

Copilot AI commented Nov 25, 2025

Uh oh!

vishaangelova commented Nov 25, 2025

Uh oh!

Copilot AI commented Nov 25, 2025

Uh oh!

Uh oh!

Uh oh!

vishaangelova commented Nov 25, 2025

Uh oh!

Copilot AI commented Nov 25, 2025

Uh oh!

github-actions bot commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

vishaangelova commented Nov 25, 2025

Uh oh!

alexandra5000 Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

vishaangelova Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vale Linting Results

Uh oh!

michel-laterman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Nov 25, 2025 •

edited

Loading

github-actions bot commented Nov 25, 2025 •

edited

Loading

github-actions bot commented Nov 28, 2025 •

edited

Loading