Tenth Edition TELNET User's Guide Mark Crispin 12/28/83 Copyright (c) 1979, 1980, 1981, 1983 by The Board of Trustees, Stanford University, Stanford, CA 94305 This software is furnished under a license and may only be used or copied in accordance with the terms of such license and with the inclusion of the above copyright notice. This software or any other copies thereof may not be provided or otherwise made available to any other person. No title to and ownership of the software is hereby transferred. The information in this software is subject to change without notice and should not be construed as a commitment by Stanford University. Stanford assumes no responsibility for the use or reliability of this software. Abstract User TELNET is a subsystem which allows a user to connect to other systems on a network (called hosts) as if she were on a local terminal at that host. As of version 5.3(918), TELNET supports: . TCP/IP TELNET protocol . TELNET protocol on Chaosnet . NRT20 protocol on DECnet . Chat protocol on 3MHz Pup Ethernet . TTY port connection TELNET requires TOPS-20 release 5.3 or later. TELNET was written by Mark Crispin to replace the older Tenex TELNET program. TELNET was written with the intent of exploiting the superior command parsing facilities of TOPS-20 to replace the older program's idiosyncratic command parser as well as greatly improving performance. Introduction TELNET allows a user to communicate with other hosts on a network as if she was on a local terminal on that host. This is done by mapping the terminal I/O operations on TOPS-20 to that of a network virtual terminal (NVT) and sending this protocol over the network. The remote host then unmaps from NVT protocol to its own idea of how a terminal works. In addition, the TELNET protocol provides for negotiated terminal options between the user (ie, the local host) and the server (remote host) TELNET processes. By design, TELNET insulates the user from this as much as possible, so that the user may for the most part forget about the presence of the local host and TELNET itself. In general, once the user has connected to a host all type-in is sent "as is" to the remote host. Another design goal of TELNET was to fit in better with the TOPS-20 way of command parsing by allowing command lines from the EXEC and using the COMND% JSYS. The simplest way to use TELNET is to give the EXEC command @TELNET host-name where host-name is the official name or known nickname of the host the user wishes to connect to. For example, the command @TELNET Score.ARPA will attempt to establish a connection to SU-SCORE, the Stanford University Computer Science Department DECSYSTEM-20 (provided that there is a path by which SU-SCORE can be reached). Note that "Score" is a recognized nickname for SU-SCORE.ARPA. If TELNET succeeds, the user will be typing to the SU-SCORE system. If it fails, an appropriate error message is printed. When the user wishes to get out of TELNET, she can type CTRL/^ C (control-caret followed by C), which closes the connection (ie, it "hangs up") and returns the user to the EXEC. CTRL/^ is the "escape character" and is the prefix for several other commands, including a second CTRL/^ which sends it to the remote host. There are no other characters which are treated specially by TELNET; in particular, characters like CTRL/C are passed to the remote host instead of causing their TOPS-20 function. TELNET States This description is a bit complicated and may be skipped in a first reading. However, understanding the material on this page is essential to be able to use TELNET effectively. The states that TELNET can be in are relatively straightforward and intuitive once the user understands the functionality which TELNET must provide above and beyond a simple "linker" program. TELNET has essentially four layered modes of operation. Each mode can invoke its immediate inferior, or return to its superior. The superior of TELNET's highest mode is the subsystem that invoked TELNET (usually the EXEC), and the inferior of TELNET's lowest mode may also be an EXEC. Top-level mode is the mode that the user is in when she invokes TELNET. There is no connection to a remote host in this mode. Top-level searches for a TELNET command in the EXEC command which invoked TELNET. If one is found it is executed and top-level returns to the EXEC when the command completes. Otherwise, top-level prompts for a command line using the standard TOPS-20 conventions. After the command completes top-level prompts for another command. When a connection has been established to a remote host, TELNET enters talk mode. In talk mode, the user is talking to the remote host and not to TELNET (or rather, not in a way which the user need be concerned about). There are some exceptions to this. If the connection is not in transparent mode (see TRANSPARENT under TELNET Commands), the 200 bit (ie, the EDIT key) is suppressed. This is the normal mode because some terminals generate a parity bit which may be misinterpreted as the EDIT key. Also, both opaque and page mode affect the data stream by inserting possible padding or other characters into the data stream as well as intercepting certain input characters. The final exception is if the user enters the escape character. Talk mode returns to top level if the connection closes. When the user enters the escape character, TELNET enters talk command mode (this can be changed by the user; see EXTENDED under TELNET Commands). It is then waiting for a single character command. The most simple case is when the escape character is entered twice, in which case it is sent once to the remote host. The escape character is initially CTRL/^ (octal 036). See the ESCAPE command documentation for a complete list of the talk command mode commands. Talk command mode returns to talk mode when the command has completed. The X command in talk command mode enters extended talk command mode, which is similar to top-level except the command set consists of the commands appropriate when a connection is in effect. Unlike talk command mode, extended talk command mode prompts for its commands, echoes, and uses the COMND% JSYS for command parsing. Extended talk command mode returns to talk mode when the command has completed. The reason for having both talk command mode and extended talk command mode is to have a way to do all the "terminal" functions (such as sending the escape character, sending ATTN, etc.) without causing the extended talk command mode prompt and echo to interfere with the typescript, yet still have the functionality of a COMND% JSYS talk command mode. By using a TELNET.CMD file on the login directory the user can change TELNET's default behavior to be similar to the old Tenex TELNET program. For example, if the user wants CTRL/Y for the intercept character, immediate entry into extended command mode at talk level, and to have the terminal in opaque mode with local XON/XOFF handling, she can create a TELNET.CMD file on her login directory containing the following lines: ESCAPE 031 ; or a quoted control-Y EXTENDED OPAQUE PAGE TELNET Commands ABORT (OUTPUT) [Networks running DoD standard TELNET protocol only] Send the protocol command to abort output to the remote host. This command is only valid in talk mode. ATTN (KEY) [Networks running DoD standard TELNET protocol only] Send the protocol command for the "Attention" signal (used mainly for Multics or IBM systems). This command is only valid in talk mode. BREAK (KEY) [Networks running DoD standard TELNET protocol only] Send the protocol command for the "Break" signal. This command is only valid in talk mode. CLOSE (CONNECTION) Close the network connection to the remote host. Exit if TELNET was invoked with a command line argument, else return to the top-level command parser. This command is only valid in talk mode. [CONNECT (TO) CHAOSNET (HOST)] host [(AT CONTACT NAME) contact-name] [CONNECT (TO) DECNET (HOST)] host [(AT OBJECT TYPE) object-number] [CONNECT (TO) PUP-ETHERNET (HOST)] host [(SOCKET) socket] [CONNECT (TO) INTERNET (HOST)] host [[(ON PORT) port] [CONNECT (TO) TTY (LINE NUMBER)] line-number Establish a connection to the specified host on the specified network using the specified contact identifier. Only networks that are actually connected to the local host are valid. The host specification depends upon the network; in general it must be a recognized host name. This command is not valid in talk mode. A host specification as a top-level command or a CONNECT command without a network specification assumes that a connection to that host on the "best network" is intended. "Best network" is a more or less arbitrary ordering usually based on network bandwidth. A Chaosnet host specification is any valid Chaosnet host name string. See the MIT Chaosnet documentation for more information. The contact name defaults to TELNET. A DECnet host specification is any DECnet node name. The object type defaults to 23. A Internet host specification is either an Internet domain format host name or a bracketed set of four octets as defined by the mail standards (e.g. [10.3.0.11]). The port specification consists of either one of the assembled in port names or two octets delimited by period; the default is TELNET (or 0.23). A Pup Ethernet host specification should be a valid Pup host specifier in conventional format. See the PARC Pup documentation for more information. The socket defaults to Telnet, and may be a socket name or number. CONTROL (CHARACTER) [quoted character | octet] Sends the control form of the quoted character, or the given octet as an ASCII code. This command is only valid in talk mode. [NO] DEBUG (PROTOCOL NEGOTIATIONS) [Meaningful for networks running DoD standard TELNET protocol only] Set or clear the flag controlling whether or not TELNET protocol negotiations should be logged on the terminal. A negotiation log is of the form *R*...protocol...* for a received protocol command or *S*...protocol...* for a protocol command sent by TELNET. This command is normally of interest only to wizards. [NO] ECHO (BY REMOTE HOST) [Networks running DoD standard TELNET protocol and TTY only] Set or clear the flag controlling whether or not TELNET expects the remote host to handle echoing of user typein. If remote echo is specified, the remote host must agree to the change, otherwise TELNET will revert back to local echo. In local echo mode, TELNET handles the echoing. Normally TELNET negotiates remote echo upon establishing the connection. This command is only valid in talk mode. ESCAPE (CHARACTER IS) {quoted-character | octal-number} Set the escape character from talk mode to the specified character. The default escape character is CTRL/^ (ASCII 036, control-caret). When this character is input from the terminal, TELNET will read a single command character as follows: Character Action ? Lists the command characters A Equivalent to the ATTN command B Equivalent to the BREAK command C Equivalent to the CLOSE command O Equivalent to the ABORT command P Equivalent to the PUSH command Q Equivalent to the QUIT command S Equivalent to the STATUS command T Toggle transparent mode X Enter extended command mode Neither the escape character nor the following command character are echoed. If the escape character is given as a command character, it is sent as a single character to the remote host (which is how you send that character!). It was a design goal of TELNET to allow any character (including the escape character) to be sent to the remote host without causing messing up of the transcript due to prompts, etc. Extended command mode (see also the EXTENDED command below) allows the user to have a more standard command parser at the expense of a prompt and echoed input on the typescript. Extended command mode is the only way to do certain functions (such as log file usage) while in talk mode. Extended command mode is similar to top-level, except that a different set of commands are valid in talk mode; some, such as ECHO, are meaningful only in talk mode. Each command notes whether or not it is valid in talk mode. When an extended command has been completed (or has failed with an error), TELNET returns to talk mode. EXIT (FROM TELNET) Return to the superior process (normally the EXEC) without closing the network connections. This is the graceful way out of TELNET once the connections have been closed. [NO] EXTENDED (COMMAND MODE AUTOMATICALLY WHEN ESCAPE CHARACTER TYPED) Set or clear the flag controlling whether or not TELNET will enter extended talk command mode when the escape character is typed immediately instead of going into talk command mode. The default is to go to talk command mode. Note that if EXTENDED mode is enabled there is no way to send the escape character to the remote host. HELP (IN USING TELNET) Type out a brief help text on how to use TELNET. [NO] LINE (EDITOR FOR LOCAL ECHO CONNECTIONS) Set or clear the flag controlling whether or not TELNET will use line buffering when communicating to the remote host. Line buffering only takes effect when echoing is being done by TELNET. When line buffering is enabled, the TOPS-20 editing characters (rubout, CTRL/R, CTRL/W, CTRL/U) will work since line buffering uses the system TEXTI% JSYS. No text is sent to the remote host until a carriage return or a line feed is typed. This command is useful for communicating with line-oriented systems such as Multics. LOG (FILE IS) log file name NO LOG (FILE) Declare a log file, which will contain a transcript of the user's session. A CLOSE command automatically closes the log file, which is reopened for append when another connection is opened. The log file name defaults to TELNET.LOG. TELNET defaults to not keeping a log file. [NO] NETWORK [more commands] This is a privileged command available only to operators and system programmers and is not documented further here. [NO] OPAQUE (MODE) Set or clear the flag controlling whether or not TELNET will use "opaque mode", ie, continue doing local terminal handling such as padding and keeping track of the cursor position, etc. In addition, certain typein characters may be affected by opaque mode; nulls are ignored and character conversion may occur. The default is NO OPAQUE, which specifies an image link between TELNET and the remote host with no local terminal handling. Opaque mode generally precludes being able to do things like use a display editor at the remote system, but it is sometimes necessary when using certain inferior terminals. Opaque mode does not change XON/XOFF handling; this is controlled by the PAGE command although opaque mode is required along with page mode to get automatic holding at end of screen. [NO] PAGE (MODE) Set or clear the flag controlling whether or not TELNET will enable local host XON/XOFF handling ("terminal page" mode). In page mode, CTRL/Q (XON) and CTRL/S (XOFF) are handled by the local TOPS-20 operating system and there is no way to send either of those characters to the remote system. Automatic holding at the end of the screen requires opaque mode as well, so TOPS-20 can know how many lines it has output. The default is NO PAGE, which specifies that CTRL/Q and CTRL/S are passed to the remote host in image mode. Page mode is sometimes necessary when XON/XOFF handling is required and the remote host does not or can not handle it. For example, old style DECnet connections do not allow TERMINAL PAGE at the remote host, and certain terminals (such as VT100's in smooth scroll mode) require faster XON/XOFF handling than can take place over a network. PUSH (COMMAND LEVEL) Run EXEC in an inferior process. The EXEC's POP command may be used to return to TELNET. This is useful for doing something temporarily at the local host while preserving the TELNET connection. TELNET disables SC%LOG capability in the inferior EXEC to protect the user against accidentally logging out with a connection still open. QUIT (OUT OF TELNET) This command returns the user to the EXEC without closing any open connection; e.g. the effect is similar to that of CTRL/C. EXIT is the preferred command to leave TELNET, as it closes any open connections. STATUS (OF TELNET CONNECTION) Report on the status of the TELNET connection, and send the protocol command to request the remote host to send a status message (ie, a reply to "are you there?"). Generally this takes the form of a job/system status message or at least the word YES. This command is only valid in talk mode. TAKE (COMMANDS FROM FILE) take file name Accept commands from the specified input file. At end of file revert to accepting commands from the terminal. TELNET does an implicit TAKE TELNET.CMD at startup. [NO] TRANSPARENT (MODE) [Networks running DoD standard TELNET protocol and TTY only] Set or clear the flag controlling whether or not TELNET will pass on the 200 bit (ie, the EDIT key) to the remote host. Normally TELNET suppresses the 200 bit on non-TTY connections. This command is useful in running remote display editors which use the 200 bit as a character modifier. This command is only valid in talk mode. TELNET Messages Occasionally an event occurs that TELNET wants the user to be aware of. Some of these messages indicate perfectly normal conditions and exist merely to confirm that it is doing what the user told it to do. Other messages indicate problems with the remote host or the network which aren't due to any error on the user's part. Connection closed The user gave a CLOSE command. TELNET is confirming that it has closed the connection. TELNET will either return to the top-level command parser or will exit, depending upon whether or not TELNET was invoked with a command-line argument. Connection closed by foreign host The remote host has closed the connection for reasons known to itself (and maybe the user) but not to TELNET. TELNET will take the same action as if the user gave a CLOSE command. Foreign host sent a subnegotiation The remote host is using the subnegotiation part of the TELNET protocol. Since TELNET does not allow subnegotiations, the host is violating protocol. Some garbage may follow this message. This is not expected to happen. ?Time out TELNET spent more than 30 seconds trying to do a single network output operation. TELNET assumes that the host at the other end is hung, and aborts the connection. Trying... The user gave a CONNECT command, and TELNET is attempting to open the connection. TELNET will report the result of the connection attempt either by stating "Open" (at which point you are talking to the remote host) or by giving one of a great many information messages saying why the connection couldn't be opened. Error Messages When an error condition happens such that TELNET can no longer continue the command the user instructed it to do, TELNET outputs one of the error messages listed below and generally aborts the command and any TAKE file in progress. Most of these errors are errors in the user's command line. ?Abnormal fork termination interrupt TELNET's network input process died involuntarily. Since it is supposed to check for all error conditions, this message is not expected to happen. If it does a wizard should be contacted. ?Can't continue It is not possible to continue TELNET after a fatal error. ?Invalid ASCII value The number specified for the escape character was not between 0 and 177 octal. ?Invalid port number ?Invalid socket number The number given was out of range for the named field. ?Log file error - ...more details... TELNET was unable to reopen the log file when opening the connection. The log file has been turned off, and the connection continues without it. ?Must have CONTROL-C capability to run TELNET The superior process which invoked TELNET has denied TELNET the SC%CTC capability, which is necessary for TELNET to be able to trap CTRL/C's. TELNET needs the capability to function properly. ?Not implemented with this protocol The command the user gave is meaningless on the connection in use, because the network protocol in use doesn't support that functionality. ?TAKE command in progress A command file run by the TAKE command tried to execute another TAKE command. TELNET doesn't support nested TAKE files. ?No such host name - ...more details... TELNET was expecting a host specification, but the input given could not be interpreted. Possibly a host name was misspelled. ?...message... A miscellaneous non-fatal JSYS error occured. This is usually a user error. ?...message..., ...instruction... at PC=...PC value... A horrible (and fatal) JSYS error occured. The PC printed is the location of the JSYS where the error occured. The user should contact a wizard to look into the problem. Sample User Session The following is a sample user session with TELNET, as actually taken on an ARPANET site (SU-SCORE). @TELNET TELNET>? command, one of the following: CONNECT DEBUG ESCAPE EXIT EXTENDED HELP LINE LOG NETWORK NO OPAQUE PAGE PUSH QUIT STATUS TAKE or host name TELNET>sierra Trying... Open Stanford Sierra, TOPS-20 Monitor 5.3(5000)-4 @sySTAT Wed 28-Dec-83 06:13:33 Up 13:39:49 0+5 Jobs Load av 0.03 0.33 0.32 Job Line Program User Foreign host 8* 145 SYSTAT Not logged in {Score} 1 DET SYSJB1 OPERATOR 2 106 OPR OPERATOR 3 107 MMAILR OPERATOR 4 110 INTSRV OPERATOR 5 111 LSRSPL OPERATOR @logo Killed Job 8, TTY 145, at 28-Dec-83 06:13:38 Used 0:00:00 in 0:00:07 Connection closed by foreign host TELNET>exIT (FROM TELNET) @