OSDOCS-5428: OCPBU-9 Set or change 'core' user password via MachineConfig

Author: Michael Burke

modules/core-user-password.adoc

@@ -0,0 +1,92 @@
+// Module included in the following assemblies:
+//
+// * post_installation_configuration/machine-configuration-tasks.adoc
+
+:_content-type: PROCEDURE
+[id="core-user-password_{context}"]
+= Changing the core user password for node access
+
+By default, {op-system-first} creates a user named `core` on the nodes in your cluster. You can use the `core` user to access the node through a cloud provider serial console or a bare metal baseboard controller manager (BMC). This can be helpful, for example, if a node is down and you cannot access that node by using SSH or the `oc debug node` command. However, by default, there is no password for this user, so you cannot log in without creating one. 
+
+You can create a password for the `core` user by using a machine config. The Machine Config Operator (MCO) assigns the password and injects the password into the `/etc/shadow` file, allowing you to log in with the `core` user. The MCO does not examine the password hash. As such, the MCO cannot report if there is a problem with the password.
+
+[NOTE]
+====
+* The password works only through a cloud provider serial console or a BMC. It does not work with SSH.
+
+* If you have a machine config that includes an `/etc/shadow` file or a systemd unit that sets a password, it takes precedence over the password hash.
+====
+
+You can change the password, if needed, by editing the machine config you used to create the password. Also, you can remove the password by deleting the machine config. Deleting the machine config does not remove the user account. 
+
+.Prerequisites
+
+* Create a hashed password by using a tool that is supported by your operating system.
+
+.Procedure
+
+. Create a machine config file that contains the `core` username and the hashed password:
++
+[source,terminal]
+----
+apiVersion: machineconfiguration.openshift.io/v1
+kind: MachineConfig
+metadata:
+  labels:
+    machineconfiguration.openshift.io/role: worker
+  name: set-core-user-password
+spec:
+  config:
+    ignition:
+      version: 3.2.0
+    passwd:
+      users:
+      - name: core <1>
+        passwordHash: $6$2sE/010goDuRSxxv$o18K52wor.wIwZp <2>
+----
+<1> This must be `core`.
+<2> The hashed password to use with the `core` account.
+
+. Create the machine config by running the following command:
++
+[source,yaml]
+----
+$ oc create -f <file-name>.yaml
+----
++
+The nodes do not reboot and should become available in a few moments. You can use the `oc get mcp` to watch for the machine config pools to be updated, as shown in the following example:
++
+----
+NAME     CONFIG                                             UPDATED   UPDATING   DEGRADED   MACHINECOUNT   READYMACHINECOUNT   UPDATEDMACHINECOUNT   DEGRADEDMACHINECOUNT   AGE
+master   rendered-master-d686a3ffc8fdec47280afec446fce8dd   True      False      False      3              3                   3                     0                      64m
+worker   rendered-worker-4605605a5b1f9de1d061e9d350f251e5   False     True       False      3              0                   0                     0                      64m
+----
+
+.Verification
+
+. After the nodes return to the `UPDATED=True` state, start a debug session for a node by running the following command:
++
+[source,terminal]
+----
+$ oc debug node/<node_name>
+----
+
+. Set `/host` as the root directory within the debug shell by running the following command:
++
+[source,terminal]
+----
+sh-4.4# chroot /host
+----
+
+. Check the contents of the `/etc/shadow` file:
++
+.Example output
+[source,terminal]
+----
+...
+core:$6$2sE/010goDuRSxxv$o18K52wor.wIwZp:19418:0:99999:7:::
+...
+----
++
+The hashed password is assigned to the `core` user.
+

post_installation_configuration/machine-configuration-tasks.adoc

@@ -66,6 +66,8 @@ include::modules/rhcos-load-firmware-blobs.adoc[leveloffset=+2]
 
 * xref:../installing/install_config/installing-customizing.adoc#installation-special-config-butane_installing-customizing[Creating machine configs with Butane]
 
+include::modules/core-user-password.adoc[leveloffset=+2]
+
 [id="configuring-machines-with-custom-resources"]
 == Configuring MCO-related custom resources