ser2net.yaml(5)               File Formats Manual              ser2net.yaml(5)



NAME
       /etc/ser2net/ser2net.yaml - Serial to network proxy configuration file


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


DEFINE SPECIFICATION
       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 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.


INCLUDING OTHER FILES
       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.


USING EXTERNAL FILES
       You may want to store passwords and such in external files for better
       security.  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 "*{*".


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

       An accepter specification looks like:

              connection: &<alias>
                     accepter: <accepter>
                     timeout: <number>
                     enable: on|off
                     connector: <connector>
                     options:
                            <option name>: <option value>
                            <option name>: <option value>...

       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:
              connection: &toS0tcp
                     accepter: tcp,1234
                     connector: serialdev,/dev/ttyS0,local

       Both accepting and connecting gensios stack, so if you want to add
       telnet with RFC2217 support, you can do:
              connection: &toS0telnet
                     accepter: telnet(rfc2217),tcp,1234
                     connector: serialdev,/dev/ttyS0,local

       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:
              connection: &tomyhost
                     accepter: telnet,sctp,::1,1234
                     connector: telnet,ssl,tcp,myhost.domain.org,1234

       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.
              connection: &authsol
                     accepter: telnet(rfc2217),mux,certauth,ssl,sctp,1234
                     connector: ipmisol,lan -U ipmiusr -P test -p 9001
                                   ipmiserver.domain.org,9600
                     options:
                            banner: My banner

       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.


   SPECIAL STRING HANDLING
       Some string values, like banners, have special formatting for inserting
       various values.  These are all prepended with '\'.  This takes the
       standard "C" \x characters.

         \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 connector string (/dev/ttyS0, etc.)
         \o - The name of the connection.
         \p - Network port number
         \B - The serial port parameters (eg 9600N81) if applicable
         \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
         \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

       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.

       Note that in banners and other strings going out (not filenames) you
       must use \r\n to send a new line; this is raw handling and \n will only
       go down one line, it will not return to the beginning of the line.


   CONNECTION SPECIFICATION OPTIONS
       kickolduser: true|false 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: <banner string> displays the given banner when a client
       connects.  It uses string handling as described in "SPECIAL STRING
       HANDLING" above.

       signature: <signature string> sends RFC2217 signature on clients
       request.  This may be an empty string.

       openstr: <openstr name string> Send the given string to the device on
       first open.  This may be an empty string.  It uses string handling as
       described in "SPECIAL STRING HANDLING" above.

       closestr: <closestr name> Send the given string to the device on final
       close.  This may be an empty string.  It uses string handling as
       described in "SPECIAL STRING HANDLING" above.

       closeon: <closeon string> If the given string is seen coming from the
       connector side of the connection, close the connection.  The comparison
       here is, for simplicity, simplistic.  Complex expressions with
       repetitive things may not compare correctly.  For instance, if your
       closeon strings is "ababc" and your input strings is "abababc", the
       comparison will fail because the comparison algorithm will see "ababa"
       and will fail on the final "a" and start over at "abc", which won't
       match.  This shouldn't cause a problem most cases, but if it does,
       contact the authors and it can be improved.

       accepter-retry-time: <time in seconds> If the accepter does not come up
       at startup, wait this many seconds and retry it.

       connector-retry-time: <time in seconds> On a connect-back port, if the
       connector does not come up or goes down.  wait this many seconds and
       retry it.

       trace-read: <filename> When the acceptor is opened, open the given file
       and store all data read from the physical device (and thus written to
       the client's network/acceptor port) in the file.  If the file already
       exists, it is appended.  The file is closed when the port is closed.
       The filename uses string handling as described in "SPECIAL STRING
       HANDLING" above.

       trace-write: <filename> Like tr, but traces data written to the
       connecting gensio.

       trace-both: <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.

       trace-hexdump: true|false turns on/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.

       trace-timestamp: true|false 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.

       [trace-read-|trace-write-|trace-both-]hexdump: true|false turns on/off
       hexdump output for only one trace file.  May be combined with hexdump.
       Order is important.

       [trace-read-|trace-write-|trace-both-]timestamp: true|false
       adds/removes a timestamp to only one the trace files May be combined
       with [-]timestamp.  Order is important.

       telnet-brk-on-sync: true|false causes a telnet sync operation to send a
       break.  By default data is flushed until the data mark, but no break is
       sent.

       chardelay: true|false enables the small wait after each character
       received on the connecting gensio before sending data on the accepted
       gensio.  Normally ser2net will wait the time it takes to receive 2
       serial port characters, or at least 1000us, before sending.  This
       allows more efficient use of network resources when receiving large
       amounts of data, but gives reasonable interactivity.  Default is true.

       chardelay-scale: <number> sets the number of serial port characters, in
       tenths of a character, to wait after receiving from the connection
       gensio and sending to the accepted gensio.  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.  The
       default value is 20.

       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.

       sendon: <sendon string> If the given string is seen coming from the
       connector side of the connection, sends buffered data up to and
       including the string. Disabled by default. As an example, this can be
       set to \r\n with appropriate chardelay settings to send one line at a
       time.  It uses string handling as described in "SPECIAL STRING
       HANDLING" above.  See the notes on the closeon string for important
       information on how the comparison is done.

       dev-to-net-bufsize: <number> sets the size of the buffer reading from
       the connecting gensio and writing to the accepted gensio.

       net-to-dev-bufsize: <number> sets the size of the buffer reading from
       the accepted gensio and writing to the connecting gensio.

       led-tx: <led-alias> use the previously defined led to indicate serial
       tx traffic on this port.  This should be a YAML alias, like *led2.

       led-rx: <led-alias> use the previously defined led to indicate serial
       rx traffic on this port.  This should be a YAML alias, like *led2.

       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, generally in the
       form <ip address>,<port>.  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.

       no-con-to-acc: true|false If true, do not transfer any data from the
       connector to the accepter.  Throw any data received from the connecter
       away.

       no-acc-to-con: true|false If true, do not transfer any data from the
       accepter to the connecter.  Throw any data received from the accepter
       away.

       connback: <connector>[;<connector>[;...]] specifies reverse connections
       that will be made when data comes in on the device.  When data comes in
       on the device side (the connection's main connector) ser2net will
       connect to each connback specified.  No connection is made until data
       comes in, and normal connection timeouts apply.

       Note that this will use one of the connection's connections all the
       time.  You may need to increase max-connections if you need more than
       one or want to accept incoming connections, too.

       Connect back addresses must match the format of the accepter address.
       So, for instance, if your accepter is "telnet,tcp,1234" your connect
       back address must be something like "telnet,tcp,hostname,1123".

       The port will send no data to any connect back unless all the connect
       backs are connected.

       A connect back port can also have connections made to it if you set the
       number of connections larger than the number of connect backs
       specified.  However, those connections will receive no data from the
       port uness all connect backs have been established.

       authdir: <directory string> specified the authentication directory to
       use for this connection.

       pamauth: <service name> Enables PAM authentication and sets the PAM
       service name.

       allowed-users: <space separated list of names> The users that are
       allowed to use this connections.  This has no meaning if authentication
       is not enabled on the connections.  If this is not set or defaulted,
       all users are allowed.  If this is set to an empty set of users, then
       no users are allowed.  This may be specified more than once, each one
       adds more users.

       mdns: true|false Enables/disables mdns support for the connection.  If
       you set this and mdns is available, ser2net will create a service on
       mdns for the port.

       mdns-interface: <num> Sets the specific network interface to advertise
       the device.  Defaults to -1, which means all network interfaces.

       mdns-nettype: unspec|ipv4|ipv6 Sets which network type to provide for
       the device advertisement.  Defaults to unspec, which means do ipv4 and
       ipv6.

       mdns-name: <string> Sets the name in the mDNS advertisement.  Defaults
       to the connection name.

       mdns-type: <string> Sets the type in the mDNS advertisement.  Defaults
       to "_iostream._xxx" where xxx is either tcp, udp # # or sctp base on
       the gensio type.

       mdns-domain: <string> Sets the name in the mDNS advertisement.
       Defaults to the system setting.  Don't set this unless you really know
       what you are doing.

       mdns-host: <string> Sets the host in the mDNS advertisement.  Defaults
       to the system setting.  Don't set this unless you really know what you
       are doing.

       mdns-txt: <string> Adds a text string to the mDNS advertisement.  The
       string should be in the form "name=value".  You can put anything you
       want in the strings.  Two default strings are added by ser2net:
       "provider=ser2net" and "gensiostack=..." where the stack of gensios is
       added, like "telnet(rfc2217),tcp)".  The idea of gensiostack is you can
       just tack on the address to the end an make a connection using
       str_to_gensio().

       mdns-sysattrs: true|false On Linux adds system attributes from sysfs
       for USB serial ports to the mDNS txt fields.  If the serial port is
       USB, it adds "devicetype=serialusb" and the following attributes from
       sysfs: bInterfaceNumber, interface, idProduct, idVendor, serial,
       manufacturer, product.  If they are not present in sysfs, they are not
       added.  If the serial port is not USB, then "devicetype=serial" is
       added.

       Note: Be *very* careful when using a gensiostack with str_to_gensio().
       Just blindly calling str_to_gensio() with it could result in
       significant security issues, as it can pass pty, stdio, trace, etc.
       gensios in it.  You must either validate that the stack is a safe set
       or just use it for information.  You have been warned.  Be careful.

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

       A rotator specification looks like:
              rotator: &<alias>
                     accepter: <accepter>
                     connections: [
                            <connection alias>,
                            <connection alias>....
                     ]
                     options:
                            <option name>: <option val>
                            <option name>: <option val>...

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

       You should use YAML aliases for the connections.

       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.


SER2NET DEFAULTS
       To set a default, do:
              default:
                     name: <default name>
                     value: <default value>
                     class: <default class>

       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),
       do:
              delete_default:
                     name: <default name>,
                     class: <default class>

       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.

ADMIN CONNECTIONS
       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:
              admin: [&<name>]
                     accepter: <accepter>
                     options:
                            <option name>: <option value>
                            <option name>: <option value>...

       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.


LEDS
       ser2net can flash LEDs during serial activity.  To create an LED, do:
              led: &<alias>
                     driver: sysfs
                     options:
                            <option name>: <option value>
                            <option name>: <option value>

       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.


FILENAME, BANNER, AND STRING FORMATTING
       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:

         \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 connecting gensio string (serialdev,/dev/ttyS0, etc.)
         \o - The device as specified on the config line (before DEVICE
         substitution)
         \N - The port name
         \p - The accepter string
         \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
         \I -> remote address of the accepter gensio
         \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 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.


   HANDLING QUOTING AND STRING FORMATTING
       yaml will process "\" escape sequences in double quotes, so use of
       double quotes is note recommended for the above.  If you put the values
       in single quotes, yaml will not process them and instead pass them
       through where they can be processed by ser2net.


SPACES, QUOTING AND PUTTING SPACES IN STRINGS
       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:
              connector: serialdev,/dev/ttyUSB0,
                     9600n81
                     local nobreak
                     rtscts
       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
       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:

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

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


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


AUTHENTICATION AND ENCRYPTION
   TCP WRAPPERS
       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.


   ENCRYPTION
       ser2net supports SSL encryption using the ssl gensio.  To enable
       encryption, use an accepter like:

              telnet,ssl,tcp,1234

       Then you can use gensiot to connect:

              gensiot telnet,ssl,<server>,1234

       or you can install telnet-ssl and do

              telnet -z ssl,secure <server> 1234

       The SSL connection is made using the provided keys.  In this example
       ser2net uses the default keys (as set in the default, see those below).
       You can also set them using (key=<keyfile>,cert=<certfile>) after ssl
       above, or modify the defaults.

       If you do not have genuine certificates from a certificate authority,
       the connection will fail due to certificate failure.  Getting
       certificates this way is very inconvenient, so there is another way.
       You can do:

              gtlssh-keygen --keydir /etc/ser2net --commonname
              "`hostname`-ser2net" serverkey ser2net

       to generate the default keys in /etc/ser2net (or wherever).  The
       certificate/key will be named /etc/ser2net/ser2net.crt|key.

       NOTE: If you compile ser2net yourself, by default autoconf sets the
       system configuration directory (normally /etc) as /usr/etc.  This is a
       major annoyance with autoconf.  So if you don't change it, you would
       need /usr/etc above where it says /etc.  However, generally the right
       way to do this is to add "--sysconfdir=/etc" to the configure command
       line when you configure ser2net.  If a distro has compiled ser2net for
       you, that should have done that by default, so no worries in that case.

       Then copy ser2net.crt over to the user system and provide it to
       connection commands, like:

              gensiot telnet,ssl(CA=ser2net.crt),<server>,1234

       or

              telnet -z ssl,secure,cacert=ser2net.crt 1234

       Then you will have an encrypted connection.  Just make sure your
       certificates are valid.

       Note that the "-ser2net" at the end of the key is important because it
       make the subject name of the certificate more unique.  You can really
       put anything you want for what you provide to keygen, as long as you
       rename it properly.  That will be the subject name of the certificate.

   AUTHENTICATION WITH SSL
       ser2net provides a way to authenticate with SSL.  It's not the
       greatest, but it does work.  You must enable clientauth on ssl:

              telnet,ssl(clientauth),tcp,1234

       or set it in the default.  Then you must create a certificate with the
       username as the common name.  You can do this with:

              gtlssh-keygen --keydir outdir --commonname username keygen
              keyname

       which will generate keyname.crt and keyname.key in outdir.  Then put
       keyname.crt in ser2net's <authdir>/username/allowed_certs.  By default
       <authdir> is /usr/share/ser2net/auth, but you can change that with the
       authdir default in the ser2net config file or by setting authdir on
       individual connections (in case you want different ones for different
       ports).  You then must rehash the allowed_certs directory:

              gtlssh-keygen rehash <authdir>/username/allowed_certs

       Then restart/reload ser2net and use one of these very long lines to
       telnet into it:

              gensiot
              telnet,ssl(CA=ser2net.crt,cert=username.crt,key=username.key),<server>,1234

              telnet -z
              ssl,secure,cacert=ser2net.crt,cert=username.crt,key=username.key
              server 1234

   AUTHENTICATION WITH CERTAUTH (GTLSSH)
       All of the above is a big pain.  Fortunately there is an easier way.
       gtlssh is a ssh-like program, but runs over TLS and it implements a
       ssh-like authentication protocol using the certauth gensio.

       ser2net supports this authentication system running on top of the ssl
       and certauth gensios.  Those gensios provide the framework for handling
       authentication, ser2net itself controls it.

       This uses the same authdir and allowed keys directory as before, and
       still requires a server certificate, but the self-signed one generated
       with gtlssh-keygen works fine without doing anything special.  Add
       certauth to the port line:

              telnet,mux,certauth,ssl,tcp,1234

       and *make sure* clientauth is disabled for ssl (or ssl will still
       attempt to authenticate the client).  Disabled is the default but in
       case you changed, the default...

       The mux entry is because gtlssh uses the mux gensio to allow multiple
       channels on the same session.  It wasn't there with older (pre 1.2)
       version of gtlssh, but is required for newer one.  gtlssh also has a
       --nomux option, just in case.

       The gtlssh program does its own certificate handling.  Look at the
       gtlssh man page for detail on that.  Take the certificate for gtlssh
       and put it in the authdir/username/allowed_certs directory and reshash
       it as before.  gtlssh will *not* use the common name provided in the
       certificate, instead it users a username provided by gtlssh.  Then
       connect with gtlssh:

              gtlssh --nosctp --telnet username@server 1234

       The --nosctp thing keep gtlssh from trying sctp, which will fail
       because we put tcp in the port line.  You could use sctp there and get
       all its advantages for free!  Then --nosctp would no longer be required
       to avoid the nagging.

       The username is optional if it's the same as your current user.  If you
       have not connected to that server/port before, gtlssh will ask you to
       verify it, much like ssh does.  If certificates, IP address, etc.
       change, gtlssh will tell you about it.

       If you do not want to use a certificate (certificates are certainly
       preferred, but may not always be workable) you can use a password
       login, too. You must set enable-password in the certauth gensio options
       for passwords to work.  When you connect with gtlssh, if certificate
       validate fails, you will be prompted for the password. Password
       authentication can be performed in two different ways.  Both are
       mutually exclusive,  depending on whether pamauth is set or not:

       o      To authenticate using the PAM library set the PAM service name
              via pamauth option.

       o      Put a password in authdir/username/password. If it matches the
              first line in the password file and pamauth is not set, then
              authentication will succeed.

   AUTHENTICATION AND ROTATORS
       Rotators are a special case.  BE CAREFUL.  A rotator has its own
       authentication.  If you set up authentication on a port that is part of
       a rotator, that port's authentication is not used.  Only the rotator's
       authentication is used.

   ENCRYPTION, AUTHENTICATION, AND DEFAULT CERTIFICATES
       ser2net expects default certificates and public keys in /etc/ser2net,
       and these are set as gensio defaults.  This means that any outgoing
       connection from ser2net, whether in a connector or in a connback, will
       use these keys.  If they aren't there or have expired or something you
       will get confusing errors about not being able to open the
       certificates.

       To solve this, you can disable the certificates by adding "cert=" to
       the gensio specification for ssl and certauth on outgoing connections.
       This will disable the certificates for the specific gensio, and is
       probably what you want.  If you are making connections and
       authenticating to the remote server, the default certificate and
       private key are probably not what you want, either.

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.


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


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


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


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


AUTHOR
       Corey Minyard <minyard@acm.org>

Serial to network proxy configuration file
                                   06/02/01                    ser2net.yaml(5)