HPUX ddfa[7]
ddfa(7) ddfa(7)
NAME
ddfa - HP DTC Device File Access software
DESCRIPTION
The HP Datacommunications and Terminal Controller (DTC) Device File
Access (DDFA) software allows access from HP-UX systems and user-
written applications to HP DTCs using standard HP-UX structures. DDFA
provides an interface to remote (LAN-connected) DTC ports that is
similar to the interface for local mux ports.
The basic principle is that a daemon is created for each configured
port based on information in a configuration file (dp 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 user applications use
the pseudonym to access the server port using standard HP-UX
intrinsics (open(), close(), write(), etc). The daemon listens on the
pty until an application does an open(pseudonym), then it manages the
connection to the server port. The end result is that the server port
is addressed via a device file, but the mechanism that makes it happen
is transparent to the user. For example, the lpadmin command can be
used to set up a connection to a printer on a remote server port by
using the pseudonym. A second configuration file (pcf) contains
information to profile the port's behavior.
DDFA consists of the following items:
dp Dedicated Port configuration file. This text file
contains the information DDFA needs to set up and
manage a connection to a specified DTC port. It
contains a one-line entry for each configured DTC port;
the line specifies the board and port, the pseudonym,
and the path to the Port Configuration File (pcf).
The dp file is parsed by the Dedicated Port Parser
(dpp) which spawns an outgoing connection daemon (ocd)
for each connection specified in the file.
dp is also used by the HP-UX telnet daemon (telnetd) to
identify incoming connections. In this usage, the
daemon negotiates the telnet environment option, and
the DTC returns the board and port numbers of the
connecting device. telnetd then looks up the port and
board numbers in the dp file and maps them to the
pseudonym (see dp(4) for more information).
There are two ways to specify a port: explicitly
specify its IP address, or specify the IP address of
the server, the board, and the port. Alternately, the
server's IP address and the TCP service port address of
the port can be given.
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
ddfa(7) ddfa(7)
pcf Port Configuration File. This file is used by DDFA to
configure specific port parameters. pcf is the generic
name of the template file. In practice it is renamed
for each port, and the values are altered appropriately
for the device attached to the port. The pcf is
referenced by an entry in the Dedicated Ports file
(dp). The Dedicated Port Parser (dpp) parses the dp
file and calls the Outbound Connection Daemon (ocd)
program to spawn a daemon for each valid line in the dp
file. A valid line is one in which the fourth field is
the name of a pcf.
dpp Dedicated Port Parser. dpp parses the Dedicated Ports
file (dp) and calls the Outbound Connection Daemon
(ocd) to spawn a daemon for each valid entry in dp. It
can be run from the shell or it can be included in
netlinkrc to automatically run the DDFA software each
time the system is booted.
dpp has one mandatory argument, the path to the dp
file. The other arguments specify an optional log
file, the path to ocd if it is not the default, and an
option to kill existing processes when the dp file is
parsed. dpp can also be run in check mode, where it
simply parses the dp file and reports any errors.
ocd Outbound Connection Daemon. ocd manages the connection
and data transfer to the remote DTC port. Normally, it
is spawned by the Dedicated Port Parser (dpp), but it
can be run directly from the shell. If it is run from
the shell, the name or IP address of the server or port
and the pseudonym (device file name) must be entered on
the command line. The board/port number or TCP service
port address must be entered if the IP address does not
explicitly name a port.
ocd creates a device file for the connection using a
file name that is determined by the pseudonym argument.
If ocd encounters an error condition that causes it to
exit, it normally removes the device file it created.
If a device file is accidentally deleted, the
corresponding ocd continues running for at least 30
seconds before it detects the absence of the device
file. The ocd then writes an error message to
/sys/adm/syslog and exits.
ocdebug Outbound Connection Daemon debug mode. ocdebug is a
special version of ocd that contains debug code.
ocdebug has to be run from the shell with all the
arguments that would normally come from the dp file
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
ddfa(7) ddfa(7)
entered on the command line. Except for -d, the
arguments are the same as the ocd arguments. The -d
option specifies the level of debugging messages.
INSTALLATION
DDFA is provided in update format, and is installed using the standard
HP-UX update command (see update(1M).
Note that update can install software from a tape or a file whose name
has the suffix .updt. To install from a file, specify the file name
ddfa.updt instead of the device, such as /dev/rct/cldos2. For more
information refer to the file readme.ddfa which contains installation
instructions.
The files, their default directories, and the correct access
permissions are shown below. All files should be owned by user bin,
group bin:
-r-xr--r-- /etc/dpp
-r-xr--r-- /etc/ocdebug
-r-xr--r-- /etc/ocd
-rw-r--r-- /etc/newconfig/ddfa/pcf
-rw-r--r-- /etc/newconfig/ddfa/dp
-rw-r--r-- /etc/dpp_login.bin
-rw-r--r-- /etc/utmp.dfa
-rw-r--r-- /etc/readme.ddfa
-r--r--r-- /usr/man/man1m.Z/dpp.1m
-r--r--r-- /usr/man/man1m.Z/ocd.1m
-r--r--r-- /usr/man/man1m.Z/ocdebug.1m
-r--r--r-- /usr/man/man4.Z/dp.4
-r--r--r-- /usr/man/man4.Z/pcf.4
-r--r--r-- /usr/man/man7.Z/ddfa.7
CONFIGURATION
There are two basic steps to configuring DDFA software:
o Entering information in the dp file,
o Entering information in the pcf files.
Configuring the dp file
The dp file contains one line for each connection that is to be
established. A template dp file is provided (/etc/newconfig/ddfa/dp)
which can be edited directly or a separate file created. It is
recommended that the file be copied and the copy edited. We suggest
you create the directory /etc/ddfa to contain dp and the pcfs. Note
the following points:
o The default file is /etc/newconfig/ddfa/dp; if another file
name or path is used, this information must be passed as an
argument to dpp (see dpp(1M) for details), whether it is run
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
ddfa(7) ddfa(7)
from the command line or from netlinkrc.
o The exact order of the fields in dp must be maintained:
IP_address board/port pseudonym pc_file_path
o Fields can be separated by spaces or tabs.
o Only one entry is allowed per line.
o Comments can be appended using the # character: everything
after the # on any given line is ignored by the parser.
o There are three ways to specify the DTC port: by explicitly
giving its IP address, by giving the IP address of the server
and then specifying the port and board, or by giving the IP
address of the server and the TCP service port address of the
port.
o It is recommended that the pcf and device file (pseudonym) are
named appropriately so that both can be easily identified
(such as when listing processes with ps -ef). For example,
the pcf could be named pcf_lp1 and the device file (pseudonym)
ocd_lp1, or the pcf could be named pcf_dtc1b2p3 and the device
file could be named ocd_dtc1b2p3.
dp file entries contain the following fields:
IP_address This is the IP address of the DTC being
accessed, or the IP address of the port on the
DTC.
board/port This field contains the DTC board and port
numbers, separated by a / character. The board
and port numbers are not checked by dpp, but
are checked by ocd. Valid values are 0 to 7
for the board, and 0 to 31 for the port (these
restrictions do not apply if a TCP service port
address is given instead).
If the IP_address field explicitly defines the
DTC port, the value in the port/board field
must be xx/xx (use X or x).
If the entry is of the form xx/n where n is a
decimal number, n is taken to be the TCP port
address, and this value is used when the
connection is established; otherwise, the
destination is filled using the formula
(256x(32xboard+port+1)+23).
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
ddfa(7) ddfa(7)
pseudonym This is the absolute path and name of the
device file known to the system and/or the end
user application. The device file name is
limited to 14 characters. We recommend that
the name reflects the connected device, and is
similar to the pcf name, for example
ocd_dtc1b1p1.
pc_file_path This is the path to the Port Configuration File
(pcf) that contains the configuration
information for the DTC port. This field is
mandatory because the parser dpp uses the
presence of this field as its flag to spawn a
daemon for the line. We recommend that the
name of the file reflect the connected device,
and be similar to the pcf name, for example
pcf_dtc1b1p1.
The following examples illustrate the structure of typical dp file
entries.
A printer is connected to port 1 of board 3 of a DTC at IP address
11.234.87.123. The printer attached to the port can be accessed with
the HP-UX spooler by specifying device file /dev/ocd_1p1 in the
lpadmin command. The port is profiled using data in the file
/etc/ddfa/pcf_lp1:
11.234.87.123 03/01 /dev/ocd_lp1 /etc/ddfa/pcf_lp1 # lp1 b1,n2,f7
A printer is connected to the DTC port at IP address 11.234.87.124, so
the board/port field contains xx/xx. File pcf_lp2 contains port
profiling information.
11.234.87.124 xx/xx /dev/ocd_lp2 /etc/ddfa/pcf_lp2 # lp2 b2,n1
Specify a port using a TCP port address. The port address is
calculated using the formula (256x(32xboard+port+1)+23).
11.234.87.215 xx/16919 /dev/ocd_lp3 /etc/ddfa/pcf_lp3 # lp3 b2,p1
Configuring the pcfs
Port Configuration Files (pcf) are used to configure individual server
ports. /etc/newconfig/ddfa/pcf is a template file; in practice it
should be renamed for each port, and the values it contains altered to
suit the device attached to the port. We recommend you create the
directory /etc/ddfa to contain the modified pcfs and the modified dp
file. The pcf is referenced by an entry in the Dedicated Ports file
(dp). The Dedicated Port Parser (dpp) parses the dp file and calls
the Outbound Connection Daemon (ocd) program to spawn a daemon for
each valid line in the dp file; a valid line is one in which the
fourth field is the name of a pcf.
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992
ddfa(7) ddfa(7)
Note the following points:
o The order of the variables is not important.
o The file consists of the names of variables and their values.
The variables in the template file are shown terminated by a
colon (:), but this is not mandatory.
o The variables and their values can be separated by spaces or
tabs.
o Only one variable-value pair is allowed per line.
o Only the value should be altered; the variable name must
remain the same.
o If you want to use the default values, simply reference the
template file /etc/newconfig/ddfa/pcf in the dp file.
o If you want to use different values for a port, make a copy of
/etc/newconfig/ddfa/pcf. It is a good idea to name the file
appropriately for the pseudonym (device file); for example,
pcf_dtc1b2p3.
The file contains the following information:
telnet_mode: Recognized values are disable and enable. When
enabled, data transfer over the network uses
Telnet protocol. This option must be enabled
for the DTC
timing_mark: Recognized values are enable and disable. When
enabled, a telnet timing-mark negotiation is
sent to the DTC after all user data has been
transferred. ocd waits for a reply to the
timing mark negotiation before closing the
connection. This ensures that all data has been
output from the DTC buffers to the device before
the buffers are flushed. It should therefore be
enabled for the DTC.
telnet_timer: Defines the time, in seconds, during which the
software waits for a response to the telnet
timing mark and binary negotiation. If the
timer expires, an error message is logged to
/usr/adm/syslog and the error is transmitted to
the user application.
binary_mode: Recognized values are disable and enable. When
it is enabled, data transfer over the network is
in binary mode, and treatment of special
Hewlett-Packard Company - 6 - HP-UX Release 9.0: August 1992
ddfa(7) ddfa(7)
characters (such as XON/XOFF) is disabled.
Due to the absence of flow control, data
integrity cannot be guaranteed when binary_mode
is enabled.
Note that even if binary_mode is disabled, it
can be negotiated at any time by the application
setting IXON to zero in the termio data
structure.
open_tries: This defines the number of times the software
tries to open a connection before giving up. If
the value is 0 the software tries ``forever''
(approximately 68 years). If the retry process
fails, an error message is logged to
/usr/adm/syslog. The error message is also
transmitted to the user application.
The retry process can be interrupted by sending
the SIGUSR2 signal to the ocd process by using
kill -17 pid.
Note that if the application exits after asking
ocd to open the connection to the DTC, ocd
continues trying to open until open_tries and/or
open_timer are exceeded.
open_timer: Defines the time, in seconds, between tries. If
the value is 0, ocd uses an exponential retry
period algorithm up to 32 seconds; that is, 1 2
4 8 16 32 32 32 ...
close_timer: Defines the time, in seconds, between the close
call made by the application on the pty slave
and the moment when the connection is actually
closed. Setting this value to, for example, 5
seconds avoids the overhead of opening and
closing the connection when a spooler spools
several files at a time. Setting a sufficiently
high value effectively leaves the connection
permanently open.
status_request: Recognized values are disable and enable. When
enabled, the software sends a status request to
the printer attached to the server and processes
the reply as follows:
LP_OK (0x30) ocd continues
processing.
Hewlett-Packard Company - 7 - HP-UX Release 9.0: August 1992
ddfa(7) ddfa(7)
LP_NO_PAPER (0x31) ocd retries
within the limits of
the status timer.
LP_BUSY (0x32) ocd retries
within the limits of
the status timer.
LP_OFF_LINE (0x23) ocd retries
within the limits of
the status timer.
LP_DATA_ERROR (0x38) ocd retries
within the limits of
the status timer.
status_timer: Defines the time, in seconds, after which the
software no longer waits for the reply to the
status request. If the timer expires, an error
message is logged to /usr/adm/syslog. The error
condition is also transmitted to the user
application.
eight_bit: Recognized values are enable and disable.
Normally, data bytes processed by the pty have
bit 7 stripped. If eight_bit is enabled, the
stripping is disabled. If eight_bit is
disabled, stripping is enabled, and bit 7 is
stripped. This can also be achieved by changing
the pseudonym's termio structure using the
ioctl() commands.
tcp_nodelay: Recognized values are enable and disable.
If enabled, data is sent to the LAN as it is
received. It can be disabled if the software is
sending packets faster than the server can
accept.
Default values are:
telnet_mode: enable
timing_mark: enable
telnet_timer: 120
binary_mode: disable
open_tries: 1500
open_timer: 30
close_timer: 0
status_request: disable
status_timer: 30
eight_bit: disable
Hewlett-Packard Company - 8 - HP-UX Release 9.0: August 1992
ddfa(7) ddfa(7)
tcp_nodelay: enable
Configuring netlinkrc
DDFA can be run at boot time by including a reference to dpp in
netlinkrc. dpp is run, the dp file is read, and the appropriate
processes created. It is recommended that the -k option be used, for
example:
dpp:2:once:/etc/dpp /etc/ddfa/dp_file -k
ERROR HANDLING
When ocd receives a serious error condition, such as when the LAN goes
down, ocd transmits the error conditions to the application by closing
the pty. Any open(), close(), 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.
KILLING DAEMONS
Outbound Connection Daemons (ocds) should be killed using kill -15.
kill -9 is not recommended because the device file remains open. ocd
verifies the validity of an existing pseudonym before trying to use
it. dpp and ocd use data stored in file /etc/utmp.dfa to verify
whether a process still owns a pseudonym before taking it over. If
ocd finds an unowned pseudonym, it will use it.
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 include modem signal control and parity
checking. The following are not available:
IGNPAR INPCK IXOFF
PARMRK IXANY CBAUD
ioctl() Request Limitations
The following ioctl() request limitations apply:
TERMIO structure:
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
Hewlett-Packard Company - 9 - HP-UX Release 9.0: August 1992
ddfa(7) ddfa(7)
handles auto parity detection for
even or odd parity.
PARENB flags Enabling/disabling done via static
configuration. No programatic
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 enabed
when ASCII mode is selected in
static port configuration and
disabled when binary mode is
selected.
IXANY flag DTC does not offer 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
TELNETD-DTC software.
Hewlett-Packard Company - 10 - HP-UX Release 9.0: August 1992
ddfa(7) ddfa(7)
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 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.
Hewlett-Packard Company - 11 - HP-UX Release 9.0: August 1992
ddfa(7) ddfa(7)
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
FILES
/etc/dpp
/etc/ocdebug
/etc/ocd
/etc/dpp_login.bin
/etc/utmp.dfa
/etc/newconfig/ddfa/pcf
/etc/newconfig/ddfa/dp
SEE ALSO
dpp(1M), ocd(1M), ocdebug(1M), ioctl(2), dp(4), pcf(4) ioctl(5).
Hewlett-Packard Company - 12 - HP-UX Release 9.0: August 1992