diff --git a/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/index.rst b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/index.rst index fd165f112..6070b8be6 100644 --- a/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/index.rst +++ b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/index.rst @@ -6,5 +6,5 @@ Advanced Operations rinv.rst rvitals.rst - rflash.rst + rflash/index.rst rspconfig.rst diff --git a/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/index.rst b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/index.rst new file mode 100644 index 000000000..dce79f855 --- /dev/null +++ b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/index.rst @@ -0,0 +1,10 @@ +``rflash`` - Remote Firmware Flashing +===================================== + +See :doc:`rflash manpage ` for more information. + +.. toctree:: + :maxdepth: 2 + + ipmi.rst + openbmc/index.rst diff --git a/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash.rst b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/ipmi.rst similarity index 69% rename from docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash.rst rename to docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/ipmi.rst index 4bb1d2d07..0e0234ac6 100644 --- a/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash.rst +++ b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/ipmi.rst @@ -1,7 +1,5 @@ -``rflash`` - Remote Firmware Flashing -===================================== - -See :doc:`rflash manpage ` for more information. +IPMI Firmware Update +==================== The ``rflash`` command is provided to assist the system administrator in updating firmware. diff --git a/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/index.rst b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/index.rst new file mode 100644 index 000000000..804913d6d --- /dev/null +++ b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/index.rst @@ -0,0 +1,8 @@ +OpenBMC Firmware Update +======================= + +.. toctree:: + :maxdepth: 2 + + manually.rst + unattended.rst diff --git a/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/manually.rst b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/manually.rst new file mode 100644 index 000000000..2806230e2 --- /dev/null +++ b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/manually.rst @@ -0,0 +1,10 @@ +Manual Firmware Flash +===================== + +.. include:: ./openbmc_common.rst + :start-after: BEGIN_flashing_OpenBMC_Servers + :end-before: END_flashing_OpenBMC_Servers + +.. include:: ./openbmc_common.rst + :start-after: BEGIN_Validation_OpenBMC_firmware + :end-before: END_Validation_OpenBMC_firmware diff --git a/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/openbmc_common.rst b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/openbmc_common.rst new file mode 100644 index 000000000..50404a5a8 --- /dev/null +++ b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/openbmc_common.rst @@ -0,0 +1,100 @@ +.. BEGIN_unattended_OpenBMC_flashing + +Unattended flash of OpenBMC firmware will do the following events: + +#. Upload both BMC firmware file and PNOR firmware file +#. Activate both BMC firmware and PNOR firmware +#. If BMC firmware becomes activate, reboot BMC to apply new BMC firmware, or else, ``rflash`` will exit +#. If BMC itself state is ``NotReady``, ``rflash`` will exit +#. If BMC itself state is ``Ready``, and use ``--no-host-reboot`` option, ``rflash`` will not reboot the compute node +#. If BMC itself state is ``Ready``, and do not use ``--no-host-reboot`` option, ``rflash`` will reboot the compute node to apply PNOR firmware + +Use the following command to flash the firmware unattended: :: + + rflash -d /path/to/directory + +Use the following command to flash the firmware unattended and not reboot the compute node: :: + + rflash -d /path/to/directory --no-host-reboot + +If there are errors encountered during the flash process, take a look at the manual steps to continue flashing the BMC. + +.. END_unattended_OpenBMC_flashing + +.. BEGIN_flashing_OpenBMC_Servers + +The sequence of events that must happen to flash OpenBMC firmware is the following: + +#. Power off the Host +#. Upload and Activate BMC +#. Reboot the BMC (applies BMC) +#. Upload and Activate PNOR +#. Power on the Host (applies PNOR) + + +Power off Host +-------------- + +Use the rpower command to power off the host: :: + + rpower off + +Upload and Activate BMC Firmware +-------------------------------- + +Use the rflash command to upload and activate the PNOR firmware: :: + + rflash -a /path/to/obmc-phosphor-image-witherspoon.ubi.mtd.tar + +If running ``rflash`` in Hierarchy, the firmware files must be accessible on the Service Nodes. + +**Note:** If a .tar file is provided, the ``-a`` option does an upload and activate in one step. If an ID is provided, the ``-a`` option just does activate the specified firmware. After firmware is activated, use the ``rflash -l`` to view. The ``rflash`` command shows ``(*)`` as the active firmware and ``(+)`` on the firmware that requires reboot to become effective. + +Reboot the BMC +-------------- + +Use the ``rpower`` command to reboot the BMC: :: + + rpower bmcreboot + +The BMC will take 2-5 minutes to reboot, check the status using: ``rpower bmcstate`` and wait for ``BMCReady`` to be returned. + +**Known Issue:** On reboot, the first call to the BMC after reboot, xCAT will return ``Error: BMC did not respond within 10 seconds, retry the command.``. Please retry. + +Upload and Activate PNOR Firmware +--------------------------------- + +Use the rflash command to upload and activate the PNOR firmware: :: + + rflash -a /path/to/witherspoon.pnor.squashfs.tar + +If running ``rflash`` in Hierarchy, the firmware files must be accessible on the Service Nodes. + +**Note:** The ``-a`` option does an upload and activate in one step, after firmware is activated, use the ``rflash -l`` to view. The ``rflash`` command shows ``(*)`` as the active firmware and ``(+)`` on the firmware that requires reboot to become effective. + +Power on Host +------------- + +User the ``rpower`` command to power on the Host: :: + + rpower on + +.. END_flashing_OpenBMC_Servers + +.. BEGIN_Validation_OpenBMC_firmware + +Validation +---------- + +Use one of the following commands to validate firmware levels are in sync: + +* Use the ``rinv`` command to validate firmware level: :: + + rinv firm -V | grep -i ibm | grep "\*" | xcoll + +* Use the ``rflash`` command to validate the firmware level: :: + + rflash -l | grep "\*" | xcoll + + +.. END_Validation_OpenBMC_firmware diff --git a/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/unattended.rst b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/unattended.rst new file mode 100644 index 000000000..b4608367b --- /dev/null +++ b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/unattended.rst @@ -0,0 +1,10 @@ +Unattended Firmware Flash +========================= + +.. include:: ./openbmc_common.rst + :start-after: BEGIN_unattended_OpenBMC_flashing + :end-before: END_unattended_OpenBMC_flashing + +.. include:: ./openbmc_common.rst + :start-after: BEGIN_Validation_OpenBMC_firmware + :end-before: END_Validation_OpenBMC_firmware diff --git a/docs/source/references/coral/cluster_mgmt/firmware/index.rst b/docs/source/references/coral/cluster_mgmt/firmware/index.rst index 1d105d896..08b0828bb 100644 --- a/docs/source/references/coral/cluster_mgmt/firmware/index.rst +++ b/docs/source/references/coral/cluster_mgmt/firmware/index.rst @@ -5,4 +5,4 @@ Power9 Firmware Update :maxdepth: 2 ipmi.rst - openbmc.rst + openbmc/index.rst diff --git a/docs/source/references/coral/cluster_mgmt/firmware/openbmc.rst b/docs/source/references/coral/cluster_mgmt/firmware/openbmc.rst deleted file mode 100644 index 49caae6bf..000000000 --- a/docs/source/references/coral/cluster_mgmt/firmware/openbmc.rst +++ /dev/null @@ -1,79 +0,0 @@ -OpenBMC Firmware Update -======================= - -The process of updating firmware on the OpenBMC managed servers is documented below. - -The sequence of events that must happen is the following: - - * Power off the Host - * Update and Activate PNOR - * Update and Activate BMC - * Reboot the BMC (applies BMC) - * Power on the Host (applies PNOR) - -**Note:** xCAT is working on streamlining this process to reduce the flexibility of the above steps at the convenience of the Administrator to handle the necessary reboots. See `Issue #4245 `_ - - - -Power off Host --------------- - -Use the rpower command to power off the host: :: - - rpower off - -Update and Activate PNOR Firmware ---------------------------------- - -Use the rflash command to upload and activate the PNOR firmware: :: - - rflash -a /path/to/witherspoon.pnor.squashfs.tar - -If running ``rflash`` in Hierarchy, the firmware files must be accessible on the Service Nodes. - -**Note:** The ``-a`` option does an upload and activate in one step, after firmware is activated, use the ``rflash -l`` to view. The ``rflash`` command shows ``(*)`` as the active firmware and ``(+)`` on the firmware that requires reboot to become effective. - -Update and Activate BMC Firmware --------------------------------- - -Use the rflash command to upload and activate the PNOR firmware: :: - - rflash -a /path/to/obmc-phosphor-image-witherspoon.ubi.mtd.tar - -If running ``rflash`` in Hierarchy, the firmware files must be accessible on the Service Nodes. - -**Note:** The ``-a`` option does an upload and activate in one step, after firmware is activated, use the ``rflash -l`` to view. The ``rflash`` command shows ``(*)`` as the active firmware and ``(+)`` on the firmware that requires reboot to become effective. - -Reboot the BMC --------------- - -Use the ``rpower`` command to reboot the BMC: :: - - rpower bmcreboot - -The BMC will take 2-5 minutes to reboot, check the status using: ``rpower bmcstate`` and wait for ``BMCReady`` to be returned. - -**Known Issue:** On reboot, the first call to the BMC after reboot, xCAT will return ``Error: BMC did not respond within 10 seconds, retry the command.``. Please retry. - - -Power on Host -------------- - -User the ``rpower`` command to power on the Host: :: - - rpower on - - -Validation ----------- - -Use one of the following commands to validate firmware levels are in sync: - -* Use the ``rinv`` command to validate firmware level: :: - - rinv firm -V | grep -i ibm | grep "\*" | xcoll - -* Use the ``rflash`` command to validate the firmware level: :: - - rflash -l | grep "\*" | xcoll - diff --git a/docs/source/references/coral/cluster_mgmt/firmware/openbmc/index.rst b/docs/source/references/coral/cluster_mgmt/firmware/openbmc/index.rst new file mode 100644 index 000000000..4f841ef1a --- /dev/null +++ b/docs/source/references/coral/cluster_mgmt/firmware/openbmc/index.rst @@ -0,0 +1,8 @@ +OpenBMC Firmware Update +======================= + +.. toctree:: + :maxdepth: 2 + + unattended.rst + manually.rst diff --git a/docs/source/references/coral/cluster_mgmt/firmware/openbmc/manually.rst b/docs/source/references/coral/cluster_mgmt/firmware/openbmc/manually.rst new file mode 100644 index 000000000..1f3c88160 --- /dev/null +++ b/docs/source/references/coral/cluster_mgmt/firmware/openbmc/manually.rst @@ -0,0 +1,10 @@ +Manual Firmware Flash +===================== + +.. include:: ../../../../../guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/openbmc_common.rst + :start-after: BEGIN_flashing_OpenBMC_Servers + :end-before: END_flashing_OpenBMC_Servers + +.. include:: ../../../../../guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/openbmc_common.rst + :start-after: BEGIN_Validation_OpenBMC_firmware + :end-before: END_Validation_OpenBMC_firmware diff --git a/docs/source/references/coral/cluster_mgmt/firmware/openbmc/unattended.rst b/docs/source/references/coral/cluster_mgmt/firmware/openbmc/unattended.rst new file mode 100644 index 000000000..21e8d9915 --- /dev/null +++ b/docs/source/references/coral/cluster_mgmt/firmware/openbmc/unattended.rst @@ -0,0 +1,10 @@ +Unattended Firmware Flash +========================= + +.. include:: ../../../../../guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/openbmc_common.rst + :start-after: BEGIN_unattended_OpenBMC_flashing + :end-before: END_unattended_OpenBMC_flashing + +.. include:: ../../../../../guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/openbmc_common.rst + :start-after: BEGIN_Validation_OpenBMC_firmware + :end-before: END_Validation_OpenBMC_firmware