HP-UX User Guide

HP-UX User Guide
TruePort HP-UX
User Guide
Chapter 8
This document provides the procedure for installing and using TruePort on HP-UX.
Table of Contents
What is TruePort?....................................................................................3
TruePort Full Mode vs Lite Mode ...........................................................3
Full Mode ............................................................................................................... 3
Lite Mode ............................................................................................................... 3
TruePort I/O Access Options ............................................................................... 4
Modbus ASCII/RTU Mode ................................................................................ 4
I/O Signal Mode................................................................................................ 4
Uninstalling TruePort ..............................................................................4
Installing TruePort...................................................................................5
Configuring TruePort on a Terminal/Device Server .............................5
Server-Initiated Mode ........................................................................................... 5
On a JetStream\LanStream.............................................................................. 6
On an IOLAN DS Family Device Server........................................................... 6
Client-Initiated Mode............................................................................................. 6
Client I/O Access Mode ........................................................................................ 7
On a IOLAN DS Family .................................................................................... 7
Configuring Ports on the TruePort Host ...............................................7
TruePort Device Names........................................................................................ 7
Configuration Methods......................................................................................... 8
TruePort HP-UX User Guide, Version 6.0, Part #5500170-10
1
Table of Contents
TruePort addports Script Options ......................................................... 8
Examples................................................................................................................ 9
Adding Server Mode Ports................................................................................ 9
Adding Client Initiated Ports.............................................................................. 9
Adding Client I/O Access Ports......................................................................... 9
TruePort Administration Tool (tpadm) Commands............................ 10
Syntax................................................................................................................... 10
Examples.............................................................................................................. 11
Adding a Port .................................................................................................. 11
Deleting a Port ................................................................................................ 12
Displaying Port Entries.................................................................................... 12
Starting the TruePort Daemon ........................................................................ 12
config.tp File Syntax ............................................................................. 13
Using TruePort ...................................................................................... 14
Starting TruePort................................................................................................. 14
As a General Device............................................................................................ 14
As a Modem Device............................................................................................. 14
As a Transparent Printer .................................................................................... 15
In Full Mode .................................................................................................... 15
In Lite Mode .................................................................................................... 15
Deleting a Single Port ......................................................................................... 15
Deleting All Ports ................................................................................................ 15
Configuring Packet Forwarding........................................................... 16
Configuration Script............................................................................................ 16
pktfwdcfg.tp File Format..................................................................................... 18
Configuring SSL/TLS ............................................................................ 19
SSL/TLS Configuration Information .................................................................. 19
SSL/TLS Support Files........................................................................................ 20
TruePort Port Configured as SSL/TLS Server ................................................ 20
TruePort Port Configured as SSL/TLS Client ................................................. 20
Pseudo Random Number Generator .............................................................. 20
sslcfg.tp File Format ........................................................................................... 21
SSL/TLS Trouble Shooting................................................................................. 21
2
TruePort HP-UX User Guide, Version 6.0
What is TruePort?
What is TruePort?
You use TruePort when you want to connect extra terminals to a server using a Device Server rather
than a multi-port serial card; it is a tty device redirector. TruePort is especially useful when you want
to improve data security, as you can create an SSL/TLS connection between the TruePort host port
and the Device Server, which will encrypt the data between the two points.
TruePort Full Mode vs Lite Mode
You can configure TruePort on HP-UX in either Full Mode or Lite Mode. When you start TruePort in
Full Mode, the serial configuration parameters are set on the TruePort host. When you start TruePort
in Lite Mode, the serial configuration parameters are set on the device/terminal server. On HP-UX,
serial configuration parameters consist of bits per second (baud rate speed), data bits, parity, stop bits,
flow control, and any other standard stty I/O parameters. In either mode, the data is passed in raw
format, although you can enable the SSL/TLS connection option to encrypt the data going through a
port.
Full Mode
This mode allows complete device control and operates exactly like a directly connected serial port.
It provides a complete tty device interface between the attached serial device and the network,
providing hardware and software flow control.
The port serial configuration parameters set on the TruePort host must match the serial configuration
parameters set on the device (in this example, to the Card Reader), as shown below:
Match Serial Configuration Parameters
perle
Card
Reader
Network
Terminal/Device Server
TruePort Host
Data
Lite Mode
This mode provides a simple raw data interface between the device and the network. Although the
port will still operate as a tty device, control signals are ignored. In this mode, the serial
communications parameters are configured on the terminal/device server and must match those
configured on the device (in this example, a Card Reader), as shown below:
Match Serial Configuration Parameters
perle
Card
Reader
Network
Terminal/Device Server
Data
TruePort Host
TruePort HP-UX User Guide 3
Uninstalling TruePort
TruePort I/O Access Options
Modbus ASCII/RTU Mode
If you have a Modbus serial application running on a PC that is connected to a network, you can use
TruePort as a virtual serial connection to communicate with the Device Server over the network to
access I/O data. You also have the option of enabling SSL as a security option to encrypt the data that
is communicated between the Device Server and the host machine (SSL/TLS must be configured on
both the Device Server and in TruePort).
UID: 15
Power
perle
Network
Device Server
PC running a
Modbus Serial
Application/
TruePort
I/O Digital
Output
I/O Signal Mode
If you have a custom application that talks to a serial port, you can use TruePort as a virtual serial
port to communicate with the Device Server over the network to access I/O data. You also have the
option of enabling SSL as a security option to encrypt the data that is communicated between the
Device Server and the host machine (SSL/TLS must be configured on both the Device Server and in
TruePort).
PC running
Custom
Application (API)/
TruePort
Power
perle
Network
Device Server
I/O Digital
Output
Uninstalling TruePort
Before you install a new version of TruePort, you should uninstall the current version of TruePort. To
uninstall TruePort, do the following:
1.
Login as a root user.
2.
Type the following:
# swremove
4
3.
Select TruePort from the list of applications.
4.
Select Actions, Remove and click OK and Yes to start the uninstall process.
5.
When the uninstall process is complete, click Done. The system may need to be rebooted to
rebuild the kernel.
TruePort HP-UX User Guide, Version 6.0
Installing TruePort
Installing TruePort
Installation uses the swinstall utility. The installable package is contained in the file
tphp<ver>-<nnn>.depot.Z where <ver> is the HP-UX version number and <nnn> is the version
number of the release. This is a compressed software depot. To install the software, do the following:
1.
Login as a root user and copy the installation package to /tmp.
2.
Decompress the depot.
# uncompress tphp<ver>-<nnn>.depot.Z
3.
Register the package as a software installation depot.
# swreg -l depot /tmp/tphp<ver>-<nnn>.depot
4.
Start the installer.
# swinstall
5.
When the SD Install window appears, click the Source Depot Path button and select
/tmp/tphp<ver>-<nnn>.depot, Click OK to return to the main window.
6.
In the SD Install window, select TruePort and then Actions, Mark for Install.
7.
Next select Actions, Install.
8.
Follow the instructions on the screen, you can view the product description and README after
the files have been installed on the computer.
9.
When the installation is complete you will be prompted to click Done and the system may be
rebooted. You can check that the software has been correctly installed with the lsdev command.
In the list of installed devices, tpm and tps should be listed. Once software installation is
complete, you are required to configure your terminal/device servers to use the TruePort service
and to enable ports on your server computer.
Configuring TruePort on a Terminal/Device Server
When you add a port, you need to configure the port(s) on the host running TruePort and you also
need to configure the port(s) on the terminal server.
Note:
Only IOLAN DS Family software version 3.0 or higher supports the TruePort Line Service.
Server-Initiated Mode
When you configure TruePort for server-initiated mode, the terminal/device server will initiate
communication to the TruePort host.
To configure a terminal/device server for server-initiated mode (which is the default mode), you need
to set the Line Service to Silent Raw or TruePort and assign the port number to be the same port
number configured on the TruePort host (by default, this number starts at 10000).
Note:
All versions of the JetStream 4000 and 8500, LanStream 2000, and IOLAN DS Family
software support TruePort Full Mode operation. However, the JetStream 6x series software
version must be 4.03 or greater.
TruePort HP-UX User Guide 5
Configuring TruePort on a Terminal/Device Server
On a JetStream\LanStream
The following instructions provide an example of how to set up four ports on the JetStream terminal
server for TruePort.
1.
Connect to the JetStream (for example, via Telnet).
2.
Log in to the JetStream as the admin user.
3.
Add the host running TruePort to the host table using the add host command as shown in the
following example:
add host hpux50 192.152.247.61
You are now ready to configure the ports that will connect to the TruePort host.
4.
To configure the ports, enter each of the following commands:
set line 1 service
kill line 1
set line 2 service
kill line 2
set line 3 service
kill line 3
set line 4 service
kill line 4
silent raw hpux50 10000
silent raw hpux50 10001
silent raw hpux50 10002
silent raw hpux50 10003
5.
At the command prompt, type save and press Enter.
6.
At the command prompt, type logout and press Enter.
The configuration of JetStream terminal server ports is now complete.
On an IOLAN DS Family Device Server
Configuring an IOLAN DS Family Device Server using the CLI is almost same as the JetStream CLI.
You will set the Line Service to TruePort and on 1-port model you won’t specify a line number.
Client-Initiated Mode
Note:
Client-Initiated mode is available on IOLAN DS Family models with firmware 3.0 or higher.
When you configure TruePort for Client-Initiated mode, the TruePort host will initiate
communication with the Device Server.
To configure a Device Server for Client-Initiated mode, you need to set the Line Service to
TruePort, enable the Client Initiated option, and assign the port number to be the same port number
configured on the client initiated configured TruePort host (by default, this number starts at 10001).
The following instructions provide an example of how to set up 4 ports on a IOLAN Device Server
for TruePort client initiated mode.
1.
Connect to the IOLAN DS (for example, via Telnet).
2.
Log in to the IOLAN DS as the admin user.
3.
To configure the ports, enter each of the following commands:
set line service
set line service
set line service
set line service
kill line 1-4
trueport
trueport
trueport
trueport
client-initiated
client-initiated
client-initiated
client-initiated
on
on
on
on
The configuration of the IOLAN DS is now complete.
6
TruePort HP-UX User Guide, Version 6.0
10001
10002
10003
10004
Configuring Ports on the TruePort Host
Client I/O Access Mode
Client I/O access mode allows a Modbus RTU/ASCII serial application running on a TruePort host to
access Device Server I/O. You can also access Device Server I/O using the Perle API in this mode. To
configure a terminal/device server for Client I/O Access mode, you need to enable I/O TruePort
Services, enable I/O Modbus Slave, assign a Modbus slave UID to match the configured UID on the
Modbus RTU serial application, and assign the port number to be the same port number configured
on the client I/O Access configured TruePort host (by default, this number is 33816).
On a IOLAN DS Family
The following instructions provide an example of how to set up an IOLAN device server for TruePort
I/O Access.
1.
Connect to the IOLAN DS (for example, via Telnet).
2.
Log in to the IOLAN DS as the admin user.
3.
To enable the I/O TruePort service, enter following command:
set io trueport mode on listen 33816
4.
3. To enable I/O Modbus slave, enter following command:
set io modbus mode on uid 1
5.
Reboot the IOLAN DS by entering the following command:
reboot
The configuration of the IOLAN DS is now complete.
Configuring Ports on the TruePort Host
After you have configured the ports on the terminal/device server, you need to configure
corresponding ports on the TruePort host. TruePort administrative files and utilities are installed in
the /etc/trueport directory.
TruePort Device Names
TruePort for HP-UX supports up to 4000 TruePort serial device nodes, however you must enable
these ports before they can be used. Each installed TTY is assigned a name by the operating system
that will be in the range 0-3999.
The HP-UX TruePort serial device naming convention are as follows:
z
Client-Initiated and Full mode devices:
/dev/ttys0 through /dev/ttys3999 for the non-modem open devices.
/dev/ttyS0 through /dev/ttyS3999 for the modem open devices.
/dev/ttyt0 through /dev/ttyt3999 for the pseudo modem open (Reynolds mode)
z
Server-Initiated Lite mode devices:
/dev/ttyX0 through /dev/ttyX3999
z
Auxiliary Printers
/dev/ttyX0p through /dev/ttyX3999p
TruePort HP-UX User Guide 7
TruePort addports Script Options
Configuration Methods
After you have configured the ports on the terminal/device server, you have to configure the same
port numbers on the TruePort host. The TruePort Host can be configured in the following ways:
1.
Use the addports script, which will automatically start each port as it is configured. See
TruePort addports Script Options on page 8 for more information.
2.
Use the addports script to create the total range of TTY ports you require and then use the
tpadm administration tool. See TruePort Administration Tool (tpadm) Commands on page 10
to remove/add ports to the config.tp file using tpadm.
3.
Use the addports script to create the total range of TTY ports and then edit the
/etc/trueport/config.tp file (see config.tp File Syntax on page 13), the
/etc/trueport/sslcfg.tp file (see sslcfg.tp File Format on page 21), and the
/etc/trueport/pktfwdcfg.tp file (see pktfwdcfg.tp File Format on page 18).
TruePort addports Script Options
The addports script allows you to add a range of ports to the config.tp file and automatically
start them, without having to use the tpadm utility. You can run addports after the TruePort host
software is installed. The addports options are as follows:
Note:
The order of the addports parameters must be as shown below.
For Server Mode:
addports [-l] [-hup] [-ssl] [-pf] [-server <host>] [-trace <level>] <firstport>
<lastport>
For Client Initiated Mode:
addports [-l] [-hup] [-ssl] [-pf] -client <host>[:<TCP-port>] [-nodisc]
[-retrytime <time>] [-retrynum <number>] [-io mb_ascii|mb_rtu|io_api]
[-trace <level>] <firstport> <lastport>
8
Parameter
Description
-l
(lower case L) Specifies that the TruePort port will be started in Lite mode.
addports will configure TruePort for Full mode by default.
-hup
Causes the tty device to automatically close or hang-up when the TCP
connection is closed.
-ssl
Enables SSL/TLS on the port. You will automatically be prompted by the
SSL/TLS configuration script. For more information see Configuring
SSL/TLS on page 19.
-pf
Enables packet forwarding on the port. You will automatically be prompted by
the packet forwarding configuration script. For more information see
Configuring Packet Forwarding on page 16.
-server <host>
You can optionally supply the remote host name or IP address that a
connection request will be accepted from. The default is to accept connections
from any host. The host can be an IPv4 address or a resolvable host name.
-client
<host>[:<TCP-port>]
Specifies a client-initiated connection (meaning that the TruePort host will
initiate the connection). You can optionally supply the starting destination TCP
port for the connection (the default is 10001, see <firstport> option below).
The host can be an IPv4 address or a resolvable host name.
-nodisc
Does not drop the TCP connection for a client-initiated connection when the
application closes the slave TTY port.
TruePort HP-UX User Guide, Version 6.0
TruePort addports Script Options
Parameter
Description
-retrytime <time>
Specifies the number of seconds between TCP connection retries after a
client-initiated connection failure. Valid values are 1-255. The default is 1
second.
-retrynum <number>Specifies the number of retry attempts for a client-initiated connection. Valid
values are 0-255. If this option is set to 0 (zero), TruePort will not try to
recover a TCP connection. The default is 5 retries.
-io mb_ascii
-io mb_rtu
-io io_api
Enables client I/O access for this client-initiated session for one of the
following:
z
A serial Modbus application configured for either the ASCII or RTU
protocol will be using this port.
z
A custom serial application using the Perle I/O Access API will be using
this port.
If you did not specify the :TCP-port option with -client, the -io option
will make the destination TCP port default to 33816 (the default value of the
TruePort client in the Device Server).
-trace <level>
The trace level for debugging purposes. The default is 1. The trace file for each
port can be found under /etc/trueport/trace.<tty-name>, where
<tty-name> is either tpmn or ttyXn, where n the TTY port number.
<firstport>
The first TTY to add starting at 0 (added as port 10001 for a client-initiated
(TruePort) connection or port 10000 for a server (terminal/device server)
initiated connection).
<lastport>
The last TTY to add.
Examples
Adding Server Mode Ports
The following addports command will create 4 ports configured for Server mode which will listen
for connections from host myjetstream on TCP ports 10000 to 10003, while running in TruePort Full
mode.
addports -server myjetstream 0 3
Adding Client Initiated Ports
The following addports command will create 4 ports configured for Client Initiated mode which
will connect to host myiolansds4 on TCP ports 10001 to 10004, while running in TruePort Lite
mode.
addports -l -client myiolansds4 0 3
Adding Client I/O Access Ports
The following addports command will create a single port configured for Client I/O Access mode
which will connect to host myiolaniods1 on TCP port 33816 and will support a serial Modbus RTU
application.
addports -client myiolaniods1 -io mb_rtu 0 0
TruePort HP-UX User Guide 9
TruePort Administration Tool (tpadm) Commands
TruePort Administration Tool (tpadm) Commands
This section describes the commands and syntax for the TruePort Administration tool.
Syntax
Description You can use the tpadm utility to add, list, start, and delete ports.
tpadm -a <new_portnumber> [-m|-n]
Syntax
[-e|-F|-e -F [-c [<existing_host>:]<existing_portnumber>
[-C <host> [-q <seconds>] [-R <retries>] [-o]
[-I mb_ascii|mb_rtu|io_api]]
[-S <host>] [-T <level>] [-h] -p <tty_letter>[<port#>]
[-k <seconds>] [-t <termtype>] [-i <start_port>] [-r <range>]
tpadm -l <portnumber>|<host>:|<host>:<TCP_number>|ALL
tpadm -s <portnumber> [-r <range>]|
<host>: [-r <range>]|<host>:<TCP_number> [-r <range>]|ALL
tpadm -d <portnumber>|<host>:|<host>:<TCP_number>
Options
10
-a <new_portnumber>
The TCP/IP port number configured for the port on the remote device or terminal
server. We recommend that you use the range 10000+.
-m
Adds a terminal in TruePort Full Mode (not Lite Mode) for full device control. This is
the default.
-n
Adds a terminal in TruePort Lite Mode (not Full Mode) for terminal/device server
device control.
-e
Enables SSL/TLS for the port. You will automatically be prompted for the SSL/TLS
configuration information when you use this command line option. See Configuring
SSL/TLS on page 19 for more information.
-F
Enables packet forwarding for this port. You will automatically be prompted for the
Packet Forwarding configuration information when you use this command line option.
See Configuring Packet Forwarding on page 16 for more information.
-c [<existing_host>:]<existing_portnumber>
Copies the specified SSL/TLS and/or packet forwarding configuration data from the
specified entry to the new port entry being created
-C <host>
Enables a client-initiated connection (by the TruePort host) for this session and will
connect to the specified host and port number.
-q <seconds>
Sets the number of seconds between TCP connection retries. The default is 1 second.
-R <retries>
Sets the number of retry attempts for TCP connection retries. The default is 5 retries.
-o
Keeps the client-initiated TCP connection open even when the application closes the
slave TTY port.
-I mb_ascii|mb_rtu|io_api
Enables client I/O access for this client-initiated session.
TruePort HP-UX User Guide, Version 6.0
TruePort Administration Tool (tpadm) Commands
-S <host>
Specifies the remote host name or IP address that a connection request will be accepted
from in Server mode. The default is to accept connections from any host.
-T <level>
Sets the trace level for debugging. The default is 1.
-h
Causes the tty device to automatically be closed when the TCP connection is closed.
-p <tty_letter>[<port#>]
<tty_letter> is the TTY name suffix for the port and should be used when adding a
range of ports. Use X for Server-Initiated Lite Mode ports and use m for Client-Initiated
or Full Mode ports.
<port#> is the port number and should be used when adding a single port and not a
range.
-k <seconds>
The time, in seconds, to wait on an idle connection before sending a keep-alive
message.
-t <termtype>
A terminal type listed in the file printcap.tp. This option turns on auxiliary printing;
you must specify the type of terminal that is connected to the printer. This option cannot
be used in conjunction with the I/O Access option (-I).
-i <start_port>
Starting port number for use in the TTY device node names (range is from 0 to 3999).
-r <range>
Number of ports/device nodes to configure or start (range is from 0 to 3999).
-l <portnumber>|<host>:|<host>:<TCP_number>|ALL
Displays specific or all port entries in the config.tp file.
-d <portnumber>|<host>:|<host>:<TCP_number>
Deletes the specified port entry from the config.tp file.
-s <portnumber>|<host>:|<host>:<TCP_number>|ALL
Starts specific or all port entries in the config.tp file.
Examples
Adding a Port
To add a Server-Initiate port in Lite Mode with SSL/TLS enabled, use the following command:
tpadm -a 10000 -n -e -p X0
To add a Client Initiated port to connect to host myiolansds4 on remote port 10001 with packet
forwarding enabled, use the following command:
tpadm -a 10001 -F -p m2 -C myiolansds4
To add a I/O Access port to connect to host myiolaniods1 on port 33816 to us a serial Modbus
RTU application with a keep alive time of 3 minutes, use the following command:
tpadm -a 33816 -p m3 -C myiolaniods1 -I mb_rtu - k 180
TruePort HP-UX User Guide 11
TruePort Administration Tool (tpadm) Commands
Deleting a Port
To delete port 10000, use the following command:
tpadm -d 10000
To delete port 10001 on host myiolands use the following command:
tpadm -d
Note:
myiolands:10000
The <host>:<port> combination you use must exist in the config.tp configuration file.
When you remove a terminal using this command, it does not stop the software running, it just deletes
the entry for this terminal in the config.tp configuration file. You must then kill the TruePort daemon
process.
Displaying Port Entries
To displays the ports configured in the config.tp file, use the following command:
tpadm -l all
To display all the ports for a specific host in the config.tp file, use the following command:
tpadm -l myiolands:
To display a specific port for a specific host in the configuration file, use the following command:
tpadm -l myiolands:10002
Starting the TruePort Daemon
To start port number 10000, use the following command:
tpadm -s 10000
To start all configured ports, use the following command:
tpadm -s ALL
To start port number 10001 on host 172.16.45.8, use the following command:
tpadm -s
172.16.45.8:10001
To start all configured port on host myjetstream, use the following command:
tpadm -s myjetstream:
12
TruePort HP-UX User Guide, Version 6.0
config.tp File Syntax
config.tp File Syntax
Note:
If you use addports to enable TruePort you do not need to use the tpadm utility.
An entry in the config.tp configuration file used to control a terminal in server Full Mode with all
the options enabled looks like this:
tpd -trueport -ssl -pf -hup -tty /dev/tpm0 -port 10000 -server myjetstream
-ka 30 -trace 4 -aux /dev/ttyX0p -term vt100
An entry in the config.tp configuration file used to control a terminal/device server in Full Mode
via Client Initiated mode and all options enabled looks like this:
tpd -trueport -ssl -pf -hup -tty /dev/tpm0 -port 10001 -client myiolansds4
-ka 30 -trace 4 -aux /dev/ttyX0p -term wy60
The config.tp port parameter options are:
-trueport
-ssl
-hup
-tty <ttyname>
-port <port_number>
-ap
-ka <seconds>
-trace <1-4>
-aux <auxdevname>
-term <type>
-client <host>
-retrytime <seconds>
-retrynum <number>
-nodisc
Enables TruePort Full Mode (not TruePort Lite) for full device control.
Enables SSL/TLS on the port.
Causes the tty device to automatically close or hang up when the TCP
connection is closed. This option is not supported in Server-Initiated Lite
Mode.
<ttyname> is the tty name for the port. This must be the complete path
name. Use /dev/ttyXn for Server-Initiated Lite Mode ports or use
/dev/tpmn for Client-Initiated or Full Mode ports, where n is the port
number.
For a server-initiated connection (terminal/device server), the TCP port
number the TruePort daemon will listen on for connection requests. For a
client-initiated connection (TruePort host), the Device Server TCP port
number (DS Port) the TruePort daemon will attempt to connect to. We
recommend that you use the range 10000+.
This option allows the TruePort daemon to autopush the ptem and ldterm
modules on to a Lite Mode device node. This is required for the getty to
properly display the login prompt.
<seconds> is the number of seconds to wait on an idle connection before
sending a keep-alive message.
<1-4> is the trace level for debugging purposes, the default is 1.
Sets the auxiliary printer device name.
Sets the terminal type of terminal that the auxiliary printer is attached to.
Indicates a client-initiated connection. The <host> can be an IPv4 address
or a resolvable host name.
For client-initiated connections, the number of seconds between TCP
connection retries. The default is 1 second.
For client-initiated connections, the number of retry attempts for a TCP
connection. The default is 5 retries.
For client-initiated connections, does not close the TCP connection when
the application closes the slave TTY port.
TruePort HP-UX User Guide
13
Using TruePort
-io mb_ascii|
mb_rtu|
io_api
-server <host>
-nagleoff
For client-initiated connections, enables I/O access for the session.
z
A serial Modbus application configured for either the ASCII or RTU
protocol will be using this port.
z
A custom serial application using the Perle I/O Access API will be
using this port.
If you did not specify the :TCP-port option with -client, the -io
option will make the destination TCP port default to 33816 (the default
listen TCP port number of the I/O TruePort services in the IOLAN Device
Server).
Specifies the remote host name or IP address that a connection request will
be accepted from in Server mode. The default is to accept connections
from any host. The <host> can be an IPv4 address or a resolvable host
name.
For client-initiated connections, turn off the TCP Nagle Algorithm, which
inserts a short delay so that each character is not sent individually, but sent
in small packets instead. The default is On.
Using TruePort
Starting TruePort
A TruePort daemon needs to be run for each port configured. There are three ways to start TruePort
daemons:
z
Use the addports script, which will automatically starts each port as it is configured.
z
When the TruePort host reboots, a TruePort daemon for each port configured in the config.tp
file will automatically be started by the trueport script, which can be found in the
/etc/init.d/trueport script. The trueport script is enabled when the TruePort software is
installed.
z
Enter the tpadm -s command to start specific individual ports or all the ports at one time; see
TruePort Administration Tool (tpadm) Commands on page 10 for the command syntax.
As a General Device
The general procedure for using TruePort is as follows:
1.
To add a login to a port, insert a line similar to the following to your /etc/inittab file.
TP8:234:respawn:/usr/sbin/getty -h ttys8 9600 vt100
2.
Type init q to start the getty application, which sets up the communication parameters and
provides a login prompt to the serial device.
As a Modem Device
1.
To control a modem connected to a JetStream, you will need a program such as mgetty.
In the /etc/inittab file, add a line similar to the following:
TP9:234:/usr/sbin/getty
2.
14
ttyS9 19200
Type init q to start the getty application, which sets up the communication parameters and
provides a login prompt to the serial device.
TruePort HP-UX User Guide, Version 6.0
Using TruePort
As a Transparent Printer
The addports script does not support adding a transparent print port so, so you must manually edit
the config.tp file.
In Full Mode
1.
An example of a Server-Initiated Full Mode port entry is:
tpd -trueport -tty /dev/tpm0 -port 10000 -ka 30
2.
To configure that entry as a transparent print port (aux port), you need to add:
tpd -trueport -tty /dev/tpm0 -port 10000 -ka 30 -aux /dev/ttyX0p
-term vt100
where the transparent printer port is called /dev/ttyX0p and the term type is vt100 (this is
required).
In Lite Mode
1.
An example of a Server-Initiated Lite Mode port entry is:
tpd -tty /dev/ttyX0 -port 10000 -ka 30
2.
To configure that entry as a transparent print port (aux port), you need to add:
tpd -tty /dev/ttyX0 -port 10000 -ka 30 -aux /dev/ttyX0p -term vt100
where the transparent printer port is called /dev/ttyX0p and the term type is vt100 (this is
required).
Deleting a Single Port
To delete serial ports, do the following:
1.
In the /etc/trueport directory, use an editor to delete the port entry in the config.tp file or
type the following command:
tpadm -d <portnumber>|<host>|<host>:<portnumber>
2.
You must then kill the TruePort daemon process.
3.
In the /etc/inittab file, either delete or comment out (by placing a # in front of the entry) the
application that is using the deleted port.
Deleting All Ports
There is a script you can run called cleanports that will kill all the TruePort daemon processes and
delete all entries in the config.tp, sslcfg.tp, and pktfwdcfg.tp files, with the exception of any
lines that have been commented out.
TruePort HP-UX User Guide
15
Configuring Packet Forwarding
Configuring Packet Forwarding
The Packet Forwarding feature allows you to control how the data written by a HP-UX application to
the slave TTY port is packetized before forwarding the packet onto the LAN network.
Configuration Script
When you specify the packet forwarding option, a configuration script is automatically launched as
follows:
Enable Packet Definition (y/n): y
Packet Size [0] ( 1 - 1024):
Idle Time ([0] - 65535):
Force Transmit Time ([0] - 65535):
Enable End Trigger1 (y/n): y
End Trigger1 Character ([0] - ff):
Enable End Trigger2 (y/n):
End Trigger2 Character ([0] - ff):
Enter the Forwarding Rule ([trigger], trigger+1, trigger+2, strip-trigger):
Enable Packet Definition (y/n): n
Enable Frame Definition (y/n): y
SOF1 Character ([0] - ff):
Enable SOF2 (y/n):
SOF2 Character ([0] - ff):
Transmit SOF Character(s) ([on]/off):
EOF1 Character ([0] - ff):
Enable EOF2 (y/n):
EOF2 Character ([0] - ff):
Enter the Forwarding Rule ([trigger], trigger+1, trigger+2, strip-trigger):
The following table describes the options:
16
Packet Definition
This section allows you to set a variety of packet definition options. The first
criteria that is met causes the packet to be transmitted. For example, if you set
a Force Transmit Timer of 1000 ms and a Packet Size of 100 bytes,
whichever criteria is met first is what will cause the packet to be transmitted.
Packet Size
The number of byte that must be written by the application before the packet is
transmitted to the network. A value of zero (0) ignores this parameter. Valid
values are 0-1024 bytes. The default is 0.
Idle Time
The amount of time, in milliseconds, that must elapse between characters
before the packet is transmitted to the network. A value of zero (0) ignores this
parameter. Valid values are 0-65535 ms. The default is 0.
Force Transmit
Timer
When the specified amount of time, in milliseconds, elapses after the first
character is written by the application, the packet is transmitted. A value of
zero (0) ignores this parameter. Valid values are 0-65535 ms. The default is 0.
End Trigger1
Character
When enabled, specifies the character that when written by the application will
define when the packet is ready for transmission. The actual transmission of
the packet is based on the Trigger Forwarding Rule. Valid values are in hex
0-FF. The default is 0.
TruePort HP-UX User Guide, Version 6.0
Configuring Packet Forwarding
End Trigger2
Character
When enabled, creates a sequence of characters that must be written by the
application to specify when the packet is ready for transmission (if the End
Trigger1 character is not immediately followed by the End Trigger2 character,
TruePort waits for another End Trigger1 character to start the End
Trigger1/End Trigger2 character sequence). The actual transmission of the
packet is based on the Trigger Forwarding Rule. Valid values are in hex 0-FF.
The default is 0.
Frame Definition
This section allows you to control the frame that is transmitted by defining the
start and end of frame character(s). If the internal buffer (1024 bytes) is full
before the EOF character(s) are received, the packet will be transmitted and the
EOF character(s) search will continue. The default frame definition is SOF=00
and EOF=00.
SOF1 Character
When enabled, the Start of Frame character defines the first character of the
frame, any character(s) received before the Start of Frame character is ignored.
Valid values are in hex 0-FF. The default is 0.
SOF2 Character
When enabled, creates a sequence of characters that must be received to create
the start of the frame (if the SOF1 character is not immediately followed by the
SOF2 character, TruePort waits for another SOF1 character to start the
SOF1/SOF2 character sequence). Valid values are in hex 0-FF. The default is
0.
Transmit SOF
Character(s)
When enabled, the SOF1 or SOF1/SOF2 characters will be transmitted with
the frame. If not enabled, the SOF1 or SOF1/SOF2 characters will be stripped
from the transmission.
EOF1 Character
Specifies the End of Frame character, which defines when the frame is ready to
be transmitted. The actual transmission of the frame is based on the Trigger
Forwarding Rule. Valid values are in hex 0-FF. The default is 0.
EOF2 Character
When enabled, creates a sequence of characters that must be received to define
the end of the frame (if the EOF1 character is not immediately followed by the
EOF2 character, TruePort waits for another EOF1 character to start the
EOF1/EOF2 character sequence), which defines when the frame is ready to be
transmitted. The actual transmission of the frame is based on the Trigger
Forwarding Rule. Valid values are in hex 0-FF. The default is 0.
Trigger Forwarding Determines what is included in the Frame (based on the EOF1 or EOF1/EOF2)
Rule
or Packet (based on Trigger1 or Trigger1/Trigger2). Choose one of the
following options:
z
Strip-Trigger—Strips out the EOF1, EOF1/EOF2, Trigger1, or
Trigger1/Trigger2, depending on your settings.
z
Trigger—Includes the EOF1, EOF1/EOF2, Trigger1, or
Trigger1/Trigger2, depending on your settings.
z
Trigger+1—Includes the EOF1, EOF1/EOF2, Trigger1, or
Trigger1/Trigger2, depending on your settings, plus the first byte that
follows the trigger.
z
Trigger+2—Includes the EOF1, EOF1/EOF2, Trigger1, or
Trigger1/Trigger2, depending on your settings, plus the next two bytes
received after the trigger.
TruePort HP-UX User Guide
17
Configuring Packet Forwarding
pktfwdcfg.tp File Format
The packet forwarding configuration file is called pktfwdcfg.tp and is broken up into ports and
their defined values as shown in the example below:
[10001]
packet_size = 1
idle_time = 2
force_transmit_time = 3
[mysds:10002]
SOF1_char = aa
SOF2_char = bb
transmit_SOF_chars = off
EOF1_char = cc
EOF2_char = dd
trigger_forwarding_rule = trigger
[yoursds:10003]
packet_size = 1000
idle_time = 99
force_transmit_time = 10000
end_trigger1_char = aa
end_trigger2_char = bb
trigger_forwarding_rule = trigger
[172.16.44.21:10004]
packet_size = 1000
idle_time = 99
force_transmit_time = 10000
end_trigger1_char = aa
end_trigger2_char = bb
trigger_forwarding_rule = trigger
18
TruePort HP-UX User Guide, Version 6.0
Configuring SSL/TLS
Configuring SSL/TLS
The SSL/TLS feature is designed to work with the IOLAN Family SDS Device Server models. When
TruePort is used with the Device Server, the cipher specified by the Device Server will be used for
the TruePort connection. Also, if the Device Server is set for SSL/TLS Type Server, then you need to
set the TruePort SSL type to client, and vice versa.
SSL/TLS Configuration Information
SSL/TLS is configured using the addports or tpadm utilities. If SSL/TLS is enabled, the following
prompts will ask for the SSL/TLS configuration information:
Certificate file name (full path and file name): /etc/trueport/sslcert.pem
SSL type (client or server): client
SSL/TLS version (any, TLSv1, or SSLv3]: any
Perform peer verification (y/n): y
The next section is asked only if peer verification is performed. If you press Enter instead of entering
a value, the parameter will not appear in the sslcfg.tp file for peer validation.
Note:
The values that you enter here are case sensitive, so the peer certificate must match exactly
or the connection will fail.
CA file name (full path and file name): /etc/trueport/ca.pem
Country (2 letter code): CA
State or Province: Ontario
Locality (e.g. city): Markham
Organisation (e.g. company): Acme Software
Organisation Unit (e.g. section): Engineering
Common Name (e.g. your name or your server's hostname): hpux50
Email Address: [email protected]
The following section provides more information about the SSL/TLS configuration parameters:
Certificate file name The full path and file name of the certificate file. If you press Enter, the default
path, /etc/trueport/sslcert.pem, will be used.
SSL type
Specify whether the TruePort daemon will act as an SSL/TLS client or server.
SSL/TLS version
Specify whether you want to use:
z
Any—The TruePort daemon will try a TLSv1 connection first. If that
fails, it will try an SSLv3 connection. If that fails, it will try an SSLv2
connection.
z
TLSv1—The connection will use only TLSv1.
z
SSLv3—The connection will use only SSLv3.
Perform peer
validation
The certificate received from the peer will be verified against the CA list,
along with any values entered in the validation criteria, for an SSL connection;
any fields left blank will not be validated against the peer certificate.
CA file name
The full path and file name of the CA (certificate authority) file. If you press
Enter, the default path, /etc/trueport/ca.pem, will be used.
Country
A two character country code; for example, US.
TruePort HP-UX User Guide
19
Configuring SSL/TLS
State or Province
Up to a 128 character entry for the state/province; for example, IL.
Locality
Up to a 128 character entry for the location; for example, a city.
Organisation
Up to a 64 character entry for the organisation; for example, Acme Software.
Organisation Unit
Up to a 64 character entry for the unit in the organisation; for example, Payroll.
Common Name
Up to a 64 character entry for common name; for example, the host name or
fully qualified domain name.
Email Address
Up to a 64 character entry for an email address; for example,
[email protected]
SSL/TLS Support Files
When you enable the SSL/TLS option for a port, you need to make sure the TruePort host and Device
Server have the appropriate support files: certificates/private keys and/or the CA list file. The IOLAN
DS Family SDS model CD-ROM contains a self-signed RSA certificate named samplecert.pem.
The samplecert.pem file can be used for both the certificate file on the SSL/TLS server and the
CA list file on the SSL/TLS client.
TruePort Port Configured as SSL/TLS Server
When the TruePort port is configured as an SSL/TLS server, the SSL/TLS private key and certificate
is required for all key exchange methods except ADH (Anonymous Diffie-Hellman). The private key
cannot be encrypted since TruePort on HP-UX does not support the configuration of an SSL/TLS
passphrase. The private key needs to be appended to the certificate file, to create one
certificate/private key file. This can be done using the HP-UX command
cat myprivatekey.pem >> mycert.pem. This certificate/private key file then becomes the
TruePort certificate. Copy the TruePort certificate file to the directory you specified in the SSL/TLS
configuration.
If the TruePort SSL/TLS server is configured to verify an SSL client, a CA list file is also required.
The CA list file is a certificate, or list of certificates, of the Certificate Authorities (CA) who created
and signed the peer certificates (the peer certificate(s) must be downloaded to the Device Server).
TruePort Port Configured as SSL/TLS Client
When the TruePort port is configured as an SSL/TLS client and peer verification is configured, a CA
list file is required. The CA list file is a certificate, or list of certificates, of the Certificate Authorities
(CA) who created and signed the peer certificates (the peer certificate(s) must be downloaded to the
Device Server). This CA list file should be copied to the TruePort host directory specified in the
SSL/TLS configuration.
Pseudo Random Number Generator
If you want to use the SSL/TLS encryption on a TruePort connection an external Random Number
Generator is required on the host system. This is available for each of the following HP-UX versions:
20
z
HP-UX 11iv2 has SRNG (Strong Random Number Generator) already built in.
z
HP-UX 11i requires SRNG (Strong Random Number Generator) and can be downloaded from
the HP website, HP-UX Strong Random Number Generator.
z
HP-UX 11.0 PRNG can be downloaded from: http://freshmeat.net/projects/hpux11-random/
TruePort HP-UX User Guide, Version 6.0
Configuring SSL/TLS
sslcfg.tp File Format
The sslcfg.tp file is created in the following format:
[10001]
certificate-file = /etc/trueport/sslcert.pem
ssl-type = server
ssl-version = any
verify-peer = yes
CA-file = /etc/trueport/ca.pem
country = CA
state-province = Ontario
locality = Markham
organisation = Acme Software
organisation-unit = Engineering
common-name = hpux50
email = [email protected]
[yoursds:10002]
certificate-file = /etc/trueport/sslcert.pem
ssl-type = client
ssl-version = TLSv1
verify-peer = yes
CA-file = /etc/trueport/ca.pem
country = UK
locality = London
common-name = hpuxuk
The [10001] specifies the port for which the SSL/TLS configuration parameters are configured.
SSL/TLS Trouble Shooting
If you are experiencing problems obtaining a successful SSL/TLS connection, you can add the
-trace 4 option at the end of the appropriate port entry in the config.tp file. After editing the
config.tp file, you will have to kill the TruePort daemon process for the port and restart it again.
Adding the -trace option will create a trace file called /etc/trueport/trace.xxxxx, where
xxxxx is the controlling TTY name; for example, /etc/trueport/trace.tpm0.
Could not obtain peer's certificate
Reason 1
User has selected a cipher key exchange of ADH (anonymous Diffie-Hellman)
and enabled Peer verification. ADH does not use certificates so they will not
be sent in an SSL/TLS handshake.
Solution 1
Disable Peer Verification or change to a cipher suite that uses certificates.
Reason 2
User has selected Peer Verification on the configured SSL/TLS server and has
not configured a certificate for the client.
Solution 2
Either disable peer verification on the SSL/TLS server or configure a
certificate for the SSL/TLS client.
SSL_accept failed on the SSL/TLS server device.
Reason
The device has failed to accept an SSL/TLS connection on top of a TCP
connection that has just been established. This could indicate that the peer from
which TruePort is trying to accept a connection from is not configured for
SSL/TLS.
Solution
Verify that the peer has been configured for an SSL/TLS client connection.
TruePort HP-UX User Guide
21
Configuring SSL/TLS
Certificate did not match configuration
Reason
The message is displayed when Verify Peer Certificate has been enabled, but
the configured Validation Criteria does not match the corresponding data in
the certificate received from the peer.
Solution
The data configured must match exactly to the data in the certificate. The data
is also case sensitive.
Encrypted private keys are not supported in TruePort
Reason
This message is displayed by the TruePort daemon when the user has created a
certificate with an encrypted private key for TruePort. This applies to either
Client mode or Server mode with configured peer validation criteria.
Solution
Create a certificate with a private key that is not encrypted.
unknown protocol message when trying to make an SSL/TLS connection
Reason 1
This will be displayed when both sides of the TCP connection are configured
as SSL/TLS clients.
Solution 1
Change one of the end points to act as an SSL/TLS server.
Reason 2
One of the endpoints is not configured for SSL/TLS.
Solution 2
Make sure both endpoints are configured for SSL/TLS, verify that one is a
client and the other is a server.
tlsv1 alert handshake failure or sslv3 alert handshake failure
Reason
The remote site has an SSL/TLS error and is sending this message with an alert
message.
Solution
Look at the error messages on the remote end and fix the problem indicated.
Certificate verify failed.
22
Reason 1
TruePort has been configured to verify the peer certificate and there is a
mismatch between the peer’s certificate and the TruePort CA list.
Solution 1
Make sure the CA lists contains the certificate of the CA which signed the
peer’s certificate.
Reason 2
The peer’s certificate or the CA certificate might have expired. Each certificate
is created with a valid date interval.
Solution 2
Make sure the certificate of the peer and CA are up to date. Also verify that the
host has the correct date/time. If the date configured on the host is not correct,
it can make it look like the certificate is invalid.
TruePort HP-UX User Guide, Version 6.0
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement