Annotation of src/usr.bin/tip/tip.1, Revision 1.39
1.39 ! jmc 1: .\" $OpenBSD: tip.1,v 1.38 2007/05/31 19:20:18 jmc Exp $
1.1 deraadt 2: .\" $NetBSD: tip.1,v 1.7 1994/12/08 09:31:05 jtc Exp $
3: .\"
4: .\" Copyright (c) 1980, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
1.24 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 16: .\" may be used to endorse or promote products derived from this software
17: .\" without specific prior written permission.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29: .\" SUCH DAMAGE.
30: .\"
31: .\" @(#)tip.1 8.4 (Berkeley) 4/18/94
32: .\"
1.38 jmc 33: .Dd $Mdocdate$
1.1 deraadt 34: .Dt TIP 1
1.6 aaron 35: .Os
1.1 deraadt 36: .Sh NAME
1.35 jmc 37: .Nm tip
1.1 deraadt 38: .Nd connect to a remote system
39: .Sh SYNOPSIS
1.35 jmc 40: .Nm
1.3 todd 41: .Op Fl nv
1.14 krw 42: .Op Fl Ar speed
1.35 jmc 43: .Op Ar system-name
1.1 deraadt 44: .Sh DESCRIPTION
1.7 aaron 45: .Nm
1.35 jmc 46: establishes a full-duplex connection to another machine, giving the
1.14 krw 47: appearance of being logged in directly on the remote CPU.
48: It goes without saying that you must have a login on the machine (or
49: equivalent) to which you wish to connect.
1.1 deraadt 50: .Pp
1.6 aaron 51: The options are as follows:
1.18 deraadt 52: .Bl -tag -width 4n
53: .It Fl n
54: No escape (disable tilde).
1.1 deraadt 55: .It Fl v
56: Set verbose mode.
57: .El
1.22 millert 58: .Pp
1.14 krw 59: If
60: .Ar speed
1.35 jmc 61: is specified, it will override any baudrate specified in the system
1.14 krw 62: description being used.
63: .Pp
64: If neither
65: .Ar speed
66: nor
67: .Ar system-name
68: are specified,
69: .Ar system-name
70: will be set to the value of the
71: .Ev HOST
72: environment variable.
73: .Pp
74: If
75: .Ar speed
76: is specified but
77: .Ar system-name
78: is not,
79: .Ar system-name
80: will be set to a value of 'tip' with
81: .Ar speed
82: appended.
1.35 jmc 83: For example,
1.14 krw 84: .Ic tip -1200
85: will set
86: .Ar system-name
87: to 'tip1200'.
88: .Pp
1.39 ! jmc 89: Line access is logged to
! 90: .Pa /var/log/aculog .
! 91: This file does not exist by default and has to be created
! 92: to enable logging.
! 93: .Pp
1.1 deraadt 94: Typed characters are normally transmitted directly to the remote
1.7 aaron 95: machine (which does the echoing as well).
96: A tilde
1.6 aaron 97: .Pq Ql ~
1.14 krw 98: appearing as the first character of a line is an escape signal; the
99: following are recognized:
100: .Bl -tag -offset indent -width Fl
1.35 jmc 101: .It Ic ~^D No or Ic ~.
102: Drop the connection and exit.
103: Only the connection is dropped \(en the login session is not terminated.
104: .It Ic ~c Op Ar name
1.1 deraadt 105: Change directory to
106: .Ar name
1.35 jmc 107: (no argument implies change to home directory).
108: .It Ic ~!
109: Escape to a shell (exiting the shell will return to
110: .Nm ) .
111: .It Ic ~\*(Gt
1.1 deraadt 112: Copy file from local to remote.
1.7 aaron 113: .Nm
1.1 deraadt 114: prompts for the name of a local file to transmit.
1.35 jmc 115: .It Ic ~\*(Lt
1.1 deraadt 116: Copy file from remote to local.
1.7 aaron 117: .Nm
1.14 krw 118: prompts first for the name of the file to be sent, then for a command
119: to be executed on the remote machine.
1.35 jmc 120: .It Ic ~p Ar from Op Ar to
1.1 deraadt 121: Send a file to a remote
122: .Ux
1.7 aaron 123: host.
1.35 jmc 124: This command causes the remote
1.1 deraadt 125: .Ux
1.35 jmc 126: system to run the following command string,
127: sending it the
128: .Sq from
129: file:
130: .Bd -literal -offset indent
131: stty -echo; cat \*(Gt 'to'; stty echo
132: .Ed
133: .Pp
1.7 aaron 134: If the
1.35 jmc 135: .Sq to
136: file isn't specified, the
137: .Sq from
1.6 aaron 138: file name is used.
1.21 fgsch 139: This command is actually a
1.1 deraadt 140: .Ux
1.6 aaron 141: specific version of the
1.35 jmc 142: .Ic ~\*(Gt
1.6 aaron 143: command.
1.35 jmc 144: .It Ic ~t Ar from Op Ar to
1.1 deraadt 145: Take a file from a remote
146: .Ux
147: host.
1.35 jmc 148: As in the
149: .Ic ~p
150: command, the
151: .Sq to
1.14 krw 152: file defaults to the
1.35 jmc 153: .Sq from
1.6 aaron 154: file name if it isn't specified.
1.35 jmc 155: The remote host executes the following command string
1.6 aaron 156: to send the file to
1.35 jmc 157: .Nm :
158: .Bd -literal -offset indent
159: cat 'from'; echo '' | tr '\e012' '\e01'
160: .Ed
161: .It Ic ~|
1.1 deraadt 162: Pipe the output from a remote command to a local
163: .Ux
164: process.
165: The command string sent to the local
166: .Ux
167: system is processed by the shell.
1.35 jmc 168: .It Ic ~$
1.1 deraadt 169: Pipe the output from a local
170: .Ux
171: process to the remote host.
172: The command string sent to the local
173: .Ux
174: system is processed by the shell.
1.35 jmc 175: .It Ic ~C
1.1 deraadt 176: Fork a child process on the local system to perform special protocols
1.7 aaron 177: such as \s-1XMODEM\s+1.
1.30 otto 178: The child program will be run with the following arrangement of
179: file descriptors:
1.14 krw 180: .Bd -literal -offset indent
1.35 jmc 181: 0 \*(Lt-\*(Gt remote tty in
182: 1 \*(Lt-\*(Gt remote tty out
183: 2 \*(Lt-\*(Gt local tty stderr
1.14 krw 184: .Ed
1.35 jmc 185: .It Ic ~#
1.1 deraadt 186: Send a
187: .Dv BREAK
188: to the remote system.
1.14 krw 189: For systems which don't support the necessary
1.4 aaron 190: .Fn ioctl
1.35 jmc 191: call, the break is simulated by a sequence of line speed changes and
1.14 krw 192: DEL characters.
1.35 jmc 193: .It Ic ~s
1.1 deraadt 194: Set a variable (see the discussion below).
1.35 jmc 195: .It Ic ~v
1.16 millert 196: List all variables and their values (if set).
1.35 jmc 197: .It Ic ~^Z
1.1 deraadt 198: Stop
1.6 aaron 199: .Nm
1.1 deraadt 200: (only available with job control).
1.35 jmc 201: .It Ic ~^Y
1.6 aaron 202: Stop only the
203: .Dq local side
204: of
205: .Nm
1.14 krw 206: (only available with job control); the
1.6 aaron 207: .Dq remote side
208: of
1.35 jmc 209: .Nm ,
1.1 deraadt 210: the side that displays output from the remote host, is left running.
1.35 jmc 211: .It Ic ~?
1.4 aaron 212: Get a summary of the tilde escapes.
1.1 deraadt 213: .El
214: .Pp
1.35 jmc 215: To find the system description, and thus the operating characteristics
1.14 krw 216: of
217: .Ar system-name ,
1.6 aaron 218: .Nm
1.14 krw 219: searches for a system description with a name identical to
220: .Ar system-name .
221: The search order is
222: .Bl -enum -offset indent
223: .It
224: If the environment variable
225: .Ev REMOTE
226: does not start with a
1.35 jmc 227: .Ql /
1.14 krw 228: it is assumed to be a system description, and is considered first.
229: .It
230: If the environment variable
231: .Ev REMOTE
232: begins with a
1.35 jmc 233: .Ql /
1.14 krw 234: it is assumed to be a path to a
235: .Xr remote 5
236: database, and the specified database is searched.
1.25 jmc 237: .It
1.14 krw 238: The default
1.7 aaron 239: .Xr remote 5
1.14 krw 240: database,
241: .Pa /etc/remote ,
242: is searched.
243: .El
244: .Pp
245: See
246: .Xr remote 5
247: for full documentation on system descriptions.
248: .Pp
249: The
1.27 jmc 250: .Ar br
1.14 krw 251: capability is used in system descriptions to specify the baud rate
252: with which to establish a connection.
253: If the value specified is not suitable, the baud rate to be used may
1.35 jmc 254: be given on the command line, e.g.\&
255: .Ql tip -300 mds .
1.39 ! jmc 256: .Pp
! 257: The
! 258: .Ar dv
! 259: capability is used to specify the device
! 260: with which to establish a connection.
! 261: For reasons outlined in
! 262: .Xr tty 4 ,
! 263: .Xr cua 4
! 264: devices should be used on architectures which have them.
! 265: For those which do not,
! 266: .Xr tty 4
! 267: devices can be used.
! 268: Users in group
! 269: .Dq dialer
! 270: are permitted to use
! 271: .Xr cua 4
! 272: devices by default;
! 273: permissions on
! 274: .Pa /dev/tty00
! 275: or
! 276: .Pa /dev/ttya
! 277: can be changed,
! 278: but they will revert to their defaults
! 279: after an upgrade or (re)install.
1.1 deraadt 280: .Pp
281: When
1.6 aaron 282: .Nm
1.35 jmc 283: establishes a connection, it sends out the connection message
1.14 krw 284: specified in the
285: .Ar cm
286: capability of the system description being used.
1.1 deraadt 287: .Pp
288: When
1.6 aaron 289: .Nm
1.35 jmc 290: prompts for an argument, for example during setup of a file transfer, the
1.14 krw 291: line typed may be edited with the standard erase and kill characters.
292: A null line in response to a prompt, or an interrupt, will abort the
1.35 jmc 293: dialogue and return the user to the remote machine.
1.1 deraadt 294: .Pp
1.6 aaron 295: .Nm
1.14 krw 296: guards against multiple users connecting to a remote system by opening
297: modems and terminal lines with exclusive access, and by honoring the
298: locking protocol used by
1.23 jmc 299: .Xr uucico .
1.1 deraadt 300: .Pp
301: During file transfers
1.6 aaron 302: .Nm
1.1 deraadt 303: provides a running count of the number of lines transferred.
1.6 aaron 304: When using the
1.35 jmc 305: .Ic ~\*(Gt
1.6 aaron 306: and
1.35 jmc 307: .Ic ~\*(Lt
1.6 aaron 308: commands, the
309: .Dq eofread
310: and
311: .Dq eofwrite
1.14 krw 312: variables are used to recognize end-of-file when reading, and specify
313: end-of-file when writing (see below).
1.29 millert 314: File transfers normally depend on hardwareflow or tandem mode for flow control.
315: If the remote system does not support hardwareflow or tandem mode,
1.6 aaron 316: .Dq echocheck
317: may be set to indicate
318: .Nm
1.1 deraadt 319: should synchronize with the remote system on the echo of each
320: transmitted character.
321: .Pp
322: When
1.6 aaron 323: .Nm
1.14 krw 324: must dial a phone number to connect to a system it will print various
325: messages indicating its actions.
1.6 aaron 326: .Nm
1.14 krw 327: supports a variety of auto-call units and modems with the
328: .Ar at
329: capability in system descriptions.
330: .Pp
331: Support for Ventel 212+ (ventel), Hayes AT-style (hayes),
332: USRobotics Courier (courier), Telebit T3000 (t3000) and
333: Racal-Vadic 831 (vadic) units is enabled by default.
334: .Pp
335: Support for Bizcomp 1031[fw] (biz31[fw]), Bizcomp 1022[fw]
336: (biz22[fw]), DEC DF0[23]-AC (df0[23]), DEC DN-11 (dn11) and
337: Racal-Vadic 3451 (v3451) units can be added by recompiling
1.25 jmc 338: .Nm tip
1.14 krw 339: with the appropriate defines.
340: .Pp
341: Note that if support for both the Racal-Vadic 831 and 3451 is enabled
342: they are referred to as the v831 and v3451 respectively.
343: If only one of the two is supported, it is referred to as vadic.
1.1 deraadt 344: .Ss VARIABLES
1.6 aaron 345: .Nm
1.14 krw 346: maintains a set of variables which control its operation.
1.1 deraadt 347: Some of these variables are read-only to normal users (root is allowed
1.7 aaron 348: to change anything of interest).
349: Variables may be displayed and set through the
1.6 aaron 350: .Sq s
1.7 aaron 351: escape.
352: The syntax for variables is patterned after
1.6 aaron 353: .Xr vi 1
1.1 deraadt 354: and
1.6 aaron 355: .Xr Mail 1 .
356: Supplying
357: .Dq all
1.1 deraadt 358: as an argument to the set command displays all variables readable by
1.7 aaron 359: the user.
1.14 krw 360: Alternatively, the user may request display of a particular variable
361: by attaching a
1.26 jmc 362: .Ql \&?
1.7 aaron 363: to the end.
364: For example,
1.6 aaron 365: .Dq escape?
1.1 deraadt 366: displays the current escape character.
367: .Pp
1.7 aaron 368: Variables are numeric, string, character, or boolean values.
1.14 krw 369: Boolean variables are set merely by specifying their name; they may be
370: reset by prepending a
1.26 jmc 371: .Ql \&!
1.7 aaron 372: to the name.
373: Other variable types are set by concatenating an
1.6 aaron 374: .Ql =
1.7 aaron 375: and the value.
376: The entire assignment must not have any blanks in it.
1.14 krw 377: A single set command may be used to interrogate as well as set a
378: number of variables.
1.1 deraadt 379: Variables may be initialized at run time by placing set commands
1.6 aaron 380: (without the
381: .Ql ~s
1.36 jmc 382: prefix) in the initialization file
383: .Pa ~/.tiprc ;
384: the
1.1 deraadt 385: .Fl v
1.36 jmc 386: option additionally causes
1.6 aaron 387: .Nm
1.1 deraadt 388: to display the sets as they are made.
389: Certain common variables have abbreviations.
1.14 krw 390: The following is a list of common variables, their abbreviations, and
391: their default values:
1.1 deraadt 392: .Bl -tag -width Ar
1.35 jmc 393: .It Ar baudrate
394: (num) The baud rate at which the connection was established;
395: abbreviated
396: .Ar ba .
1.1 deraadt 397: .It Ar beautify
1.14 krw 398: (bool) Discard unprintable characters when a session is being
399: scripted; abbreviated
1.4 aaron 400: .Ar be .
1.1 deraadt 401: .It Ar dialtimeout
1.14 krw 402: (num) When dialing a phone number, the time (in seconds) to wait for a
403: connection to be established; abbreviated
1.4 aaron 404: .Ar dial .
1.1 deraadt 405: .It Ar echocheck
406: (bool) Synchronize with the remote host during file transfer by
407: waiting for the echo of the last character transmitted; default is
1.4 aaron 408: .Ar off .
1.1 deraadt 409: .It Ar eofread
410: (str) The set of characters which signify an end-of-transmission
1.6 aaron 411: during a
1.35 jmc 412: .Ic ~\*(Lt
1.6 aaron 413: file transfer command; abbreviated
1.4 aaron 414: .Ar eofr .
1.1 deraadt 415: .It Ar eofwrite
1.6 aaron 416: (str) The string sent to indicate end-of-transmission during a
1.35 jmc 417: .Ic ~\*(Gt
1.6 aaron 418: file transfer command; abbreviated
1.4 aaron 419: .Ar eofw .
1.1 deraadt 420: .It Ar eol
421: (str) The set of characters which indicate an end-of-line.
1.6 aaron 422: .Nm
1.1 deraadt 423: will recognize escape characters only after an end-of-line.
424: .It Ar escape
425: (char) The command prefix (escape) character; abbreviated
1.6 aaron 426: .Ar es ;
427: default value is
428: .Ql ~ .
1.1 deraadt 429: .It Ar exceptions
1.14 krw 430: (str) The set of characters which should not be discarded due to the
431: beautification switch; abbreviated
1.7 aaron 432: .Ar ex ;
1.6 aaron 433: default value is
434: .Dq \et\en\ef\eb .
1.1 deraadt 435: .It Ar force
436: (char) The character used to force literal data transmission;
437: abbreviated
1.7 aaron 438: .Ar fo ;
1.6 aaron 439: default value is
440: .Ql ^P .
1.1 deraadt 441: .It Ar framesize
1.11 millert 442: (num) The amount of data (in bytes) to buffer between filesystem
1.1 deraadt 443: writes when receiving files; abbreviated
1.4 aaron 444: .Ar fr .
1.29 millert 445: .It Ar hardwareflow
446: (bool) Whether hardware flow control (CRTSCTS) is enabled for the
447: connection; abbreviated
448: .Ar hf ;
449: default value is
450: .Ql off .
1.1 deraadt 451: .It Ar host
452: (str) The name of the host to which you are connected; abbreviated
1.4 aaron 453: .Ar ho .
1.37 mbalmer 454: .It Ar linedisc
455: (num) The line discipline to use; abbreviated
456: .Ar ld .
1.1 deraadt 457: .It Ar prompt
458: (char) The character which indicates an end-of-line on the remote
459: host; abbreviated
1.6 aaron 460: .Ar pr ;
461: default value is
462: .Ql \en .
1.7 aaron 463: This value is used to synchronize during data transfers.
1.14 krw 464: The count of lines transferred during a file transfer command is based
465: on receipt of this character.
1.1 deraadt 466: .It Ar raise
467: (bool) Upper case mapping mode; abbreviated
1.6 aaron 468: .Ar ra ;
1.1 deraadt 469: default value is
1.4 aaron 470: .Ar off .
1.11 millert 471: When this mode is enabled, all lowercase letters will be mapped to
472: uppercase by
1.6 aaron 473: .Nm
1.1 deraadt 474: for transmission to the remote machine.
475: .It Ar raisechar
1.11 millert 476: (char) The input character used to toggle uppercase mapping mode;
1.1 deraadt 477: abbreviated
1.6 aaron 478: .Ar rc ;
479: default value is
480: .Ql ^A .
1.1 deraadt 481: .It Ar record
482: (str) The name of the file in which a session script is recorded;
483: abbreviated
1.6 aaron 484: .Ar rec ;
485: default value is
486: .Dq tip.record .
1.1 deraadt 487: .It Ar script
488: (bool) Session scripting mode; abbreviated
1.7 aaron 489: .Ar sc ;
1.1 deraadt 490: default is
1.4 aaron 491: .Ar off .
1.1 deraadt 492: When
493: .Ar script
494: is
1.8 aaron 495: .Li true ,
1.6 aaron 496: .Nm
1.14 krw 497: will record everything transmitted by the remote machine in the script
498: record file specified in
1.4 aaron 499: .Ar record .
1.1 deraadt 500: If the
501: .Ar beautify
502: switch is on, only printable
503: .Tn ASCII
1.14 krw 504: characters will be included in the script file (those characters
505: between 040 and 0177).
1.7 aaron 506: The variable
1.1 deraadt 507: .Ar exceptions
508: is used to indicate characters which are an exception to the normal
509: beautification rules.
510: .It Ar tabexpand
511: (bool) Expand tabs to spaces during file transfers; abbreviated
1.7 aaron 512: .Ar tab ;
1.1 deraadt 513: default value is
1.4 aaron 514: .Ar false .
1.1 deraadt 515: Each tab is expanded to 8 spaces.
1.29 millert 516: .It Ar tandem
517: (bool) Use XON/XOFF flow control to throttle data from the remote host;
518: abbreviated
519: .Ar ta .
520: The default value is
521: .Ar true
522: unless the
523: .Ar nt
524: capability has been specified in
525: .Pa /etc/remote ,
526: in which case the default value is
1.31 jmc 527: .Ar false .
1.1 deraadt 528: .It Ar verbose
529: (bool) Verbose mode; abbreviated
1.7 aaron 530: .Ar verb ;
1.1 deraadt 531: default is
1.4 aaron 532: .Ar true .
1.1 deraadt 533: When verbose mode is enabled,
1.6 aaron 534: .Nm
1.14 krw 535: prints messages while dialing, shows the current number of lines
536: transferred during a file transfer operations, and more.
1.1 deraadt 537: .El
538: .Sh ENVIRONMENT
539: .Bl -tag -width Fl
540: .It Ev HOME
1.14 krw 541: The home directory to use for the
1.6 aaron 542: .Ic ~c
1.14 krw 543: command.
1.1 deraadt 544: .It Ev HOST
1.14 krw 545: The default value for
546: .Ar system-name
547: if none is specified via the command line.
1.35 jmc 548: .It Ev PHONES
549: A path to a
550: .Xr phones 5
551: database.
1.14 krw 552: .It Ev REMOTE
553: A system description, or an absolute path to a
554: .Xr remote 5
555: system description database.
1.35 jmc 556: .It Ev SHELL
557: The name of the shell to use for the
558: .Ic ~!\&
559: command; default value is
560: .Dq /bin/sh .
1.1 deraadt 561: .El
562: .Sh FILES
1.14 krw 563: .Bl -tag -width "/var/spool/lock/LCK..*" -compact
1.35 jmc 564: .It Pa ~/.tiprc
565: initialization file
566: .It Pa tip.record
567: record file
568: .It Pa /etc/phones
569: default
570: .Xr phones 5
571: file
1.1 deraadt 572: .It Pa /etc/remote
1.14 krw 573: global
574: .Xr remote 5
575: database
1.4 aaron 576: .It Pa /var/log/aculog
577: line access log
1.1 deraadt 578: .It Pa /var/spool/lock/LCK..*
1.4 aaron 579: lock file to avoid conflicts with
580: .Xr uucp
1.1 deraadt 581: .El
582: .Sh SEE ALSO
1.35 jmc 583: .Xr cu 1 ,
1.4 aaron 584: .Xr phones 5 ,
585: .Xr remote 5
1.1 deraadt 586: .Sh HISTORY
587: The
1.6 aaron 588: .Nm
1.20 miod 589: command appeared in
1.1 deraadt 590: .Bx 4.2 .
591: .Sh BUGS
592: The full set of variables is undocumented and should, probably, be
593: pared down.