Skip to content

Commit 5cb2496

Browse files
jldohmannjldohmann
authored
Merge pull request #50697 from jldohmann/OSDOCS-4183
OSDOCS-4183: add enabling serial console
2 parents 619c313 + 31f3b16 commit 5cb2496

8 files changed

+194
-23
lines changed

‎installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -118,25 +118,33 @@ include::modules/installation-user-infra-machines-pxe.adoc[leveloffset=+2]
118118

119119
include::modules/installation-user-infra-machines-advanced.adoc[leveloffset=+2]
120120

121-
include::modules/installation-user-infra-machines-advanced-customizing-iso-or-pxe.adoc[leveloffset=+4]
121+
include::modules/installation-user-infra-machines-advanced-console-configuration.adoc[leveloffset=+3]
122+
123+
include::modules/installation-user-infra-machines-advanced-enabling-serial-console.adoc[leveloffset=+3]
124+
125+
include::modules/installation-user-infra-machines-advanced-customizing-iso-or-pxe.adoc[leveloffset=+3]
122126

123127
:boot-media: ISO image
124128
:boot: iso
125-
include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+4]
129+
include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+3]
126130

127-
include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+5]
131+
include::modules/installation-user-infra-machines-advanced-customizing-live-serial-console.adoc[leveloffset=+4]
128132

129-
include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+5]
133+
include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+4]
134+
135+
include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+4]
130136
:boot-media!:
131137
:boot!:
132138

133139
:boot-media: PXE environment
134140
:boot: pxe
135-
include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+4]
141+
include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+3]
142+
143+
include::modules/installation-user-infra-machines-advanced-customizing-live-serial-console.adoc[leveloffset=+4]
136144

137-
include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+5]
145+
include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+4]
138146

139-
include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+5]
147+
include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+4]
140148
:boot-media!:
141149
:boot!:
142150

‎installing/installing_bare_metal/installing-bare-metal.adoc

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -133,25 +133,33 @@ include::modules/installation-user-infra-machines-pxe.adoc[leveloffset=+2]
133133

134134
include::modules/installation-user-infra-machines-advanced.adoc[leveloffset=+2]
135135

136-
include::modules/installation-user-infra-machines-advanced-customizing-iso-or-pxe.adoc[leveloffset=+4]
136+
include::modules/installation-user-infra-machines-advanced-console-configuration.adoc[leveloffset=+3]
137+
138+
include::modules/installation-user-infra-machines-advanced-enabling-serial-console.adoc[leveloffset=+3]
139+
140+
include::modules/installation-user-infra-machines-advanced-customizing-iso-or-pxe.adoc[leveloffset=+3]
137141

138142
:boot-media: ISO image
139143
:boot: iso
140-
include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+4]
144+
include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+3]
141145

142-
include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+5]
146+
include::modules/installation-user-infra-machines-advanced-customizing-live-serial-console.adoc[leveloffset=+4]
143147

144-
include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+5]
148+
include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+4]
149+
150+
include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+4]
145151
:boot-media!:
146152
:boot!:
147153

148154
:boot-media: PXE environment
149155
:boot: pxe
150-
include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+4]
156+
include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+3]
157+
158+
include::modules/installation-user-infra-machines-advanced-customizing-live-serial-console.adoc[leveloffset=+4]
151159

152-
include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+5]
160+
include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+4]
153161

154-
include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+5]
162+
include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+4]
155163
:boot-media!:
156164
:boot!:
157165

‎installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -139,25 +139,33 @@ include::modules/installation-user-infra-machines-pxe.adoc[leveloffset=+2]
139139

140140
include::modules/installation-user-infra-machines-advanced.adoc[leveloffset=+2]
141141

142-
include::modules/installation-user-infra-machines-advanced-customizing-iso-or-pxe.adoc[leveloffset=+4]
142+
include::modules/installation-user-infra-machines-advanced-console-configuration.adoc[leveloffset=+3]
143+
144+
include::modules/installation-user-infra-machines-advanced-enabling-serial-console.adoc[leveloffset=+3]
145+
146+
include::modules/installation-user-infra-machines-advanced-customizing-iso-or-pxe.adoc[leveloffset=+3]
143147

144148
:boot-media: ISO image
145149
:boot: iso
146-
include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+4]
150+
include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+3]
147151

148-
include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+5]
152+
include::modules/installation-user-infra-machines-advanced-customizing-live-serial-console.adoc[leveloffset=+4]
149153

150-
include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+5]
154+
include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+4]
155+
156+
include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+4]
151157
:boot-media!:
152158
:boot!:
153159

154160
:boot-media: PXE environment
155161
:boot: pxe
156-
include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+4]
162+
include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+3]
163+
164+
include::modules/installation-user-infra-machines-advanced-customizing-live-serial-console.adoc[leveloffset=+4]
157165

158-
include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+5]
166+
include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+4]
159167

160-
include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+5]
168+
include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+4]
161169
:boot-media!:
162170
:boot!:
163171

‎modules/installation-user-infra-machines-advanced-console-configuration.adoc

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Module included in the following assemblies
2+
//
3+
// * installing/installing_bare_metal/installing-bare-metal.adoc
4+
// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
5+
// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc
6+
7+
:_content-type: CONCEPT
8+
[id="installation-user-infra-machines-advanced-console-configuration_{context}"]
9+
= Default console configuration
10+
11+
{op-system-first} nodes installed from an {product-title} {product-version} boot image use a default console that is meant to accomodate most virtualized and bare metal setups. Different cloud and virtualization platforms may use different default settings depending on the chosen architecture. Bare metal installations use the kernel default settings which typically means the graphical console is the primary console and the serial console is disabled.
12+
13+
The default consoles may not match your specific hardware configuration or you might have specific needs that require you to adjust the default console. For example:
14+
15+
* You want to access the emergency shell on the console for debugging purposes.
16+
* Your cloud platform does not provide interactive access to the graphical console, but provides a serial console.
17+
* You want to enable multiple consoles.
18+
19+
Console configuration is inherited from the boot image. This means that new nodes in existing clusters are unaffected by changes to the default console.
20+
21+
You can configure the console for bare metal installations in the following ways:
22+
23+
* Using `coreos-installer` manually on the command line.
24+
* Using the `coreos-installer iso customize` or `coreos-installer pxe customize` subcommands with the `--dest-console` option to create a custom image that automates the process.
25+
26+
[NOTE]
27+
====
28+
For advanced customization, perform console configuration using the `coreos-installer iso` or `coreos-installer pxe` subcommands, and not kernel arguments.
29+
====

‎modules/installation-user-infra-machines-advanced-customizing-live-serial-console.adoc

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
// Module included in the following assemblies
2+
//
3+
// * installing/installing_bare_metal/installing-bare-metal.adoc
4+
// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
5+
// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc
6+
7+
:_content-type: PROCEDURE
8+
[id="installation-user-infra-machines-advanced-customizing-live-{boot}-serial-console_{context}"]
9+
= Modifying a live install {boot-media} to enable the serial console
10+
11+
On clusters installed with {product-title} 4.12 and above, the serial console is disabled by default and all output is written to the graphical console. You can enable the serial console with the following procedure.
12+
13+
.Procedure
14+
15+
. Download the `coreos-installer` binary from the link:https://mirror.openshift.com/pub/openshift-v4/clients/coreos-installer/latest/[`coreos-installer` image mirror] page.
16+
17+
ifeval::["{boot-media}" == "ISO image"]
18+
. Retrieve the {op-system} ISO image from the link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/[{op-system} image mirror] page and run the following command to customize the ISO image to enable the serial console to receive output:
19+
+
20+
[source,terminal]
21+
----
22+
$ coreos-installer iso customize rhcos-<version>-live.x86_64.iso \
23+
--dest-ignition <path> \//<1>
24+
--dest-console tty0 \//<2>
25+
--dest-console ttyS0,<options> \//<3>
26+
--dest-device /dev/sda <4>
27+
----
28+
+
29+
<1> The location of the Ignition config to install.
30+
<2> The desired secondary console. In this case, the graphical console. Omitting this option will disable the graphical console.
31+
<3> The desired primary console. In this case, the serial console. The `options` field defines the baud rate and other settings. A common value for this field is `115200n8`. If no options are provided, the default kernel value of `9600n8` is used. For more information on the format of this option, see the link:https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html[Linux kernel serial console] documentation.
32+
<4> The specified disk to install to. In this case, `/dev/sda`. If you omit this option, the {boot-media} automatically runs the installation program which will fail unless you also specify the `coreos.inst.install_dev` kernel argument.
33+
+
34+
[NOTE]
35+
====
36+
The `--dest-console` option affects the installed system and not the live ISO system. To modify the console for a live ISO system, use the `--live-karg-append` option and specify the console with `console=`.
37+
====
38+
+
39+
Your customizations are applied and affect every subsequent boot of the {boot-media}.
40+
41+
. Optional: To remove the {boot-media} customizations and return the image to its original state, run the following command:
42+
+
43+
[source,terminal]
44+
----
45+
$ coreos-installer iso reset rhcos-<version>-live.x86_64.iso
46+
----
47+
+
48+
You can now recustomize the live {boot-media} or use it in its original state.
49+
50+
endif::[]
51+
52+
ifeval::["{boot-media}" == "PXE environment"]
53+
. Retrieve the {op-system} `kernel`, `initramfs` and `rootfs` files from the link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/[{op-system} image mirror] page and the Ignition config file, and then run the following command to create a new customized `initramfs` file that enables the serial console to receive output:
54+
+
55+
[source,terminal]
56+
----
57+
$ coreos-installer pxe customize rhcos-<version>-live-initramfs.x86_64.img \
58+
--dest-ignition <path> \//<1>
59+
--dest-console tty0 \//<2>
60+
--dest-console ttyS0,<options> \//<3>
61+
--dest-device /dev/sda \//<4>
62+
-o rhcos-<version>-custom-initramfs.x86_64.img
63+
----
64+
+
65+
<1> The location of the Ignition config to install.
66+
<2> The desired secondary console. In this case, the graphical console. Omitting this option will disable the graphical console.
67+
<3> The desired primary console. In this case, the serial console. The `options` field defines the baud rate and other settings. A common value for this field is `115200n8`. If no options are provided, the default kernel value of `9600n8` is used. For more information on the format of this option, see the link:https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html[Linux kernel serial console] documentation.
68+
<4> The specified disk to install to. In this case, `/dev/sda`. If you omit this option, the {boot-media} automatically runs the installer which will fail unless you also specify the `coreos.inst.install_dev` kernel argument.
69+
+
70+
Your customizations are applied and affect every subsequent boot of the {boot-media}.
71+
endif::[]

‎modules/installation-user-infra-machines-advanced-enabling-serial-console.adoc

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/installing_bare_metal/installing-bare-metal.adoc
4+
// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
5+
// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc
6+
7+
:_content-type: PROCEDURE
8+
[id="installation-user-infra-machines-advanced-enabling-serial-console_{context}"]
9+
= Enabling the serial console for PXE and ISO installations
10+
11+
By default, the {op-system-first} serial console is disabled and all output is written to the graphical console. You can enable the serial console for an ISO installatiand reconfigure the bootloader so that output is sent to both the serial console and the graphical console.
12+
13+
.Procedure
14+
15+
. Boot the ISO installer.
16+
17+
. Run the `coreos-installer` command to install the system, adding the `--console` option once to specify the graphical console, and a second time to specify the serial console:
18+
+
19+
[source,terminal]
20+
----
21+
$ coreos-installer install \
22+
--console=tty0 \//<1>
23+
--console=ttyS0,<options> \//<2>
24+
--ignition-url=http://host/worker.ign /dev/sda
25+
----
26+
+
27+
<1> The desired secondary console. In this case, the graphical console. Omitting this option will disable the graphical console.
28+
<2> The desired primary console. In this case the serial console. The `options` field defines the baud rate and other settings. A common value for this field is `11520n8`. If no options are provided, the default kernel value of `9600n8` is used. For more information on the format of this option, see link:https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html[Linux kernel serial console] documentation.
29+
+
30+
. Reboot into the installed system.
31+
+
32+
[NOTE]
33+
====
34+
A similar outcome can be obtained by using the `coreos-installer install --append-karg` option, and specifying the console with `console=`. However, this will only set the console for the kernel and not the bootloader.
35+
====
36+
37+
To configure a PXE installation, make sure the `coreos.inst.install_dev` kernel command line option is omitted, and use the shell prompt to run `coreos-installer` manually using the above ISO installation procedure.
38+

‎modules/installation-user-infra-machines-pxe.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@ or other boot options.
201201
+
202202
[NOTE]
203203
====
204-
This configuration does not enable serial console access on machines with a graphical console. To configure a different console, add one or more `console=` arguments to the `APPEND` line. For example, add `console=tty0 console=ttyS0` to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information, see link:https://access.redhat.com/articles/7212[How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?].
204+
This configuration does not enable serial console access on machines with a graphical console. To configure a different console, add one or more `console=` arguments to the `APPEND` line. For example, add `console=tty0 console=ttyS0` to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information, see link:https://access.redhat.com/articles/7212[How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?] and "Enabling the serial console for PXE and ISO installation" in the "Advanced {op-system} installation configuration" section.
205205
====
206206

207207
ifndef::only-pxe[]
@@ -228,7 +228,7 @@ For example, to use DHCP on a NIC that is named `eno1`, set `ip=eno1:dhcp`.
228228
+
229229
[NOTE]
230230
====
231-
This configuration does not enable serial console access on machines with a graphical console. To configure a different console, add one or more `console=` arguments to the `kernel` line. For example, add `console=tty0 console=ttyS0` to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information, see link:https://access.redhat.com/articles/7212[How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?].
231+
This configuration does not enable serial console access on machines with a graphical console. To configure a different console, add one or more `console=` arguments to the `kernel` line. For example, add `console=tty0 console=ttyS0` to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information, see link:https://access.redhat.com/articles/7212[How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?] and "Enabling the serial console for PXE and ISO installation" in the "Advanced {op-system} installation configuration" section.
232232
====
233233
+
234234
ifndef::openshift-origin[]

‎modules/installation-user-infra-machines-static-network.adoc

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -334,6 +334,9 @@ a|Digest `type-value` of the Ignition config.
334334
a|`-p`, `--platform <name>`
335335
a|Override the Ignition platform ID for the installed system.
336336

337+
a|`--console <spec>`
338+
a|Set the kernel and bootloader console for the installed system. For more information about the format of `<spec>`, see the link:https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html[Linux kernel serial console] documentation.
339+
337340
a|`--append-karg <arg>...`
338341
a|Append a default kernel argument to the installed system.
339342

@@ -399,6 +402,9 @@ a|Remove the embedded Ignition config from an ISO image.
399402
a|`--dest-ignition <path>`
400403
a|Merge the specified Ignition config file into a new configuration fragment for the destination system.
401404

405+
a|`--dest-console <spec>`
406+
a|Specify the kernel and bootloader console for the destination system.
407+
402408
a|`--dest-device <path>`
403409
a|Install and overwrite the specified destination device.
404410

@@ -468,6 +474,9 @@ a|Show the wrapped Ignition config in an image.
468474
a|`--dest-ignition <path>`
469475
a|Merge the specified Ignition config file into a new configuration fragment for the destination system.
470476

477+
a|`--dest-console <spec>`
478+
a|Specify the kernel and bootloader console for the destination system.
479+
471480
a|`--dest-device <path>`
472481
a|Install and overwrite the specified destination device.
473482

0 commit comments

Comments
 (0)