Idea for clarifying what commands need to be run by root

[drothery-edb]

Summary

We received this feedback from a federal customer shared by the CSM, Georgia Nicolaides:

Most of your documentation does not indicate which user should run a command (e.g. root, enterprisedb, etc.). Obviously the systemctl commands are run by root, but for other install/configure commands it is not so evident. PostgreSQL/EPAS/PEM are all new to us, so it would be most helpful if your documentation indicated the user for all commands. Thus far, we have just been doing trial and error to figure it out.

We do have one topic where we used a new parameter for a code block (promptUser) to indicate when a command required root. See https://www.enterprisedb.com/docs/pem/latest/registering_agent/#examples. For the examples that did not require root, we added dollar signs to represent a regular user prompt. Here are some options for a more holistic approach when user clarification is not handled in the content itself or by other methods (for example, using sudo for install commands):

1. Only indicate when root is required
2. Always indicate what type of user can run the command
3. To indicate root is required, use one of:
   1. Use promptUser for root
   2. Use a comment in the code block to indicate root is required (not promptUser)
   3. Use text in the content to indicate root is required (might be the correct approach in some contexts)
4. If we decide to use an indicator when root is not required: 2. Use promptUser 3. Use a comment 4. Use text in the content

Probably the best user experience would be 2, 3.i, 4.i. This might be overkill though and comes at a very high cost.

Two MVP approaches we could run by the customer are:

• 1., 3.i
• 1., 3.ii

[drothery-edb]

Question: is using sudo in commands requiring a root user a viable option? If we think so, we could include that as another possible MVP approach.

[josh-heyer]

Let's start by gathering some examples across different products where commands need to be run as a specific user. Ex:

• Command needs to be run as root
• Command needs to be run as postgres
• Command needs to be run as barman
• Command needs to be run as a normal user account.

With these examples, we can experiment with different options to see what strateg(ies) work well across the board.

See also: https://github.com/EnterpriseDB/docs/pull/3330

[drothery-edb]

Here is a link with some examples in the existing content.

[josh-heyer]

Waiting on customer feedback on example!

[drothery-edb]

Here is our prototype: https://github.com/EnterpriseDB/docs/pull/3733

[drothery-edb]

Add more examples from Index Advisor topic (https://www.enterprisedb.com/docs/epas/latest/epas_guide/03_database_administration/02_index_advisor/02_index_advisor_configuration/) , write up guidelines, socialize with team

[josh-heyer]

TODOs:

• reduce instances (and provide style guide prohibition) where we instruct readers to log in as root vs sudo, etc
• be consistent about guidance where commands need to be run as a specific user (e.g. enterprisedb)
• look into styling convention for using admonitions to indicate role (e.g. "danger" for root...)

[josh-heyer]

At some point @djw-m and @nidhibhammar are going to sync up on this...

[djw-m]

1. Policy first: We should never tell users to log in as root, or raise privileges unecessarily. Always use sudo to execute single commands with privilege.
2. Use sudo for alternate user identities
3. No need to delineate that a privilege is being taken - the sudo command does that inline for us
4. Danger comes in many forms and we should select an admonition (Warning/Danger?) for dangerous activities in general, not just root/privilege issues. Also best not to say Danger. "Be Aware"?

Searching for user/superuser is probably going to give a lot of false positives.

Suggest searching for "root" and "su -" for any privilege changes.

[nidhibhammar]

PEM Agent can be registered using sudo: https://www.enterprisedb.com/docs/pem/latest/registering_agent/#examples