Release Notes PN 93000512_C / 93000572_B Digi RealPort Device Driver Version 3.8.16.0 AIX 5.X and AIX 6.x 32bit and 64 bit Software Package PN 40001927_D / 40002500_C 07/30/2008 CONTENTS Section Description 1 Introduction 2 Supported Products 3 Enhancements 4 Bug Fixes 5 Known Limitations 6 PortServer Setup 7 Driver Installation 8 Device Configuration 9 stty-ncxa program 10 Transparent Printing 11 Error Logging 12 History 1. INTRODUCTION The Digi AIX RealPort (ncxa) driver makes the ports on Digi Ethernet-based Serial Products appear as though they are local AIX tty devices directly attached to the computer. When the AIX system boots, one ncxd daemon is spawned for each serial unit. Each daemon makes a single TCP/IP connection to its associated unit and sends all asynchronous serial data on this single connection. The daemon accesses the RealPort driver a through special parent adapter device set up by "smit". On most systems smit will assign /dev/sa2 for the first unit, /dev/sa3 for the second unit and so on. This is a privileged, exclusive access device used only by the daemon. The ports on Ethernet-based Serial Products can be accessed any time they are configured for RealPort operations and are not otherwise in use. The RealPort Service requires the TCP/IP driver to be installed and properly configured. This RealPort package includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). 2. SUPPORTED PRODUCTS Digi Connect Family Digi EtherLite Family Digi Flex Family Digi One Family Digi CM Family Digi PortServer Family Digi PortServer II Family Digi PortServer TS Family Digi PortServer TS MEI Family Digi PortServer TS W MEI Family Digi PortServer TS M MEI Family Digi PortServer TS H MEI Family Digi PortServer TS P MEI Family IBM LAN Attached RAN 16 3. ENHANCEMENTS Added support for AIX 6.1 Added new ncxd daemon option called "network timeout". This value is in seconds. If this value is set to a non-zero value the driver will consider the value entered as an idle period in seconds. When the idle period is detected, it will proceed as though the network connection has died, it will abort the connection, and attempt to reconnect. NOTE: It is HIGHLY recommended to set this value to 0. Only under certain circumstances (such as, unstable WAN links) should this be used. In which case, it is also HIGHLY recommended to not set it below 120 seconds. Added support for specifying /dev/random or /dev/urandom when using encrypted RealPort. /dev/random is more secure, and should be used by default. 4. BUG FIXES Fixed very rare panic issue that could occur under high loads on SMP systems with many CPUs. Fixed problem restarting ncxd daemon when making a change to the device setup in SMIT. Fixed problem with PPP not receiving DCD drop notifications. Fixed problem on system bootup with Encrypted RealPort. 5. KNOWN LIMITATIONS If a unit loses power it may be necessary to wait for up to 2 minutes before communication is re-established with that unit. Power Management does NOT work with RealPort. If running RealPort, AIX's Power Management must be unconfigured. If not unconfigured, the RealPort driver will disable Power Management. You cannot define an EtherLite unit as both an EtherLite (stsdd) device and a PortServer (ncxadd) device. The EtherLite devices may require a firmware change to work with this driver. EtherLite RS-422 and RS-485 ports should always add CLOCAL to the run and login modes when defining ports. Specify RS-422 for EL2 RS-485 ports. The OpenSSL software requires an external Random Number Generator. AIX 5.2 and higher includes this software as part of the base OS. If you have AIX 5.2, you can skip the below steps. On AIX 5.0 or 5.1, you must install PRNGD. IBM has this package prepared for AIX 5.0 and 5.1 on their ftp site. 1) Install the "RPM" package manager first from: ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/INSTALLP/ppc/rpm.rte 2) Install the "PRNGD" RPM package from: ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/prngd/prngd-0.9.23-3.aix4.3.ppc.rpm NOTE: Both of these package links were correct at time of driver release. In case they are changed at some time in the future, you can find any updated links from this web page: http://www-1.ibm.com/servers/aix/products/aixos/linux/download.html Driver support for RealPort with encryption is only supported for Digi products that also include support for RealPort with encryption. Not all Digi products support encryption. Please check your Digi product's firmware documentation for more information. 6. PORTSERVER SETUP The Digi PortServers are full featured terminal and communication servers whose configuration is detailed in the PortServer Manual. We note here the minimum needed for RealPort operation. First you must login as root on the PortServer. You can connect a 9600 baud 8N1 terminal to port 1, or (if you obtained an IP address through RARP or BOOTP) you can telnet to the box. The factory default root password is "dbps". Basic IP parameters must be set up before the PortServer will operate on the network. If you have not done this with RARP, BOOTP, or DHCP (PortServer III only), you must do it from the command line. Substitute your own IP address, net mask and (optionally) gateway address into the following PortServer command: set config ip=192.168.0.1 submask=255.255.255.0 gateway=192.168.0.254 The RealPort driver works best if the PortServer configuration for the ports is set to printers rather than as terminals. It works VERY POORLY if the devices are configured as terminals, for example. The following command sets up ports 1-16 as device type prn (printer). set port range=1-16 dev=prn If 8-pin RJ-45 plugs are used in the PortServer, the altpin option should be selected to make DCD available on one of the inner pins. The following command sets altpin on 16 ports. set flow range=1-16 altpin=on You can check the current configuration with: set config set flow range=1-16 set port range=1-16 7. DRIVER INSTALLATION You should have received a file named "realport.installp" or "40001927.bin" with this file. We will refer to this file as {filename} below. Assuming you copied this file {filename} to your /tmp directory, you can install the driver from the command line with: installp -ad /tmp/{filename} all You may also install with "smit", using the following procedure: Select "Software Installation and Maintenance" Select "Install and Update Software" Select "Install/Update Selectable Software (Custom Install)" Select "Install/Update from All Available Software" When smit asks you for the "INPUT device / directory for software", enter "/tmp/{filename}", and hit ENTER. Then for "SOFTWARE to install" enter "all" and hit ENTER twice. 8. DEVICE CONFIGURATION Before you can use the devices on your unit, you must first configure each PortServer, and then configure each port on the unit. This is easiest to do with smit. Configure each unit as follows: Select "Devices" Select "Digi Device and Terminal Servers" Select "Add a Digi Device or Terminal Server" Select the type of unit you have. Enter the "INTERNET ADDRESS" of your unit. If the network connection between you AIX system and the unit includes a WAN Link slower than 1 MBit, enter the bits-per-second "WAN Link Speed" in the field provided. This parameter is not needed if your AIX system connects to the unit over a high-speed LAN. If your Digi RealPort product supports RealPort with encryption, and you would like the session to be encrypted, change the default of "Encrypt RealPort session" from "never" to "always". Hit Enter to complete configuration. Configure each TTY as follows: Select "Devices" Select "TTY" Select "Add a TTY" Select "tty rs232 Asynchronous Terminals" Select a Digi Parent Adapter. Enter the desired "Port number". Modify other TTY parameters as desired. Hit Enter to complete configuration. Configure each printer as follows: Select "Printer/Plotter" Select "Printer/Plotter Devices" Select "Add a Printer/Plotter" Select "osp Other serial printer" Select "rs232" Select a Digi Parent Adapter. Enter the desired "Port number". Modify other printer/plotter parameters as desired. Hit Enter to complete configuration. 9. STTY-NCXA PROGRAM The stty-ncxa program is a Digi-special version of stty that allows you to access Digi extensions to standard AIX ports. This program is installed as: /usr/lbin/tty/stty-ncxa The RealPort driver differs from the documentation as follows: altpin The altpin option is set in the unit, and may not be changed from AIX. Altpin settings are configured on the unit itself. See "PORTSERVER SETUP" for more details. hupcl This option is ineffective, since carrier is always dropped by the unit when a port is closed. The /usr/lbin/tty/stty-ncxa program's fastbaud option changes the baud rate table to be a higher range of baud rates for users that need baud rates abover termios's limit of 38400. The fastbaud table of substitute baud rates are: 0 - 0 50 - 57600 75 - 76800 110 - 115200 134 - 131657 150 - 153600 200 - 230400 300 - 460800 600 - 921600 1200 - N/A 1800 - N/A 2400 - 2400 4800 - 4800 9600 - 9600 19200 - 19200 38400 - 38400 10. TRANSPARENT PRINT If you configure a unit's port as a tty, and you ask for an associated transparent print port, the following two devices will be created: /dev/ttyN - Login Port /dev/ttyNp - Transparent Print port Where "N" is the tty port number assigned by "smit". If you configure a port as a printer, only one device will be created: /dev/lpN - Printer Port The Login ports and Transparent Print ports will not operate unless carrier (DCD) is present. The stty-ncxa command may be used to change this with the "forcedcd" option. Printer Ports normally require both DCD and Clear To Send (CTS). The Login and Transparent Print ports may be open at the same time. Data sent to the Login port goes out the port without modification, while data sent to the transparent print port is bracketed with printer-on and printer-off sequences before output. The stty-ncxa command can set the on-off sequences and adjust the print speed. The Login port receives all input data; reads to the print device always fail. 11. ERROR LOGGING Driver detected errors are logged to the error log, displayed with the AIX command "errpt". A limit of 100 messages is imposed. Daemon messages are written to the System Log. To direct these errors to a file, insert the following line in your /etc/syslog.conf file. *.info /var/adm/messages As ROOT, then run: touch /var/adm/messages chmod 0644 /var/adm/messages kill -1 `cat /etc/syslog.pid` The /var/adm/messages file can grow very large over a period of weeks or months, and should be periodically truncated to avoid wasting disk space. 12. HISTORY Version 3.8.7 - October 14th, 2005 Fixed drain problem during tty close. If DCD is inactive, or CLOCAL is set, don't bother draining any remaining data, just flush it. Version 3.8.0 - July 31st, 2003 Added support for AIX 5.x 64bit. Added support for RealPort with encryption. Split AIX 5.x support from the AIX 4.x package. Daemons are no longer started in /etc/inittab. They are now started automatically during system boot by cfgmgr. Version 3.7.0 - March 24th, 2003 Added support for EtherLite 80. Added support for custom baud rates. A custom baud rate overrides all other baud rate control for a port until the custom baud rate is set to zero or the system is reset. To set a custom baud rate, use stty-ncxa cspeed {custom-rate} ttyname. The new ioctls to get and set custom baud rates are defined here: #define DIGI_SETCUSTOMBAUD (('d'<<8) | 106) /* Set custom baud */ #define DIGI_GETCUSTOMBAUD (('d'<<8) | 107) /* Get custom baud */ Keep in mind that the ioctls do not know the valid range of baud rates supported by each unit, and will let you set the baud rate to values that are unsupported by that port. In the examples below, the variable fd is the file descriptor of a RealPort tty device that is currently open by the calling process. { int speed, check; if (ioctl(fd, DIGI_SETCUSTOMBAUD, &speed) < 0) fprintf (stderr,"ioctl DIGI_SETCUSTOMBAUD fails: %s\n", strerror(errno)); if (ioctl(fd, DIGI_GETCUSTOMBAUD, &check) < 0) fprintf (stderr,"ioctl DIGI_SETCUSTOMBAUD fails: %s\n" strerror(errno)); } Version 3.5.0 - June 6, 2001 Added support for PortServer TS, EtherLite and Digi One products. Streamlined the configuration process for the purpose of speeding up the boot cycle. This was done to avoid the previously long boot process, that was seen on machines with a high RealPort device count. Updated the fastbaud table to include baud rates up to 921600. Fixed a problem where the driver was not properly displaying the correct device number for devices of sa100 and higher. Sped up device initialization at boot time. Devices entries to the /etc/inittab file now precede the tty entries so gettys don't error out with respawning too radidly messages. Version 3.3.0 - January 7, 2000 Bug Fixes A problem with the driver removing all transparent print nodes (not just the associated nodes for that particular PortServer) has been resolved. The symptom of this error was the removal of all /dev/ttyXp nodes upon removal or unconfiguration of any configured PortServer device node. Version 3.2.0 - July 29, 1999 Bug Fixes Fixed a problem where the driver incorrectly sends a break while waiting for output data to drain. Fixed a system crash which occurs when a modem hangup signal is received. Fixed a problem where data was lost at the end of a printout. Removed incorrect assert() message that triggered occasionally at some sites. Enhancements Increased the size of transparent print packets sent from the host system to the Portserver. Version 3.1.0 - May 7, 1999 Enhancements Redesigned the driver to improve stability and add new features.