Documentation

Netty is a utility for AIX 3.2, 4.1, 4.2, 4.3 and 5.1 that allows printers, modems, and terminals attached to network terminal servers to behave like locally attached devices. Netty creates links in /dev for the network attached devices which can be accessed directly by existing software (cu and ate for modem dial-out, AIX local print queues, and so forth).

Netty functions by creating a pseudo-terminal (pty) which connects via TCP/IP to a specified TCP port number on your network terminal server. A link is then made from a user-specified device name to the pseudo-terminal. The pseudo-terminal behaves for the most part as any tty on the RS/6000. Programs that open the pseudo-terminal can perform all tty operations and calls for the device. Some of the calls are accepted and ignored for obvious reasons, such as a call to set the baud rate of a pseudo-terminal makes no sense as the device being communicated with is actually network attached. Suitability to a particular task may vary. It is advised that netty be evaluated thoroughly for any given environment.

Netty consists of several files archived together in a single tar file. You may receive this tar file on a floppy diskette, or via modem or ftp. If you receive the software on diskette, simply extract the file from the diskette as follows: tar -xvf /dev/fd0 If you received the files via another means such as from our web site, the tar file will be stored on your system in the location you have placed it during retrieval. For example, if the file was downloaded into your /tmp filesystem from our web site and the file is named netty.tar, you would extract the file as follows: tar -xvf /tmp/netty.tar In either event, the files are placed into the appropriate destination location by full path name. The files extracted from the tar are explained below: /usr/lpp/netty/bin/netty The executable netty utility. /usr/lpp/netty/data/netty.config Netty may be given the filename of a datafile containing a list of hostnames, TCP ports, and entries in /dev to create at startup. This file is a sample of such a configuration. /usr/lpp/netty/netty.readme The newest documentation for netty. If you are installing a 30-day evaluation copy of netty, remember that if you don't register the software then thirty days from the time you first use the software, it will cease to function by simply exitting with a warning message when the utility is started.

1) STARTING NETTY WITHOUT A CONFIGURATION FILE To start netty from the command-line without a configuration file, netty will need to know several pieces of information including the hostname or IP address to connect to, the TCP port number or service name that it is to connec to, the name of the link in /dev to create. Several additional options include an optional logfile, a level of diagnostic output to place into the logfile, an optional time-out value or whether or not AIX's tty locking mechanism should be checked for. Suppose you wish to connect to a terminal server which has the hostname "termserv". Suppose your terminal server documentation indicates that if you connect to it on TCP port 2000 + n, you will be communicating with the device attached to port n of that server. You have a modem attached to the terminal server port 5 which you wish netty to refer to this as /dev/ntty0. Then, you could run the command: /usr/lpp/netty/bin/netty -h termserv -p 2005 -f /dev/ntty0 -h hostname The hostname or IP address of the network terminal server -p port The TCP port number the server listens on for incoming data -f linkfile The quot&;devicequot&; to create in /dev by which other programs will refer to the network terminal. Note the command will start in the foreground and you will not return to a shell prompt. If you hit ctrl-c, then netty will exit. If you want netty to run in the background, you may add a -b flag to background netty: /usr/lpp/netty/bin/netty -h termserv -p 2005 -f /dev/ntty0 -b -b Backgrounds the process that communicates with the terminal server. If you are experiencing difficulties with netty or want to use its logging ability to see what is going on, two additional options you may wish to use are -l and -d. -l is used to specify the name of a logfile where netty will output information about its operation, and -d is the debugging level, the amount of detail you want netty to put into the logging. The -d detail levels vary from 0 to 5, with higher numbers indicating greater detail. /usr/lpp/netty/bin/netty -h termserv -p 2005 -f /dev/ntty0 -l /tmp/log -d5 -d Controls amount of diagnostic information written to the -l logfile. Higher values indicate more output. Valid values are 0 - 5. will give you the most detailed logging information. This is useful for troubleshooting, but leaving detailed debugging on at all times will increase the amount of work netty has to do, lowering performance. When netty is started, it creates a pseudo-terminal (pty), associates it with a port on a terminal server, and then creates a symbolic link from the name specified with the -f parameter to the pseudo-terminal as the true pseudo-terminal name is assigned dynamically by AIX and therefore cannot be relied on the always be the same name for the same device. The facility of the link ensures a given device is always accessable by a constant name. Your applications may open this linkfile and treat it as though it were a regular tty. Applications can read, write, and perform ioctl operations on the link. Please note that netty cannot tell when your application has opened or closed the link file. Therefore, if you run a program such as cu to dial-out on the /dev/ntty0 device created in the above example, your dial-out will work fine, but if you do not hang up the connection before exitting cu, netty will not (immediately) know to tell the terminal server to hang up the modem. Netty provides two mutually exclusive mechanisms you can use to deal with this limitation: 1) -y Tells netty to check for AIX tty locks (/etc/locks/LCK..ntty0 in the case of the above example). If such a lock file was created by a program (for example cu) but the lock file is now gone, then the connection to the terminal server is broken and re-established by netty which should cause most terminal servers to "hang up" on the terminal attached to the given port. Please note that AIX utilities such as cu and ate make use of this tty locking facility, but other applications not included with AIX may never create such a lock at all. 2) -t# Provides netty with an inactivity time-out specified in minutes. It the specified number of minutes go by without data coming in from or out to a device, the connection to that device is broken and reestablished. This may also be useful to keep outbound modems from being accidently left connected to remote systems. Remember, at most one of these two flags can be specified.

2) CREATING A CONFIGURATION FILE FOR NETTY If you are starting netty to create many devices which refer to network printers, terminals, and modems, then it may be more convenient to invoke netty, passing it the filename of a configuration file that informs netty of which connections to make and how to name these connections. A netty configuration file entry consists of a hostname, a TCP port number on that hostname, a link to create that refers to that device, and optionally an idle timeout period value. Blank lines or lines which begin with '#' in the first column are ignored. For example, your config file may contain: #Hostname service device timeout #====================================================== termserv 2005 /dev/nty1 termserv 2006 /dev/nty2 server2 1234 /dev/nty3 10 server2 1235 /dev/mymodem Note that the order of the fields and number of fields on each line is important. Line-end comments are not allowed. If you invoke netty to act on the configuration file above: /usr/lpp/netty/bin/netty -c filename Netty will start 4 additional netty processes (the parent process and one child process to handle each connection). Killing the parent process will kill all four connections. If you prefer to have individual control over killing each session: /usr/lpp/netty/bin/netty -c filename -b Four child processes will be created, one to handle each connection. The parent process will then exit, orphaning each child process and making it a child of init. Each process can then be controlled individually. SUGGESTION: Though the naming conventions for the link files to create in /dev are entirely under your control, it is advised your naming convention does not conflict with a device AIX could create (such as lp## or tty##). It is also advisable to use a common naming convention for all devices, such as /dev/ntty##. This way if you want to kill all netty processes on the system root can: fuser -k /dev/ntty* As with starting netty without a config file, several command-line options can be used with netty: -l logfilename Specifies where to put logging output for ALL connections started by this instance of netty. To have different logfiles for different groups of network connections, they will have to be started from different config files, or started individually without a config file. -t Minutes After this number of minutes of inactivity on a given device, the TCP connection to the terminal server is broken and reestablished. The primary goal is to prevent modems on terminal servers to stay connected for long periods of time while not in use. If a config file entry specifies a timeout value, that time-out value will override the command-line timeout value for that individual connection. -t and -y are mutually exclusive options. -y Breaks and reestablishes the connection to a port on the terminal server if some process on AIX has created and then later removed the /etc/locks lockfile on a netty link device. -y and -t are mutually exclusive options.

V USING NETTY Once netty has been started the link device can be used as any other tty on the system, with the exception that an application closing the link device will not notify netty the device has been closed. Also, keep in mind that certain operations an application such as cu or ate can perform on a tty will be accepted, but ignored by netty. Operations such as setting the baud rate for example, do not make sense for a TCP/IP connection between AIX and a terminal server. Control over attributes such as baud rate of a serial port on a terminal server must be configured on the terminal server. If you are having problems setting up netty, there is no better way to troubleshoot than to have netty log what it is doing (-l logfile) in great detail (-d4 or -d5). Other helpful hints =================== If you've configured netty to connect to your terminal server on a given port, but your log shows "connection refused" repeatedly - the terminal server is not accepting connection requests. This could indicate either the TCP port number netty is trying to connect to is not correct for your terminal server, that the terminal server is not configured correctly, or most frequently - the device on the terminal server port is not accessable and therefore the server will not accept connections to communicate with a serial port it cannot access. There are several services on your RS/6000 you can use to test netty with to take a terminal server out of the picture entirely. For example: netty -h localhost -p echo -l /tmp/log -d5 -f /dev/mytty -b Add an entry into /etc/uucp/Devices: Direct mytty - 9600 direct cu -dml mytty You have used cu to connect to /dev/mytty which is a connection to localhost (your loopback TCP/IP interface) on port "echo" (see /etc/services). The echo service simply echoes back anything you send to it. Another example: netty -h localhost -p discard -l /tmp/log -f /dev/test -b lptest > /dev/test The output of the lptest command is sent through netty to the host "localhost" to the "discard" port (see /etc/services) which accepts what is sent to it and discards it.

LAIX Software Consulting (800) 558-LAIX PO Box 1001 Derby, KS 67037-1001 laixsoft@flash.net http://www.flash.net/~laixsoft Terms and licensing information for Netty for AIX Important: Read this before using the product. Acceptance: Use of this product indicates acceptance of the licensing terms outlined below: Rights: The software contained herein is subject to a "site-wide" licensing agreement. Purchase of this product constitutes the owner's right to copy and to use the product on any system within the purchaser's company or organization regardless of location, but not to distribute the product outside of that organization. The product may not be transferred in possession to another company or organization. You may not sub-license or lease this product to another company or organization. The product may be modified or customized by the owner, or used by the owner in a manner other than that described in the documentation. The registered version of this software in its original or in a modified state, may not be transferred, sold, or used in whole or in part outside of the purchasing organization or company. Diskettes labeled with "30-day evaluation copy" which actually contain the 30-day evaluation version of this software may be freely distributed.

The software is included under a limited warranty. LAIX Software Consulting warrants for a period of ninety (90) days from the date of purchase that the diskette on which the software is recorded and the software is free of defects and will function substantially as documented in the enclosed documentation.

LAIX Software Consulting assumes no liability for damages, loss of profit, loss of data or information of any kind or for consequential, special, indirect, incidental, punitive, or other damages caused by the use of this product. Should the owner find that the product does not function as described in the documentation, the product may be returned within a period of ninety (90) days of purchase for a full refund of the purchase price. Upon request of a refund, the purchasers agrees to destroy or return all copies of the software in their company or organization's possession.

Technical assistance with the installation, configuration, and usage of the enclosed software shall be free of charge for a period of thirty (30) days from the date of purchase. Requests for technical assistance may be submitted by telephone or fax to (800) 558-LAIX or by e-mail to laixsoft@flash.net. No response time criteria is guaranteed but LAIX Software Consulting will do its best to assist in a timely fashion. Support for this product may be withdrawn at any time after 30 days from the date of purchase.