From e354783c7677482c62ca11796501609ebcced7d7 Mon Sep 17 00:00:00 2001 From: Mark Gurevich Date: Wed, 29 Jun 2016 11:36:29 -0400 Subject: [PATCH 1/2] Grammar and formatting changes to troubleshooting doc --- docs/source/troubleshooting/index.rst | 2 +- .../os_installation/debug_port.rst | 24 +++++++------- .../troubleshooting/os_installation/index.rst | 24 +++++++------- .../os_installation/log_to_mn_cn.rst | 32 +++++++++---------- .../os_installation/ssh_enable.rst | 8 ++--- 5 files changed, 45 insertions(+), 45 deletions(-) diff --git a/docs/source/troubleshooting/index.rst b/docs/source/troubleshooting/index.rst index 5d1f1124c..cc481d124 100644 --- a/docs/source/troubleshooting/index.rst +++ b/docs/source/troubleshooting/index.rst @@ -1,7 +1,7 @@ Troubleshooting =============== -This chapter introduces the methods of how to troubleshoot a real cluster. Basically, it includes the following parts. +This chapter introduces the methods of troubleshooting a real cluster. It includes the following parts. .. toctree:: :maxdepth: 2 diff --git a/docs/source/troubleshooting/os_installation/debug_port.rst b/docs/source/troubleshooting/os_installation/debug_port.rst index c80d891be..e7264b252 100644 --- a/docs/source/troubleshooting/os_installation/debug_port.rst +++ b/docs/source/troubleshooting/os_installation/debug_port.rst @@ -1,21 +1,21 @@ -Enable Debug Port: Running commands in the installer from MN ------------------------------------------------------------- +Enabling Debug Port: Running commands in the installer from MN +-------------------------------------------------------------- -**This mode is only supported with debug level set to 1 or 2** +**This mode is supported with debug level set to 1 or 2** -xCAT creates a server in the **installer** listening on port ``3001``. It executes commands sent to it from the xCAT MN and returns the response output. +xCAT creates a server in the **installer**, listening on port ``3001``. It executes commands sent to it from the xCAT MN and returns the response output. -The command ``runcmdinstaller`` can be used to send request to installer: :: +The command ``runcmdinstaller`` can be used to send request to installer: - Usage: +Usage: :: - runcmdinstaller "" + runcmdinstaller "" - make sure all the commands are quoted by "" +make sure all the commands are quoted by ``""`` - Example: +Example: - To list all the items under the /etc directory in the installer - - runcmdinstaller c910f03c01p03 "ls /etc" +To list all the items under the /etc directory in the installer :: + runcmdinstaller c910f03c01p03 "ls /etc" + diff --git a/docs/source/troubleshooting/os_installation/index.rst b/docs/source/troubleshooting/os_installation/index.rst index dfdff4a0c..4330f5080 100644 --- a/docs/source/troubleshooting/os_installation/index.rst +++ b/docs/source/troubleshooting/os_installation/index.rst @@ -3,19 +3,19 @@ Operating System Installation The ability to access the installer or to collect logs during the installation process can be helpful when debugging installation problems. -A new attribute is provided in the site table called ``xcatdebugmode``. :: +A new attribute is provided in the **site** table called ``xcatdebugmode``. - xcatdebugmode=0: Only diagnose Log will be show in corresponding files. - xcatdebugmode=1: Diagnose Log will be show in corresponding files and debug port will be opened. - xcatdebugmode=2: SSH is supported while installing also with diagnose log show and debug port enable. +* xcatdebugmode=0: Diagnose Log will be shown in corresponding files. +* xcatdebugmode=1: Diagnose Log will be shown in corresponding files and debug port will be opened. +* xcatdebugmode=2: Diagnose Log will be shown in corresponding files, debug port will be opened and SSH access is enabled. -List of Supported OS. :: +Supported OS: - RHEL: 6.7 and above - SLES: 11.4 and above - UBT: 14.04.3 and above +* RHEL: 6.7 and above +* SLES: 11.4 and above +* UBT: 14.04.3 and above -The following behavior is observed during OS install: +The following behavior is supported during OS installation: +-----------------+--------------+--------------+--------------+ |**xcatdebugmode**| 0 | 1 | 2 | @@ -29,11 +29,11 @@ The following behavior is observed during OS install: | SSH Access | N | N | N | N | N | N | Y | Y | Y | +-----------------+----+----+----+----+----+----+----+----+----+ -Y means the behavior is supported by OS at current xcatdebugmode. +* Y - the behavior is supported by OS at specified **xcatdebugmode** level. -N means the opposite meaning. +* N - the behavior is not supported. -This chapter introduces the procedures of how to troubleshoot operating system installation. Basically, it includes the following parts. +Next chapter introduces the procedures on how to troubleshoot operating system installation. .. toctree:: :maxdepth: 2 diff --git a/docs/source/troubleshooting/os_installation/log_to_mn_cn.rst b/docs/source/troubleshooting/os_installation/log_to_mn_cn.rst index 54f3827a5..334ad5274 100644 --- a/docs/source/troubleshooting/os_installation/log_to_mn_cn.rst +++ b/docs/source/troubleshooting/os_installation/log_to_mn_cn.rst @@ -1,14 +1,14 @@ -Log Collecting: Collecting logs of the whole installation process +Log Collection: Collecting logs of the whole installation process ----------------------------------------------------------------- -The ability to collect logs during the installation(diskfull and diskless) can be enabled by setting the "site.xcatdebugmode" to different levels(0,1,2), which is quite helpful when debugging installation problems. +The ability to collect logs during the installation (diskful and diskless) can be enabled by setting the "site.xcatdebugmode" to different levels (0,1,2), which is quite helpful when debugging installation problems. -The logs during diskfull provision: -``````````````````````````````````` +The logs during diskful provision: +`````````````````````````````````` * Pre-Install logs: the logs of pre-installation scripts, the pre-installation scripts include "%pre" section in anaconda, "" section for SUSE and "partman/early_command" and "preseed/early_command" sections for ubuntu. The logs include the STDOUT and STDERR of the scripts as well as the debug trace output of bash scripts with "set -x" -* Installer logs: the logs from the os installer itself, i.e, the logs of installation program(anaconda, autoyast and preseed,etc.) +* Installer logs: the logs from the os installer itself, i.e, the logs of installation program (anaconda, autoyast and preseed,etc.) * Post-Install logs: the logs of post-installation scripts, the post-installation scripts include "%post" section in anaconda, "" and "" sections for SUSE and "preseed/late_command" section for ubuntu. The logs include the STDOUT and STDERR of the scripts as well as the debug trace output of bash scripts with "set -x" @@ -57,25 +57,25 @@ The logs during diskless provision: | | CN | C1 | C1 C2 | C1 C2 | +----------------+----+----+----+----+----+----+----+----+----+----+ -MN: the logs forwarded to management node(M1-M4 is the operation for MN). :: +MN: the logs forwarded to management node (M1-M4 is the operation for MN). - M1 means the installer logs can be forwarded to the MN in ``/var/log/xcat/computes.log`` file. +* M1: the installer logs will be forwarded to the MN in ``/var/log/xcat/computes.log`` file. - M2 means the error messages can be forwarded to ``/var/log/xcat/computes.log`` file on MN only when critical error happens. +* M2: the error messages will be forwarded to ``/var/log/xcat/computes.log`` file on MN only when critical error happens. - M3 means the installation logs can be forwarded to ``/var/log/xcat/computes.log`` file on MN. +* M3: the installation logs will be forwarded to ``/var/log/xcat/computes.log`` file on MN. - M4 means the debug trace("set -x" or "-o xtrace") of bash scripts enabled. +* M4: the debug trace("set -x" or "-o xtrace") of bash scripts enabled. - N means the logs can not be forwarded to MN. +* N: the logs will not be forwarded to MN. -CN: the logs on compute node(C1-C3 is the operation for CN). :: +CN: the logs on compute node (C1-C3 is the operation for CN). - C1 means the installation logs can be saved to ``/var/log/xcat/xcat.log`` file on CN. +* C1 - the installation logs will be saved to ``/var/log/xcat/xcat.log`` file on CN. - C2 means the debug trace("set -x" or "-o xtrace") of bash scripts enabled. +* C2 - the debug trace("set -x" or "-o xtrace") of bash scripts enabled. - C3 means the installer logs can be saved to the CN in ``/var/log/anaconda`` for RHEL, ``/var/log/YaST2`` for SLES, ``/var/log/installer`` for UBT. +* C3 - the installer logs will be saved to the CN in ``/var/log/anaconda`` for RHEL, ``/var/log/YaST2`` for SLES, ``/var/log/installer`` for UBT. - N means the logs can not be saved to CN. +* N - the logs will not be saved to CN. diff --git a/docs/source/troubleshooting/os_installation/ssh_enable.rst b/docs/source/troubleshooting/os_installation/ssh_enable.rst index 5d1bebd3a..8f2e94b80 100644 --- a/docs/source/troubleshooting/os_installation/ssh_enable.rst +++ b/docs/source/troubleshooting/os_installation/ssh_enable.rst @@ -1,9 +1,9 @@ SSH Access: Accessing the installer via "ssh" --------------------------------------------- -**This mode is only supported with debug level set to 2** +**This mode is supported with debug level set to 2** -The ssh access to the installer is enabled, the admin can login into the installer through: +When ssh access to the installer is enabled, the admin can login into the installer through: #. For RHEL, the installation won't halt, just login into the installer with ``ssh root@``. @@ -28,7 +28,7 @@ The ssh access to the installer is enabled, the admin can login into the install SYSTEMCTL_OPTIONS=--ignore-dependencies yast.ssh -#. For UBT, the installation will halt on the following similar message in the console: :: +#. For UBT, the installation will halt on the message in the console similar to: :: ┌───────────┤ [!!] Continue installation remotely using SSH ├───────────┐ │ │ @@ -49,7 +49,7 @@ The ssh access to the installer is enabled, the admin can login into the install │ │ └───────────────────────────────────────────────────────────────────────┘ - Just as the message show, the admin can run ``ssh installer@`` with the password "cluster" to login into the installer, the following message shows on login: :: + Just as the message above suggests, the admin can run ``ssh installer@`` with the password "cluster" to login into the installer, the following message shows on login: :: ┌────────────────────┤ [!!] Configuring d-i ├─────────────────────┐ │ │ From 28bb64214488f1994420aaa984c41fb6e0057e05 Mon Sep 17 00:00:00 2001 From: Mark Gurevich Date: Thu, 30 Jun 2016 14:44:50 -0400 Subject: [PATCH 2/2] Suggested improvements --- docs/source/troubleshooting/index.rst | 2 +- .../os_installation/debug_port.rst | 12 ++--- .../troubleshooting/os_installation/index.rst | 6 +-- .../os_installation/log_to_mn_cn.rst | 46 +++++++++++-------- 4 files changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/source/troubleshooting/index.rst b/docs/source/troubleshooting/index.rst index cc481d124..d8f69a11b 100644 --- a/docs/source/troubleshooting/index.rst +++ b/docs/source/troubleshooting/index.rst @@ -1,7 +1,7 @@ Troubleshooting =============== -This chapter introduces the methods of troubleshooting a real cluster. It includes the following parts. +This chapter introduces the methods of troubleshooting a xCAT cluster. It includes the following parts. .. toctree:: :maxdepth: 2 diff --git a/docs/source/troubleshooting/os_installation/debug_port.rst b/docs/source/troubleshooting/os_installation/debug_port.rst index e7264b252..f5d043892 100644 --- a/docs/source/troubleshooting/os_installation/debug_port.rst +++ b/docs/source/troubleshooting/os_installation/debug_port.rst @@ -7,15 +7,9 @@ xCAT creates a server in the **installer**, listening on port ``3001``. It execu The command ``runcmdinstaller`` can be used to send request to installer: -Usage: :: +Usage: ``runcmdinstaller ""`` - runcmdinstaller "" +Note: Make sure all the commands are quoted by ``""`` -make sure all the commands are quoted by ``""`` - -Example: - -To list all the items under the /etc directory in the installer :: - - runcmdinstaller c910f03c01p03 "ls /etc" +To list all the items under the /etc directory in the installer: ``runcmdinstaller c910f03c01p03 "ls /etc"`` diff --git a/docs/source/troubleshooting/os_installation/index.rst b/docs/source/troubleshooting/os_installation/index.rst index 4330f5080..6a263c5f3 100644 --- a/docs/source/troubleshooting/os_installation/index.rst +++ b/docs/source/troubleshooting/os_installation/index.rst @@ -5,9 +5,9 @@ The ability to access the installer or to collect logs during the installation p A new attribute is provided in the **site** table called ``xcatdebugmode``. -* xcatdebugmode=0: Diagnose Log will be shown in corresponding files. -* xcatdebugmode=1: Diagnose Log will be shown in corresponding files and debug port will be opened. -* xcatdebugmode=2: Diagnose Log will be shown in corresponding files, debug port will be opened and SSH access is enabled. +* xcatdebugmode=0: Diagnostic entries will be shown in corresponding log files. +* xcatdebugmode=1: Diagnostic entries will be shown in corresponding log files and debug port will be opened. +* xcatdebugmode=2: Diagnostic entries will be shown in corresponding log files, debug port will be opened and SSH access is enabled. Supported OS: diff --git a/docs/source/troubleshooting/os_installation/log_to_mn_cn.rst b/docs/source/troubleshooting/os_installation/log_to_mn_cn.rst index 334ad5274..007142084 100644 --- a/docs/source/troubleshooting/os_installation/log_to_mn_cn.rst +++ b/docs/source/troubleshooting/os_installation/log_to_mn_cn.rst @@ -3,17 +3,8 @@ Log Collection: Collecting logs of the whole installation process The ability to collect logs during the installation (diskful and diskless) can be enabled by setting the "site.xcatdebugmode" to different levels (0,1,2), which is quite helpful when debugging installation problems. -The logs during diskful provision: +The diskful provision logs: `````````````````````````````````` - -* Pre-Install logs: the logs of pre-installation scripts, the pre-installation scripts include "%pre" section in anaconda, "" section for SUSE and "partman/early_command" and "preseed/early_command" sections for ubuntu. The logs include the STDOUT and STDERR of the scripts as well as the debug trace output of bash scripts with "set -x" - -* Installer logs: the logs from the os installer itself, i.e, the logs of installation program (anaconda, autoyast and preseed,etc.) - -* Post-Install logs: the logs of post-installation scripts, the post-installation scripts include "%post" section in anaconda, "" and "" sections for SUSE and "preseed/late_command" section for ubuntu. The logs include the STDOUT and STDERR of the scripts as well as the debug trace output of bash scripts with "set -x" - -* PostBootScript logs: the logs during the post boot scripts execution, which are specified in "postbootscripts" attribute of node and osimage definition and run during the 1st reboot after installation. - +---------------------+--------------+--------------+--------------+ | **xcatdebugmode** | 0 | 1 | 2 | +---------------------+----+----+----+----+----+----+----+----+----+ @@ -36,13 +27,8 @@ The logs during diskful provision: | | CN | C1 | C1 C2 | C1 C2 | +----------------+----+----+----+----+----+----+----+----+----+----+ -The logs during diskless provision: +The diskless provision logs: ``````````````````````````````````` - -* Provision logs: the logs during the diskless provision. - -* PostBootScript logs: the logs during the post boot scripts execution, which are specified in "postbootscripts" attribute of node and osimage definition and run during the 1st reboot after installation. - +---------------------+--------------+--------------+--------------+ | **xcatdebugmode** | 0 | 1 | 2 | +---------------------+----+----+----+----+----+----+----+----+----+ @@ -57,7 +43,27 @@ The logs during diskless provision: | | CN | C1 | C1 C2 | C1 C2 | +----------------+----+----+----+----+----+----+----+----+----+----+ -MN: the logs forwarded to management node (M1-M4 is the operation for MN). +* **Pre-Install** logs: the logs of pre-installation scripts, including: + + * ``%pre`` section in anaconda, + * ```` section for SUSE and ``partman/early_command`` and ``preseed/early_command`` sections for ubuntu. + * STDOUT and STDERR of the scripts + * debug trace output of bash scripts with ``set -x`` + +* **Installer** logs: the logs from the os installer itself, i.e, the logs of installation program (anaconda, autoyast and preseed,etc.) + +* **Post-Install** logs: the logs of post-installation scripts, including + + * ``%post`` section in anaconda, + * ```` and ```` sections for SUSE and ``preseed/late_command`` section for ubuntu. + * STDOUT and STDERR of the scripts + * debug trace output of bash scripts with ``set -x`` + +* **Provision** logs: the logs during the diskless provision. + +* **PostBootScript** logs: the logs during the post boot scripts execution, which are specified in ``postbootscripts`` attribute of node and osimage definition and run during the 1st reboot after installation. + +MN: the logs forwarded to management node: * M1: the installer logs will be forwarded to the MN in ``/var/log/xcat/computes.log`` file. @@ -65,15 +71,15 @@ MN: the logs forwarded to management node (M1-M4 is the operation for MN). * M3: the installation logs will be forwarded to ``/var/log/xcat/computes.log`` file on MN. -* M4: the debug trace("set -x" or "-o xtrace") of bash scripts enabled. +* M4: the debug trace(``set -x`` or ``-o xtrace``) of bash scripts enabled. * N: the logs will not be forwarded to MN. -CN: the logs on compute node (C1-C3 is the operation for CN). +CN: the logs on compute node: * C1 - the installation logs will be saved to ``/var/log/xcat/xcat.log`` file on CN. -* C2 - the debug trace("set -x" or "-o xtrace") of bash scripts enabled. +* C2 - the debug trace(``set -x`` or ``-o xtrace``) of bash scripts enabled. * C3 - the installer logs will be saved to the CN in ``/var/log/anaconda`` for RHEL, ``/var/log/YaST2`` for SLES, ``/var/log/installer`` for UBT.