ser2net - Serial to network proxy
[-c configfile] [-C configline] [-p controlport] [-n] [-d] [-b]
[-v] [-P pidfile]
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.
- -c config-file
- Set the configuration file to one other than the default of
- -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.
- Stops the daemon from forking and detaching from the
controlling terminal. This is useful for running from init.
- 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
- If UUCP locking is enabled, this will disable the use of
- 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
- 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.
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
- Display a short list and summary of commands.
- Disconnect from the control port.
- 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
- 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,
- setportcontrol <tcp port>
- 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
- 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 is accomplished through the file /etc/ser2net.conf
. A file
with another name or path may be specified using the -c
individual config lines may be specified with the -C
option. This file
consists of one or more entries with the following format:
- BANNER:<banner name>:<banner text>
- SIGNATURE:<signature name>:<signature
- OPENSTR:<openstr name>:<openstr text>
- CLOSESTR:<closestr name>:<closestr text>
- CLOSEON:<closeon name>:<closeon text>
- TRACEFILE:<tracefile name>:<tracefile>
- CONTROLPORT:<port spec>
- 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
- 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
- The time (in seconds) before the port will be disconnected
if there is no activity on it. A zero value disables this function.
- 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
- 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.
- 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.
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
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
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.
- 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
Almost all error output goes to syslog, not standard output.
Corey Minyard <firstname.lastname@example.org>