Merge "Bootstrap Login Banner Configuration"

doc/source/system_configuration/kubernetes/branding-the-login-banner-during-commissioning.rst

@@ -9,7 +9,8 @@ Brand the Login Banner During Commissioning
 You can customize the pre-login message (issue) and post-login |MOTD| across
 the entire |prod| cluster during system commissioning and installation.
 
-The following files can be customized to use this feature:
+The following Linux files controlling pre-login (issue) and post-login (motd)
+messaging can be customized with the procedure below.
 
 .. _branding-the-login-banner-during-commissioning-d665e16:
 
@@ -28,51 +29,91 @@ The following files can be customized to use this feature:
     |                                                                                             | This file is not present by default. You must first create it to apply your customizations. |
     +---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+
 
-issue and issue.net are free standing files. /etc/motd is generated
+``issue`` and ``issue.net`` are free-standing files. ``/etc/motd`` is generated
 from the following sources in the order presented:
 
 .. _branding-the-login-banner-during-commissioning-d665e97:
 
-#.  /etc/motd.head
+#.  ``/etc/motd.head``
 
-#.  /etc/sysinv/motd.system
+#.  ``/etc/sysinv/motd.system``
 
-#.  /etc/platform/motd.license
+#.  ``/etc/platform/motd.license``
 
-#.  /etc/motd.tail
+#.  ``/etc/motd.tail``
 
 Complete the following procedure to customize the login banner during
 installation and commissioning:
 
 .. rubric:: |proc|
 
-#.  Provide customization files.
+#.  Define customized banners. To configure the issue and |MOTD| messages,
+    there are two available options:
 
-    To customize any of the four customizable banner files listed above,
+    -   Define banner variable in the Ansible Overrides file for the Bootstrap
-    provide the new files in the following locations:
+        Playbook (``$HOME/localhost.yml``)
 
-    -   /opt/banner/issue
+        It is possible to configure the issue and |MOTD| messages by defining
+        the "banner" variable in the ``ansible-override`` YAML file. Messages
+        should be formatted as multiline string entries.  For each category, it
+        is possible to define either one or both parameters, or leave them
+        undefined. If parameters are left undefined, default values will be
+        applied for each message.
 
-    -   /opt/banner/issue.net
+        .. code-block:: none
 
-    -   /opt/banner/motd.head
+            banner: {}
 
-    -   /opt/banner/motd.tail
+            e.g.
+            banner:
+               issue:
+                  network: |
+                     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+                     ::::::::::::::::::::: EXAMPLE SSH WELCOME MESSAGE ::::::::::::::::::::
+                     ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+                  console: |
+                     :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+                     ::::::::::::::::::: EXAMPLE CONSOLE WELCOME MESSAGE ::::::::::::::::::
+                     :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+               motd:
+                  head: |
+                     -----------------------------------------------------------------------------------------------
+                     ---------------------- EXAMPLE MOTD HEAD MESSAGE ---------------------
+                     -----------------------------------------------------------------------------------------------
+                  tail: |
+                     ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+                     ++++++++++++++++++++++ EXAMPLE MOTD TAIL MESSAGE +++++++++++++++++++++
+                     ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+    -   Provide customization files.
+
+        Alternatively, to customize any of the four customizable banner files
+        listed above, it is possible to provide the new files directly in the
+        following locations:
+
+        -   ``/opt/banner/issue``
+
+        -   ``/opt/banner/issue.net``
+
+        -   ``/opt/banner/motd.head``
+
+        -   ``/opt/banner/motd.tail``
 
     See the :command:`issue` and :command:`motd` man pages for details on
     file syntax.
 
-#.  Run Ansible Bootstrap playbook.
+#.  Run the Ansible Bootstrap playbook.
 
-    When Ansible Bootstrap playbook is run, these files are moved from
+    When the Ansible Bootstrap playbook is run, either the messages defined in
-    /opt/banner to configuration storage and are applied to the controller
+    the Ansible Overrides or the files specified in ``/opt/banner are moved``
-    node as it is initialized. All nodes in the cluster which are
+    to configuration storage and are applied to the controller node as it is
-    subsequently configured will retrieve these custom banners as well.
+    initialized. All nodes in the cluster which are subsequently configured
+    will retrieve these custom banners as well.
 
     .. note::
-        In the event that an error is reported for the banner customization,
+
-        it can be repeated after running Ansible Bootstrap playbook and
+        To update the pre-login message (issue) or the post-login |MOTD| after
-        system deployment. Customization errors do not impact Ansible
+        the system has been installed and commissioned, see :ref:`Brand the
-        Bootstrap playbook.
+        Login Banner on a Commissioned System
-        See :ref:`Brand the Login Banner on a Commissioned System <branding-the-login-banner-on-a-commissioned-system>`
+        <branding-the-login-banner-on-a-commissioned-system>` for more
-        for more information.
+        information.