DragonFly On-Line Manual Pages
COMSERVD(8) DragonFly System Manager's Manual COMSERVD(8)
NAME
comservd - make network terminal server serial ports accessible via /dev
SYNOPSIS
comservd [-f config_file]
DESCRIPTION
The comservd program provides a facility to access network terminal
server serial ports, such as those available on Xyplex terminal server
models, via /dev device file entries. This allows programs such as
tip(1) to access devices connected to the terminal server serial ports.
Comservd can also serve local serial ports to remote systems via the
network, turning the local system into a network terminal server with
respect to its own local serial ports. At startup, comservd loads and
executes commands from its configuration file.
The options are as follows:
-f config_file
At startup, read configuration commands from the file config_file
instead of the default /usr/local/etc/comservd.conf.
The configuration file should contain the commands required to tell
comservd what terminal server ports to attach to and name the local
device file used to access those ports. It also contains which local
serial ports the localhost will serve out via the network, making it
function like a terminal server itself. See below for a few examples.
The complete list of valid commands are:
add devid devname host hwport tcpport logspec
Add a remote endpoint to local enpoint mapping. This associates
the device file named by devname with the terminal server, serial
port, and tcp port named by host, hwport and tcpport. If devname
is not an absolute path, it is taken relative to the path
specified by the devdir command. comservd creates the device
name named by devname which is a symbolic link to the slave side
of a pty(4) device. comservd opens the master side of the pty(4)
pair. Logspec may be log, nolog, or a filename. If log is used,
the log file is the same as was specified for the device id and
is relative to the path specified by the logdir command. If
anything other than log or nolog is used, it is treated as a
filename. Relative filenames are treated relative to the path
specified by the logdir command.
ctl devid devname
Add a control port to local enpoint mapping. This allows one to
establish a direct local command mode connection to the daemon on
the specified device file named by devname.
devdir path
Specify the default path to place symbolic links to pty(4) device
files. The devdir path is the default location for relative
device names specified in the devname field of the add command.
endpoints
List local and remote endpoint connections.
help, ?
Print a list of valid commands.
list List all device ids and their corresponding device and log files.
logdir path
Specify the default path to place session log files. The logdir
path is the default directory to place log files specified in the
logspec field of the add command. Each connection may have a log
file to which the data flow is logged.
quit Quit command mode and disconnect from the daemon.
restart
Restart the daemon.
serve devid devname hwport tcpport logspec
Specify a local serial port to serve over the network at the
specified TCP port. The serial port is named by devname, with
the serial port number specified by hwport. The hwport value is
actually not used by comservd except for display purposes. The
TCP port number is given by tcpport. If devname is not an
absolute path, it is taken relative to the path specified by the
devdir command. Unlike the add command, serve does not create
the device named by devname. Instead, devname must be a real
device and must already exist. comservd creates a network socket
and binds it to the specified TCP port and then listens for
incoming connections. When an incoming connection is made,
comservd passes data between the network connection and the local
device. Logspec serves the same purpose as in the add command
above.
set devid parmeter = value
Set operation parameters for the device referenced by device
named by devid. The special devid global refers to parameters
that affect all connections. Valid paremeter values are:
options
Valid values for the options parameter are:
wait, nowait
wait for data on the local side before initiating
a connection to the remote side. nowait is
appropriate if the remote side functions
independently of the local side, such as when the
remote side is a serial system console. The
default is nowait.
block, noblock
block the producing side if the receiving side
can't receive the data immediately. When noblock
is in effect, data is lost if the receiver is not
ready. Regardless of the whether block or
noblock is in effect, all data is properly
written in the log file if logging is enabled.
noblock is appropriate when the producing side
must be able to continue even if there is not a
process on the receiving side to see the data.
Examples include when the remote side is a serial
system console. block is appropriate when
reliable transmission of all data between the
local and remote sides is required, even if it
means blocking one of the sides until the other
can consume the data. The default is block.
logall, nologall
When logall is specified, comservd will log all
data originating from the local side of the
connection as well as data originating from the
remote side of the connection to the log file.
When nologall is in effect, comservd will log
only data originating from the remote side of the
connection. Use nologall for most cases. The
logall option is useful when debugging a protocol
stream between two devices. The default is
nologall.
loghex, nologhex
When loghex is in effect, comservd will write its
data to the log file in hexadecimal format as
well as provide an ASCII representation and
identify the source of the data, either remote or
local. loghex is useful for debugging a protocol
stream between two devices. nologhex is
appropriate when only ASCII data is present. The
default is nologhex.
verbose
The verbose variable takes a numeric value, and the
higher the value, the more verbose the output of
comservd. At present, any setting of 1 or greater will
enable all informational messages.
The special device id global is available for setting global
options which are used as defaults for new device ids.
show devid
Show operational settings for the device id specified by devid.
shutdown
Shutdown the server.
version
Display the revision timestamp. This information is very useful
to include in bug reports.
EXAMPLES
comservd can be used for many applications. One of the more common
applications is using comservd to provide access to serial system
consoles. A Xyplex MAXserver 1600 has 16 serial ports which can be
connected to the serial console of your system. The example below
provides the setup:
#
# /usr/local/etc/comservd.conf
# Configuration file for serial consoles
# Host terminal server is named xyplex1
# Specify default directory for device log files and for device symlinks.
logdir /usr/local/comserv/log
devdir /usr/local/comserv/dev
# Define a control port
ctl comserv comserv
# Don't block the remote side of a connection if there is no one
# listening locally.
set default options=noblock
# Serve up our own com1 and com2 serial ports for remote access at
# ports 2100 and 2200 respectively.
#
# DevId Device Com# TCP/IP Port LogFile Spec
# ----- ---------- ---- ----------- ------------
serve com1 /dev/cuaa0 1 2100 nolog
serve com2 /dev/cuaa1 2 2200 nolog
# Add device nodes to point to the first 4 serial ports of 'xyplex1'.
#
# DevId Device TermSrv Termsrv TermSrv LogFile
# Symlink Hostname Port # TCP/IP Port # Spec
# ----- ------- -------- ------- ------------- -------
add srv1 srv1 xyplex1 1 2100 log
add srv2 srv2 xyplex1 2 2200 log
add srv3 srv3 xyplex1 3 2300 log
add srv4 srv4 xyplex1 4 2400 log
Add the following entries to /etc/remote:
comserv:dv=/usr/local/comserv/dev/comserv:br#9600:pa=none
srv1:dv=/usr/local/comserv/dev/srv1:br#9600:pa=none
srv2:dv=/usr/local/comserv/dev/srv2:br#9600:pa=none
srv3:dv=/usr/local/comserv/dev/srv3:br#9600:pa=none
srv4:dv=/usr/local/comserv/dev/srv4:br#9600:pa=none
One can now use a program like tip(1) to connect to comserv and issue
commands or connect to srv1-srv4 and attach to the console of the
respective machine. The console log files are placed in
/usr/local/comserv/log/srv1-srv4. Additionally, one can connect to TCP
ports 2100 and 2200 of the system running comservd and to access its
local serial ports.
To use comservd to debug the data stream between two devices, set up the
device entry as follows in /usr/local/etc/comservd.conf:
ctl comserv comserv
add ppp ppp xyplex1 1 2100 log
set ppp options=block,logall,loghex
The log file /usr/local/comserv/log/ppp will contain the data
transmission log of the form:
L 7e ff 7d 23 c0 21 7d 21 7d 21 7d 20 7d 2e 7d 25 |~.}#.!}!}!} }.}%|
L 7d 26 89 4b f6 e5 7d 27 7d 22 7d 28 7d 22 7d 2b |}&.K..}'}"}(}"}+|
L f3 7e |.~ |
R 7e ff ff 7d 23 c0 21 7d 21 7d 25 7d 20 7d 34 7d |~..}#.!}!}%} }4}|
R 22 7d 26 7d 20 7d 2a 7d 20 7d 20 7d 25 7d |"}&} }*} } }%} |
R 26 7d 25 7d 24 92 70 7d 27 7d 22 7d 28 7d 22 bb |&}%}$.p}'}"}(}".|
R c8 7e |.~ |
L 7e ff 7d 23 c0 21 7d 21 7d 21 7d 20 7d 2e 7d 25 |~.}#.!}!}!} }.}%|
L 7d 26 89 4b f6 e5 7d 27 7d 22 7d 28 7d 22 7d 2b |}&.K..}'}"}(}"}+|
L f3 7e |.~ |
Data prefixed with L originate from the local endpoint, while data
prefixed with R originate from the remote side.
FILES
/usr/local/etc/comservd.conf Configuration file.
/usr/local/etc/comservd.conf.sample Sample configuration file.
/usr/local/comserv/log Default directory for session logs.
/usr/local/comserv/dev Default directory for device
symlinks.
SEE ALSO
pty(4), remote(5), syslogd(8), tip(1)
AUTHORS
Brian S. Dean <bsd@FreeBSD.org>
BUGS
Please send bug reports to bsd@FreeBSD.org.
BSD 4.4 May 14, 2002 BSD 4.4