Provided by: ser2net_4.3.12-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 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.
OPTIONS
-c config-file
Set the configuration file to one other than the default of
/etc/ser2net/ser2net.yaml. If the filename does not end in ".yaml" or the first
line in the file does not begin with "%YAML", the configuration file is parsed as
an old-style configuration file, which should work but is no longer supported. If
the config-file is - then standard input is read as the config file. This only
supports yaml.
-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 old style 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.
Note that this is the old-style configuration lines and is likely to go away when
old style configuration is removed.
-Y yaml-config-string
Add a yaml config string to the end of strings to be processed. This may be
specified multiple times for multiple strings. These are appended onto the end of
a yaml config file; though if this is specified, the default config file is
disabled and you have to enable it with the -c option.
To make things easier to handle, any # in the config string that is not inside
quote (what would normally start a comment in yaml) is converted to a new line.
Plus a new line is added after each separate config string. So, for instance:
-Y 'connection: &con01# accepter: tcp,2013'
-Y ' connector: serialdev,/dev/ttyEcho0,9600n81,local'
-Y ' options:# banner: "### A Banner ###\r\n"'
can be put on the ser2net command line.
-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.
-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.
-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 <admin-accepter>
Enables the admin interface on the given accepter specification. See "ADMIN
CONNECTION" in ser2net.yaml(5) for more details on how to configure this, and
"ADMIN INTERFACE" below for details on how to use it.
-s signature
Specifies the default RFC2217 signature.
ADMIN INTERFACE
The admin interface 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 displayed.
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.
help Display a short list and summary of commands.
exit Disconnect from the control port.
yaml Go into yaml output mode. See YAML MODES below.
version
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 one controller.
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/ser2net.yaml 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. Parity, databits, and stopbits may be
specified in the classical manner after the speed, as in 9600N81. This has the
following format: <speed>[N|E|O|M|S[5|6|7|8[1|2]]]. Setting serial options this
way does not work on SOL, SOL has fixed N81 serial options. 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, DTR, etc.)
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.
reload Causes ser2net to reload its configuration. Any error output will come out in the
output, along with going to syslog.
YAML MODES
If the "yaml" command is issued, echo is turned off and all output is YAML compliant. The
form is basically the same as the non-YAML output, with some minor adjustments to make it
YAML compliant. In addition, all responses are in the form:
%YAML 1.1
---
response:
<response info here>
...
If there is an error, it is returned in the response with the "error" key. If the command
succeeded, no "error" key will be present in the response mapping. The "..." will be at
the end of all responses.
The following commands are available in yaml output mode: exit, version, showport,
disconnect, setporttimeout, setportenable, setportcontrol, reload,
If "%YAML" is seen in the input, YAML input and output modes are activated, echo is
disabled, and all input is expected to be in the form:
---
command:
name: <command name>
id: <optional id>
parms: [ parm1 [, parm2 [...]]]
...
The id is optional and will just be returned in the response. The parms are optional,
too, unless the command requires them. Extra parms are ignored, along with unknown keys
in the main mapping.
Note that you have to deal with the "->" that is issued when the connection is made,
before going into YAML mode, YAML doesn't handle that well.
In YAML output mode, you will get asynchronous reports of connections and disconnections
in the form:
%YAML 1.1
---
new connection:
name: !!str 'con1'
remaddr: !!str 'ipv6,::1,59072'
...
%YAML 1.1
---
disconnect:
name: !!str 'con1'
remaddr: !!str 'ipv6,::1,59072'
...
CONFIGURATION
Configuration is accomplished through the file /etc/ser2net/ser2net.yaml. A file with
another name or path may be specified using the -c option. If the file ends in .yaml, it
will be processed with the new yaml parser. If it ends in anything else, it will use the
old configuration file format, no longer supported or documented. The old style
configuration will go away at some point.
The yaml configuration file is described in ser2net.yaml(5)
SIGNALS
SIGHUP
If ser2net receives a SIGHUP, it will reread it configuration file and make the
appropriate changes. If an in use connection is changed or deleted, the actual
change will not occur until the port is disconnected, except that if you disable a
connection it will kick the users off.
ser2net uses the name (the connection alias) of the connection to tell if it is new,
changed or deleted. If the new configuration file has a connection with the same
name, it is treated as a change.
This has some unusual interactions with connections that allow more than one
simultaneous connection. It works just like the other port, but the accepter is
disabled and new connections will not be accepted until all the existing connections
are closed.
ERRORS
All error output after startup goes to syslog, not standard output, unless you use the -d
option.
FILES
/etc/ser2net/ser2net.yaml, /etc/ser2net/ser2net.key, /etc/ser2net/ser2net.crt,
/usr/share/ser2net
SEE ALSO
telnet(1), ser2net.yaml(5), hosts_access(5)
KNOWN PROBLEMS
None.
AUTHOR
Corey Minyard <minyard@acm.org>