Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
COMSERVD(8)		FreeBSD	System Manager's Manual		   COMSERVD(8)

     comservd -- make network terminal server serial ports accessible via /dev

     comservd [-f config_file]

     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 net-
     work, turning the local system into a network terminal server with	re-
     spect to its own local serial ports.  At startup, comservd	loads and exe-
     cutes 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 com-
     servd 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	com-
     plete 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 speci-
	     fied 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 any-
	     thing other than log or nolog is used, it is treated as a file-
	     name.  Relative filenames are treated relative to the path	speci-
	     fied 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 de-
	     vice names	specified in the devname field of the add command.

	     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 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	abso-
	     lute 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 de-
	     vice and must already exist.  comservd creates a network socket
	     and binds it to the specified TCP port and	then listens for in-
	     coming 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

     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:

		     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 ap-
			     propriate if the remote side functions indepen-
			     dently of the local side, such as when the	remote
			     side is a serial system console.  The default is

		     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	writ-
			     ten 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	reli-
			     able 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 con-
			     nection as	well as	data originating from the re-
			     mote 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

		     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 iden-
			     tify the source of	the data, either remote	or
			     local.  loghex is useful for debugging a protocol
			     stream between two	devices.  nologhex is appro-
			     priate when only ASCII data is present.  The de-
			     fault is nologhex.

		     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 op-
	     tions which are used as defaults for new device ids.

     show devid
	     Show operational settings for the device id specified by devid.

	     Shutdown the server.

	     Display the revision timestamp.  This information is very useful
	     to	include	in bug reports.

     comservd can be used for many applications.  One of the more common ap-
     plications	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:


     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 respec-
     tive 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 lo-
     cal 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 transmis-
     sion 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	pre-
     fixed with	R originate from the remote side.

     /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 sym-

     pty(4), remote(5),	syslogd(8), tip(1)

     Brian S. Dean <>

     Please send bug reports to

4.4BSD				 May 14, 2002				4.4BSD


Want to link to this manual page? Use this URL:

home | help