Provided by: ser2net_2.10.1-1_amd64 
NAME
ser2net - Serial to network proxy
SYNOPSIS
ser2net [-c configfile] [-C configline] [-p controlport] [-n] [-d] [-b] [-v] [-P pidfile]
DESCRIPTION
The ser2net daemon allows telnet and tcp sessions to be established with a unit's serial
ports.
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.
OPTIONS
-c config-file
Set the configuration file to one other than the default of /etc/ser2net.conf
-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.
-n Stops the daemon from forking and detaching from the controlling terminal.
This is useful for running from init.
-d Like -n, but also sends the system logs to standard output. This is most useful for
debugging purposes.
-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
-u If UUCP locking is enabled, this will disable the use of UUCP locks.
-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. Note that this capability is now handled
automatically and this option is ignored.
-v Prints the version of the program and exits.
-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.
-s signature
Specifies the default RFC2217 signature.
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:
showport [<TCP port>]
Show information about a port. If no port is given, all ports are displayed.
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.
help Display a short list and summary of commands.
exit Disconnect from the control port.
version
Display the version of this program.
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 tcp or 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.
monitor stop
Stop the current monitor.
disconnect <tcp port>
Disconnect the tcp connection on the port.
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.
setportconfig <tcp port> <config>
Set the port configuration as in the device configuration in the /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 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200 set the various
baud rates. The following speed may be available if your system has the values
defined and your hardware supports it: 230400, 460800, 500000, 576000, 921600,
1000000, 1152000, 1500000, 2000000, 2500000, 3000000, 3500000, 4000000. EVEN, ODD,
NONE set the parity. 1STOPBIT, 2STOPBITS set the number of stop bits. 7DATABITS,
8DATABITS set the number of data bits. [-]XONXOFF turns on (- off) XON/XOFF
support. [-]RTSCTS turns on (- off) hardware flow control. [-]LOCAL ignores (-
checks) the modem control lines (DCD, DTR, etc.)
setportcontrol <tcp port> <controls>
Modify dynamic port controls. These do not stay between connections. Controls
are: DTRHI, DTRLO Turns on and off the DTR line. RTSHI, RTSLO Turns on and off the
RTS line.
setportenable <tcp port> <enable state>
Sets the port operation state. Valid states are: off to shut the TCP port down,
raw to enable the TCP port transfer all I/O as-is, rawlp to enable the TCP port
input and device output without termios setting, and telnet to enable the TCP port
is up run the telnet negotiation protocol on the port.
CONFIGURATION
Configuration is accomplished through the file /etc/ser2net.conf. A file with another
name or path may be specified using the -c option, or individual config lines may be
specified with the -C option. This file consists of one or more entries with the
following format:
<TCP port>:<state>:<timeout>:<device>:<options>
or
BANNER:<banner name>:<banner text>
or
SIGNATURE:<signature name>:<signature text>
or
OPENSTR:<openstr name>:<openstr text>
or
CLOSESTR:<closestr name>:<closestr text>
or
CLOSEON:<closeon name>:<closeon text>
or
TRACEFILE:<tracefile name>:<tracefile>
or
CONTROLPORT:<port spec>
FIELDS
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.
state Either raw or rawlp or telnet or off. off disables the port from accepting
connections. It can be turned on later from the control port. raw enables the
port and transfers all data as-is between the port and the long. 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. telnet
enables the port and runs the telnet protocol on the port to set up telnet
parameters. This is most useful for using telnet.
timeout
The time (in seconds) before the port will be disconnected if there is no activity
on it. A zero value disables this function.
device The name of the device to connect to. This must be in the form of
/dev/<device>.
device configuration options
Sets operational parameters for the serial port. Values may be separated by spaces
or commas. Options 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200 set
the various baud rates. The following speed may be available if your system has
the values defined and your hardware supports it: 230400, 460800, 500000, 576000,
921600, 1000000, 1152000, 1500000, 2000000, 2500000, 3000000, 3500000, 4000000.
EVEN, ODD, NONE set the parity. 1STOPBIT, 2STOPBITS set the number of stop bits.
7DATABITS, 8DATABITS set the number of data bits. [-]XONXOFF turns on (- off)
XON/XOFF support. [-]RTSCTS turns on (- off) hardware flow control. [-]LOCAL
ignores (- checks) the modem control lines (DCD, DTR, etc.) [-]HANGUP_WHEN_DONE
lowers (- does not lower) the modem control lines (DCD, DTR, etc.) when the
connection closes. NOBREAK disables automatic clearing of the break setting of the
port. remctl allows remote control of the serial port parameters via RFC 2217.
See the README for more info. kickolduser sets the port so that the previous user
will be kicked off if a new user comes in. Useful if you forget to log off from
someplace else a lot. <banner name> displays the given banner when a user connects
to the port. <signature name> sends RFC2217 signature on clients request.
<openstr name> Send the given string to the device when the port is opened.
<closestr name> Send the given string to the device when the port is closed.
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.
tw=<filename> Like tr, but traces data written to the device.
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.
[-]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.
[-]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.
[-][tr-|tw-|tb-]hexdump turns on (- turns off) hexdump output for only one trace
file. May be combined with [-]hexdump. Order is important.
[-][tr-|tw-|tb-]timestamp adds (- removes) a timestamp to only one the trace files
May be combined with [-]timestamp. Order is important.
telnet_brk_on_sync causes a telnet sync operation to send a break. By default data
is flushed until the data mark, but no break is sent.
banner name
A name for the banner; this may be used in the options of a port.
banner text
The text to display as the banner. It takes escape sequences for substituting
strings, see "FILENAME, BANNER, AND STRING FORMATTING" for details.
tracefile name
A name for the tracefile, this is used in the tw, tr, and tb options of a port.
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.
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.
Blank lines and lines starting with `#' are ignored.
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:
\a - bell
\b - backspace
\f - form feed
\n - newline
\r - carriage return
\t - tab
\v - vertical tab
\\ - \
\? - ?
\' - '
\" - "
\nnn - octal value for nnn
\xXX - hex value for XX
\d - The device name (/dev/ttyS0, etc.)
\p - TCP port number
\B - The serial port parameters (eg 9600N81)
\Y -> year
\y -> day of the year (days since Jan 1)
\M -> month (Jan, Feb, Mar, etc.)
\m -> month (as a number)
\A -> day of the week (Mon, Tue, etc.)
\D -> day of the month
\e -> epoc (seconds since Jan 1, 1970)
\U -> microseconds in the current second
\p -> local port number
\d -> local device name
\I -> remote IP address (in dot format)
\H -> hour (24-hour time)
\h -> hour (12-hour time)
\i -> minute
\S -> second
\q -> am/pm
\P -> AM/PM
In addition, for backwards compatibility because filenames and banners used to have
different formatting, \s 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 \d, 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.
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.
SIGNALS
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.
Error
Almost all error output goes to syslog, not standard output.
FILES
/etc/ser2net.conf
SEE ALSO
telnet(1), hosts_access(5)
KNOWN PROBLEMS
None.
AUTHOR
Corey Minyard <minyard@acm.org>