Knowledgebase

Issue:

Instructions for Installation and Usage of Trueport for SCO Openserver 5.x

Cause:
Current User Guide does not include instruction set.

Solution:

TruePort - Release 1.0.2 , Technical Notes. Sep.28, 2001.
OPERATING SYSTEM SCO OpenServer 5.0.X.

New in this Release
===================
The SCO trueport driver can now handle upto 256 trueport connections. To make
sure it works properly, your sco system must be tuned to meet the following 
requirements (use scoadmin utility):

1,  set the number of pseudo-tty to 256
2,  set the NCLIST no less than 1024

If you only use small amount of trueports (eg. less than 64), you probably do not
need to change anything. 

If you need all 256 trueport connections, check with existing setup to ensure 
the above requirements are met. When change is made, re-build the kernel and
reboot system.
 

Note on last Release 1.01
=========================
Release 1.0.1 now supports TruePort Standard mode as the default installation mode. 
Earlier release 1.0.0, supported Lite mode only.


Introduction and Overview
=========================

This software has been built on OpenServer 5.0. It was designed for use on 
SCO OpenServer 5.0.X. Package installation tools, pkgadd, pkgrm are required
to install and de-install this product.

TruePort for OpenServer 5 is a UNIX serial port emulation system for the 
Perle Jetstream terminal server family. TruePort provides a standard
UNIX TTY interface to application software. This is achieved using either
TruePort serial device drivers (Standard mode) OR the UNIX pseudo TTY system
used by software such as the telnet and rlogin programmes (Lite mode).

TruePort provides a more general interface via a fixed /dev TTY name,
this allows application software to send and receive data from ports on the
terminal server as if they were directly connected to the application server.

TruePort supports some additional features that make it more flexible than
either rlogin or telnet :

* Support for an auxiliary port (or printer port) on each connection;
* Programmable keep-alives for improved connection reliability;
* Automatic reconnection after network disconnects.

Note for Lite Mode Only
=======================
TruePort now has 2 modes of operation, the default (Standard) TruePort mode
and Lite mode. In TruePort Standard mode, serial ports operate exactly like
standard serial ports and support a full range of serial I/O commands (IOCTLs).

TruePort Lite mode provides most of the features of a standard serial port but
it has no physical device control capabilities. You must pre-configure terminal
server ports for the required baud rates, parity etc.
Application IOCTL commands to TruePort ports are NOT propagated to the terminal
Server in Lite mode.

Features
========

TruePort creates a standard UNIX TTY in the /dev directory.
Each TTY is connected to a unique TCP/IP port number on the terminal server.
This port number is used to uniquely identify the port and the connection to
the OpenServer 5 computer.

Each connection supports an optional auxiliary port, this is typically used
for printing to a printer connected to a terminal.
Auxiliary devices have their own /dev TTY name and can be used by any
application.  When the auxiliary port is used by a printing application,
it is necessary to identify the terminal type to TruePort so that the 
appropriate printer ON/OFF codes can be added to the data stream. A terminal
capabilities file /etc/trueport/printcap.tp is included with definitions for
some commonly used terminal types. Additional definitions can be added for
other terminal types.

The keep-alive feature improves robustness, TruePort will always attempt
to keep the application interface available. If the network connection fails,
TruePort will reconnect when the network is available. This feature allows
terminal server power cycles without a server reboot.

Installation and Configuration
==============================

The supplied user guide currently only describes TruePort Lite for SCO OpenServer.
Additional information in this release note describes the default Standard mode.

NOTE - Please remove any previous versions of TruePort software OR MTSRD for SCO
Openserver before attempting to install this product.

Installation uses the pkgadd utility (NOTE - this package is NOT a scoadmin/custom installable image).

Once the installation package has been copied onto your computer
(in this example named /tmp/tpsco101.pkg), the package can be installed as follows:

Login as root user.

# pkgadd -d /tmp/tpsco101.pkg

This will install the device drivers, rebuild the UNIX kernel and create the
Required device names.

The JETSTREAM/LANSTREAM product documentation has detailed information on configuration
options when using TruePort (MTSRD).

The following is an example for adding two lines using the 
JETSTREAM CLI commands:

 JS_8500# add host  openserver 192.101.34.99
 JS_8500# set line 1 service silent raw openserver 10000
 JS_8500# set line 2 service silent raw openserver 10001
 JS_8500# save
 JS_8500# reboot

TruePort software uses the "silent raw" service on the terminal server,
in this mode the line is configured to connect to your host UNIX system on a
specified TCP/IP host port number. This is how the TruePort system matches
the network connection to the TTY name.

The standard installation installs 64 TruePort device nodes, but the system
configuration files contain the entries required for all 128 supported devices.
The remaining 64 devices can be enabled later by editing the system
configuration files and rebuilding the UNIX kernel.

Trueport administrative files and utilities are located in the directory /etc/trueport.

Enabling Ports
==============

All TruePort ports must be enabled before they can be used.

TTY ports are enabled using the TruePort admin tool "tpadm". The user guide 
describes the use of this utility to edit the TruePort configuration files.

To simplify configuration of the default Standard TruePort mode, a 
quick start script (addports) is installed in the /etc/trueport directory.

In Standard mode all ports are named:

 /dev/ttys0 through /dev/ttys127 for the non-modem open devices.
 /dev/ttyS0 through /dev/ttyS127 for the modem open devices.

The addports syntax is:

# cd /etc/trueport
# ./addports <start port> <end port>

Where <start port> is the number of the first port to use and <end port>
is the number of the last port to use.

So the command:

./addports 0 63

Would enable all 64 default installed TruePort devices (provided that 64
terminal server ports have been correctly configured).

The TruePort system is configured to start the required drivers at a system
Reboot. To start the TruePort system you should reboot your server at this point.

Once the system has been rebooted, the enabled ports can be used as standard serial ports.

To use a TruePort port as a login port, you should enable the appropriate
getty entry that was added by the installer in the /etc/inittab file.

Transparent Print Throttle Feature
==================================

Please consult the user guide for information about using transparent print devices.

When using the auxiliary port as a transparent printer device (printer 
connected to the terminal printer port), the printer can seriously degrade 
terminal performance, especially if the printer baud rate and print speed is
lower than the terminal speed. In order to preserve reasonable terminal response
while printing, the auxiliary port is throttled to a fixed maximum bytes
per Second. The default throttle is 200 bytes/Second as this gives acceptable
performance on a terminal printer at 4800 baud. If your printer is faster you 
can increase this count via the "-tpbps #" option in the TruePort configuration
file, e.g.

tpd -port 10000 -tty /dev/ttyX0 -aux /dev/ttyX0p -term vt100 -tpbps 500

As a rule of thumb we recommend that you calculate the tpbps as 25% of the
line speed (in bytes/Second) of the printer or terminal - which ever is the 
slower. So for example, if the terminal baud is 19200 (1920 Bytes/S) and the
printer is 9600 baud (960 Bytes/S), then the tpbps could be set for 240.

The maximum count supported is 800 bytes/Second. If you notice that terminal
response is poor when printing then try reducing tpbps below the default 200.

Known Issues and Bugs
=====================

1. The default TruePort mode is now the Standard native device driver mode,
with full IOCTL support. Device names are fixed to /dev/tty[sS]0-127.
You may enable Lite mode, Lite mode device names may be chosen by you,
but if you use the addports script to enable Lite mode devices,
they will be named /dev/ttyX0-127. The addports syntax for Lite mode is :
addports -l <start port> <end port>.

2. Transparent print is not supported by addports, you must enable transparent
print manually by editing the /etc/trueport/config.tp file,
or by using tpadm directly.

3. The script /etc/trueport/cleanports will disable all TruePort devices.
They must then be re-enabled using addports.

4. TruePort Lite uses the UNIX pseudo TTY system. Unix pseudo TTYs are 
dynamically allocated to TruePort as more ports are configured in config.tp. 
You may eventually configure more daemons than you have pseudo TTYs in your 
operating system. You should consult your operating system documentation for 
information about increasing the number of pseudo TTYs in this case.
By default TruePort (Lite) for SCO is configured for a maximum 128 ports, please
contact your customer support contact if you require more !

5. When each daemon runs it may create a trace file if the trace option
is specified. These files can become large so the trace option should be used
only as needed.

6. Never use the kill -9 (SIGKILL) command on a tpd process, as this prevents
tpd from exiting cleanly and restoring it's pseudo TTYs. There is a cleanup
system that operates on a system reboot that will restore TTY's lost in this way.

7. Never use existing device names as TruePort Lite device names as they may be
replaced by a TruePort TTY.

FILE REFERENCE
==============

/etc/trueport   - Installation directory.
 config.tp  - Trueport configuration file.
 printcap.tp  - Terminal printer codes definition file.
 addports  - Quick start configuration script.
 cleanports  - Cleanup script.
 tpd   - TruePort daemon program.
 tpadm   - Configuration utility (used by addports).

/dev/    - Devices directory.
 ttys0-63  - Non-modem serial ports.
 ttyS0-63  - Modem serial ports.
 tpm0-127  - TruePort control device nodes.

/etc/    - System configuration directory.
 inittab   - Login ports (getty) definitions.
 rc2.d/S79tpadm  - TruePort start-up script.

/etc/conf/node.d  - Device node file directory
 tps   - TruePort serial device node file
 tpm   - Master device node file.

TruePort running in Standard mode is actually a pair of device drivers.
The TTY (or slave) device driver is called tps.
The control (or master) device driver is called tpm.