DOKK / manpages / debian 12 / s390-tools / iucvconn.1.en
iucvconn(1) IUCV terminal applications iucvconn(1)

iucvconn - start terminal connection over z/VM IUCV

iucvconn [-h|--help]
iucvconn [-v|--version]
iucvconn [-e|--escape-char escape_char] [-s|--sessionlog log_file] vm_guest terminal_id

The iucvconn application establishes a terminal connection to another Linux instance. The Linux instance where iucvconn runs and the target Linux instance must be z/VM guest operating systems of the same z/VM instance. The communication path between both virtual machines is based on the z/VM Inter-User Communication Vehicle (IUCV). Because z/VM IUCV is independent from TCP/IP, Linux instances with no external network can be accessed.

iucvconn accesses the terminal specified by terminal_id on the z/VM guest virtual machine vm_guest. The terminal_id is similar to a port number in TCP/IP communications. terminal_id is case-sensitive and consists of up to 8 alphanumeric characters. terminal_id must either identify a running iucvtty instance, or a terminal device provided by the z/VM IUCV hypervisor console (HVC) device driver.

Display a short help text, then exit.
Display the version number of iucvconn, then exit.
Set an escape character for this terminal session. You need an escape character to access special iucvconn functions. The default escape character is underscore (_). If escape_char is set to "none", escaping is not possible. The escape character can be the closing bracket (]), the caret (^), the underscore (_), or any alphabetical character except C, D, Q, S and Z. The escape_char character is not case-sensitive.

To invoke a iucvconn function, press Ctrl+escape_char, followed by the function character. For example, press "Ctrl+_ d" to disconnect the terminal session and exit iucvconn.

For details, see section "ESCAPE CHARACTERS" below.

Create a transcript of the terminal session and write session data to three different files.

log_file contains the raw terminal data stream. The log_file.timing file contains timing data that can be used for replaying the raw terminal data stream using realistic output delays. Additional terminal session information is logged to log_file.info.

If any of these files already exist, iucvconn exits with an error. To proceed either delete the files or choose another file name for log_file.

iucvconn supports functions through the use of an escape character. The default escape character (escape_char) is underscore (_).

To enter the "escape mode" of iucvconn, press the Control and the escape_char key together ("Ctrl+_") In the "escape mode", iucvconn expects a single character designating the special function.

The special functions are (assuming escape_char is set to underscore (_)):

Send the escape character to the connected terminal.
. or d
Disconnect and exit iucvconn.
Force resizing of the connected terminal.

Any other single character is ignored and is not send to the terminal. If multiple characters are entered together, iucvconn leaves the "escape mode" and sends the characters to the connected terminal.

To access the "lnxterm" terminal on the Linux instance in z/VM guest virtual machine LNXSYS01:


iucvconn LNXSYS01 lnxterm

To access the first z/VM IUCV HVC terminal on the Linux instance in z/VM guest virtual machine LNXSYS02:


iucvconn LNXSYS02 lnxhvc0

To create a transcript of the terminal session to the Linux instance in z/VM guest virtual machine LNXSYS99:


iucvconn -s ~/transcripts/lnxsys99 LNXSYS99 lnxhvc0

The terminal environment variable contains the name of the terminal (e.g. linux, xterm, ...) and also specifies the terminal capabilities.

iucvconn transfers the value of the TERM environment variable at connection startup to the target system. The iucvtty application sets the TERM environment variable on the target system before the login program is started. Setting the TERM environment variable ensures that the terminal capabilities are the same on both sides of the connection.

The z/VM IUCV hypervisor console (HVC) device driver ignores the content of the TERM environment variable transferred by iucvconn. See the hvc_iucv(9) manual page for instructions to configure the terminal environment.

If the Linux kernel does not include kernel support for the AF_IUCV network addressing family, iucvconn exits and displays the message 'AF_IUCV address family is not available: Address family not supported by protocol'.

The iucvconn program does not require superuser privileges and can be used by regular users. Each connection attempt and failure is logged to the authpriv syslog facility.

Terminal session transcripts facilitate logging and auditing of terminal activity on remote systems or recording and playing back terminal sessions, for example for education and presentations.

The z/VM guest virtual machine must have authorization to establish IUCV communication paths to other z/VM guest virtual machines.

See the af_iucv(7) manual page for details about IUCV authorizations.

The Linux instance where iucvconn runs and the target Linux instances must be z/VM guest operating systems of the same z/VM instance.

iucvtty(1), hvc_iucv(9), af_iucv(7), scriptreplay(1)

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

March 2009 s390-tools