Copyright (c) 1992, Xylogics, Inc. ALL RIGHTS RESERVED. ALL RIGHTS RESERVED. Licensed Material - Property of Xylogics, Inc. This software is made available solely pursuant to the terms of a software license agreement which governs its use. Unauthorized duplication, distribution or sale are strictly prohibited. RTELNET (Reverse Telnet) User's Guide DESCRIPTION Rtelnet is a modified version of the Berkeley telnetd program. It will create a pseudo-tty (pty) device on the host that is connected via TELNET or raw TCP to an Annex serial port. This allows UNIX programs such as tip(1C) and uucp(1C) to access serial devices attached to Annex ports. Rtelnet works like a telnet daemon program (telnetd) except in a reverse fashion; instead of accepting telnet connections from other network machines, rtelnet makes telnet connections to Annexes. Rtelnet creates a new file-like device (usually in /dev) that programs can open and use like a normal "/dev/tty" terminal. COMMAND LINE ARGUMENTS Usage: rtelnet [-abcdfhkmnoprstCDFOPRTV] [-lfile] [-uuser] [-Mmode] /dev/ Where: -a Use alternate pty banks. This option selects use of BSD ptys rather than System V ptys, where applicable. -b Use telnet binary mode -- useful for terminal connections. This option tells rtelnet to negotiate TELNET BINARY mode, and to not translate CR/LF sequences. CR will be sent as CR/NUL and translated back to CR by the Annex with this option enabled. -c Default to CBREAK mode on the pty -- avoid cooked line breaks. Use of this option requires that the slave pty be kept open by rtelnet on System V compliant machines. See discussion of pty modes below. -d Turn on socket-level debugging. This just sets the SO_DEBUG flag (or equivalent) on the created network connection -- the actual operation of this option depends on the underlying operating system. -f Open network connection when slave pty is opened. This option causes rtelnet to wait for the pty to open before it attempts to create the connection to the Annex. This option is incompatible with any option that would keep the pty open. -h Use 'na reset' to hang up port when slave pty is closed. Since this option is rather primitive, its use is discouraged. It requires that the Annex either have no "annex password" set, or "annex enable_security" set to "N" -- since there is no way to enter the required password. -k Periodically retry network connection. This option tests the connection to the Annex by attempting to reopen the same port every 20 seconds, when the connection is quiet. If this new connection succeeds, then the old connection must have become disconnected -- presumably by a reboot of the Annex -- and a new one is necessary. This is useful when the traffic is primarily from the Annex to the host and SO_KEEPALIVE is unimplemented, since writes from the host to the Annex will be able to detect a failed connection. -lfile Append log output to given file name. This option opens the requested file in append mode so that all error and debugging output is placed here once command line parsing is complete. (This may not be useful if debugging.sys is used -- see below.) -m Close network connection when pty is closed. This can be used to cause a dial-out modem to hang up when a program like tip exits. -n Never open slave side of pty. This option will prohibit some systems from setting up default I/O modes, but is much cleaner. -o Hold slave side of pty open at all times. This is a useful option when detecting pty open/close isn't necessary. Since closing the slave pty causes the master pty to close (on most systems), there is a small timing window where, if the slave pty is closed and then rapidly reopened, the second open will fail because the rtelnet process hasn't had a chance to close and reopen the master pty. This most often occurs in scripts where one might use: echo "Some text" > /dev/mypty echo "Some more text" > /dev/mypty The second "echo" command may fail because the shell will open and close the pty too rapidly. This option will keep the slave open at all times so that the master does not need to be recycled. -p Give process ID of child on standard output. This is useful for logging the PIDs of all the rtelnets started on a system so that they can be removed quickly. For example: rtelnet -pt myannex 1 /dev/port1 > rtelnetlist rtelnet -pt myannex 2 /dev/port2 >> rtelnetlist Now typing "kill `cat rtelnetlist`" will cleanly terminate both connections. -r Overwrite if it exists, rather than aborting. This option checks that the specified device is not a data file or a directory, and then removes it if necessary. -s Use a symbolic link instead of a hard link for the slave. This option allows you to place the slave pty anywhere in your file system. If this option isn't specified, then a hard link is created by default, and hard links cannot normally span across mounted devices. -t Use a transparent TCP connection, rather than telnet protocol. (If used with -f option, the pty will not default to RAW mode.) -uuser Change UID to before creating pty. This option is useful for ptys that will be used with cu or tip on System V machines. In this case, you should set "-uuucp" to get the pty owner set to uucp. If this option is set on a System V machine without the -a option, and autopush is implemented on that machine, then this option will cause rtelnet to fork into two copies -- one remaining as root, the other as the given UID. This is done because autopush information can be set only by root. -C Don't try to fix cooked-mode pty problems with LF insertion. See discussion of ptys below. -D Enable debugging mode (more D's for higher levels). See below. -F Force rtelnet to fork into background, even in debug mode. This is usually used with the -l option (above) when doing long-term testing. -Mmode Set default pty file mode to , given in octal. The default file mode is 0666. Use this option to set another mode. -O Disable out-of-band telnet data (for pre-R7.0 Annexes). For compatibility with older Annex operational code, the TELNET IAC DM signal, which is used to implement the output flush IOCTL, can be disabled. The telnetd process on older Annexes did not implement out-of-band signaling, and it would see the IAC DM (hex FF F2) characters as data. (A symptom of this problem might be the appearance of mysterious r's in the serial data stream -- many devices will strip the eighth bit, resulting in 7F 72, which is DEL r in ASCII.) -P Interpret the port number as a TCP port (1-65535 or name). This can be used to establish a slave pty that links to the Annex Port Server (port 23), the VCLI (port 5000) and to rotaries in the 6000-range. -R Rename the slave pty rather than linking to it. This is a dangerous option, and should be used only if it is absolutely necessary to have a single file extant with the slave's combination of major/minor numbers. -T Truncate (rather than break) lines that would choke pty. See below for pty bug discussion. -V Display version information on standard output and exit. This information is useful for Xylogics technical support so that they can precisely identify the version of software you are using. - is the Inet address or hostname of the Annex - is the Annex port number or TCP port number or TCP service name (see -P flag above). /dev/ - is the linked file name to be created. EXAMPLE You have a dial-out modem attached to port 15 of an Annex named "modem-annex". You would like users on a SUN workstation to be able to use the modem via 'tip'. 1. Configure Annex port 15 using "na" or local CLI admin to "control_lines: modem_control". 2. Add an entry to the "/etc/rc" script to create the tip pseudo-device whenever the workstation is booted. Entry would be: rtelnet -rm modem-annex 15 /dev/modem1 3. Create new system definition in "/etc/remote" specifying "/dev/modem1" as the tip (dv) device. For example: dialer|generic dial-out: \ :dv=/dev/modem1:cm=^M^JATe1^M^J:at=hayes:du: PTY MODES There are three basic modes used with the pseudo-terminal device -- RAW, CBREAK and COOKED. RAW mode is the default with the -t switch, unless -n is specified. In RAW mode, all data is passed through the pty unchanged. CBREAK mode can be specified as the default with the -c switch. This is a half-RAW mode in which the interrupt and flow control characters still work, but the line-entry characters are disabled and the new-line character has no special meaning. In COOKED mode, the line does normal tty line editing (erase character / word / line, et cetera). This mode has many bugs that the code attempts to work around. The worst problem with this mode is that there is a limit to the number of characters that may be written to the master pty by rtelnet between new-line characters. If more than some arbitrary number are written (134 on Encore umax, 255 on Sequent's DYNIX), then the pty will simply lock up. Therefore, these lines must either be broken with a new-line character (the default), or truncated at 134 characters (using the -T switch). DEBUGGING The debugging module "debugging.c" receives all of the output possible from the operation of the rtelnet code. This file is linked to one of the following: debugging.novf - for systems that are missing the v[fs]printf library routines. debugging.vf - for systems with a K&R C compiler and the v[fs]printf library routines. This is usually the default module. debugging.ansi - for systems with an ANSI C compliant compiler. debugging.sys - for sending output to syslog(3), rather than a log file. In the first three cases, each line of the output is formatted as follows: TYPE:pid:yyyymmddhhmmss: Where "TYPE" is one of: INIT - Entry or exit message. INFO - Informational message (from debugging code). WARN - Warning message. ERR - Error message. FATL - Fatal error message -- rtelnet aborted. These tags indicate the severity and content of the message -- they are not necessarily tied to the debug level flag. (Although "ERR " and "FATL" messages are usually sent out at debug level zero, i.e. always.) Using the -D switch, one may specify the debug level on start-up. This number filters the output sent to the log file -- the higher the level, the more verbose the output that is sent to the file. Setting level 2, for example, is accomplished by specifying '-DD'. The levels and what they show are roughly defined as: 0 - Unexpected system errors and fatal errors only. 1 - Exceptional conditions and entry / exit. 2 - I/O statistics and verbose TELNET protocol data. 3 - Flow control upcalls and system library call data. 4 - I/O selection and testing verification. 5 - Raw I/O dump (can be used to reconstruct a session). While rtelnet is running, you may change these levels by issuing a SIGUSR1 to increase the debug level, or SIGURG2 to set it back to zero. For example, if the pid of the rtelnet process is 9654: kill -USR2 9654 This would disable debugging on that copy of rtelnet without aborting any current data transfer. If operating system routines write to standard error (descriptor 2), then this output will pass directly into the output file without the debug line headers, except in the case of debugging.sys. This has not been observed to be a problem. NOTES Turning off debug with "#define NO_DEBUG" in rtelnet.h saves about 7K bytes of storage per image. It also disables the -dDF command line switches. If -r is specified, the linked file may change from one slave pty to another if an error occurs while reopening the master after the slave closes. Otherwise, without this flag, only one pty pair will ever be used, and an error will cause an exit, since rtelnet will be unable to remove and reassign the link. The document INTERN describes the internal procedure interfaces. This document should be consulted before attempting to port any of the "machdep.c" modules to a new system. Original Author: Unknown Created on: Unknown Revision Control Information: $Id: README 1.1 Mon, 03 Mar 2003 12:07:03 +1100 abo $ This file created by RCS from $Source: newrtelnet/README $ Revision History: $Log: README,v $ Revision 1.3 1993/02/04 17:08:19 carlson Added -a, -u and -M flags. Revision 1.2 92/08/13 17:13:50 carlson Added -C and -R flags. Revision 1.1 92/08/05 15:40:22 carlson Initial revision This file is currently under revision by: $Locker: $