Improve install docs

docs/whpg/6x/install_guide/config_os.md

@@ -49,6 +49,10 @@ If you choose to deactivate SELinux:
     SELINUX=disabled
     ```
 
+    ::: info Note
+    After editing the config file, rerun `sestatus` and confirm `Mode from config file: disabled`. That field reads `/etc/selinux/config` directly and reflects your edit immediately. `SELinux status:` and `Current mode:` show the state the running kernel loaded at boot, and continue to show the previous state until you reboot.
+    :::
+
 3.  If the System Security Services Daemon (SSSD) is installed on your systems, edit the SSSD configuration file and set the `selinux_provider` parameter to `none` to prevent SELinux-related SSH authentication denials that could occur even with SELinux deactivated. As root, edit `/etc/sssd/sssd.conf` and add this parameter:
 
     ```
@@ -105,9 +109,13 @@ To deactivate `iptables`:
 
     ```
     # systemctl stop firewalld.service
-    # systemctl deactivate firewalld.service
+    # systemctl disable firewalld.service
     ```
 
+    ::: info Note
+    On some machine images, `firewalld` isn't installed. In that case, `systemctl stop firewalld.service` returns `Failed to stop firewalld.service: Unit firewalld.service not loaded`, and `systemctl disable firewalld.service` fails with its own `unit not found` message. Both errors are harmless. If `firewalld` isn't installed, it's already effectively deactivated, and no further action is needed.
+    :::
+
 If you decide to enable `iptables` with WarehousePG for security purposes, see [Enabling iptables (Optional)](enable_iptables.md) for important considerations and example configurations.
 
 See the documentation for the firewall or your operating system for additional information.
@@ -153,6 +161,10 @@ The `sysctl.conf` parameters listed in this topic are for performance, optimizat
 
 Set the parameters in the `/etc/sysctl.conf` file and reload with `sysctl -p`:
 
+:::: warning Caution
+The `kernel.shmall`, `kernel.shmmax`, and `vm.overcommit_ratio` values in this example are calculated for a specific host with 1583 GB of memory. Don't copy these values as-is to a host with a different amount of memory. A `vm.overcommit_ratio` that's too high for the host's actual memory can produce the same `could not map anonymous shared memory` failure covered in [Troubleshooting Initialization Problems](init_whpg.md#topic7). Calculate `kernel.shmall` and `kernel.shmmax` for your own host as described in [Shared Memory Pages](#shared-memory-pages) below, and `vm.overcommit_ratio` as described in [Segment Host Memory](#segment-host-memory) below, then substitute your calculated values in the file.
+::::
+
 ```
 
 # kernel.shmall = _PHYS_PAGES / 2 # See Shared Memory Pages
@@ -206,8 +218,8 @@ kernel.shmmax = ( _PHYS_PAGES / 2) * PAGE_SIZE
 To calculate the values for `kernel.shmall` and `kernel.shmmax`, run the following commands using the `getconf` command, which returns the value of an operating system variable.
 
 ```
-$ echo $(expr $(getconf _PHYS_PAGES) / 2) 
-$ echo $(expr $(getconf _PHYS_PAGES) / 2 \* $(getconf PAGE_SIZE))
+echo $(expr $(getconf _PHYS_PAGES) / 2) 
+echo $(expr $(getconf _PHYS_PAGES) / 2 \* $(getconf PAGE_SIZE))
 ```
 
 As best practice, we recommend you set the following values in the `/etc/sysctl.conf` file using calculated values. For example, a host system has 1583 GB of memory installed and returns these values: \_PHYS_PAGES = 395903676 and PAGE_SIZE = 4096. These would be the `kernel.shmall` and `kernel.shmmax` values:
@@ -521,7 +533,8 @@ After adding the parameter, reboot the system.
 This cat command checks the state of THP. The output indicates that THP is deactivated.
 
 ```
-$ cat /sys/kernel/mm/*transparent_hugepage/enabled
+cat /sys/kernel/mm/*transparent_hugepage/enabled
+__OUTPUT__
 always [never]
 ```
 
@@ -686,9 +699,9 @@ The `gpadmin` user must have permission to access the services and directories r
 
 The `gpadmin` user on each WarehousePG host must have an SSH key pair installed and be able to SSH from any host in the cluster to any other host in the cluster without entering a password or passphrase (called "passwordless SSH"). If you enable passwordless SSH from the coordinator host to every other host in the cluster ("1-*n* passwordless SSH"), you can use the WarehousePG `gpssh-exkeys` command-line utility later to enable passwordless SSH from every host to every other host ("*n*-*n* passwordless SSH").
 
-You can optionally give the `gpadmin` user sudo privilege, so that you can easily administer all hosts in the WarehousePG cluster as `gpadmin` using the `sudo`, `ssh/scp`, and `gpssh/gpscp` commands.
+Give the `gpadmin` user sudo privilege, so that you can administer all hosts in the WarehousePG cluster as `gpadmin` using the `sudo`, `ssh/scp`, and `gpssh/gpscp` commands. Several procedures in this guide run `sudo` commands on remote hosts through `gpssh`, which provides no terminal for a password prompt, so the grant must let `gpadmin` run `sudo` without a password (`NOPASSWD`), as shown in step 3 below.
 
-The following steps show how to set up the `gpadmin` user on a host, set a password, create an SSH key pair, and (optionally) enable sudo capability. These steps must be performed as root on every WarehousePG cluster host. (For a large WarehousePG cluster you will want to automate these steps using your system provisioning tools.)
+The following steps show how to set up the `gpadmin` user on a host, set a password, create an SSH key pair, and enable passwordless sudo capability. These steps must be performed as root on every WarehousePG cluster host. (For a large WarehousePG cluster you will want to automate these steps using your system provisioning tools.)
 
 > **Note** See [Example Ansible Playbook](ansible-example.md) for an example that shows how to automate the tasks of creating the `gpadmin` user and installing the WarehousePG software on all hosts in the cluster.
 
@@ -702,6 +715,7 @@ The following steps show how to set up the `gpadmin` user on a host, set a passw
     # groupadd gpadmin
     # useradd gpadmin -r -m -g gpadmin
     # passwd gpadmin
+    __OUTPUT__
     New password: <changeme>
     Retype new password: <changeme>
     ```
@@ -713,8 +727,9 @@ The following steps show how to set up the `gpadmin` user on a host, set a passw
 2.  Switch to the `gpadmin` user and generate an SSH key pair for the `gpadmin` user.
 
     ```
-    $ su gpadmin
-    $ ssh-keygen -t rsa -b 4096
+    su gpadmin
+    ssh-keygen -t rsa -b 4096
+    __OUTPUT__
     Generating public/private rsa key pair.
     Enter file in which to save the key (/home/gpadmin/.ssh/id_rsa):
     Created directory '/home/gpadmin/.ssh'.

docs/whpg/6x/install_guide/create_data_dirs.md

@@ -19,24 +19,24 @@ A data storage area is required on the WarehousePG coordinator and standby coord
 
 The data directory location on the coordinator is different than those on the segments. The coordinator does not store any user data, only the system catalog tables and system metadata are stored on the coordinator instance, therefore you do not need to designate as much storage space as on the segments.
 
-1.  Create or choose a directory that will serve as your coordinator data storage area. This directory should have sufficient disk space for your data and be owned by the `gpadmin` user and group. For example, run the following commands as `root`:
+1.  Create or choose a directory that will serve as your coordinator data storage area. This directory should have sufficient disk space for your data and be owned by the `gpadmin` user and group. For example, run the following command using `sudo`:
 
     ```
-    # mkdir -p /data/master
+    sudo mkdir -p /data/master
     ```
 
-2.  Change ownership of this directory to the `gpadmin` user. For example:
+2.  Change ownership of this directory, and any parent directories you created, to the `gpadmin` user. For example:
 
     ```
-    # chown gpadmin:gpadmin /data/master
+    sudo chown gpadmin:gpadmin /data
+    sudo chown -R gpadmin:gpadmin /data/master
     ```
 
-3.  Using [gpssh](../ref_guide/utility_guide/reference/gpssh.md), create the coordinator data directory location on your standby coordinator as well. For example:
+3.  As the `gpadmin` user, use [gpssh](../ref_guide/utility_guide/reference/gpssh.md) to create the coordinator data directory location on your standby coordinator as well. For example:
 
     ```
-    # source /usr/edb/whpg6/greenplum_path.sh 
-    # gpssh -h smdw -e 'mkdir -p /data/master'
-    # gpssh -h smdw -e 'chown gpadmin:gpadmin /data/master'
+    gpssh -h smdw -e 'sudo mkdir -p /data/master'
+    gpssh -h smdw -e 'sudo chown -R gpadmin:gpadmin /data/master'
     ```
 
 <a id="topic_plx_zps_vhb"></a>
@@ -49,12 +49,17 @@ Data storage areas are required on the WarehousePG segment hosts for primary seg
 
 ### To create the data directory locations on all segment hosts
 
-1.  On the coordinator host, log in as `root`:
+1.  On the coordinator host, switch to the `gpadmin` user and source the `greenplum_path.sh` file.
 
     ```
-    # su
+    sudo -iu gpadmin
+    source /usr/local/greenplum-db/greenplum_path.sh
     ```
 
+    ::: info Note
+    Logging in as `root` with `su` fails on hosts where root login is deactivated, such as Amazon EC2 instances. The `gpssh` commands in this topic use `sudo` on the remote hosts instead, so you can run them as `gpadmin`, provided `gpadmin` has `sudo` privilege as described in [Creating the WarehousePG Administrative User](config_os.md#topic23).
+    :::
+
 2.  Create a file called `hostfile_gpssh_segonly`. This file should have only one machine configured host name for each segment host. For example, if you have three segment hosts:
 
     ```
@@ -66,14 +71,17 @@ Data storage areas are required on the WarehousePG segment hosts for primary seg
 3.  Using [gpssh](../ref_guide/utility_guide/reference/gpssh.md), create the primary and mirror data directory locations on all segment hosts at once using the `hostfile_gpssh_segonly` file you just created. For example:
 
     ```
-    # source /usr/edb/whpg6/greenplum_path.sh 
-    # gpssh -f hostfile_gpssh_segonly -e 'mkdir -p /data1/primary'
-    # gpssh -f hostfile_gpssh_segonly -e 'mkdir -p /data2/primary'
-    # gpssh -f hostfile_gpssh_segonly -e 'mkdir -p /data1/mirror'
-    # gpssh -f hostfile_gpssh_segonly -e 'mkdir -p /data2/mirror'
-    # gpssh -f hostfile_gpssh_segonly -e 'chown -R gpadmin /data*/*'
+    gpssh -f hostfile_gpssh_segonly -e 'sudo mkdir -p /data1/primary'
+    gpssh -f hostfile_gpssh_segonly -e 'sudo mkdir -p /data2/primary'
+    gpssh -f hostfile_gpssh_segonly -e 'sudo mkdir -p /data1/mirror'
+    gpssh -f hostfile_gpssh_segonly -e 'sudo mkdir -p /data2/mirror'
+    gpssh -f hostfile_gpssh_segonly -e 'sudo chown -R gpadmin:gpadmin /data1 /data2'
     ```
 
+    ::: warning Caution
+    Use `chown -R gpadmin:gpadmin /data1 /data2` rather than `chown -R gpadmin /data*/*`. The latter sets only the owner, not the group, so the primary and mirror directories stay in the `root` group. Setting both the owner and group to `gpadmin` avoids permission problems later.
+    :::
+
 <a id="topic_cwj_hzb_vhb"></a>
 
 ## Next Steps