ddfa(7)

NAME

ddfa — Data Communications and Terminal Controller (DTC) Device File Access (DDFA) software

DESCRIPTION

The Data Communications and Terminal Controller (DTC) Device File Access (DDFA) software allows access from HP-UX system utilities and user applications to terminal servers using standard HP-UX structures. DDFA provides an interface to remote LAN-connected terminal server ports that is similar to the interface for local directly-connected ports.

The basic principle is that a daemon is created for each configured terminal server port based on information in a configuration file (a Dedicated Ports file). When the daemon is spawned, it takes a pty from the pool and creates a device file with the same major and minor number as the pty slave. The device file is known as the "pseudonym" and utilities and applications use the pseudonym to access the terminal server port by exercising standard HP-UX system functions (open(), close(), read(), write(), and ioctl()). The daemon listens on the pty until an application does an open() on the pseudonym. It then sets up and manages the connection to the terminal server port until the application does a close() on the pseudonym. The end result is that the terminal server port is addressed via a device file, but the mechanism that makes it happen is transparent to the user. A second configuration file (a port configuration file) contains information to profile the terminal server port.

DDFA consists of the following items:

dp

Dedicated Ports file. This text file contains the information that DDFA needs to set up and manage a connection between a pseudonym and a terminal server port.

The dp file is parsed by the Dedicated Port Parser (dpp) which spawns an Outbound Connection Daemon (ocd) for each outbound connection specified in the file. The dp file is also used by the HP-UX Telnet daemon (telnetd) to identify incoming connections from a DTC and map them to a pseudonym (the Telnet port identification feature).

pcf

Port Configuration File. This text file is used by DDFA to profile the terminal server port. The generic name of the template file is pcf. A port configuration file is referenced by an entry in the Dedicated Ports file (dp).

dpp

Dedicated Port Parser. This command parses the Dedicated Ports file (dp) and spawns an Outbound Connection Daemon (ocd) for each valid entry in the dp file. It can be run from the shell or it can be included in a system initialization script to automatically run the DDFA software each time the system is booted.

ocd

Outbound Connection Daemon. This daemon manages the connection and data transfer to the remote terminal server port. Normally, it is spawned by the Dedicated Ports Parser (dpp), but it can be run directly from the shell.

As it starts, it creates its pseudonym for the connection. As it terminates normally, it removes the pseudonym. If the pseudonym is removed while it is running, ocd will terminate with an error condition.

ocdebug

Outbound Connection Daemon debug mode. This is a special version of ocd that contains debugging code. It must be run from the shell.

CONFIGURATION

There are two basic steps to configuring the DDFA software:

Enter information in the dp file.
Enter information in the port configuration files.

Configuring the dp File

The dp file contains one line for each outbound connection that is to be established and one line for each incoming connection request. A default file /usr/examples/ddfa/dp should be copied to a new file and the copy edited as needed. It is recommended that a directory be created to hold the dp file and the port configuration files.

Each line of the dp file must contain the location of the terminal server port and the location of the pseudonym. In addition, for an outbound connection, the port configuration file must be specified and a logging level may be specified.

Configuring the Port Configuration Files

A port configuration file is used to configure individual terminal server ports. A master port configuration file is /usr/examples/ddfa/pcf. In practice, it is renamed for each port that needs different configuration values and the values are altered appropriately for the device attached to the port. It is recommended that a directory be created to hold the port configuration files and the dp file.

Each line of a port configuration file must consist of a name of a variable and its value. The variable-value pairs contain information on how to open a connection to a terminal server port, how to close a connection to a terminal server port, and how to manage the data transfer to a terminal server port.

Configuring a System Initialization Script

DDFA can be run at boot time by including a reference to dpp in a system initialization script. It is recommended that the -k option be used when running dpp in this environment.

KILLING DAEMONS

Note that ocd should be killed using kill -15. Do not use kill -9 for this purpose as it does not remove the device file. ocd verifies the validity of an existing pseudonym before trying to use it. dpp and ocd use data stored in the file /var/adm/utmp.dfa to verify whether a process still owns a pseudonym before taking it over. If ocd finds an unowned pseudonym, it uses it.

ERROR HANDLING

When ocd receives a serious error condition, such as when the LAN goes down, it transmits the error condition to the application by closing the pty. Any open(), close(), read(), or write() to the pseudonym returns the error condition 0 bytes read. If the pseudonym is the controlling terminal for the group to which the application belongs, SIGHUP is sent to all the processes in the group, including the application.

ioctl() LIMITATIONS

Not all ioctl() functionality is available, due to the lack of a protocol that allows the transmission of such commands over the LAN to the remote port.

termio Attribute Limitations

The main restrictions on termio attributes (see termio(7)) include modem signal control and parity checking. The following are not available:

CBAUD IGNPAR INPCK IXANY IXOFF PARMRK

ioctl() Request Limitations

The following ioctl() request limitations apply:

CSTOPB flag

DTC only supports one stop bit.

CSIZE

DTC only supports 8 bits per character. Value cannot be modified.

PARODD flag

DTC offers static configuration to handle even or odd parity. It also handles auto parity detection for even or odd parity.

PARENB flags

Enabling/disabling done via static configuration. No programmatic interface supplied.

INPCK flag

No way to separate input from output parity features.

IGNPAR flag

Cannot be configured on DTC.

PARMRK

Bad characters are forwarded to the system without marking them with OFFH or OH.

CBAUD

Speed is part of static configuration.

IXOFF flag

Flow control is enabled if the DTC static configuration specifies an ASCII access mode. If binary is selected, no flow control is provided.

IXON flags

Pacing of output to a terminal via a programmatic interface is enabled when ASCII mode is selected in static port configuration and disabled when binary mode is selected.

IXANY flag

DTC does not offer the ability to restart output on any character received if XOFF was previously received.

HUPCL flag

DDFA does not support the hanging up of modem signals on the last close of the device file. If the modem signals used on the DTC drop, the connection is closed.

CLOCAL flag

Not supported.

c_flags

IENQACK not supported.

OFILL, OFDEL, NLDLY, CRDLY, TABDLY, BSDLY, FFDLY not supported by Telnet port identification software.

BINARY mode flags

Part of static configuration is done in DTC Manager by selecting binary mode. If switching is enabled, binary can be selected at user interface level. There is no way to automatically negotiate binary mode when proper termio flags are reset when using telnetd. Binary/ASCII switching is possible with DDFA. The DTC cannot support large reads in pure binary mode, so transferred blocks of data should not be more than 256 bytes. If half-duplex with remote acknowledgement is implemented, binary applications can be supported.

ioctl() System Call Requests

The following ioctl() system call limitations apply:

TCSBRK: The ability to send a break without waiting for previous data to be sent is not provided at the system level in telnetd or DDFA. Receiving a Telnet break command in the DTC allows it to generate a break on asynchronous ports.
TCFLSH: The DTC output queue cannot be flushed.
Hardware handshake request: Not supported on DTC.
TCXONC: Local handshake cannot be disabled on DTC.
MCGETA: Not supported.
MCSETA, MCSETAF, MCSETAW: There is no way to separately set modem lines of a DTC port.
MCGETT: Modem timers, CD timer, connect timer, and disconnect cannot be configured.
CCITT simple, and direct call-in/call-out modes: DTC cannot handle simple mode because there is programmatic interface for modem signals. Call-in mode cannot be simulated if the port is opened, because modem signals (or the call) must be present within 2 minutes or the connection is cleared.
DACIDY get device adapter info: No way to get device adapter information.
Download ioctl() DACRADDR, DACDLADDR, DACDLGO, DACDLVER: No programmatic call to download the DTC.
DACHWSTATUS, DACSELFTEST, DACLOADED, DACISBROKE status: No programmatic interface to get such info.
DACLOOPBACK DACSUBTEST port test

WARNINGS

In order to ensure that commands (such as ps) display the correct device file name (that is, the pseudonym), all pseudonyms should be placed into the directory /dev/telnet. If pseudonyms are not specified for placement in this directory, the correct display of device file names with many commands is not guaranteed.

In addition, in order to ensure that commands (such as w, passwd, finger, and wall) work correctly, each pseudonym must be unique in its first 17 characters (including the directory prefix /dev/telnet/). If pseudonyms are not unique in their first 17 characters, the correct functioning of many commands is not guaranteed.

Also, in order to reliably handle timing mark negotiations (and ensure that files printing on a printer attached to a terminal server have been completely flushed to that printer), the following line must be added near the end of each printer interface script for printers attached to a terminal server:

stty exta <&1 2>/dev/null 

The printer interface scripts reside in the directory /etc/lp/interface. The line must be added just prior to the final exit command in each printer interface script.

If this line is not added as specified, the printing reliability of printers attached to a terminal server is not guaranteed.

FILES

/usr/examples/ddfa/dp
/usr/examples/ddfa/pcf
/usr/sbin/dpp
/usr/sbin/ocd
/usr/sbin/ocdebug
/var/adm/dpp_login.bin
/var/adm/utmp.dfa