Connecting to z/VM IUCV HVC terminal devices¶

Connections to z/VM IUCV HVC terminal devices are established with the IUCV terminal application iucvconn(1).

To connect to the first z/VM IUCV HVC terminal device on the z/VM guest virtual machine "LNX1234", run:

iucvconn LNX1234 lnxhvc0

The lnxhvcn identifier refers to the IUCV name of z/VM IUCV HVC terminal devices; where n corresponds to the terminal device number.

For z/VM IUCV HVC terminal devices, iucvconn(1) does not set the terminal environment. See section "Setting up the terminal environment" below for further instructions.

The terminal connection is disconnected if the terminal session ends by logging off (for example, by typing exit). Alternatively, iucvconn(1) provides an escape function for disconnecting from the terminal at any time. See also the manual page of iucvconn(1).

Note:

If the first z/VM HVC terminal device is configured as the preferred Linux console, a logoff might be followed by a new login prompt. End the terminal session by using the disconnect escape function. Reconnecting always resumes the existing terminal session. Explicitly logging off before using the disconnect escape function assures that users must log in again.

Using the magic sysrequest function on the first z/VM IUCV HVC terminal¶

The first z/VM IUCV HVC terminal, which can be used as Linux console, supports the "magic sysrequest" function if the Linux kernel has been built with CONFIG_MAGIC_SYSRQ.

To invoke the "magic sysrequest" function, press "Ctrl+o" followed by a second character that designates the debugging or emergency function.

The most important magic sysrequest functions are:

See sysrq.txt of the Linux kernel documentation for a more complete list of functions.

This feature can be switched on or off during runtime by echoing "1" (on) or "0" (off) to /proc/sys/kernel/sysrq.

Using the z/VM IUCV HVC terminal device as Linux console¶

The first z/VM IUCV HVC terminal device can display kernel messages and it can also be used as the preferred Linux console (i.e. become /dev/console). The preferred console is used as the initial input and output device, beginning at the stage of the boot process when the init(8) program is called. Messages issued by programs that run at this stage are only displayed on the preferred console.

Note:

Console messages are not displayed if the z/VM IUCV HVC terminal is not connected. If console messages flood the terminal, the z/VM HVC terminal device driver might discard console messages if they come in too fast.

To use the z/VM IUCV hypervisor console as the preferred console, append the console=hvc0 parameter to the kernel command line.

To display console messages only and use another device as preferred console, append console=hvc0, followed by an additional console= parameter that explicitly defines the preferred console, e.g. console=ttyS0.

Note:

The last console= parameter designates the device for use as the preferred console. For Linux on System z, the default preferred console device is ttyS0.

Restricting terminal connections using a z/VM user ID filter¶

The z/VM IUCV HVC device driver can filter incoming connection requests based on the user ID of the originating z/VM guest virtual machine.

The z/VM user ID filter is specified as a comma separated list of user IDs for the hvc_iucv_allow kernel parameter. If an user ID ends with an asterisk (*), only the characters up to the asterisk must match. You can use the asterisk to match multiple z/VM user IDs. The kernel parameter can be set initially on the kernel command line or through a sysfs attribute at runtime.

For changing the parameter value at runtime, see the chiucvallow(8) command.

If the z/VM user ID filter is changed at runtime, the new filter applies only to new incoming connection requests. Existing terminal connections remain active until they get closed. Any re-connection attempt is subject to the new z/VM user ID filter.

Note:

If z/VM user ID filtering is active, connection attempts from the z/VM guest virtual machine to itself are also subject to filtering. If the local z/VM user ID is not listed, local connection requests are refused.

Configuring HVC terminals for user logins¶

Typically, getty programs initialize terminals and prepare terminals for user logins.

For each HVC terminal device, a getty program must be started. To configure and start getty on a HVC terminal, open /etc/inittab(5), and add a new entry similar to this one:

h0:2345:respawn:/sbin/mingetty hvc0

See inittab(5) about the format of inittab entries; see getty(8), or mingetty(8) for options that are related to terminal setup and user login.

Setting up HVC terminals for root logins¶

To allow root logins on HVC terminals, ensure that the respective terminal device names are listed in /etc/securetty(5). HVC terminal device names start with hvc followed by an integer in the range 0 to 7.

Setting up the terminal environment¶

The terminal environment is changed by assigning the terminal name to the TERM environment variable. This can be done manually, or by a getty program.

Complete the following steps for setting up the terminal environment for a z/VM IUCV HVC terminal:

If unsure which terminal name to use, assign "linux" to the terminal environment variable.

For getty programs, a sample terminal environment configuration might look like:

h0:2345:respawn:/sbin/agetty -L 9600 hvc0 linux

The terminal name typically follows the terminal device name. In the example, agetty(8) sets the terminal environment variable to "linux" before login(1) is started.

Some getty programs do not support the terminal name parameter, see the manual page of the respective getty program for more information.