ser2net.yaml - Man Page

ser2net used to be a program for connection network connections to serial ports.  It's now a program for connecting accepter gensio to connecting gensios.  See gensio(5) for details on gensios.

ser2net is configured with YAML, which is flexible and easy to use. Look at yaml documentation on the internet for how that works.

However, there are two types of YAML files that ser2net can use: version 1 and version 2.  Version 1 YAML files have more capability than version 2 files, but they are non-standard YAML, a standard YAML parser cannot read them.  ser2net will autodetect the version based upon what it finds.

In version 2, you can have multiple documents in a file and ser2net will read all of them.  YAML separates documents in a file with a single "---" by itself at the beginning of a line.  Though you can only have one set of defaults, defines, connections, etc. in a document, you can have multiple documents in a file to allow more than one.  You might, for instance, group all the connections with a certain set of defaults into its own document.

YAML has the ability to create aliases that can be used elsewhere in the configuration file.  These can be used for tying things together between parts of the file, or (as an extension to YAML) for string substitution.

You define an alias in version 1 with the following:

define: &aliasname alias text

This will create an alias with the given name.  Then you can use it elsewhere like:

banner: *aliasname

and the banner will be "alias text".  Unlike standard YAML, you can also use this inside strings using

*(aliasname)

so if you have

banner: My banner *(aliasname) is here

The banner will be "My banner alias text is here".  See the YAML documentation for how spaces are handled, but as a note, use quotes if you are not sure, like:

define: &aliasname "alias text"
banner: "My banner *(aliasname) is here"

If you for some reason need "*(" in your text, use "*(*" for that.

For version 2 YAML files, the definition is:

defines:
 aliasname: alias text
 aliasname2: alias text 2

where you can list as many aliases as you like.  In version 2, you always refer to an alias with "=" instead of "*", like:

banner: "My banner =(aliasname) is here"

and if you for some reason need "=(" in your text, use "=(=" for that.

In version 2, per standard YAML, you can only have one defines section, so they must all be together.

A YAML file may include another file at the main level, with:

include: <filename>

This filename can include globs, and all referenced files are included.  These must be full yaml files, but are included in context at this point, with all the defines, connection names, etc.  This can let you have individual connections in individual files to ease management.

In version 2, You can only have one include in each document for legal YAML, so if you need multiple includes you will have to have multiple documents.

You may want to store passwords and such in external files for better security.  For version 1, putting "*{filename}" in a YAML scalar will put the file's contents into the scalar at that point.  If you need a "*{" in the string for some reason, use "*{*".

For version 2, use "={filename}" instead.  And "={=" to include a "={" in a file.

A connection is a structure that describes how to connect an accepting gensio to a connecting gensio.

An connection specification in version 1 starts with:

In version 2, it's specified as:

In version 2, all the connections must occur together in one place.

The <definition> of a connection is the same for version 1 and version 2:

An <accepter> is an accepting gensio specification.  When ser2net receives a connection on the accepter, it attempts to make a connection to the <connector> gensio.  The alias is required, it sets the name that is used for the connection in the admin interface and for referencing from rotators.

If the connection receive no activity in <timeout> seconds, ser2net will close the connection.  Setting <timeout> to zero disables the timeout.  The timeout field is optional and defaults to zero.

The connection may be enabled or disabled with the enable.  The enable field is optional and defaults to on.  This is useful for temporarily disabling port by setting enable to off and sending a SIGHUP.  If there are users connected and you disable a port and send a SIGHUP, the users will be kicked off.

An option is a configuration setting that doesn't have anything to do with specific gensios, they are controls for ser2net in general.  The option section is optional.

See gensio(5) for a lot of information about the specific gensios available.

To allow a TCP connection to a serial port and ignore modem control, you can do:

Both accepting and connecting gensios stack, so if you want to add telnet with RFC2217 support, you can do:

If you want to accept a telnet over SCTP connection only on IPv6 localhost and connect to a telnet connection with SSL over tcp, you can do:

RFC2217 support only make sense with a serial-capable device as the connector.  Also note that IPv6 is fully supported.  Accepters will generally default to being both IPv4 and IPv6 unless otherwise specified.  See gensio(5) for details.

And yes, SCTP is supported and is highly recommended if you can use it.  Multi-homing alone is worth it.

You could create a secure login with telnet RFC2217 support that then connects to an IPMI sol connection.  Notice how splitting the connector line is done with YAML.

These are some examples.  For SSL and certauth, I have ignored the authentication configuration, more on that later.  Using authentication is strongly recommended, it's easy now with gtlssh and if you need to use it from a program, it's easy with gensio.  There is even python support.  Adding support for other scripting languages shouldn't be too hard.

A rotator allows a single network connection to connect to one of a number of connections.

A version 1 rotator specification starts with:

A version 2 rotator specification starts with:

Just like connections, in version 2 you have to put all the rotators together.

The definition of a rotator is almost the same between version 1 and version 2:

A rotator has four possible options, "authdir", "pamauth", "allowed-users", and "accepter-retry-time", both same as connections.

For version 1, you should use YAML aliases for the connections.  For version 2, just use the alias names.

Connections to the accepter will go through the set of connections and find the first unused one and use that.  The next connection will start after the last connection used.  Note that disabled connections are still accessible through rotators.

Note that the security of the connection is NOT used, only the security of the rotator.

To set a default in version 1, do:

default:

name: <default name>
value: <default value>
class: <default class>

In version 2, like other things, the defaults are all in one place in a document, like:

The class is optional, if it is not there it sets the base default for all classes that is used unelss overridden for a specific class.  If the class is there, it sets the default for a specific gensio class. There is also a ser2net class that is for ser2net specific options.

The class is useful if you want different values for different gensio types.  For instance, if you wanted all serial ports to run at 9600 baud and all IPMI SOL connections to run at 115200 baud, you could do:

default:

name: speed
value: 9600
class: serialdev

default:

name: speed
value: 115200
class: ipmisol

The value is also optional, if it is not present a string value is set to NULL and an integer value is set to 0.

The order in the file is important, you must set a default before it is used, and you can change the value of the default.  It will affect all uses following the setting.

To delete a default value for class (so it will use the base default), for version 1 do:

delete_default:

name: <default name>,
class: <default class>

For version 2, do:

and it will delete the defaults for the classes in the list after it.

You must supply the class, you cannot delete base defaults.

The following default values are specific to ser2net, given with their default values:

telnet-brk-on-sync: false

If a telnet sync is received, send a break on the connected gensio (if applicable).  By default data is flushed until the data mark, but no break is sent.

kickolduser: false

If a new user comes in on a connection that already has a user, kick off the previous user.

chardelay: true

Enable asmall 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: 20

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 receive 2.5 serial port characters before sending the data on to the TCP port.  This can range from 1-1000.

chardelay-min: 1000

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.  This can range from 1-100000.

net-to-dev-bufsize: 64

sets the size of the buffer reading from the network port and writing to the serial device.

dev-to-net-bufsize: 64

sets the size of the buffer reading from the serial device and writing to the network port.

max-connections: 1

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.

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.  If a "!" is given at the beginning of the address, the address is a "connect back" address.  If a connect back address is specified, one of the network connections (see max-connections) is reserved for that address.  If data comes in on the device, ser2net will attempt to connect to the address.  This works on TCP and UDP.

authdir: /usr/share/ser2net/auth

The authentication directory for ser2net.  The AUTHENTICATION for more details.

authdir-admin: /etc/ser2net/auth

The authentication directory for ser2net for admin connections.  The "ADMIN_CONNECTIONS" for more details.

pamauth: <NULL>

The PAM service name for ser2net PAM authentication (<NULL> for disabled).

pamauth-admin: <NULL>

The PAM service name for ser2net admin connection PAM authentication (<NULL> for disabled). See "ADMIN_CONNECTIONS" for more details.

mdns-interface: -1

The default mDNS interface.

mdns-type: <NULL>

The default mDNS type.

mdns-domain: <NULL>

The default mDNS domain.

mdns-host: <NULL>

The default mDNS host.

There is an admin accepter that you can define for ser2net, it lets you log in, look at status, and change some things.  See "ADMIN INTERFACE" in ser2net(8) for detail on how to use it.  The format is:

The following authentications options available are "authdir-admin", which sets the authentication directory for the admin port and "pamauth-admin" which sets the PAM service name and enables PAM authentication. Both are different than "authdir" resp.  "pamauth" for connections, though you can set it to the same value.

In addition, the same mdns option are available for admin ports as are available for connections.  And you can set an optional alias that will also set the mdna name.

Like connections, default mdns options work for "mdns-interface", "mdna-type", "mdns-domain", and "mdns-host".  Unlike connections, the "mdns" boolean does not come from the default, you must specify it as an admin option to turn on mdns for the admin port.  This is to allow it to be specified separately and maintain backwards compatibility.

ser2net can flash LEDs during serial activity.  To create an LED in version 1, do:

In version 2, use:

The only supported driver is sysfs.  Supported options are:

device: <sysfs device name> gives the name of the LED in /sys/class/led.  These generally have ":" in them, so you will need to put the name in quotes.  This is required.

duration: <time in ms> The time in milliseconds to flash the LED.  Defaults to 10.

state: <number> The value to set the LED to to enable it.  Defaults to 1, but may need to be a different value.

You reference the LED by alias in the connection options section, see that for details.  Make sure you have "modprobe ledtrig-transient" done or the triggers will not work, they require the transient trigger.

You also probably need root access to access LED settings.

NOTE: yaml has it's own quoting mechanism, see below for more details.

Filenames, banners, open/close strings, closeon strings, and sendon strings may contain normal "C" escape sequences and a large number of other escape sequences, too:

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 or \o, 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.

YAML and the accepter/connector processing interact when dealing with quoting.  By default, YAML ignores the number of spaces between elements separated by spaces.  Lines that are indented after an element are considered a continuation of the element, so something like:

is the same as

connector: serialdev,/dev/ttyUSB0, 9600n81 local nobreak rtscts

YAML has it's own standard quoting mechanisms, so if you do:

connector: "serialdev,/dev/ttyUSB0,9600n81  local"

the two spaces before "local" will be preserved when passed to the connector processing (though in this case it won't matter because the connector processing will ignore the extra spaces).

If you need a significant space, say in a filename passed to a key, You cannot do:

accepter: ssl(CA=/etc/ser2net/my CA/),tcp,3000

because the accepter processing will split the arguments at the space and won't recognize what "CA/" is.  You also cannot do:

accepter: ssl(CA="/etc/ser2net/my CA/"),tcp,3000

because YAML will remove the quotes, this is functionally equivalent to the previous example. And

accepter: ssl(CA="/etc/ser2net/my\ CA/"),tcp,3000

also will not work, inside of double quotes YAML will convert "\ " to a space.  You have a couple of options.  You can do:

accepter: ssl(CA=/etc/ser2net/my\ CA/),tcp,3000

or

accepter: ssl(CA='/etc/ser2net/my\ CA/'),tcp,3000

because outside of quotes YAML will not process the "\ " and it will not process it in single quotes.  Or if you have a lot of spaces or colons, too, you can do:

accepter: ssl(CA="\"/etc/ser2net/my CA/\""),tcp,3000

because inside the outside quotes YAML will convert the '\"' into a '"' and pass it on to the accepter processing which will interpret the quotes as you would expect.

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 receives 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 accept new connections up to "max-connections" then ignore packets from other addresses until a disconnect occurs.

Unfortunately, there is no easy way to know when to disconnect.  You have two basic options:

• 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 fine) 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 and a connect back port (see discussion on remote addresses above), 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:

flow control 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.

closeon will close all connections when the closeon sequence is seen.

openstr is only sent when the port is unconnected and the first connections is made.

closestr 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.

kickolduser will kick off an existing connection if a connection comes in on a port that already has a maximum number of connections.  The connection kicked off is arbitrarily chosen and the algorithm is subject to change.

tracing will trace data from all network connections.

rfc2217 (remote telnet serial control) will change the connection settings on the device and will be accepted from any network connection.

reconfig on SIGHUP See ser2net(8) "SIGHUP" section for details.

Rotator 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.

timeout will be per TCP port and will only disconnect that TCP port on a timeout.

telnet_brk_on_sync will send a break for any TCP port that does a sync.

showport in the admin interface will show all possible connections, so if you say max-connections=3 you will get three entries.

showshortport in the admin interface 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.

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.

Almost all error output goes to syslog, not standard output.

/etc/ser2net/ser2net.yaml, /etc/ser2net/ser2net.key, /etc/ser2net/ser2net.crt, /usr/share/ser2net

ser2net(8) telnet(1), hosts_access(5), gensio(5), gtlssh(1), gtlssh-keygen(1)

If they were known, they would be fixed :).

Corey Minyard <minyard@acm.org>

ser2net(8).