The ePipe/EasyServerII "Reverse Telnet" Facility for UNIX ========================================================= Introduction ------------ This document describes the svr_tty utility (a Reverse Telnet facility) that is available with both the ePipe and EasyServerII products. As the configuration of both the utility itself and the ePipe and EasyServerII devices is common, the term "Server" will be used to refer to both the ePipe and the EasyServerII. Where the configuration may differ detween the ePipe and EasyServerII devices, these differences will be noted. NOTE : To use svr_tty with the ePipe, the Direct Connection Services (DCS) Feature will need to be activated. The Server "reverse telnet" facility is a feature that allows UNIX applications to treat the serial ports on a Server unit as if they were serial ports on the local system. The Servers may be connected either via a LAN or a Wan to the Unix host. This provides a convenient method for using modems, printers and other serial devices connected to an Server port, as well as providing the ability to run dedicated applications on these ports. This document describes how the reverse telnet facility works, how to configure it, and how to acquire or build the pieces needed to implement it. Operating system dependencies are dealt with individually at the end of the document. The reverse telnet facility was previously named "remote port" or "hard TTY" and older documentation may still refer to it by this name. Theory of Operation ------------------- This section discusses the theory of the reverse telnet facility. An understanding of this is helpful but not mandatory. If you have trouble with this section you can skip ahead and follow the configuration "recipes". The reverse telnet facility is implemented by a UNIX application called "svr_tty" and the Telnet Listener capability of the Servers. A block diagram showing the various pieces and their relationships follows. +-------------+ | UNIX | | application | +-------------+ | | +---------------+--------+ | user supplied | slave | | device name | device | Pseudo |---------------+--------| TTY | master device | +------------------------+ | | +----------+ +---------------+ | svr_tty |------ TCP/IP ------| Server | +----------+ +---------------+ | | | | | | | | Applications talk to the serial ports on a Server via a UNIX pseudo-tty device. The actual transfer of data between the pseudo-tty device and a Server serial port is done by a svr_tty daemon process. svr_tty reads data from the master side of the pseudo-tty and passes it to the Server and vice versa. svr_tty uses a simple protocol to communicate with the serial ports on an Server unit via Telnet Listeners. Telnet listeners are processes that execute within the Server and transfer data between the network and the serial ports of the Server. Limitations ----------- The use of a UNIX pseudo-tty imposes some limitations, although these are not normally a problem for most applications. The same limitations occur in other situations where pseudo-ttys are used, e.g. a remote login connection using telnet or rlogin. The major difference between a real serial port and the pseudo-tty which provides a reverse telnet connection is that hardware-related characteristics such as baud rate, number of bits per character, hardware flow control, etc. cannot be set by the application program using the normal UNIX tty device API (ioctl). These characteristics must be configured in the Server using the facilities it provides (web interface, command line interface, configuration files, etc.) The reverse telnet facility is not available on units with firmware prior to version 4.219. If you have an old version of the firmware please contact your supplier or Stallion to arrange for an upgrade. Configuring a Telnet Listener for Reverse Telnet ------------------------------------------------ Each Server serial port that is to be configured for use with reverse telnet must be configured with a telnet listener. This section lists the commands required to configure a telnet listener but does not describe the commands in detail. For more information on these commands, see the documentation available on the Stallion Software and User Documention CD or the Stallion web site, www.stallion.com. The following examples show the commands required to configure telnet listeners for various devices. These commands are typed at the Server command line interface (you must be in privileged mode). The commands may also be entered using the web interface. Note that each telnet listener is identified by a TCP port number (2003 in the example below). We recommend the use of TCP port number 2001 for serial port 1, 2002 for port 2, etc. The following changes would be required to create a telnet listener on a Server. CHANGE TELNET LISTENER 2003 CONNECTIONS ENABLED CHANGE TELNET LISTENER 2003 RAW MODEM ENABLED CHANGE TELNET LISTENER 2003 NOTIFICATION DISABLED CHANGE TELNET LISTENER 2003 PORT 3 ENABLED CHANGE PORT 3 ACCESS REMOTE Note that the command: CHANGE TELNET LISTENER 2003 IDENTIFICATION "Pink laser printer" could be used to attach a comment to a telnet listener for administration purposes. As well as configuring telnet listeners you will also need to configure appropriate serial port characteristics for the connected devices. These include such parameters as baud rate, parity flow control. The autobaud feature should also be disabled. See the Server documentation for further details. For example, to configure the port for 38400 bps and hardware flow control, the following addtional commands would be required. CHANGE PORT 3 AUTOBAUD DISABLED SPEED 38400 CHANGE PORT 3 STOP BITS 1 CHANGE PORT 3 FLOW CONTROL CTS Configuring svr_tty - the original configuration file format ------------------------------------------------------------ As described above, a svr_tty daemon process must be used to make connection between pseudo-ttys and Server serial ports. This mapping is defined in a configuration file. The configuration file may contain one or more lines, each of which can be a: - blank line (a single newline character) - comment (line starting with '#') - port configuration entry A port configuration entry consists of a single line with three fields separated by white-space characters. These fields specify: - the name of a master pseudo-tty device - the IP address of an Server unit (hostname or numeric value) - a TCP port number The pseudo-tty device will be connected to the serial port specified by the combination of the name or IP address of a Server and TCP port number associated with a telnet listener configured on the Server. The exact form of the master pseudo-tty device name varies depending on the operating system. See the operating system specific notes below for details. Here is an example configuration file: # # R&D lab printer # ptyq2 lab_ts 2001 # # Support modems # ptyq3 192.168.80.17 2007 ptyq4 192.168.80.17 2008 This would connect pseudo-tty "/dev/ptyq2" to telnet listener 2001 (serial port 1 if our recommendation on port assignment for telnet listeners has been followed) on the "lab_ts" Server. Likewise "/dev/ptyq3" and "/dev/ptyq4" would be connected to serial ports 7 and 8 on the Server identified by the IP address 192.168.80.17 respectively. Note that applications should use the corresponding slave pseudo-tty devices to use the reverse telnet facility. The printer interface script for the R&D lab printer above would send data to "/dev/ttyq2", this being the corresponding slave device for the master pseudo-tty device "/dev/ptyq2". When selecting pseudo-tty devices to use in a configuration file, you should select devices that will not be in use when svr_tty is invoked. If svr_tty is started at boot time this is generally a simple process as there will normally be no devices in use at this time. Don't use the same pseudo-tty device in more than one configuration entry or more than one configuration file. See the section "Testing Pseudo-ttys" for some hints on finding available devices. Configuration files should be owned by root and should not be writeable by ordinary users, e.g. chmod 644 config_file. A single svr_tty daemon process can handle many individual connections but for performance reasons we recommend that the number is kept small. For slow or infrequently used devices up to 16 devices per daemon should be fine. For fast devices an upper limit of 4 devices is generally reasonable. Multiple daemon processes can be used to handle large numbers of devices, and the system overhead for each is small. On some systems you may find that the operating system will not allocate enough file descriptors to a process to allow more than 16 or so devices to be handled by a single daemon. For administrative purposes it is also suggested to allocate no more than one Server per svr_tty process. In the event that it is necessary to restart a svr_tty process, the impact is limited to one Server. Configuring svr_tty - the new configuration file format ------------------------------------------------------- On some operating systems, such as SVR4 based operating systems and AIX, it is possible for the user to supply device names rather than use the name of the master pseudo-tty device in the configuration file. NOTE : This feature requires Version 1.30 or later of svr_tty. In the example configuration file listed above, it is possible to replace the name of the master pseudo-tty device with a user defined name. For example, it might be desired to name the lab printer device as "labprinter" and the modems as "modem1" and "modem2". In this case the configuration file would appear as follows. # # R&D lab printer # labprinter lab_ts 2001 # # Support modems # modem1 192.168.80.17 2007 modem2 192.168.80.17 2008 In this case, when invoked svr_tty will read the configuration file, create the devices listed in the file and symbolically link these devices to the next available pseudo-tty devices. No changes to the telnet listener configuration is required when used with svr_tty in this fashion. For this feature to be available, the operating system must support clone devices, in particular, clone pseudo-tty devices. The clone pseudo-tty device may be a device a such as /dev/ptmx. Operating systems that support this feature include AIX Version 4 and SVR4 based operating systems such as UnixWare. svr_tty must also be invoked with the "-n" option. Setting up svr_tty - Invoking the Daemon ---------------------------------------- The svr_tty daemon can be invoked from a shell command line, which is useful for testing, or from a system startup file. It should not be invoked until after all TCP/IP initialisation has completed! svr_tty should be invoked with super-user privileges, i.e. with an effective UID of 0. When invoked, svr_tty automatically executes in the background, unless the -F option is used. svr_tty has the following command line options: svr_tty [-?hvdofmnkBF] [-t poll-time[,wait-time]] [-D debug-file] [-p link server port] [config-file] -h or -? displays the command line options -d output debug and/or trace information to stderr, usually the console. stderr can be re-directed to a file, but the -D option will be more usual in that case. Useful when executing svr_tty in foreground mode for debugging purposes. -D debug-file output debug and/or trace information to the specified file -v displays the version of svr_tty -o use the original configuration file format, that is the first field is a master pseudo-tty device. This is the default configuration file format. -n use the new configuration file format, that is the first field is the name of a device that svr_tty is to create in the /dev directory -f when this option is specified on the command line, the TCP connection between the Unix host and the Server is not created until an application opens the slave pseudo-tty device -m close the TCP connection between the Unix host and the Server when the application using the slave pseudo-tty device closes the slave device. This option is not supported on all operating systems, as not all operating systems signal the master device when the slave device is closed. -k sets the TCP Keepalive option on the socket when the connection between the Unix host and the Server is created. This allows TCP on the Unix to detect when the connection to the Server has been lost. TCP will then "clean up" the lost connection. -B execute svr_tty as a daemon. This is the default action of svr_tty. -F execute svr_tty in foreground mode. In this mode svr_tty does not disassociate itself from the controlling terminal. This mode would be used when debugging svr_tty. See the -d option also. -t poll-time[,wait-time] check the TCP connection between the Unix host and the Server every poll-time seconds, waiting wait-time seconds for a response. If the connection is deemed to have failed, try to restart the connection. -p link server port rather than use a configuration file, this option allows you to specify the device to create, the Server and the telnet listener TCP port number on the command line. This would normally be used in the initial configuration process or when debugging problems with the configuration. Here are some example command lines: svr_tty -D /tmp/svr_tty.log -t 300,2 - use the default configuration file /etc/svr_tty.conf, log any messages or error messages to /tmp/svr_tty.log. Test for failed connections every 5 minutes and wait up to 2 seconds for a response from the server. svr_tty /usr/config/svr1.conf - use a specific configuration file svr_tty -D /tmp/svr_tty.log - use the default configuration file and log errors and debug messages to /tmp/svr_tty.log Configuration files can be stored anywhere in the filesystem as long as the svr_tty startup command explicitly references the file. Also, the configuration files should not be placed on a filesystem that is not yet mounted when svr_tty is invoked. Why use the -t option? ---------------------- If the -t option is not specified svr_tty does not restart dropped network connections (a connection may fail due to a network error, server reboot, etc.) Restarting svr_tty is the only way to recover these connections. If -t is specified, then svr_tty will check all its network connections every poll-time seconds. Any connection found to be dead will be reopened as soon as possible (svr_tty will continue to retry at regular intervals if this can not be done immediately). wait-time determines how many seconds svr_tty will wait for a response before deciding that a connection has been dropped. If wait-time is not specified a short timeout suitable for most LAN connections is used (50ms). This would not be suitable for the vast majority of WAN connections with large latencies. A value larger than the highest expected latency should be specified to prevent live connections being reset. Troubleshooting --------------- There are a number of steps that can be taken to diagnose issues with a svr_tty installation. To verify the correct configuration of the Server . verify that the Server is accessible by using the ping command. A failure here indicates a fundamental networking issue, such as a faulty network cable, incorrect IP address, incorrect router configuration if the Server is accessible via a WAN, etc. . verify that it is possible to telnet to the Server itself. If the Server is reachable using the ping command, then a failure here most likely indicates an incorrect Server configuration, eg the following command may have been used to configure the server resulting in access not being allowed CHANGE PORT ALL ....... instead of CHANGE PORT 1-8 ....... or CHANGE PORT 1-16 ....... . verify that the telnet listener is configured correctly by telnet'ing to the telnet listener. if this fails, then the telnet listener or the associated port is not configured correctly. If problems are still occurring, then make sure that the svr_tty daemon is running. If svr_tty is running, then restarting svr_tty, logging output to the standard error device using the -d command line option with svr_tty executing in foreground mode may provide the answer. For longer term investigation, it may be more appropriate to use the -D file_name option with svr_tty running as a daemon. The most common problem is that svr_tty refuses to connect to one or more telnet listeners. This may occur because the telnet listener is not enabled or access to the port is not configured with access set to either "remote" or "dynamic". The Server has a number of commands that can be used to check the configuration and status of telnet listeners and serial ports, e.g.: show telnet listener all status show telnet listener all characteristics show/monitor port characteristics show/monitor port counters show/monitor port status Building or Retrieving a Copy of svr_tty ---------------------------------------- The easiest way to get a binary copy of svr_tty for your favourite operating system is to look in the Download area of the Stallion web site. http://www.stallion.com Alternatively, you can find the binaries on our anonymous FTP site, ftp://ftp.stallion.com, in the directories drivers/epipe/* or drivers/easyserver2/* If you do not have access to our site or we don't have a precompiled binary for your O/S, you can compile svr_tty from the source code. This is available from an Server unit itself, and the latest source code is always available via the Internet. To extract the source code from a server, see the online tutorial section "Unix Utility Programs" or point a Web browser at the pages built into the server and select "Files". Compilation instructions for various operating systems are given in the comments at the beginning of the svr_tty source code. For other operating systems you may need to experiment using the documented instructions as a guideline. Please contact the distributor from which you bought the product if you require any further assistance. The svr_tty binary is normally installed in /etc and should be executable by the super-user. Testing Pseudo-ttys ------------------- To find available pseudo-ttys, first use the "ls" command to find what pseudo-tty devices are available in the /dev directory (the O/S specific sections below describe the naming conventions). Pseudo-ttys are used for many purposes, but mostly for remote logins (telnet or rlogin). These can usually be seen with the "who" or "ps" command. Pseudo-ttys which appear to be free can then be tested by using the "dd" command on the master device, e.g.: dd if=/dev/ptyp5 If dd just "hangs" waiting for input then you've found an available working pty. dd: cannot open /dev/ptyp5: I/O error (error 5) means the pty is already in use. dd: cannot open /dev/pty1000: No such file or directory (error 2) means there is no device file of that name -- check you typed the name correctly. dd: cannot open /dev/ptyp32: No such device or address (error 6) means that the pty device file exists, but the kernel isn't configured to support it. Unfortunately there is considerable variation between pseudo-tty implementations on different operating systems, so this technique may not work in all cases. Using Reverse Telnet on AIX --------------------------- The precompiled binary of svr_tty was compiled and tested on AIX 4.1. Valid pseudo-tty master device names are: "ptyp[0-9a-f]", and the corresponding slave device names are: "/dev/ttyp[0-9a-f]". The daemon may be started from an entry in /etc/inittab, e.g.: ts:2:respawn:/etc/svr_tty >/tmp/svr_tty.log 2>&1 Alternatively, an /etc/rc script could be used. AIX also supports the new configuration file format. Using Reverse Telnet on BSDI UNIX --------------------------------- The precompiled binary of svr_tty was compiled and tested on BSDI v2.1. Valid pseudo-tty master device names are: "pty[pqrs][0-9a-f]", and the corresponding slave device names are: "/dev/tty[pqrs][0-9a-f]". The daemon may be started by placing a command to invoke it in the file "/etc/rc.local": /etc/svr_tty >/tmp/svr_tty.log 2>&1 Using Reverse Telnet on FreeBSD ------------------------------- The precompiled binary of svr_tty was compiled and tested on FreeBSD 2.1.5. Valid pseudo-tty master device names are: "pty[pqrs][0-9a-f]", and the corresponding slave device names are: "/dev/tty[pqrs][0-9a-f]". The daemon may be started by placing a command to invoke it in the file "/etc/rc.local": /etc/svr_tty >/tmp/svr_tty.log 2>&1 Using Reverse Telnet on HP/UX ----------------------------- The precompiled binary "svr_tty_hpux10" was compiled and tested on HP/UX 10.01. The binary "svr_tty_hpux9" was compiled on HP/UX V9. Valid pseudo-tty master device names are: "pty[pqr][0-9a-f]", and the corresponding slave device names are: "/dev/tty[pqr][0-9a-f]". There is also support for the "ptym/pty*" pseudo-tty master naming convention. The slave devices corresponding to these are called "/dev/pty/tty*". The daemon may be started from an entry in /etc/inittab, e.g.: ts1:34:respawn:/etc/svr_tty >/tmp/svr_tty.log1 2>&1 Using Reverse Telnet on Linux ----------------------------- The precompiled binary of svr_tty was compiled and tested on Linux v2.0.0 (ELF format with shared libraries). Valid pseudo-tty master device names are: "pty[pqrs][0-9a-f]", and the corresponding slave device names are: "/dev/tty[pqrs][0-9a-f]". The daemon may be started by placing a command to invoke it in the file "/etc/rc.d/rc.local": /etc/svr_tty >/tmp/svr_tty.log 2>&1 Using Reverse Telnet on SCO UNIX -------------------------------- The precompiled binary of svr_tty was compiled and tested on SCO Unix 3.4v4.2, and should run on all versions of SCO UNIX. Valid pseudo-tty master device names are: ptyp0, ptyp1, ..., and the corresponding slave device names are: /dev/ttyp0, /dev/ttyp1, ... The daemon may be started from an entry in /etc/inittab, e.g.: ts:2:respawn:/etc/svr_tty >/tmp/svr_tty.log 2>&1 Alternatively, an /etc/rc2.d script could be used. Using Reverse Telnet on Solaris ------------------------------- The precompiled binaries of svr_tty were compiled and tested on Solaris 2.4 (Intel x86) and Solaris 2.5.1 (SPARC). Valid master pseudo-tty names are: pts/0, pts/1, ... and the corresponding slave device names are: /dev/pts/0, /dev/pts/1, ... The daemon may be started from an entry in /etc/inittab, e.g.: ts:23:respawn:/etc/svr_tty >/tmp/svr_tty.log 2>&1 Alternatively, an /etc/rc2.d script could be used. Solaris also supports the new configuration file format. Using Reverse Telnet on SunOS ----------------------------- The precompiled binary of svr_tty was compiled and tested on SunOS 4.1.4. Valid pseudo-tty master device names are: "pty[pqrs][0-9a-f]", and the corresponding slave device names are: "/dev/tty[pqrs][0-9a-f]". The daemon may be started by placing a command to invoke it in the file "/etc/rc.local": /etc/svr_tty >/tmp/svr_tty.log 2>&1 Using Reverse Telnet on UnixWare -------------------------------- The precompiled binaries of svr_tty were compiled and tested on UnixWare 2.0. Valid pseudo-tty names are: pts/0, pts/1, ... and the corresponding slave device names are: /dev/pts000, /dev/pts001, ... The daemon may be started from an entry in /etc/inittab, e.g.: ts:23:respawn:/etc/svr_tty >/tmp/svr_tty.log 2>&1 Alternatively, an /etc/rc2.d script could be used. UnixWare also supports the new configuration file format. Using Reverse Telnet on Some Other Unix --------------------------------------- The simplest way to implement the reverse telnet facility on a new operating system is to start with the compilation flags and configuration information for a similar system, and modify as necessary. The main differences between operating systems occurs in the pseudo-tty implementation. There are two major flavours: Berkeley (BSD) and System V Release 4. Berkeley-based UNIX implementations normally use the /dev/pty[pqrs]* naming convention, and SVR4-based implementations use /dev/pts/*. If your system is Berkeley-based, start with one of the BSD ports (e.g. BSDI, FreeBSD). If your system is SVR4-based, then the UnixWare port would be a good start. You will need to: - find appropriate compilation flags and libraries to build svr_tty (use -DSVR4 for SVR4 pseudo-tty names, otherwise you will get BSD conventions) - use the appropriate pseudo-tty naming conventions in the svr_tty configuration file - find an appropriate place to invoke the svr_tty daemon on system startup. svr_tty should not be invoked until after any TCP/IP initialisation has been performed, and should be invoked with super-user privileges. Notes ----- (1) The latest version of the source code for svr_tty and svr_print can always be found in the download area of the Stallion web site. Due to the time required to compile the binaries on all the supported operating systems, the binary in operating system directory may not be the latest version. We will, of course, endeavour to keep the binaries up to date, but this may not always be possible.