hvc_iucv - Introduction to the z/VM IUCV hypervisor console (HVC) device driver
=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
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
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
The first z/VM IUCV HVC terminal device is registered automatically for use as
the Linux console.
(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
To connect to the first z/VM IUCV HVC terminal device on the z/VM guest virtual
machine "LNX1234", run:
iucvconn LNX1234 lnxhvc0
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
an escape function for disconnecting from the terminal at any time. See also
the manual page of iucvconn
- 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
To invoke the "magic sysrequest" function, press "Ctrl+o"
followed by a second character that designates the debugging or emergency
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
- 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
- Send the KILL signal to end all tasks except
of the Linux kernel documentation for a more complete list
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
parameter to the kernel command line.
To display console messages only and use another device as preferred console,
, followed by an additional console=
parameter that explicitly defines the preferred console, e.g.
- 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
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
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.
programs initialize terminals and prepare terminals for
For each HVC terminal device, a getty
program must be started. To
configure and start getty
on a HVC terminal, open
(5), and add a new entry similar to this one:
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.
(5) about the format of inittab
(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
environment variable. This can be done manually, or by a getty
Complete the following steps for setting up the terminal environment for a z/VM
IUCV HVC terminal:
- To display the current terminal name, issue the command:
user@host:~$ echo $TERM
- To connect to a z/VM IUCV HVC terminal, run
iucvconn(1) and log in as usual:
user@host:~$ iucvconn MYLNX01 lnxhvc0
- 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
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,
(8) sets the terminal environment variable to "linux"
(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
of the Linux kernel
documentation for more information about kernel boot parameters and the magic
Linux on System z - Device Drivers, Features, and Commands