hvc_iucv(9)

📦 version 2.44.1, in opensuse-leap 16.0

💖 hvc_iucv — z/VM IUCV hypervisor console (HVC) driver 💖

okay so bestie, welcome to hvc_iucv(9) — the intro page for the z/VM IUCV hypervisor console (HVC) device driver. literally everything you need to know to not embarrass yourself in front of the mainframe. iykyk 🎀

✨ SYNOPSIS ✨

hvc_iucv=number

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

two kernel parameters, that's it, that's the whole vibe check 💅

🌸 DESCRIPTION 🌸

okay so first things first: the Hypervisor Console (HVC) device driver is a generic TTY device driver that gives you terminal devices with pluggable transport device drivers. very modular, very icon energy 🦋

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. no cap, that's the whole job.

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. slay, you're a sysadmin now ✨

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 — everyone else? blocked, blocked, blocked 🙈

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

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. just press Return bestie, it's not broken, i promise 😭

🦋 USAGE 🦋

💜 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). the way that pair just works together, ugh 🫶

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. lowkey elegant naming scheme.

For z/VM IUCV HVC terminal devices, iucvconn(1) does not set the terminal environment. See the section "Setting up the terminal environment" below for further instructions. don't skip it, i'm serious 😤

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. it's giving "break glass in case of emergency" 🚨

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

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.
  • b — Re-IPL immediately (without syncing or unmounting file systems). The re-IPL configuration is used for the re-IPL of the Linux system. ⚠️ no syncing!! no unmounting!! she's fast and she's scary
  • s — Emergency sync all file file systems.
  • u — Emergency remount all mounted file systems read-only.
  • t — Show task info.
  • m — Show memory.
  • e — Send the TERM signal to end all tasks except init(8).
  • i — 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. toggle era 🔥

🎀 CONFIGURATION 🎀

⭐ 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. main character console energy, honestly 👑

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. last one wins, that's the rule 💅

🧚 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. gatekeeping, but make it infrastructure 🚪

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. no retroactive blocking, we don't do that here ✨

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. yes even you. especially you. 💀

🍓 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

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. that's the whole hack, you're welcome 🫶

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. root access, but make it consensual 🔐

💜 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:

  1. To display the current terminal name, issue the command:
user@host:~$ echo $TERM
xterm
  1. To connect to a z/VM IUCV HVC terminal, run iucvconn(1) and log in as usual:
user@host:~$ iucvconn MYLNX01 lnxhvc0
     ...
user@MYLNX01:~$
  1. 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. see how the little pieces fit together?? obsessed 🧚

Some getty programs do not support the terminal name parameter, see the manual page of the respective getty program for more information. read the docs bestie, i'm begging 🙈

🔥 DIAGNOSTICS 🔥

The z/VM IUCV hypervisor console device driver uses the kernel message infrastructure for its messages. The message prefix is hvc_iucv. so if you see that prefix in dmesg, that's her talking 🫶

⭐ SEE ALSO ⭐

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

okay that's the whole page bestie, you're basically a mainframe girlie now 💅✨ this little love letter to your terminal came from s390-tools, dated March 2015 — go forth and iucvconn responsibly, mwah 🎀💖

📦 where this page comes from