ser2net.8

.TH ser2net 8 06/02/01  "Serial to network proxy"

.SH NAME
ser2net \- Serial to network proxy

.SH SYNOPSIS
.B ser2net
[\-c configfile] [\-C configline] [\-p controlport] [\-n] [\-d] [\-b] [\-v]
[-P pidfile]

.SH DESCRIPTION
The
.BR ser2net
daemon allows telnet and tcp sessions to be established with a unit's
serial ports.
.PP
The program comes up normally as a daemon, opens the TCP ports
specified in the configuration file, and waits for connections.  Once
a connection occurs, the program attempts to set up the connection and
open the serial port.  If another user is already using the connection
or serial port, the connection is refused with an error message.

.SH OPTIONS
.TP
.I "\-c config\-file"
Set the configuration file to one other than the default of
.BR "/etc/ser2net.conf"
.TP
.I "\-C config-line"
Handle a single configuration line.  This may be
specified multiple times for multiple lines.  This is just like a
line in the config file.  This disables the default config file,
you must specify a -c after the last -C to have it read a config
file, too.
.TP
.I \-n
Stops  the  daemon  from  forking  and  detaching  from the controlling
terminal. This is useful for running from init.
.TP
.I \-d
Like -n, but also sends the system logs to standard output. This is
most useful for debugging purposes.
.TP
.I \-P pidfile
If specified, put the process id (pid) of ser2net in the pidfile,
replacing whatever was in that file previously.  A pidfile is not created
by default, you must specify this to create one.  Note also that this
filename must be specific with the full path, as ser2net will change
directory to "/" when it becomes a daemon.
when it 
.TP
.I \-u
If UUCP locking is enabled, this will disable the use of UUCP locks.
.TP
.I \-b
Cisco IOS uses a different mechanism for specifying the baud rates
than the mechanism described in RFC2217.  This option sets the IOS
version of setting the baud rates.  The default is RFC2217's.
.TP
.I \-v
Prints the version of the program and exits.
.TP
.I \-p controlport
Enables the control port and sets the TCP port to listen to for the
control port.  A port number may be of the form [host,]port, such as
127.0.0.1,2000
or localhost,2000.  If this is specified, it will only bind to the
IP address specified for the port.  Otherwise, it will bind to all the
addresses on the machine.

If the port number is zero, that means that standard in/out will be
used for the only input/output, and only one port should be specified
in the config.  This way, it can be used from inetd.
.TP
.I \-s signature
Specifies the default RFC2217 signature.

.SH CONTROL PORT
The control port provides a simple interface for controlling the ports and 
viewing their status. To accomplish this, it has the following commands:
.TP
.B showport [<TCP port>]
Show information about a port. If no port is given, all ports are displayed.
.TP
.B showshortport [<TCP port>]
Show information about a port, each port on one line. If no port is given,
all ports are displayed.  This can produce very wide output.
.TP
.B help
Display a short list and summary of commands.
.TP
.B exit
Disconnect from the control port.
.TP
.B version
Display the version of this program.
.TP
.B monitor <type> <tcp port>
Display all the input for a given port on
the calling control port.  Only one direction may be monitored
at a time.  The type field may be 
.I tcp
or
.I term
and specifies
whether to monitor data from the TCP port or from the serial port
Note that data monitoring is best effort, if the controller port
cannot keep up the data will be silently dropped.  A controller
may only monitor one thing and a port may only be monitored by
one controller.
.TP
.B monitor stop
Stop the current monitor.
.TP
.B disconnect <tcp port>
Disconnect the tcp connection on the port.
.TP
.B setporttimeout <tcp port> <timeout>
Set the amount of time in seconds before the port connection will be
shut down if no activity has been seen on the port.
.TP
.B setportconfig <tcp port> <config>
Set the port configuration as in the device configuration in the
.BR /etc/ser2net.conf
file.  If conflicting options are specified, the last option will
be the one used.  Note that these will not change until the port
is disconnected and connected again.  Options
.I 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
set the various baud rates.
.I EVEN, ODD, NONE
set the parity.
.I 1STOPBIT, 2STOPBITS
set the number of stop bits.
.I 7DATABITS, 8DATABITS
set the number of data bits.
.I [-]XONXOFF
turns on (- off) XON/XOFF support.
.I [-]RTSCTS
turns on (- off) hardware flow control.
.I [-]LOCAL
ignores (- checks) the modem control lines (DCD, DTR, etc.)
.TP
.B setportcontrol <tcp port> <controls>
Modify dynamic port controls.  These do not stay between connections.
Controls are:
.I DTRHI, DTRLO
Turns on and off the DTR line.
.I RTSHI, RTSLO
Turns on and off the RTS line.
.TP
.B setportenable <tcp port> <enable state>
Sets the port operation state.  Valid states are:
.I off
to shut the TCP port down,
.I raw
to enable the TCP port transfer all I/O as-is,
.I rawlp
to enable the TCP port input and device output without termios setting, and
.I telnet
to enable the TCP port is up run the telnet negotiation protocol on the port.

.SH CONFIGURATION
Configuration is accomplished through the file
.BR /etc/ser2net.conf .
A file with another name or path may be specified using the
.I \-c
option, or individual config lines may be specified with the
.I \-C
option.  This  file consists of one or more entries with the following
format:
.IP
<TCP port>:<state>:<timeout>:<device>:<options>
.PP
or
.IP
BANNER:<banner name>:<banner text>
.PP
or
.IP
SIGNATURE:<signature name>:<signature text>
.PP
or
.IP
OPENSTR:<openstr name>:<openstr text>
.PP
or
.IP
CLOSESTR:<closestr name>:<closestr text>
.PP
or
.IP
TRACEFILE:<tracefile name>:<tracefile>
.PP
or
.IP
CONTROLPORT:<port spec>
.PP

.SS FIELDS
.TP
.I "TCP port"
Name  or number of the TCP/IP port to accept connections from for this
device.  A port number may be of the form [host,]port, such as 127.0.0.1,2000
or localhost,2000, or ::,2000.  If this is specified, it will only bind to the
IP address specified for the port.  Otherwise, it will bind to all the
ports on the machine.  You can specify an IPV6 address in the port, any
colon before the comma is ignored for parsing fields.
.TP
.I state
Either 
.BR raw
or
.BR rawlp
or
.BR telnet
or
.BR off.
.I off
disables the port from accepting connections.  It can be turned
on later from the control port.
.I raw
enables the port and transfers all data as-is between the port and
the long.
.I rawlp
enables the port and transfers all input data to device,
device is open without any termios setting. It allow to use /dev/lpX
devices and printers connected to them.
.I telnet
enables the port and runs the telnet protocol on the port to set up
telnet parameters.  This is most useful for using telnet.
.TP
.I timeout
The time (in seconds) before the port will be disconnected if there is
no activity on it.  A zero value disables this function.
.TP
.I device
The  name  of  the  device  to connect to. This must be in the form of
.BR /dev/<device> .
.TP
.I "device configuration options"
Sets operational parameters for the serial port.  Values may be
separated by spaces or commas.  Options
.I 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
set the various baud rates.
.I EVEN, ODD, NONE
set the parity.
.I 1STOPBIT, 2STOPBITS
set the number of stop bits.
.I 7DATABITS, 8DATABITS
set the number of data bits.
.I [-]XONXOFF
turns on (- off) XON/XOFF support.
.I [-]RTSCTS
turns on (- off) hardware flow control.
.I [-]LOCAL
ignores (- checks) the modem control lines (DCD, DTR, etc.)
.I [-]HANGUP_WHEN_DONE
lowers (- does not lower) the modem control lines (DCD, DTR, etc.) when
the connection closes.
.I NOBREAK
disables automatic clearing of the break setting of the port.
.I remctl
allows remote control of the serial port parameters via RFC 2217.  See
the README for more info.
.I <banner name>
displays the given banner when a user connects to the port.
.I <signature name>
sends RFC2217 signature on clients request.
.I <openstr name>
Send the given string to the device when the port is opened.
.I <closestr name>
Send the given string to the device when the port is closed.

.I tr=<filename>
When the port is opened, open the given tracefile and store all data read
from the physical device (and thus written to the user's TCP port) in
the file.  The actual filename is specified in the TRACEFILE directive.
If the file already exists, it is appended.  The file is closed
when the port is closed.

.I tw=<filename>
Like tr, but traces data written to the device.

.I tb=<filename>
trace both read and written data to the same file.  Note that this is
independent of tr and tw, so you may be tracing read, write, and both
to different files.

.I [-]hexdump
turns on (- turns off) hexdump output to all trace files.  Each line in the
trace file will be 8 (or less) bytes in canonical hex+ASCII format.  This is
useful for debugging a binary protocol.

.I [-]timestamp
adds (- removes) a timestamp to all of the trace files. A timestamp
is prepended to each line if hexdump is active for the trace file.  A
timestamped line is also recorded in the trace file when a remote client
connects or disconnects from the port.

.I [-][tr-|tw-|tb-]hexdump
turns on (- turns off) hexdump output for only one trace file.
May be combined with [-]hexdump.  Order is important.

.I [-][tr-|tw-|tb-]timestamp
adds (- removes) a timestamp to only one the trace files
May be combined with [-]timestamp.  Order is important.


.TP
.I "banner name"
A name for the banner; this may be used in the options of a port.
.TP
.I "banner text"
The text to display as the banner.  It takes escape sequences for
substituting strings, see "FILENAME, BANNER, AND STRING FORMATTING"
for details.

.TP
.I "tracefile name"
A name for the tracefile, this is used in the tw, tr, and tb options
of a port.
.TP
.I "tracefile"
The file to send the trace into.  Note that this takes escape
sequences for substituting strings, see "FILENAME, BANNER, AND STRING
FORMATTING" for details.  Note that when using the time escape
sequences, the time is read once at port startup, so if you use both
tw and tr they will have the same date and time.
.TP
.I "port spec"
The control port specification as defined by the [\-p] option on the
command line.  This lets the control port be specified in the configuration
file.  The command line will override this, and only the first port
specified is used.

.PP
Blank lines and lines starting with `#' are ignored.

.SH FILENAME, BANNER, AND STRING FORMATTING
Filenames, banners, and open/close string may contain normal "C"
escape sequences and a large number of other escape sequences, too:

.RS 2
\ea - bell
.br
\eb - backspace
.br
\ef - form feed
.br
\en - newline
.br
\er - carriage return
.br
\et - tab
.br
\ev - vertical tab
.br
\e\e - \e
.br
\e? - ?
.br
\e' - '
.br
\e" - "
.br
\ennn - octal value for nnn
.br
\exXX - hex value for XX
.br
\ed - The device name (/dev/ttyS0, etc.)
.br
\ep - TCP port number
.br
\eB - The serial port parameters (eg 9600N81)
.br
\eY -> year
.br
\ey -> day of the year (days since Jan 1)
.br
\eM -> month (Jan, Feb, Mar, etc.)
.br
\em -> month (as a number)
.br
\eA -> day of the week (Mon, Tue, etc.)
.br
\eD -> day of the month
.br
\ee -> epoc (seconds since Jan 1, 1970)
.br
\eU -> microseconds in the current second
.br
\ep -> local port number
.br
\ed -> local device name
.br
\eI -> remote IP address (in dot format)
.br
\eH -> hour (24-hour time)
.br
\eh -> hour (12-hour time)
.br
\ei -> minute
.br
\eS -> second
.br
\eq -> am/pm
.br
\eP -> AM/PM
.RE

In addition, for backwards compatibility because filenames and banners
used to have different formatting, \es is the serial port parameters
if in a banner and seconds if in a filename.  Use of this is
discouraged as it may change in the future.

These sequences may be used to make the filename unique per open and
identify which port/device the filename was for.  Note that in
filenames when using \ed, everything up to and including last / in the
device name is removed, because you can't have a / in a filename.  So
in a filename /dev/ttyS0 would become just ttyS0.

.SH SECURITY
ser2net uses the tcp wrappers interface to implement host-based security.
See hosts_access(5) for a description of the file setup.  Two daemons are
used by ser2net, "ser2net" is for the data ports and "ser2net-control"
is for the control ports.

.SH "SIGNALS"
.TP 0.5i
.B SIGHUP
If ser2net receives a SIGHUP, it will reread it configuration file
and make the appropriate changes.  If an inuse port is changed or deleted,
the actual change will not occur until the port is disconnected.

.SH "Error"
Almost all error output goes to syslog, not standard output.

.SH "FILES"
/etc/ser2net.conf

.SH "SEE ALSO"
telnet(1), hosts_access(5)

.SH "KNOWN PROBLEMS"
None.

.SH AUTHOR
.PP
Corey Minyard <minyard@acm.org>