Tidy up README (#43)

This cleans up the README, fixing old/stale links and formatting various
pieces.

README.md

@@ -1,4 +1,3 @@
-<a name="metal-90mdsquash---redundant-squashfs-and-overlayfs-storage"></a>
 # METAL 90mdsquash - redundant squashFS and overlayFS storage
 
 The Metal MDSquash dracut module lives in the initramFS, used during a server's boot. Within the initramFS, `metalmdsquash` does three things:
@@ -13,58 +12,50 @@ Variable by customization arguments, the redundant storage will provision mirror
 will contain 3 partitions; a partition for storing the fallback bootloader, another for storing squashFS images, and a final one for
 storing persistent overlays.
 
-> For information on partitioning and disks in Shasta, see [NCN Partitioning](https://stash.us.cray.com/projects/MTL/repos/docs-csm-install/browse/104-NCN-PARTITIONING.md).
-
-<a name="table-of-contents"></a>
-#### Table of Contents
-
-* [METAL 90mdsquash - redundant squashFS and overlayFS storage](README.md#metal-90mdsquash---redundant-squashfs-and-overlayfs-storage)
-  * [Table of Contents](README.md#table-of-contents)
-  * [Requirements](README.md#requirements)
-  * [Usage](README.md#usage)
-  * [URI Drivers](README.md#uri-drivers)
-* [Parameters](README.md#parameters)
-  * [Kernel Parameters](README.md#kernel-parameters)
-    * [metal-mdsquash customizations](README.md#metal-mdsquash-customizations)
-      * [`metal.debug`](README.md#metaldebug)
-      * [`metal.disks`](README.md#metaldisks)
-      * [`metal.md-level`](README.md#metalmd-level)
-      * [`metal.no-wipe`](README.md#metalno-wipe)
-      * [`metal.wipe-delay`](README.md#metalwipe-delay)
-      * [`metal.ipv4`](README.md#metalipv4)
-      * [`metal.sqfs-md-size`](README.md#metalsqfs-md-size)
-      * [`metal.oval-md-size`](README.md#metaloval-md-size)
-      * [`metal.aux-md-size`](README.md#metalaux-md-size)
-    * [dmsquashlive customizations](README.md#dmsquashlive-customizations)
-      * [`rd.live.dir`](README.md#`rdlivedir`)
-      * [`root`](README.md#`root`)
-      * [`rd.live.overlay`](README.md#`rdliveoverlay`)
-      * [`rd.live.overlay.readonly`](README.md#`rdliveoverlayreadonly`)
-      * [`rd.live.overlay.reset`](README.md#`rdliveoverlayreset`)
-      * [`rd.live.overlay.size`](README.md#`rdliveoverlaysize`)
-      * [`rd.live.squashimg`](README.md#`rdlivesquashimg`)
-    * [dracut : standard customizations](README.md#dracut--standard-customizations)
-      * [`rootfallback`](README.md#`rootfallback`)
-  * [Required Parameters](README.md#required-parameters)
-    * [`metal.server=http://pit/$hostname`](README.md#metalserver)
-* [RootFS and the Persistent OverlayFS](README.md#rootfs-and-the-persistent-overlayfs)
-  * [What is a Persistent Overlay?](README.md#what-is-a-persistent-overlay)
-  * [Feature Toggles](README.md#feature-toggles)
-    * [Toggling Persistence](README.md#toggling-persistence)
-    * [Toggling Read-Only OverlayFS](README.md#toggling-read-only-overlayfs)
-    * [Toggling Resetting the Persistent OverlayFS on Boot](README.md#toggling-resetting-the-persistent-overlayfs-on-boot)
-
-
-<a name="requirements"></a>
+> For information on partitioning and disks in Shasta, see [NCN Partitioning](https://github.com/Cray-HPE/docs-csm/blob/main/background/ncn_mounts_and_file_systems.md).
+
+## Table of Contents
+
+- [Requirements](README.md#requirements)
+- [Usage](README.md#usage)
+- [URI Drivers](README.md#uri-drivers)
+- [Parameters](README.md#parameters)
+  - [Kernel Parameters](README.md#kernel-parameters)
+    - [metal-mdsquash customizations](README.md#metal-mdsquash-customizations)
+      - [`metal.debug`](README.md#metaldebug)
+      - [`metal.disks`](README.md#metaldisks)
+      - [`metal.md-level`](README.md#metalmd-level)
+      - [`metal.no-wipe`](README.md#metalno-wipe)
+      - [`metal.wipe-delay`](README.md#metalwipe-delay)
+      - [`metal.ipv4`](README.md#metalipv4)
+      - [`metal.sqfs-md-size`](README.md#metalsqfs-md-size)
+      - [`metal.oval-md-size`](README.md#metaloval-md-size)
+      - [`metal.aux-md-size`](README.md#metalaux-md-size)
+    - [dmsquashlive customizations](README.md#dmsquashlive-customizations)
+      - [`rd.live.dir`](README.md#rdlivedir)
+      - [`root`](README.md#root)
+      - [`rd.live.overlay`](README.md#rdliveoverlay)
+      - [`rd.live.overlay.readonly`](README.md#rdliveoverlayreadonly)
+      - [`rd.live.overlay.reset`](README.md#rdliveoverlayreset)
+      - [`rd.live.overlay.size`](README.md#rdliveoverlaysize)
+      - [`rd.live.squashimg`](README.md#rdlivesquashimg)
+    - [dracut : standard customizations](README.md#dracut--standard-customizations)
+      - [`rootfallback`](README.md#`rootfallback`)
+- [RootFS and the Persistent OverlayFS](README.md#rootfs-and-the-persistent-overlayfs)
+  - [What is a Persistent Overlay?](README.md#what-is-a-persistent-overlay)
+  - [Feature Toggles](README.md#feature-toggles)
+    - [Toggling Persistence](README.md#toggling-persistence)
+    - [Toggling Read-Only OverlayFS](README.md#toggling-read-only-overlayfs)
+    - [Toggling Resetting the Persistent OverlayFS on Boot](README.md#toggling-resetting-the-persistent-overlayfs-on-boot)
+
 ## Requirements
 
 In order to use this dracut module, you need:
 
 1. A local-attached-usb or remote server with a squashFS image.
 2. Physical block devices must be installed in your blade(s).
-3. Two physical disk of 0.5TiB or less (or the RAID must be overridden, see [module customization](#module-customization)
+3. Two physical disk of 0.5TiB or less (or the RAID must be overridden, see [metal mdsquash customization](#metal-mdsquash-customizations)
 
-<a name="usage"></a>
 ## Usage
 
 Specify a local disk device for storing images, and the URL/endpoint to fetch images from on the kernel commandline (e.g. via `grub.cfg`, or an iPXE script).
@@ -76,13 +67,13 @@ metal.server=<URI> root=live:LABEL=SQFSRAID rd.live.squashimg=filesystem.squashf
 The above snippet is the minimal cmdline necessary for this module to function. Additional options 
 are denoted throughout the [module customization](#parameters) section.
 
-<a name="uri-drivers"></a>
 ## URI Drivers
 
 The URI scheme, authority, and
 path values will tell the module where to look for SquashFS. Only those parts of a URI are supported.
 
 - file driver
+
     ```bash
     # Example: Load from another USB stick on the node.
     file://mydir?LABEL=MYUSB
@@ -91,208 +82,167 @@ path values will tell the module where to look for SquashFS. Only those parts of
     # Example: load a file from a PIT recovery USB.
     file://ephemeral/data/ceph/?LABEL=PITDATA
     ```
+
 - http or https driver
+
     ```bash
     http://api-gw-service/path/to/service/endpoint
     http://pit/
     http://10.100.101.111/some/local/server
     ```
 
-Other drivers, such as native `s3`, `scp`, and `ftp` could be _added_.
+Other drivers, such as native `s3`, `scp`, and `ftp` could be *added*.
 
 These drivers schemes are all defined by the rule generator, [`metal-genrules.sh`](./90metalmdsquash/metal-genrules.sh).
 
-<a name="parameters"></a>
-# Parameters
+## Parameters
 
 **The assigned value denotes the default value when the option is omitted on the cmdline.**
 
-<a name="kernel-parameters"></a>
-## Kernel Parameters
+### Kernel Parameters
 
-<a name="metal-mdsquash-customizations"></a>
-### metal-mdsquash customizations
+#### metal-mdsquash customizations
 
-<a name="metaldebug"></a>
 ##### `metal.debug`
-> - `Default: 0`
-> 
+
 > Set `metal.debug=1` to enable debug output from only metal modules. This will verbosely print the creation of the RAIDs and fetching of the squashFS image. **This effectively runs all dracut-metal code with `set -x`**, while leaving the rest of dracut to its own debug level.
+> - `Default: 0`
 
-<a name="metaldisks"></a>
 ##### `metal.disks`
-> - `Default: 2`
-> 
+
 > Specify the number of disks to use in the local RAID (see [`metal.md-level`](README.md#metalmd-level) for changing the RAID type).
+> - `Default: 2`
 
-<a name="metalmd-level"></a>
 ##### `metal.md-level`
-> - `Default: mirror`
-> 
+
 > Change the level passed to mdadm for RAID creation, possible values are any value it takes. 
 > Milaege varies, buyer beware this could dig a hole deeper.
-
-> **`NOTE**: When `metal.disks=1` is set, only mirror and stripe will work.
+> - `Default: mirror`
+>
+> ***NOTE***: When `metal.disks=1` is set, only mirror and stripe will work.
 
 
-<a name="metalno-wipe"></a>
 ##### `metal.no-wipe`
-> - `Default: 0`
-> 
+
 > If this is set to `metal.no-wipe=1`, then all destructive behavior is disabled. The metal modules will either use what they find or make 0 changes during boots. This is insurance, it should not be required. This is helpful for development, or for admins tracking old and new nodes.
+> - `Default: 0`
 
 
-<a name="metalwipe-delay"></a>
 ##### `metal.wipe-delay`
+
+> The number of seconds that the wipe function will wait to allow an administrator to cancel it (by powering the node off). See the source code in [`metal-md-lib.sh`](./90metalmdsquash/metal-md-lib.sh) for minimum and maximum values.
 > - `Default: 5`
 > - `Unit: Seconds`
->
-> The number of seconds that the wipe function will wait to allow an administrator to cancel it (by powering the node off). See the source code in [`metal-md-lib.sh`](./90metalmdsquash/metal-md-lib.sh) for minimum and maximum values.
 
 
-<a name="metalipv4"></a>
 ##### `metal.ipv4`
-> - `Default: 1`
->
+
 > By default, metal-dracut will use IPv4 to resolve the deployment server for the initial call-to-home and when downloading artifacts regardless if IPv6 networking is present in the environment. To disable this constraint, simply set `metal.ipv4=0` in the cmdline. Setting this to `0` will enable all `ping` and `curl` calls for calling-home and downloading artifacts to use **either** IPv6 or IPv4 on their own accord (e.g. if IPv6 exists, then `ping` and `curl` will prefer to use it by default). Presumably if IPv6 is desired and exists, then IPv6 DHCP/DNS and general TCP/IP connectivity is working.
 > Lastly, if IPv6 does not exist then toggling this value to `0` has no effect.
+> - `Default: 1`
 
 
-<a name="metalsqfs-md-size"></a>
 ##### `metal.sqfs-md-size`
-> - `Default: 25`
-> - `Unit: Gigabytes`
-> 
+
 > Set the size for the new SQFS partition.
 > Buyer beware this does not resize, this applies for new partitions.
+> - `Default: 25`
+> - `Unit: Gigabytes`
 
 
-<a name="metaloval-md-size"></a>
 ##### `metal.oval-md-size`
-> - `Default: 150`
-> - `Unit: Gigabytes`
-> 
+
 > Set the size for the new SQFS partition.
 > Buyer beware this does not resize, this applies for new partitions.
+> - `Default: 150`
+> - `Unit: Gigabytes`
 
 
-<a name="metalaux-md-size"></a>
 ##### `metal.aux-md-size`
-> - `Default: 150`
-> - `Unit: Gigabytes`
->
+
 > Set the size for the new SQFS partition.
 > Buyer beware this does not resize, this applies for new partitions.
+> - `Default: 150`
+> - `Unit: Gigabytes`
 
+#### dmsquashlive customizations
 
-<a name="dmsquashlive-customizations"></a>
-### dmsquashlive customizations
-
-reference: [dracut dmsquashlive cmdline](1)
-
+reference: [dracut dmsquashlive cmdline][1]
 
-<a name="rdlivedir"></a>
 ##### `rd.live.dir`
-> - `Default: LiveOS`
-> 
+
 > Name of the directory store and load the artifacts from. Changing this value will affect metal and native-dracut.
+> - `Default: LiveOS`
 
-<a name="root"></a>
 ##### `root`
-> - `Default: live:LABEL=SQFSRAID`
-> 
+
 > Specify the FSlabel of the block device to use for the SQFS storage. This could be an existing RAID or non-RAIDed device.
 > If a label is not found in `/dev/disk/by-label/*`, then the os-disks are paved with a new mirror array.
 > Can also be of UUID or 
+> - `Default: live:LABEL=SQFSRAID`
 
-<a name="rdliveoverlay"></a>
 ##### `rd.live.overlay`
-> - `Default: LABEL=ROOTRAID`
-> 
+
 > Specify the FSlabel of the block device to use for persistent storage.
 > If a label is not found in `/dev/disk/by-label/*`, then the os-disks are paved.
 > If this is specified, then rd.live.overlay=$newlabel must also be specified.
+> - `Default: LABEL=ROOTRAID`
 
-<a name="rdliveoverlay.readonly"></a>
 ##### `rd.live.overlay.readonly`
-> - `Default: 0`
-> 
+
 > Make the persistent overlayFS read-only.
+> - `Default: 0`
 
-<a name="rdliveoverlayreset"></a>
 ##### `rd.live.overlay.reset`
-> - `Default: 0`
-> 
+
 > Reset the persistent overlayFS, regardless if it is read-only.
 > On the **next** boot the overlayFS will clear itself, it will continue to clear itself every
 > reboot until this is unset. This does not remake the RAID, this remakes the OverlayFS. Metal only
 > provides the underlying array, and the parent directory structure necessary for an OverlayFS to detect the array as compatible.
+> - `Default: 0`
 
-<a name="rdliveoverlaysize"></a>
 ##### `rd.live.overlay.size`
-> - `Default: 204800`
-> 
+
 > Specify the size of the overlay in MB.
+> - `Default: 204800`
 
-<a name="rdlivesquashimg"></a>
 ##### `rd.live.squashimg`
-> - `Default: filesystem.squashfs`
-> 
+
 > Specify the filename to refer to download.
+> - `Default: filesystem.squashfs`
 
-<a name="dracut--standard-customizations"></a>
-### dracut : standard customizations
+#### dracut : standard customizations
 
-notereference: [dracut standard cmdline](2)
+notereference: [dracut standard cmdline][2]
 
-<a name="rootfallback"></a>
 ##### `rootfallback`
-> - `Default: LABEL=BOOTRAID`
-> 
+
 > This the label for the partition to be used for a fallback bootloader.
+> - `Default: LABEL=BOOTRAID`
 
-<a name="required-parameters"></a>
-## Required Parameters
-
-The following parameters are required for this module to work, however they belong to the native dracut space.
-
-> See [`module-setup.sh`](./90metalmdsquash/module-setup.sh) for the full list of module and driver dependencies.
-
-<a name="metal.server"></a>
-##### `metal.server`
-
-> The endpoint to fetch artifacts from. Can be any protocol defined in [`metal-genrules.sh`](./90metalmdsquash/metal-genrules.sh).
->
-> **NOTE**: Omitting this value entirely will disable the (re)build function of this dracut module.
-
-<a name="rootfs-and-the-persistent-overlayfs"></a>
-# RootFS and the Persistent OverlayFS
+## RootFS and the Persistent OverlayFS
 
 
-<a name="what-is-a-persistent-overlay"></a>
 ### What is a Persistent Overlay?
 
 The idea of persistence is that changes _persist_ across reboots, when the state of the machine
 changes it preserves information.
 
 
-<a name="feature-toggles"></a>
-## Feature Toggles
+### Feature Toggles
 
 Metal squashFS URL Dracut module has a few feature toggles, by default it is recommended to leave
 them alone unless you must change them for your environment.
 
 
-<a name="toggling-persistence"></a>
-### Toggling Persistence
+#### Toggling Persistence
 
 Disable the overlayFS entirely by setting `rd.live.overlay=0`, this will cause a temporary overlay
 to be created that exists in memory. A prompt may appear during boot to acknowledge the RAM overlayFS.
 
 To disable it entirely, delete all `rd.live.overlay.*` options.
 
-<a name="toggling-read-only-overlayfs"></a>
-### Toggling Read-Only OverlayFS
+#### Toggling Read-Only OverlayFS
 
 Setting `rd.live.readonly=1` will cause the next boot's persistent overlayFS to be mounted
 as read-only. This has a different convention in overlayFS and will look differently on your
@@ -311,8 +261,7 @@ system pending certain toggles:
   overlay, in order to complete the booted root filesystem.
 
 
-<a name="toggling-resetting-the-persistent-overlayfs-on-boot"></a>
-### Toggling Resetting the Persistent OverlayFS on Boot
+#### Toggling Resetting the Persistent OverlayFS on Boot
 
 To cleanly reset the overlayFS, reboot the node with this kernel option:
 `rd.live.overlay.reset=1`.