Add node serial console documentation

This commit adds the serial console documentation.

Partial-Bug: #1553083
Change-Id: I3f5cef40a1fc9276efa85b643cabbc2b81f53169
This commit is contained in:
Yuiko Takada Mori 2016-07-29 00:07:04 +09:00 committed by John L. Villalovos
parent 245e25bf13
commit bdb488e6a8
2 changed files with 97 additions and 8 deletions

View File

@ -1,7 +1,18 @@
.. _console:
Configure node web console
--------------------------
=================================
Configuring Web or Serial Console
=================================
Overview
--------
There are two types of console which are available in Bare Metal service,
one is web console (`Node web console`_) which is available directly from web
browser, another is serial console (`Node serial console`_).
Node web console
----------------
The web console can be configured in Bare Metal service in the following way:
@ -58,11 +69,13 @@ The web console can be configured in Bare Metal service in the following way:
# Options defined in ironic.drivers.modules.console_utils
#
# Path to serial console terminal program (string value)
# Path to serial console terminal program. Used only by Shell
# In A Box console. (string value)
#terminal=shellinaboxd
# Directory containing the terminal SSL cert(PEM) for serial
# console access (string value)
# Directory containing the terminal SSL cert (PEM) for serial
# console access. Used only by Shell In A Box console. (string
# value)
terminal_cert_dir=/tmp/ca
# Directory for holding terminal pid files. If not specified,
@ -116,7 +129,7 @@ The web console can be configured in Bare Metal service in the following way:
number to ``<customized_port>``, for example ``8023``, this customized port is used in
web console url.
* Get web console information::
Get web console information for a node as follows::
ironic node-get-console <node-uuid>
+-----------------+----------------------------------------------------------------------+
@ -128,8 +141,84 @@ The web console can be configured in Bare Metal service in the following way:
You can open web console using above ``url`` through web browser. If ``console_enabled`` is
``false``, ``console_info`` is ``None``, web console is disabled. If you want to launch web
console, refer to ``Enable web console`` part.
console, see the ``Configure node web console`` part.
.. _`shellinabox page`: https://code.google.com/p/shellinabox/
.. _`openssl page`: https://www.openssl.org/
.. _`FedoraProject page`: https://fedoraproject.org/wiki/Infrastructure/Mirroring
Node serial console
-------------------
Serial consoles for nodes are implemented using `socat`_.
In Newton, the following drivers support socat consoles for nodes:
* agent_ipmitool_socat
* fake_ipmitool_socat
* pxe_ipmitool_socat
Serial consoles can be configured in the Bare Metal service as follows:
* Install socat on the ironic conductor node. Also, ``socat`` needs to be in
the $PATH environment variable that the ironic-conductor service uses.
Installation example::
Ubuntu:
sudo apt-get install socat
Fedora 21/RHEL7/CentOS7:
sudo yum install socat
Fedora 22 or higher:
sudo dnf install socat
* Append ``console`` parameters for bare metal PXE boot in the Bare Metal
service configuration file
(``[pxe]`` section in ``/etc/ironic/ironic.conf``),
including the serial port terminal and serial speed. Serial speed must be
the same as the serial configuration in the BIOS settings, so that the
operating system boot process can be seen in the serial console.
In the following example, the console parameter 'console=ttyS0,115200n8'
uses ttyS0 for console output at 115200bps, 8bit, non-parity::
pxe_* driver:
[pxe]
#Additional append parameters for bare metal PXE boot. (string value)
pxe_append_params = nofb nomodeset vga=normal console=ttyS0,115200n8
* Configure node console.
Enable the serial console, for example::
ironic node-update <node-uuid> add driver_info/ipmi_terminal_port=<port>
ironic node-set-console-mode <node-uuid> true
Check whether the serial console is enabled, for example::
ironic node-validate <node-uuid>
Disable the serial console, for example::
ironic node-set-console-mode <node-uuid> false
ironic node-update <node-uuid> remove driver_info/ipmi_terminal_port
Serial console information is available from the Bare Metal service. Get
serial console information for a node from the Bare Metal service as follows::
ironic node-get-console <node-uuid>
+-----------------+----------------------------------------------------------------------+
| Property | Value |
+-----------------+----------------------------------------------------------------------+
| console_enabled | True |
| console_info | {u'url': u'tcp://<host>:<port>', u'type': u'socat'} |
+-----------------+----------------------------------------------------------------------+
If ``console_enabled`` is ``false`` or ``console_info`` is ``None`` then
the serial console is disabled. If you want to launch serial console, see the
``Configure node console``.
.. _`socat`: http://www.dest-unreach.org/socat

View File

@ -152,7 +152,7 @@ of ironic that may or may not be suitable to every situation.
Adopting Nodes in an ACTIVE state <deploy/adoption>
Auditing API Traffic <deploy/api-audit-support>
Configuring for Multi-tenant Networking <deploy/multitenancy>
Configuring node web console <deploy/console>
Configuring node web or serial console <deploy/console>
.. TODO::
Add page on metrics.