Merge "Add centralized secure boot documentation"

4 files changed, 94 insertions, 81 deletions

diff --git a/doc/source/admin/drivers/ilo.rst b/doc/source/admin/drivers/ilo.rst
index fe97d94e8..24ac8c2c4 100644
--- a/doc/source/admin/drivers/ilo.rst
+++ b/doc/source/admin/drivers/ilo.rst
@@ -582,69 +582,22 @@ element to the diskimage-builder command to build the image.  For example::
 
 UEFI Secure Boot Support
 ^^^^^^^^^^^^^^^^^^^^^^^^
-The hardware type ``ilo`` supports secure boot deploy.
-
-The UEFI secure boot can be configured in ironic by adding
-``secure_boot`` parameter in the ``capabilities`` parameter  within
-``properties`` field of an ironic node.
-
-``secure_boot`` is a boolean parameter and takes value as ``true`` or
-``false``.
-
-To enable ``secure_boot`` on a node add it to ``capabilities`` as below::
-
- baremetal node set <node> --property capabilities='secure_boot:true'
-
-Alternatively see `Hardware Inspection Support`_ to know how to
-automatically populate the secure boot capability.
-
-Nodes having ``secure_boot`` set to ``true`` may be requested by adding an
-``extra_spec`` to the nova flavor::
-
-  nova flavor-key ironic-test-3 set capabilities:secure_boot="true"
-  nova boot --flavor ironic-test-3 --image test-image instance-1
-
-If ``capabilities`` is used in ``extra_spec`` as above, nova scheduler
-(``ComputeCapabilitiesFilter``) will match only ironic nodes which have
-the ``secure_boot`` set appropriately in ``properties/capabilities``. It will
-filter out rest of the nodes.
-
-The above facility for matching in nova can be used in heterogeneous
-environments where there is a mix of machines supporting and not supporting
-UEFI secure boot, and operator wants to provide a choice to the user
-regarding secure boot.  If the flavor doesn't contain ``secure_boot`` then
-nova scheduler will not consider secure boot mode as a placement criteria,
-hence user may get a secure boot capable machine that matches with user
-specified flavors but deployment would not use its secure boot capability.
-Secure boot deploy would happen only when it is explicitly specified through
-flavor.
-
-Use element ``ubuntu-signed`` or ``fedora`` to build signed deploy iso and
-user images from
-`diskimage-builder <https://pypi.org/project/diskimage-builder>`_.
-Please refer to :ref:`deploy-ramdisk` for more information on building
-deploy ramdisk.
+The hardware type ``ilo`` supports secure boot deploy, see :ref:`secure-boot`
+for details.
 
-The below command creates files named cloud-image-boot.iso, cloud-image.initrd,
-cloud-image.vmlinuz and cloud-image.qcow2 in the current working directory::
+iLO specific notes:
 
- cd <path-to-diskimage-builder>
- ./bin/disk-image-create -o cloud-image ubuntu-signed baremetal iso
+In UEFI secure boot, digitally signed bootloader should be able to validate
+digital signatures of kernel during boot process. This requires that the
+bootloader contains the digital signatures of the kernel.
+For the ``ilo-virtual-media`` boot interface, it is recommended that
+``boot_iso`` property for user image contains the glance UUID of the boot
+ISO.  If ``boot_iso`` property is not updated in glance for the user image,
+it would create the ``boot_iso`` using bootloader from the deploy iso. This
+``boot_iso`` will be able to boot the user image in UEFI secure boot
+environment only if the bootloader is signed and can validate digital
+signatures of user image kernel.
 
-.. note::
-   In UEFI secure boot, digitally signed bootloader should be able to validate
-   digital signatures of kernel during boot process. This requires that the
-   bootloader contains the digital signatures of the kernel.
-   For the ``ilo-virtual-media`` boot interface, it is recommended that
-   ``boot_iso`` property for user image contains the glance UUID of the boot
-   ISO.  If ``boot_iso`` property is not updated in glance for the user image,
-   it would create the ``boot_iso`` using bootloader from the deploy iso. This
-   ``boot_iso`` will be able to boot the user image in UEFI secure boot
-   environment only if the bootloader is signed and can validate digital
-   signatures of user image kernel.
-
-Ensure the public key of the signed image is loaded into bare metal to deploy
-signed images.
 For HPE ProLiant Gen9 servers, one can enroll public key using iLO System
 Utilities UI. Please refer to section ``Accessing Secure Boot options`` in
 `HP UEFI System Utilities User Guide <https://h20628.www2.hp.com/km-ext/kmcsdirect/emr_na-c03886429-5.pdf>`_.
diff --git a/doc/source/admin/drivers/irmc.rst b/doc/source/admin/drivers/irmc.rst
index 20ac68c42..460a59b75 100644
--- a/doc/source/admin/drivers/irmc.rst
+++ b/doc/source/admin/drivers/irmc.rst
@@ -189,30 +189,12 @@ Optional functionalities for the ``irmc`` hardware type
 
 UEFI Secure Boot Support
 ^^^^^^^^^^^^^^^^^^^^^^^^
-The hardware type ``irmc`` supports secure boot deploy.
+The hardware type ``irmc`` supports secure boot deploy, see :ref:`secure-boot`
+for details.
 
 .. warning::
      Secure boot feature is not supported with ``pxe`` boot interface.
 
-The UEFI secure boot can be configured by adding ``secure_boot`` parameter,
-which is a boolean value. Enabling the secure boot is different when
-Bare Metal service is used with Compute service or without Compute service. The
-following sections describe both methods:
-
-* Enabling secure boot with Compute service:
-  To enable secure boot we need to set a capability on the bare metal node
-  and the bare metal flavor, for example::
-
-    baremetal node set <node> --property capabilities='secure_boot:true'
-    openstack flavor set FLAVOR-NAME --property capabilities:secure_boot="true"
-
-* Enabling secure boot without Compute service:
-  Since adding capabilities to the node's properties is only used by the nova
-  scheduler to perform more advanced scheduling of instances, we need
-  to enable secure boot without nova, for example::
-
-    baremetal node set <node> --instance-info capabilities='{"secure_boot": "true"}'
-
 .. _irmc_node_cleaning:
 
 Node Cleaning Support
diff --git a/doc/source/admin/security.rst b/doc/source/admin/security.rst
index 846aeb82f..d00e59e9b 100644
--- a/doc/source/admin/security.rst
+++ b/doc/source/admin/security.rst
@@ -121,7 +121,7 @@ include:
 
 - installing signed firmware for BIOS and peripheral devices
 - using a TPM (Trusted Platform Module) to validate signatures at boot time
-- booting machines in :ref:`iLO UEFI Secure Boot Support`, rather than BIOS mode, to
+- booting machines in `UEFI secure boot mode`_, rather than BIOS mode, to
   validate kernel signatures
 - disabling local (in-band) access from the host OS to the management controller (BMC)
 - disabling modifications to boot settings from the host OS
@@ -130,6 +130,81 @@ Additional references:
 
 - :ref:`cleaning`
 
+.. _secure-boot:
+
+UEFI secure boot mode
+=====================
+
+Some hardware types support turning `UEFI secure boot`_ dynamically when
+deploying an instance. Currently these are :doc:`/admin/drivers/ilo` and
+:doc:`/admin/drivers/irmc`.
+
+Support for the UEFI secure boot is declared by adding the ``secure_boot``
+capability in the ``capabilities`` parameter in the ``properties`` field of
+a node. ``secure_boot`` is a boolean parameter and takes value as ``true`` or
+``false``.
+
+To enable ``secure_boot`` on a node add it to ``capabilities``::
+
+ baremetal node set <node> --property capabilities='secure_boot:true'
+
+Alternatively use :doc:`/admin/inspection`  to automatically populate
+the secure boot capability.
+
+.. warning::
+   UEFI secure boot only works in UEFI boot mode, see :ref:`boot_mode_support`
+   for how to turn it on and off.
+
+Compatible images
+-----------------
+
+Use element ``ubuntu-signed`` or ``fedora`` to build signed deploy ISO and
+user images with `diskimage-builder
+<https://pypi.org/project/diskimage-builder>`_.
+
+The below command creates files named cloud-image-boot.iso, cloud-image.initrd,
+cloud-image.vmlinuz and cloud-image.qcow2 in the current working directory::
+
+ cd <path-to-diskimage-builder>
+ ./bin/disk-image-create -o cloud-image ubuntu-signed baremetal iso
+
+Ensure the public key of the signed image is loaded into bare metal to deploy
+signed images.
+
+Enabling with OpenStack Compute
+-------------------------------
+
+Nodes having ``secure_boot`` set to ``true`` may be requested by adding an
+``extra_spec`` to the nova flavor::
+
+  openstack flavor set <flavor> --property capabilities:secure_boot="true"
+  openstack server create --flavor <flavor> --image <image> instance-1
+
+If ``capabilities`` is used in ``extra_spec`` as above, nova scheduler
+(``ComputeCapabilitiesFilter``) will match only ironic nodes which have
+the ``secure_boot`` set appropriately in ``properties/capabilities``. It will
+filter out rest of the nodes.
+
+The above facility for matching in nova can be used in heterogeneous
+environments where there is a mix of machines supporting and not supporting
+UEFI secure boot, and operator wants to provide a choice to the user
+regarding secure boot.  If the flavor doesn't contain ``secure_boot`` then
+nova scheduler will not consider secure boot mode as a placement criteria,
+hence user may get a secure boot capable machine that matches with user
+specified flavors but deployment would not use its secure boot capability.
+Secure boot deploy would happen only when it is explicitly specified through
+flavor.
+
+Enabling standalone
+-------------------
+
+To request secure boot for an instance in standalone mode (without OpenStack
+Compute), you need to add the capability directly to the node's
+``instance_info``::
+
+  baremetal node set <node> --instance-info capabilities='{"secure_boot": "true"}'
+
+.. _UEFI secure boot: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface#Secure_boot
 
 Other considerations
 ====================
diff --git a/doc/source/install/include/boot-mode.inc b/doc/source/install/include/boot-mode.inc
index c528895fc..622c6cc71 100644
--- a/doc/source/install/include/boot-mode.inc
+++ b/doc/source/install/include/boot-mode.inc
@@ -80,3 +80,6 @@ following way:
   boot modes. If the flavor doesn't contain ``boot_mode`` and ``boot_mode``
   is configured for bare metal nodes, then nova scheduler will consider all
   nodes and user may get either ``bios`` or ``uefi`` machine.
+
+Some hardware support setting secure boot mode, see :ref:`secure-boot` for
+details.