From c64a25a52879365229c2b656827279b8870c072c Mon Sep 17 00:00:00 2001 From: Victor Hu Date: Sat, 16 Dec 2017 22:36:10 -0500 Subject: [PATCH 1/3] Add section for OpenBMC rflash in admin-guide, link this section to CORAL reference section --- .../ppc64le/management/advanced/index.rst | 2 +- .../management/advanced/rflash/index.rst | 10 ++++ .../advanced/{rflash.rst => rflash/ipmi.rst} | 6 +- .../advanced/rflash/openbmc/index.rst | 8 +++ .../advanced/rflash/openbmc/manually.rst | 10 ++++ .../rflash/openbmc/openbmc_common.rst} | 57 ++++++++++++------- .../advanced/rflash/openbmc/unattended.rst | 10 ++++ .../coral/cluster_mgmt/firmware/index.rst | 2 +- .../cluster_mgmt/firmware/openbmc/index.rst | 8 +++ .../firmware/openbmc/manually.rst | 10 ++++ .../firmware/openbmc/unattended.rst | 10 ++++ 11 files changed, 105 insertions(+), 28 deletions(-) create mode 100644 docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/index.rst rename docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/{rflash.rst => rflash/ipmi.rst} (69%) create mode 100644 docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/index.rst create mode 100644 docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/manually.rst rename docs/source/{references/coral/cluster_mgmt/firmware/openbmc.rst => guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/openbmc_common.rst} (68%) create mode 100644 docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/unattended.rst create mode 100644 docs/source/references/coral/cluster_mgmt/firmware/openbmc/index.rst create mode 100644 docs/source/references/coral/cluster_mgmt/firmware/openbmc/manually.rst create mode 100644 docs/source/references/coral/cluster_mgmt/firmware/openbmc/unattended.rst 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..4f841ef1a --- /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 + + unattended.rst + manually.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/references/coral/cluster_mgmt/firmware/openbmc.rst b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/openbmc_common.rst similarity index 68% rename from docs/source/references/coral/cluster_mgmt/firmware/openbmc.rst rename to docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/openbmc_common.rst index 49caae6bf..980fc8d83 100644 --- a/docs/source/references/coral/cluster_mgmt/firmware/openbmc.rst +++ b/docs/source/guides/admin-guides/manage_clusters/ppc64le/management/advanced/rflash/openbmc/openbmc_common.rst @@ -1,18 +1,27 @@ -OpenBMC Firmware Update -======================= +.. BEGIN_unattended_OpenBMC_flashing -The process of updating firmware on the OpenBMC managed servers is documented below. +Unattended flash of OpenBMC managed BMC means that xCAT will attempt to: -The sequence of events that must happen is the following: +#. Upload and active BMC, PNOR or both depending on which files are provided. +#. Reboot the necessary components (BMC and/or HOST) to activate the firmware levels - * Power off the Host - * Update and Activate PNOR - * Update and Activate BMC - * Reboot the BMC (applies BMC) - * Power on the Host (applies PNOR) +Use the following command to flash the firmware unattended: :: -**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 `_ + rpower -d /path/to/directory +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 @@ -22,18 +31,7 @@ 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 +Upload and Activate BMC Firmware -------------------------------- Use the rflash command to upload and activate the PNOR firmware: :: @@ -55,6 +53,16 @@ The BMC will take 2-5 minutes to reboot, check the status using: ``rpower -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 ------------- @@ -63,6 +71,9 @@ User the ``rpower`` command to power on the Host: :: rpower on +.. END_flashing_OpenBMC_Servers + +.. BEGIN_Validation_OpenBMC_firmware Validation ---------- @@ -77,3 +88,5 @@ Use one of the following commands to validate firmware levels are in sync: 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/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 From 8ed0cece2dcadc2ebbf52d048a5cc1786e0f8dd9 Mon Sep 17 00:00:00 2001 From: bybai Date: Thu, 8 Mar 2018 02:06:27 -0500 Subject: [PATCH 2/3] enhance rflash unattended doc --- .../management/advanced/rflash/openbmc/index.rst | 2 +- .../advanced/rflash/openbmc/openbmc_common.rst | 12 +++++++++--- 2 files changed, 10 insertions(+), 4 deletions(-) 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 index 4f841ef1a..804913d6d 100644 --- 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 @@ -4,5 +4,5 @@ OpenBMC Firmware Update .. toctree:: :maxdepth: 2 - unattended.rst manually.rst + unattended.rst 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 index 980fc8d83..6ad105759 100644 --- 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 @@ -2,12 +2,18 @@ Unattended flash of OpenBMC managed BMC means that xCAT will attempt to: -#. Upload and active BMC, PNOR or both depending on which files are provided. -#. Reboot the necessary components (BMC and/or HOST) to activate the firmware levels +#. Upload both BMC and PNOR +#. Activate both BMC and PNOR +#. If BMC state is ready, reboot BMC to apply BMC, or else, ``rflash`` will exit +#. If PNOR state is ready, and use ``--no-host-reboot`` option, ``rflash`` will not reboot HOST +#. If PNOR state is ready, and do not use ``--no-host-reboot`` option, ``rflash`` will reboot HOST to apply PNOR Use the following command to flash the firmware unattended: :: - rpower -d /path/to/directory + rflash -d /path/to/directory +Use the following command to flash the firmware unattended and not reboot HOST: :: + + 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. From 6da5a510100351aa61fe19db1da95109b0c41560 Mon Sep 17 00:00:00 2001 From: bybai Date: Thu, 8 Mar 2018 21:36:55 -0500 Subject: [PATCH 3/3] enhance rflash doc --- .../advanced/rflash/openbmc/openbmc_common.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) 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 index 6ad105759..50404a5a8 100644 --- 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 @@ -1,17 +1,19 @@ .. BEGIN_unattended_OpenBMC_flashing -Unattended flash of OpenBMC managed BMC means that xCAT will attempt to: +Unattended flash of OpenBMC firmware will do the following events: -#. Upload both BMC and PNOR -#. Activate both BMC and PNOR -#. If BMC state is ready, reboot BMC to apply BMC, or else, ``rflash`` will exit -#. If PNOR state is ready, and use ``--no-host-reboot`` option, ``rflash`` will not reboot HOST -#. If PNOR state is ready, and do not use ``--no-host-reboot`` option, ``rflash`` will reboot HOST to apply PNOR +#. 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 HOST: :: + +Use the following command to flash the firmware unattended and not reboot the compute node: :: rflash -d /path/to/directory --no-host-reboot @@ -46,7 +48,7 @@ Use the rflash command to upload and activate the PNOR firmware: :: 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. +**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 --------------