Documentation improvements

Improved the documentation to make it clearer and more readable. Mostly,
I added a bunch of commas because, in general, commas make the world a
better, safer place. Isn't that right, Grandma?

Author: jsollom-hpe

background/ncn_boot_workflow.md

@@ -29,15 +29,44 @@ PXE. The method to use will vary depending on the system environment.
    ncn# cat /proc/cmdline
    ```
 
-   If it starts with `kernel` then the node network booted. If it starts with `BOOT_IMAGE=(` then it disk booted.
+   If it starts with `kernel`, then the node network booted. If it starts with `BOOT_IMAGE=(`, then it disk booted.
 
 1. Check output from `efibootmgr`.
 
    ```bash
    ncn# efibootmgr
    ```
 
-   The `BootCurrent` value should be matched to the list beneath to see if it lines up with a networking option or a `cray sd*)` option for disk boots.
+   The `BootCurrent` value should be matched to the list beneath it to see if it lines up with a networking option or a `cray sd*)` option for disk boots.
+
+   ```bash
+   ncn# efibootmgr
+   BootCurrent: 0016    <---- BootCurrent
+   Timeout: 2 seconds
+   BootOrder: 0000,0011,0013,0014,0015,0016,0017,0005,0007,0018,0019,001A,001B,001C,001D,001E,001F,0020,0021,0012
+   Boot0000* cray (sda1)
+   Boot0001* UEFI: Built-in EFI Shell
+   Boot0005* UEFI: PXE IP4 Mellanox Network Adapter - B8:59:9F:1D:D8:4E
+   Boot0007* UEFI: PXE IP4 Mellanox Network Adapter - B8:59:9F:1D:D8:4F
+   Boot0010* UEFI: AMI Virtual CDROM0 1.00
+   Boot0011* cray (sdb1)
+   Boot0012* UEFI: Built-in EFI Shell
+   Boot0013* UEFI OS
+   Boot0014* UEFI OS
+   Boot0015* UEFI: AMI Virtual CDROM0 1.00
+   Boot0016* UEFI: SanDisk     <--- Matches here
+   Boot0017* UEFI: SanDisk, Partition 2
+   Boot0018* UEFI: HTTP IP4 Intel(R) I350 Gigabit Network Connection
+   Boot0019* UEFI: PXE IP4 Intel(R) I350 Gigabit Network Connection
+   Boot001A* UEFI: HTTP IP4 Mellanox Network Adapter - B8:59:9F:1D:D8:4E
+   Boot001B* UEFI: HTTP IP4 Mellanox Network Adapter - B8:59:9F:1D:D8:4F
+   Boot001C* UEFI: HTTP IP4 Intel(R) I350 Gigabit Network Connection
+   Boot001D* UEFI: PXE IP4 Intel(R) I350 Gigabit Network Connection
+   Boot001E* UEFI: PXE IP6 Intel(R) I350 Gigabit Network Connection
+   Boot001F* UEFI: PXE IP6 Intel(R) I350 Gigabit Network Connection
+   Boot0020* UEFI: PXE IP6 Mellanox Network Adapter - B8:59:9F:1D:D8:4E
+   Boot0021* UEFI: PXE IP6 Mellanox Network Adapter - B8:59:9F:1D:D8:4F
+   ```
 
 <a name="set-bmcs-to-dhcp"></a>
 ### Set BMCs to DHCP

index.md

@@ -12,8 +12,8 @@ perform their function as Kubernetes master nodes, Kubernetes worker nodes, or u
 nodes with the Ceph storage.
 
 System services on these nodes are provided as containerized micro-services packaged for deployment
-as helm charts. These services are orchestrated by Kubernetes to be scheduled on Kubernetes worker
-nodes with horizontal scaling to increase or decrease the number of instances of some services as
+via Helm charts. Kubernetes orchestrates these services and schedules them on Kubernetes worker
+nodes with horizontal scaling. Horizontal scales increases or decreases the number of service instances as
 demand for them varies, such as when booting many compute nodes or application nodes.
 
 This information is intended for system installers, system administrators, and network administrators

install/boot_livecd_virtual_iso.md

@@ -115,4 +115,4 @@ tar xf /run/overlay.tar.gz -C /run/overlayfs/rw
 mount -o remount /
 ```
 
-If you excluded the `squashfs` files from the backup you will also need to repopulate them following the configuration section.
+If you excluded the `squashfs` files from the backup, you will also need to repopulate them following the configuration section.

install/bootstrap_livecd_remote_iso.md

@@ -30,8 +30,8 @@ The LiveCD Remote ISO has known compatibility issues for nodes from certain vend
 ### 2. Attaching and Booting the LiveCD with the BMC
 
 > **Warning:** If this is a re-installation on a system that still has a USB device from a prior
-> installation then that USB device must be wiped before continuing. Failing to wipe the USB, if present, may result in confusion.
-> If the USB is booted still then it can wipe itself using the [basic wipe from Wipe NCN Disks for Reinstallation](wipe_ncn_disks_for_reinstallation.md#basic-wipe). If it is not booted, please do so and wipe it _or_ disable the USB ports in the BIOS (not available for all vendors).
+> installation, then that USB device must be wiped before continuing. Failing to wipe the USB, if present, may result in confusion.
+> If the USB is still booted, then it can wipe itself using the [basic wipe from Wipe NCN Disks for Reinstallation](wipe_ncn_disks_for_reinstallation.md#basic-wipe). If it is not booted, please do so and wipe it _or_ disable the USB ports in the BIOS (not available for all vendors).
 
 Obtain and attach the LiveCD cray-pre-install-toolkit ISO file to the BMC. Depending on the vendor of the node,
 the instructions for attaching to the BMC will differ.
@@ -109,7 +109,7 @@ On first login (over SSH or at local console) the LiveCD will prompt the adminis
    1. Setup Variables.
 
       ```bash
-      # The IPv4 Address for the nodes external interface(s); this will be provided if not already by the site's network administrator or network authority.
+      # The IPv4 Address for the nodes external interface(s); this will be provided, if not already by the site's network administrator or network authority.
       pit# site_ip=172.30.XXX.YYY/20
       pit# site_gw=172.30.48.1
       pit# site_dns=172.30.84.40
@@ -126,7 +126,7 @@ On first login (over SSH or at local console) the LiveCD will prompt the adminis
       pit# /root/bin/csi-setup-lan0.sh $site_ip $site_gw $site_dns $site_nics
       ```
 
-   1. (recommended) print `lan0`, and if it has an IP address then exit console and log in again using SSH. The
+   1. (recommended) print `lan0`, and if it has an IP address, then exit console and log in again using SSH. The
       SSH connection will provide larger window sizes and better bufferhandling (screen wrapping).
 
       ```bash
@@ -237,7 +237,7 @@ On first login (over SSH or at local console) the LiveCD will prompt the adminis
 
 1. Download and install/upgrade the workaround and documentation RPMs.
 
-   If this machine does not have direct Internet access these RPMs will need to be externally downloaded and then copied to the system.
+   If this machine does not have direct Internet access, these RPMs will need to be externally downloaded and then copied to the system.
 
    **Important:** In an earlier step, the CSM release plus any patches, workarounds, or hotfixes
    were downloaded to a system using the instructions in [Check for Latest Workarounds and Documentation Updates](../update_product_stream/index.md#workarounds). Use that set of RPMs rather than downloading again.
@@ -265,14 +265,14 @@ On first login (over SSH or at local console) the LiveCD will prompt the adminis
    - `ncn_metadata.csv`
    - `switch_metadata.csv`
    - `system_config.yaml` (see below)
-
-   > The optional `application_node_config.yaml` file may be provided for further defining of settings relating to how application nodes will appear in HSM for roles and subroles. See [Create Application Node YAML](create_application_node_config_yaml.md)
-
+   
+   > The optional `application_node_config.yaml` file may be provided to further assign application nodes to roles and subroles in the HSM. See [Create Application Node YAML](create_application_node_config_yaml.md)
+   
    > The optional `cabinets.yaml` file allows cabinet naming and numbering as well as some VLAN overrides. See [Create Cabinets YAML](create_cabinets_yaml.md).
-
-   > The `system_config.yaml` is required for a reinstall, because it was created during a previous install. For a first time install, the information in it can be provided as command line arguments to `csi config init`.
-
-
+   
+   > The `system_config.yaml` is required for a reinstall because it was created during a previous install. For a first time install, the information in it can be provided as command line arguments to `csi config init`.
+   
+   
    1. Change into the preparation directory.
 
       ```bash
@@ -281,9 +281,9 @@ On first login (over SSH or at local console) the LiveCD will prompt the adminis
       ```
 
       After gathering the files into this working directory, generate your configurations.
-
-   1. If doing a reinstall and have the `system_config.yaml` parameter file avail available, then generate the system configuration reusing this parameter file (see [avoiding parameters](../background/cray_site_init_files.md#save-file--avoiding-parameters)).
-
+   
+   1. If doing a reinstall and have the `system_config.yaml` parameter file available, then generate the system configuration reusing this parameter file (see [avoiding parameters](../background/cray_site_init_files.md#save-file--avoiding-parameters)).
+   
       If not doing a reinstall of Shasta software, then the `system_config.yaml` file will not be available, so skip the rest of this step.
 
       1. Check for the configuration files. The needed files should be in the current directory.

install/collect_mac_addresses_for_ncns.md

@@ -1,7 +1,7 @@
 # Collect MAC Addresses for NCNs
 
 Now that the PIT node has been booted with the LiveCD and the management network switches have been configured,
-the actual MAC address for the management nodes can be collected. This process will include repetition of some
+the actual MAC addresses for the management nodes can be collected. This process will include repetition of some 
 of the steps done up to this point because `csi config init` will need to be run with the proper
 MAC addresses and some services will need to be restarted.
 
@@ -33,7 +33,7 @@ See [Collecting BMC MAC Addresses](collecting_bmc_mac_addresses.md).
 <a name="restart_services_after_bmc_mac_addresses_collected"></a>
 ### 2. Restart Services after BMC MAC Addresses Collected
 
-The previous step updated `ncn_metadata.csv` with the BMC MAC Addresses so several earlier steps need to be repeated.
+The previous step updated `ncn_metadata.csv` with the BMC MAC Addresses, so several earlier steps need to be repeated.
 
 1. Change into the preparation directory.
 
@@ -132,7 +132,7 @@ making a backup of them, in case they need to be examined at a later time.
 
 1. Check that IP addresses are set for each interface and investigate any failures.
 
-    1. Check IP addresses, do not run tests if these are missing and instead start triage.
+    1. Check IP addresses. Do not run tests if these are missing and instead start triaging the issue.
 
        ```bash
        pit# wicked show bond0 vlan002 vlan004 vlan007
@@ -166,7 +166,7 @@ making a backup of them, in case they need to be examined at a later time.
        addr:     ipv4 10.254.1.4/17 [static]
        ```
 
-    1. Run tests, inspect failures.
+    1. Run tests; inspect failures.
 
        ```bash
        pit# csi pit validate --network
@@ -244,7 +244,7 @@ so several earlier steps need to be repeated.
    pit# cat ncn_metadata.csv
    ```
 
-1. Remove the incorrectly generated configs. Before deleting the incorrectly generated configs consider
+1. Remove the incorrectly generated configs. Before deleting the incorrectly generated configs, consider
 making a backup of them, in case they need to be examined at a later time.
 
    > **`WARNING`** Ensure that the `SYSTEM_NAME` environment variable is correctly set.
@@ -325,7 +325,7 @@ making a backup of them, in case they need to be examined at a later time.
 
 1. Check that IP addresses are set for each interface and investigate any failures.
 
-    1. Check IP addresses, do not run tests if these are missing and instead start triage.
+    1. Check IP addresses. Do not run tests if these are missing and instead start triaging the issue.
 
        ```bash
        pit# wicked show bond0 vlan002 vlan004 vlan007
@@ -359,7 +359,7 @@ making a backup of them, in case they need to be examined at a later time.
        addr:     ipv4 10.254.1.4/17 [static]
        ```
 
-    1. Run tests, inspect failures.
+    1. Run tests; inspect failures.
 
        ```bash
        pit# csi pit validate --network

install/collecting_ncn_mac_addresses.md

@@ -5,8 +5,8 @@ you will have the MAC addresses needed for the Bootstrap MAC, Bond0 MAC0, and Bo
 
 The Bootstrap MAC address will be used for identification of this node during the early part of the PXE boot process before the bonded interface can be established.
 The Bond0 MAC0 and Bond0 MAC1 are the MAC addresses for the physical interfaces that your node will use for the various VLANs.
-The Bond0 MAC0 and Bond0 MAC1 should be on the different network cards to establish redundancy for a failed network card.
-On the other hand, if the node has only a single network card, then MAC1 and MAC0 will still produce a valid configuration if they do reside on the same physical card.
+The Bond0 MAC0 and Bond0 MAC1 should be on different network cards to establish redundancy in case either network card fails.
+On the other hand, if the node only has a single network card, then MAC1 and MAC0 will still produce a valid configuration if they reside on the same physical card.
 
 #### Sections
 
@@ -18,13 +18,13 @@ On the other hand, if the node has only a single network card, then MAC1 and MAC
 
 The easy way to do this leverages the NIC-dump provided by the metal-ipxe package. This page will walk-through
 booting NCNs and collecting their MACs from the conman console logs.
-> The alternative is to use serial cables (or SSH) to collect the MACs from the switch ARP tables, this can become exponentially difficult for large systems.
+> The alternative is to use serial cables (or SSH) to collect the MACs from the switch ARP tables, which can become exponentially difficult for large systems.
 > If this is the only way, please proceed to the bottom of this page.
 
 <a name="procedure-ipxe-consoles"></a>
 ## Procedure: iPXE Consoles
 
-This procedure is faster for those with the LiveCD (CRAY Pre-Install Toolkit) it can be used to quickly
+This procedure is faster for those with the LiveCD (CRAY Pre-Install Toolkit). It can be used to quickly
 boot-check nodes to dump network device information without an operating system. This works by accessing the PCI Configuration Space.
 
 <a name="requirements"></a>
@@ -72,7 +72,7 @@ For help with either of those, see [LiveCD Setup](bootstrap_livecd_remote_iso.md
     pit# sleep 10
     pit# grep -oP "($mtoken|$stoken|$wtoken)" /etc/dnsmasq.d/statics.conf | sort -u | xargs -t -i ipmitool -I lanplus -U $USERNAME -E -H {} power on
     ```
-4. Now wait for the nodes to netboot. You can follow them with `conman -j ncn-*id*-mgmt` (use `conman -q` to see ). This takes less than 3 minutes, speed depends on how quickly your nodes POST.
+4. Now wait for the nodes to netboot. You can follow them with `conman -j ncn-*id*-mgmt` (use `conman -q` to see the list of nodes). This takes less than 3 minutes, speed depends on how quickly your nodes POST.
 5. Print off what has been found in the console logs, this snippet will omit duplicates from multiple boot attempts:
     ```bash
     pit# for file in /var/log/conman/*; do
@@ -101,7 +101,7 @@ For help with either of those, see [LiveCD Setup](bootstrap_livecd_remote_iso.md
             grep -Eoh '(net[0-9] MAC .*)' $file | sort -u | grep PCI | grep -Ev "$did" && echo -----
         done
         ```
-7. Examine the output from `grep` to identify the MAC address that make up Bond0 for each management NCN, use the lowest value MAC address per PCIe card.
+7. Examine the output from `grep` to identify the MAC address that make up Bond0 for each management NCN. Use the lowest value MAC address per PCIe card.
 
     > example: 1 PCIe card with 2 ports for a total of 2 ports per node.\
 
@@ -127,7 +127,7 @@ For help with either of those, see [LiveCD Setup](bootstrap_livecd_remote_iso.md
     -----
     ```
 
-    The above output identified MAC0 and MAC1 of the bond as 94:40:c9:5f:b5:df and 14:02:ec:da:b9:99 respectively.
+    The above output identified MAC0 and MAC1 of the bond as 94:40:c9:5f:b5:df and 14:02:ec:da:b9:98 respectively.
 
 8. Collect the NCN MAC address for the PIT node. This information will be used to populate the MAC addresses for ncn-m001.
 
@@ -140,7 +140,7 @@ For help with either of those, see [LiveCD Setup](bootstrap_livecd_remote_iso.md
 9. Update `ncn_metadata.csv` with the collected MAC addresses for Bond0 from all of the management NCNs.
     > Tip: Mind the index (3, 2, 1.... ; not 1, 2, 3)
 
-    For each NCN update the corresponding row in `ncn_metadata` with the values for Bond0 MAC0 and Bond0 MAC1. The Bootstrap MAC should have the same value as the Bond0 MAC0.
+    For each NCN, update the corresponding row in `ncn_metadata` with the values for Bond0 MAC0 and Bond0 MAC1. The Bootstrap MAC should have the same value as the Bond0 MAC0.
 
     ```
     Xname,Role,Subrole,BMC MAC,Bootstrap MAC,Bond0 MAC0,Bond0 MAC1
@@ -179,7 +179,8 @@ is quicker.
 
 If you have an incorrect `ncn_metadata.csv` file, you will be unable to deploy the NCNs. This section details a recovery procedure in case that happens.
 
-1. Remove the incorrectly generated configurations. Before deleting the incorrectly generated configurations, consider making a backup of them. In case they need to be examined at a later time.
+1. Remove the incorrectly generated configurations. Before deleting the incorrectly generated configurations, consider making a backup of them, in case, they need to be examined at a later time. 
+
 
     > **`WARNING`** Ensure that the `SYSTEM_NAME` environment variable is correctly set. If `SYSTEM_NAME` is
     > not set the command below could potentially remove the entire prep directory.

install/configure_administrative_access.md

@@ -3,7 +3,7 @@
 There are several operations which configure administrative access to different parts of the system.
 Ensuring that the `cray` CLI can be used by administrative credentials enables use of many management
 services via commands. The management nodes can be locked from accidental manipulation by the
-`cray capmc` and `cray fas` commands when then intent is to work on the entire system except the
+`cray capmc` and `cray fas` commands when the intent is to work on the entire system except the
 management nodes. The `cray scsd` command can change the SSH keys, NTP server, syslog server, and
 BMC/controller passwords.
 
@@ -38,9 +38,9 @@ BMC/controller passwords.
       APIs into easily usable commands.
 
       Later procedures in the installation workflow use the `cray` command to interact with multiple services.
-      The `cray` CLI configuration needs to be initialized for the Linux account and the keycloak user credentials
-      used in initialization running the procedure needs to be authorized for administrative actions.
-
+      The `cray` CLI configuration needs to be initialized for the Linux account. The Keycloak user who initializes the
+      CLI configuration needs to be authorized for administrative actions.
+   
       See [Configure the Cray Command Line Interface (cray CLI)](../operations/configure_cray_cli.md)
    <a name="lock_management_nodes"></a>
    1. Lock Management Nodes
@@ -53,9 +53,8 @@ BMC/controller passwords.
       If a single node is taken down by mistake, it is possible that things will recover. However, if all management
       nodes are taken down, or all Kubernetes worker nodes are taken down by mistake, the system is dead and has to be
       completely restarted.
-
-      Lock the management nodes **now**!
-
+      **Lock the management nodes now!**
+   
       See [Lock and Unlock Nodes](../operations/hardware_state_manager/Lock_and_Unlock_Management_Nodes.md)
    <a name="configure_with_scsd"></a>
    1. Configure BMC and Controller Parameters with SCSD

install/configure_management_network.md

@@ -9,7 +9,7 @@ It is assumed that the administrator configuring the Management Network has a ba
 
 Before configuring/reconfiguring any switches make sure to get the current running config and save that in case you need to revert the config.
 
-save the output of.
+Save the output:
 ```
 show run
 ```