NAME¶

iucvconn - start terminal connection over z/VM IUCV

SYNOPSIS¶

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

DESCRIPTION¶

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.

OPTIONS¶

-h, --help

Display a short help text, then exit.

-v, --version

Display the version number of iucvconn, then exit.

-e, --escape-char escape_char

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.

-s, --sessionlog logfile

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.

ESCAPE CHARACTERS¶

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 (_)):

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.

EXAMPLES¶

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

ENVIRONMENT¶

TERM

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.

DIAGNOSTICS¶

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

SECURITY¶

NOTES¶

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

SEE ALSO¶

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

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