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 or with an IPMI Serial Over LAN (SOL) interface.
The program comes up normally as a daemon, opens the network 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 UUCP locks.
- 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.
- Prints the version of the program and exits.
- -t <num threads>
- Spawn the given number of threads for ser2net to use. The default is 1.
Only valid if pthreads is enabled at build time.
- -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 [<network port>]
- Show information about a port. If no port is given, all ports are
- showshortport [<network 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.
- Display a short list and summary of commands.
- Disconnect from the control port.
- Display the version of this program.
- monitor <type> <network 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 network 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
- monitor stop
- Stop the current monitor.
- disconnect <network port>
- Disconnect the tcp connection on the port.
- setporttimeout <network 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 <network 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 (MARK and SPACE if supported) 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,
- setportcontrol <network 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 <network port> <enable state>
- Sets the port operation state. Valid states are: off to shut the
network port down, raw to enable the network port transfer all I/O
as-is, rawlp to enable the network port input and device output
without termios setting, and telnet to enable the network 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 text>
- OPENSTR:<openstr name>:<openstr text>
- CLOSESTR:<closestr name>:<closestr text>
- CLOSEON:<closeon name>:<closeon text>
- TRACEFILE:<tracefile name>:<tracefile>
- CONTROLPORT:<port spec>
- ROTATOR:<TCP port>:<port list>
A line that ends in '\' (it must be the very last character) is continued on the
next line. There is no arbitrary maximum line length.
- network port
- Name or number of the network port to accept connections from for this
device. A port number may be of the form
[ipv4,|ipv6,][tcp,|udp,][host,]port, such as 127.0.0.1,2000 or
ipv4,localhost,2000, or udp,::,2000. If host 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. If ipv4 or ipv6
is specified, it will only bind to that network type.
If udp is specified, any data received on the port from a remote source is
considered a "connection" and the data for that port will go
back to the remote source address. See the later section on UDP for
- 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
- 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> or sol.<solparms>. For SOL
parameters, see the solterm man page that is part of openipmi. This may be
specified in a DEVICE directive, then you can use the name in the DEVICE
directive to specify the device in the DEVICE directive. This can be used
to give shorter and/or meaningful names for devices, or to allow special
characters (like a colon) in the device name.
- device configuration options
- Sets operational parameters for the serial port. Values are be separated
by spaces. Options 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600,
115200 set the various baud rates for serial device and SOL ports. 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.
Note that only a limited set are available on SOL. [-]NOBREAK
disables automatic clearing of the break setting of the port. Available on
serial device and SOL ports.
EVEN, ODD, NONE (MARK and SPACE if supported) set the parity. (serial
device only) Note that MARK and SPACE are not available on all systems or
hardware, if it is not supported then it will be silently set to ODD or
EVEN parity. 1STOPBIT, 2STOPBITS set the number of stop bits.
(serial device only) 5DATABITS, 6DATABITS, 7DATABITS, 8DATABITS set
the number of data bits. (serial device only) [-]XONXOFF turns on
(- off) XON/XOFF support. (serial device only) [-]RTSCTS turns on
(- off) hardware flow control. (serial device only) [-]LOCAL
ignores (- checks) the modem control lines (DCD, DTR, etc.) (serial device
only) [-]HANGUP_WHEN_DONE lowers (- does not lower) the modem
control lines (DCD, DTR, etc.) when the connection closes. (serial device
only) [-]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.
[-]disable-chardelay disables the small wait after each character
received on the serial port before sending data on the TCP port. Normally
ser2net will wait the time it takes to receive 2 serial port characters,
or at least 1000us, before sending on the TCP port. This allows more
efficient use of network resources when receiving large amounts of data,
but gives reasonable interactivity.
chardelay-scale=<number> sets the number of serial port
characters, in tenths of a character, to wait after receiving from the
serial port and sending to the TCP port. So setting this to 25 will cause
ser2net to wait the amount of time it takes to recieve 2.5 serial port
characters before sending the data on to the TCP port. The default value
chardelay-min=<number> sets the minimum delay that ser2net will
wait, in microseconds. If the calculation for chardelay-scale results in a
value smaller than this number, this number will be used instead. The
default value is 1000.
chardelay-max=<number> sets the maximum delay that ser2net will
wait, in microseconds, before sending the data. The default value is
20000. This keeps the connection working smoothly at slow speeds.
dev-to-net-bufsize=<number> sets the size of the buffer reading
from the serial device and writing to the network port.
net-to-dev-bufsize=<number> sets the size of the buffer reading
from the network port and writing to the serial device.
[-]authenticated enable (-disable) authentication on the link. (SOL
[-]encrypted enable (-disable) encryption on the link. (SOL only)
shared_serial_alert_fail fail the connection if the serial port is in
use through hardware. (SOL only)
shared_serial_alert_deferred if the serial port is already in use
through hardware, wait until it is released. (SOL only)
shared_serial_alert_deferred if the serial port is already in use via
hardware, take over the connection. (SOL only)
[-]deassert_CTS_DCD_DSR_on_connect deassert (- do not deassert) the
given serial signals on a SOL connection. (SOL only)
ack-timeout=n set the timeout for resending to n microseconds. (SOL
ack-retries=n set the number of retries before failure to n times.
<parm> is a parameter to set a default for. When you set a
default, it sets the default value for all following config lines.
Available parameters are: speed, databits, stopbits, parity, xonxoff,
rtscts, local, hangup_when_done, nobreak, remctl, telnet_brk_on_sync,
kickolduser, chardelay, chardelay-scale, chardelay-min, and chardelay-max.
See ser2net.conf for details.
<defaultval> The default value to set the parameter.
<port list> A space separated list of ports. When connecting to
the given TCP port, ser2net will go through the port list until it finds a
free one and attempt to connect to that port.
led-tx=<led-name> use the previously defined led to indicate
serial tx traffic on this port.
led-rx=<led-name> use the previously defined led to indicate
serial rx traffic on this port.
max-connections=<number> set the maximum number of connections
that can be made on this particular TCP port. If you make more than one
connection to the same port, each ports output goes to the device, and the
device output goes to all ports simultaneously. See "MULTIPLE
CONNECTIONS" below for details. The default is 1.
remaddr=<addr>[;<addr>[;...]] specifies the allowed
remote connections, where the addr is a standard address in the form (see
"network port" above). Multiple addresses can be separated by
semicolons, and you can specify remaddr more than once. If you set the
port for an address to zero, ser2net will accept a connection from any
port from the given network host.
- 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
- 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.
- Define an LED with given name. At the moment, the only available driver is
"sysfs" which uses a Linux's LED class device
(/sys/class/leds/<device>) and configures it for transient LED
trigger. It knows about the required parameter "device" which
specifies which LED class device to use (the directory name of the LED
below /sys/class/leds). The optional "duration" parameter
controls the length of the flash pulse in milliseconds and defaults to 10.
The optional parameter "state" controls whether the LED is
off/on when the timer is active. It takes 0 or 1 as values and defaults to
1. See ledtrig-transient.txt in Linux kernel documentation for more
The transient trigger must be compiled into the kernel or already loaded as
Individual network ports can refer to this LED and thus trigger flashing of
this LED when tx/rx traffic is seen.
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 - Network 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
UDP handling is a bit different than you might imagine, because it's hard for
ser2net to know where to send the data to. To handle this, UDP ports still
have the concept of a "connection". If a UDP port is not connected,
then if it received a packet the remote address for that packet is set to the
remote end of the "connection". It will do all the normal new
connection operations. ser2net will then ignore packets from other addresses
until a disconnect occurs.
Unfortunately, there is no easy way to know when to disconnect. You have two
- Set a timeout, if the remote end isn't heard from before the timeout, then
the port is disconnected and something else can connect. This means
anything that is using the port must periodically send a packet (empty is
find) to ser2net to keep the connection alive.
Use the kickolduser option on the port, any new connection that comes in
will replace the previous connection.
Note that UDP ports handle multiple connections just like TCP ports, so you can
have multiple UDP listeners.
You also have a third option. If you set a remote address (remaddr) with a
non-zero port, ser2net will take one of the connections and assign it to that
port permanently. This is called a fixed remote address. All the traffic from
the device will go to that port. Every fixed remote address on a UDP port has
to have a corresponding connection, so if you have 3 fixed remote addresses,
you must have at least 3 connections.
As mentioned earlier, you can set max-connections=<n>
on a port to
allow more than one connection at a time to the same serial port. These
connections will share all the settings. You cannot have two separate TCP
ports connect to the same port at the same time.
This has some significant interactions with other features:
is not exactly a feature, but more an interaction between
the different connections. If a TCP port stops receiving data from ser2net,
all TCP ports connected will be flow-controlled. This means a single TCP
connection can stop all the others.
will close all connections when the closeon sequence is seen.
is only sent when the port is unconnected and the first
connections is made.
is only sent when the last port disconnects and there are no
more connections to the port.
Any monitor ("monitor start" from a control connections) will catch
input from all network connections.
will kick off all connections if a connection comes in on a
port that already has a maximum number of connections.
will trace data from all network connections.
(remote telnet serial control) will change the connection settings
on the device and will be accepted from any network connection.
will only choose a port if there are no connections at all on the
port. Note that the use of a rotator with a port with max-connections > 1
will result in undefined behavior.
will be per TCP port and will only disconnect that TCP port on a
will send a break for any TCP port that does a sync.
will show all possible connections, so if you say
you will get three entries.
will only show the first live connection, or if no
connection is present it will show whatever the first one was the last time a
connection was present.
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 disconnected.
Almost all error output goes to syslog, not standard output.
Corey Minyard <email@example.com>