Add centralized secure boot documentation

Move the bits from iLO and iRMC, clean them up a bit.

Change-Id: I5b6da854ae0214141ae25a17b8ea3c7874636372
This commit is contained in:
Dmitry Tantsur 2021-01-25 17:48:30 +01:00
parent 2a7871d060
commit 04400eea47
4 changed files with 94 additions and 81 deletions

View File

@ -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 hardware type ``ilo`` supports secure boot deploy, see :ref:`secure-boot`
for details.
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.
iLO specific notes:
``secure_boot`` is a boolean parameter and takes value as ``true`` or
``false``.
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.
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 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
.. 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>`_.

View File

@ -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

View File

@ -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
====================

View File

@ -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.