mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
b627b8d8e1
This commit is based on the s390-tools-1.39.0 version. Changes on top of s390-tools-1.39.0: - Add MIT license to all source files - Add LICENSE file - Transform REAMDE to README.md (markdown) - Add AUTHORS.md file - Add CONTRIBUTING.md file - Move changelog from README to CHANGELOG.md file Reviewed-by: Stefan Haberland <sth@linux.vnet.ibm.com> Signed-off-by: Michael Holzheu <holzheu@linux.vnet.ibm.com>
224 lines
6.4 KiB
Groff
224 lines
6.4 KiB
Groff
.\" iucvconn.1
|
|
.\"
|
|
.\"
|
|
.\" Copyright IBM Corp. 2008, 2017
|
|
.\" s390-tools is free software; you can redistribute it and/or modify
|
|
.\" it under the terms of the MIT license. See LICENSE for details.
|
|
.\" ----------------------------------------------------------------------
|
|
.TH iucvconn "1" "March 2009" "s390-tools" "IUCV terminal applications"
|
|
.
|
|
.ds i \fBiucvconn\fP
|
|
.
|
|
.
|
|
.
|
|
.SH NAME
|
|
iucvconn \- start terminal connection over z/VM IUCV
|
|
.
|
|
.
|
|
.
|
|
.SH SYNOPSIS
|
|
.B iucvconn
|
|
.RB [ \-h | \-\-help ]
|
|
.br
|
|
.B iucvconn
|
|
.RB [ \-v | \-\-version ]
|
|
.br
|
|
.B iucvconn
|
|
.RB [ \-e | \-\-escape-char
|
|
.IR escape_char ]
|
|
.RB [ \-s | \-\-sessionlog
|
|
.IR log_file ]
|
|
.I vm_guest
|
|
.I terminal_id
|
|
.
|
|
.
|
|
.
|
|
.SH DESCRIPTION
|
|
The \*i application establishes a terminal connection to another
|
|
Linux instance. The Linux instance where \*i 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.
|
|
.PP
|
|
\*i accesses the terminal specified by \fIterminal_id\fP on the z/VM guest
|
|
virtual machine \fIvm_guest\fP.
|
|
The \fIterminal_id\fP is similar to a port number in TCP/IP communications.
|
|
.
|
|
\fIterminal_id\fP is case-sensitive and consists of up to 8 alphanumeric
|
|
characters. \fIterminal_id\fP must either identify a running \fBiucvtty\fP
|
|
instance, or a terminal device provided by the z/VM IUCV hypervisor console
|
|
(HVC) device driver.
|
|
.
|
|
.
|
|
.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BR \-h ", " \-\-help
|
|
Display a short help text, then exit.
|
|
.
|
|
.TP
|
|
.BR \-v ", " \-\-version
|
|
Display the version number of \*i, then exit.
|
|
.
|
|
.TP
|
|
.BR \-e ", " \-\-escape-char\~\fIescape_char\fP
|
|
Set an escape character for this terminal session. You need an escape character
|
|
to access special \*i functions. The default escape character is underscore (_).
|
|
If \fIescape_char\fP 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 \fIescape_char\fP character is not case-sensitive.
|
|
|
|
To invoke a \*i function, press Ctrl\^+\^\fIescape_char\fP, followed
|
|
by the function character. For example, press "Ctrl\^+\^_ d" to disconnect the
|
|
terminal session and exit \*i.
|
|
|
|
For details, see section "ESCAPE CHARACTERS" below.
|
|
.
|
|
.TP
|
|
.BR \-s ", " \-\-sessionlog\~\fIlogfile\fP
|
|
Create a transcript of the terminal session and write session data to three
|
|
different files.
|
|
|
|
\fIlog_file\fP contains the raw terminal data stream. The
|
|
.I log_file\fB.timing\fP
|
|
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
|
|
.IR log_file\fB.info\fP "."
|
|
|
|
If any of these files already exist, \*i exits with an error. To proceed
|
|
either delete the files or choose another file name for \fIlog_file\fP.
|
|
.
|
|
.
|
|
.
|
|
.SH "ESCAPE CHARACTERS"
|
|
\*i supports functions through the use of an escape character.
|
|
The default escape character (\fIescape_char\fP) is underscore (_).
|
|
|
|
To enter the "escape mode" of \*i, press the Control and the \fIescape_char\fP
|
|
key together ("Ctrl\^+\^_") In the "escape mode", \*i expects a single character
|
|
designating the special function.
|
|
|
|
The special functions are (assuming \fIescape_char\fP is set to underscore (_)):
|
|
.RS 4
|
|
.IP "\fBCtrl\^+\^_\fP" 8
|
|
Send the escape character to the connected terminal.
|
|
.IP "\fB.\fP or \fBd\fP" 8
|
|
Disconnect and exit \*i.
|
|
.IP "\fBr\fP" 8
|
|
Force resizing of the connected terminal.
|
|
.RE
|
|
.PP
|
|
Any other single character is ignored and is not send to the terminal. If
|
|
multiple characters are entered together, \*i leaves the "escape mode" and sends
|
|
the characters to the connected terminal.
|
|
.
|
|
.\" FIXME: change "connected terminal" to terminal
|
|
.
|
|
.
|
|
.SH "EXAMPLES"
|
|
To access the "lnxterm" terminal on the Linux instance in
|
|
z/VM guest virtual machine LNXSYS01:
|
|
.PP
|
|
.ft CW
|
|
.in +0.25in
|
|
.nf
|
|
iucvconn LNXSYS01 lnxterm
|
|
.fi
|
|
.in -0.25in
|
|
.ft
|
|
.PP
|
|
To access the first z/VM IUCV HVC terminal on the Linux instance in
|
|
z/VM guest virtual machine LNXSYS02:
|
|
.PP
|
|
.ft CW
|
|
.in +0.25in
|
|
.nf
|
|
iucvconn LNXSYS02 lnxhvc0
|
|
.fi
|
|
.in -0.25in
|
|
.ft
|
|
.PP
|
|
To create a transcript of the terminal session to the Linux instance in
|
|
z/VM guest virtual machine LNXSYS99:
|
|
.PP
|
|
.ft CW
|
|
.in +0.25in
|
|
.nf
|
|
iucvconn -s ~/transcripts/lnxsys99 LNXSYS99 lnxhvc0
|
|
.fi
|
|
.in -0.25in
|
|
.ft
|
|
.
|
|
.
|
|
.
|
|
.SH ENVIRONMENT
|
|
.TP
|
|
.B TERM
|
|
The terminal environment variable contains the name of the terminal
|
|
(e.g. linux, xterm, ...) and also specifies the terminal capabilities.
|
|
|
|
\*i transfers the value of the \fBTERM\fP environment variable at connection
|
|
startup to the target system. The \fBiucvtty\fP application sets the
|
|
\fBTERM\fP environment variable on the target system before the login program
|
|
is started.
|
|
Setting the \fBTERM\fP 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 \fBTERM\fP environment variable transferred by \*i. See the
|
|
.BR hvc_iucv (9)
|
|
manual page for instructions to configure the terminal environment.
|
|
.
|
|
.
|
|
.
|
|
.SH DIAGNOSTICS
|
|
If the Linux kernel does not include kernel support for the AF_IUCV network
|
|
addressing family, \*i exits and displays the message
|
|
.I 'AF_IUCV address family is not available: Address family not supported by
|
|
.IR protocol' "."
|
|
.
|
|
.
|
|
.
|
|
.SH SECURITY
|
|
.SS Linux
|
|
The \*i program does not require superuser privileges and can be used by
|
|
regular users. Each connection attempt and failure is logged to the
|
|
.BR authpriv
|
|
syslog facility.
|
|
.\".PP
|
|
.\"Depending on the login program started by the \fBiucvtty\fP program,
|
|
.\"the user must authenticate to the remote system.
|
|
.PP
|
|
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.
|
|
.
|
|
.
|
|
.SS z/VM guest virtual machine
|
|
The z/VM guest virtual machine must have authorization to establish IUCV
|
|
communication paths to other z/VM guest virtual machines.
|
|
|
|
See the
|
|
.BR af_iucv (7)
|
|
manual page for details about IUCV authorizations.
|
|
.
|
|
.
|
|
.
|
|
.SH NOTES
|
|
The Linux instance where \*i runs and the target Linux instances
|
|
must be z/VM guest operating systems of the same z/VM instance.
|
|
.
|
|
.
|
|
.
|
|
.SH "SEE ALSO"
|
|
.BR iucvtty (1),
|
|
.BR hvc_iucv (9),
|
|
.BR af_iucv (7),
|
|
.BR scriptreplay (1)
|
|
|
|
.I "Linux on System z - Device Drivers, Features, and Commands"
|