DOKK / manpages / debian 12 / s390-tools / hvc_iucv.9.en
hvc_iucv(9) z/VM IUCV HVC device driver hvc_iucv(9)

hvc_iucv - Introduction to the z/VM IUCV hypervisor console (HVC) device driver

hvc_iucv=number

hvc_iucv_allow=comma-separated list of z/VM user IDs

The Hypervisor Console (HVC) device driver is a generic TTY device driver providing terminal devices with pluggable transport device drivers.

The z/VM IUCV hypervisor console (HVC) device driver is a transport plug-in that uses z/VM IUCV communication to establish terminal connections and to transfer terminal data.

The kernel parameter hvc_iucv controls the number of HVC terminals managed by the z/VM IUCV HVC device driver. number is an integer in the range 0 to 8. If number is zero, the z/VM IUCV HVC device driver is switched off; otherwise up to number z/VM IUCV HVC terminal devices are created.

The hvc_iucv_allow kernel parameter optionally specifies a comma separated list of z/VM user IDs. If the kernel parameter has been specified, the z/VM IUCV HVC device driver accepts IUCV connections from listed z/VM user IDs only.

The first z/VM IUCV HVC terminal device is registered automatically for use as the Linux console.

The iucvconn(1) program establishes connections to z/VM IUCV HVC terminal devices. If a terminal is disconnected, output written by Linux is not displayed or saved. Therefore, a newly opened connection to a terminal is always blank. For most applications, like login or shell prompts, it is sufficient to press "Return" to obtain a new prompt.

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).

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.

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:

0 .. 9
Set the Linux console log level and control which kernel message are written to Linux console devices.
Re-IPL immediately (without syncing or unmounting file systems). The re-IPL configuration is used for the re-IPL of the Linux system.
Emergency sync all file file systems.
Emergency remount all mounted file systems read-only.
Show task info.
Show memory.
Send the TERM signal to end all tasks except init(8).
Send the KILL signal to end all tasks except init(8).

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.

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.

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.

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.

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.

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.

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

Add new entries for each HVC terminal device that is designated for user logins. You can use ttyrun(8) to start a getty program on each HVC terminal device and to prevent respawns through the init(8) program when a HVC terminal is not available. You can then change the number of HVC terminal devices without adding or removing entries every time.

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.

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.

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:

1.
To display the current terminal name, issue the command: 


user@host:~$ echo $TERM
xterm

2.
To connect to a z/VM IUCV HVC terminal, run iucvconn(1) and log in as usual: 


user@host:~$ iucvconn MYLNX01 lnxhvc0


     ...
user@MYLNX01:~$

3.
To assign the terminal name from step 1. to the terminal environment variable, issue the following command: 


user@MYLNX01:~$ export TERM=xterm

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.

The z/VM IUCV hypervisor console device driver uses the kernel message infrastructure for its messages. The message prefix is hvc_iucv.

iucvconn(1), chiucvallow(8), af_iucv(7), bootparam(7), inittab(5), getty(8), agetty(8), mingetty(8), ttyrun(8), login(1), securetty(5)

See kernel-parameters.txt and sysrq.txt of the Linux kernel documentation for more information about kernel boot parameters and the magic sysrequest function.

Linux on System z - Device Drivers, Features, and Commands

March 2015 s390-tools