iucvterm/doc/iucvconn.1

   1 .\" iucvconn.1
   2 .\"
   3 .\"
   4 .\" Copyright IBM Corp. 2008, 2009.
   5 .\" Author(s): Hendrik Brueckner <brueckner@linux.vnet.ibm.com>
   6 .\" ----------------------------------------------------------------------
   7 .TH iucvconn "1" "March 2009" "s390-tools" "IUCV terminal applications"
   8 .LO 8
   9 .
  10 .ds i \fBiucvconn\fP
  11 .
  12 .
  13 .
  14 .SH NAME
  15 iucvconn \- start terminal connection over z/VM IUCV
  16 .
  17 .
  18 .
  19 .SH SYNOPSIS
  20 .B iucvconn
  21 .RB [ \-h | \-\-help ]
  22 .br
  23 .B iucvconn
  24 .RB [ \-v | \-\-version ]
  25 .br
  26 .B iucvconn
  27 .RB [ \-e | \-\-escape-char
  28 .IR escape_char ]
  29 .RB [ \-s | \-\-sessionlog
  30 .IR log_file ]
  31 .I vm_guest
  32 .I terminal_id
  33 .
  34 .
  35 .
  36 .SH DESCRIPTION
  37 The \*i application establishes a terminal connection to another
  38 Linux instance. The Linux instance where \*i runs and the target Linux instance
  39 must be z/VM guest operating systems of the same z/VM instance.
  40 The communication path between both virtual machines is based on the z/VM
  41 Inter-User Communication Vehicle (IUCV).
  42 Because z/VM IUCV is independent from TCP/IP, Linux instances with no external
  43 network can be accessed.
  44 .PP
  45 \*i accesses the terminal specified by \fIterminal_id\fP on the z/VM guest
  46 virtual machine \fIvm_guest\fP.
  47 The \fIterminal_id\fP is similar to a port number in TCP/IP communications.
  48 .
  49 \fIterminal_id\fP is case-sensitive and consists of up to 8 alphanumeric
  50 characters. \fIterminal_id\fP must either identify a running \fBiucvtty\fP
  51 instance, or a terminal device provided by the z/VM IUCV hypervisor console
  52 (HVC) device driver.
  53 .
  54 .
  55 .
  56 .SH OPTIONS
  57 .TP
  58 .BR \-h ", " \-\-help
  59 Display a short help text, then exit.
  60 .
  61 .TP
  62 .BR \-v ", " \-\-version
  63 Display the version number of \*i, then exit.
  64 .
  65 .TP
  66 .BR \-e ", " \-\-escape-char\~\fIescape_char\fP
  67 Set an escape character for this terminal session. You need an escape character
  68 to access special \*i functions. The default escape character is underscore (_).
  69 If \fIescape_char\fP is set to "none", escaping is not possible.
  70 The escape character can be the closing bracket (]), the caret (^), the
  71 underscore (_), or any alphabetical character except C, D, Q, S and Z.
  72 The \fIescape_char\fP character is not case-sensitive.
  73
  74 To invoke a \*i function, press Ctrl\^+\^\fIescape_char\fP, followed
  75 by the function character. For example, press "Ctrl\^+\^_ d" to disconnect the
  76 terminal session and exit \*i.
  77
  78 For details, see section "ESCAPE CHARACTERS" below.
  79 .
  80 .TP
  81 .BR \-s ", " \-\-sessionlog\~\fIlogfile\fP
  82 Create a transcript of the terminal session and write session data to three
  83 different files.
  84
  85 \fIlog_file\fP contains the raw terminal data stream. The
  86 .I log_file\fB.timing\fP
  87 file contains timing data that can be used for replaying the raw terminal data
  88 stream using realistic output delays.
  89 Additional terminal session information is logged to
  90 .IR log_file\fB.info\fP "."
  91
  92 If any of these files already exist, \*i exits with an error. To proceed
  93 either delete the files or choose another file name for \fIlog_file\fP.
  94 .
  95 .
  96 .
  97 .SH "ESCAPE CHARACTERS"
  98 \*i supports functions through the use of an escape character.
  99 The default escape character (\fIescape_char\fP) is underscore (_).
 100
 101 To enter the "escape mode" of \*i, press the Control and the \fIescape_char\fP
 102 key together ("Ctrl\^+\^_") In the "escape mode", \*i expects a single character
 103 designating the special function.
 104
 105 The special functions are (assuming \fIescape_char\fP is set to underscore (_)):
 106 .RS 4
 107 .IP "\fBCtrl\^+\^_\fP" 8
 108 Send the escape character to the connected terminal.
 109 .IP "\fB.\fP or \fBd\fP" 8
 110 Disconnect and exit \*i.
 111 .IP "\fBr\fP" 8
 112 Force resizing of the connected terminal.
 113 .RE
 114 .PP
 115 Any other single character is ignored and is not send to the terminal. If
 116 multiple characters are entered together, \*i leaves the "escape mode" and sends
 117 the characters to the connected terminal.
 118 .
 119 .\" FIXME: change "connected terminal" to terminal
 120 .
 121 .
 122 .SH "EXAMPLES"
 123 To access the "lnxterm" terminal on the Linux instance in
 124 z/VM guest virtual machine LNXSYS01:
 125 .PP
 126 .ft CW
 127 .in +0.25in
 128 .nf
 129 iucvconn LNXSYS01 lnxterm
 130 .fi
 131 .in -0.25in
 132 .ft
 133 .PP
 134 To access the first z/VM IUCV HVC terminal on the Linux instance in
 135 z/VM guest virtual machine LNXSYS02:
 136 .PP
 137 .ft CW
 138 .in +0.25in
 139 .nf
 140 iucvconn LNXSYS02 lnxhvc0
 141 .fi
 142 .in -0.25in
 143 .ft
 144 .PP
 145 To create a transcript of the terminal session to the Linux instance in
 146 z/VM guest virtual machine LNXSYS99:
 147 .PP
 148 .ft CW
 149 .in +0.25in
 150 .nf
 151 iucvconn -s ~/transcripts/lnxsys99 LNXSYS99 lnxhvc0
 152 .fi
 153 .in -0.25in
 154 .ft
 155 .
 156 .
 157 .
 158 .SH ENVIRONMENT
 159 .TP
 160 .B TERM
 161 The terminal environment variable contains the name of the terminal
 162 (e.g. linux, xterm, ...) and also specifies the terminal capabilities.
 163
 164 \*i transfers the value of the \fBTERM\fP environment variable at connection
 165 startup to the target system. The \fBiucvtty\fP application sets the
 166 \fBTERM\fP environment variable on the target system before the login program
 167 is started.
 168 Setting the \fBTERM\fP environment variable ensures that the terminal
 169 capabilities are the same on both sides of the connection.
 170
 171 The z/VM IUCV hypervisor console (HVC) device driver ignores the content of
 172 the \fBTERM\fP environment variable transferred by \*i. See the
 173 .BR hvc_iucv (9)
 174 manual page for instructions to configure the terminal environment.
 175 .
 176 .
 177 .
 178 .SH DIAGNOSTICS
 179 If the Linux kernel does not include kernel support for the AF_IUCV network
 180 addressing family, \*i exits and displays the message
 181 .I 'AF_IUCV address family is not available: Address family not supported by
 182 .IR protocol' "."
 183 .
 184 .
 185 .
 186 .SH SECURITY
 187 .SS Linux
 188 The \*i program does not require superuser privileges and can be used by
 189 regular users.  Each connection attempt and failure is logged to the
 190 .BR authpriv
 191 syslog facility.
 192 .\".PP
 193 .\"Depending on the login program started by the \fBiucvtty\fP program,
 194 .\"the user must authenticate to the remote system.
 195 .PP
 196 Terminal session transcripts facilitate logging and auditing of terminal
 197 activity on remote systems or recording and playing back terminal sessions,
 198 for example for education and presentations.
 199 .
 200 .
 201 .SS z/VM guest virtual machine
 202 The z/VM guest virtual machine must have authorization to establish IUCV
 203 communication paths to other z/VM guest virtual machines.
 204
 205 See the
 206 .BR af_iucv (7)
 207 manual page for details about IUCV authorizations.
 208 .
 209 .
 210 .
 211 .SH NOTES
 212 The Linux instance where \*i runs and the target Linux instances
 213 must be z/VM guest operating systems of the same z/VM instance.
 214 .
 215 .
 216 .
 217 .SH "SEE ALSO"
 218 .BR iucvtty (1),
 219 .BR hvc_iucv (9),
 220 .BR af_iucv (7),
 221 .BR scriptreplay (1)
 222
 223 .I "Linux on System z - Device Drivers, Features, and Commands"