ser2net(8)

🌸 ser2net — the serial-to-network proxy, bestie edition 💅

okay so. this is the manual page for ser2net, from the System Manager's Manual (section 8, system manager girlies rise up 👑). Serial to network proxy. that's the whole vibe. let's get into it 🦋

---

✨ SYNOPSIS ✨

ser2net [-c configfile] [-C sysconfdir] [-Y configline] [-p admin-accepter] [-n] [-d] [-b] [-v] [-P pidfile]

like. look at her. so many little flags. we're gonna go through every single one, no skips, no cap 🫶

---

💖 DESCRIPTION 💖

okay so the ser2net daemon is literally the main character that lets telnet and tcp sessions be established with a unit's serial ports, or with an IPMI Serial Over LAN (SOL) interface. that's it. that's the job.

the program comes up normally as a daemon, opens the network ports specified in the configuration file, and then just. waits. patiently. for connections. 🧚

once a connection occurs, the program attempts to set up the connection and open the serial port. and if another user is already using the connection or the serial port? nope. the connection is refused with an error message. sorry bestie, it's taken 💀

---

🎀 OPTIONS 🎀

• -c config-file — sets the configuration file to something other than the default of sysconfdir/ser2net/ser2net.yaml. and listen, if the config-file is - then standard input is read as the config file. iconic. see -C for info on sysconfdir.
• -C sysconfdir — sets the directory where the configuration file and ssl keys are stored. generally this is /etc/ser2net on Unix-type systems. on Windows it's ../etc/ser2net from the executable's location by default.
• -a authdir — sets the default directory where authentication information is stored. generally /usr/share/ser2net on Unix-type systems, on Windows it's ../share/ser2net from the executable's location by default. this can be overridden in the config file. see the ser2net.yaml.5 for info on what this does.
• -A admin-authdir — sets the default directory where the administrator's authentication information is stores. this is sysconfdir/auth by default. this can be overridden in the config file. see the ser2net.yaml.5 for info on what this does.
• -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 quotes (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.
• -w — allow unhashed passwords. normally only hashed passwords are allowed, this is for backwards compatibility.
• -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.
• 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.

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. literally none. she's perfect. ate and left no crumbs 🔥

---

🌸 AUTHOR 🌸

Corey Minyard <minyard@acm.org> — thank you for our lives, king 👑

---

okay bestie that's the whole page 💖 source/version is Serial to network proxy, dated 06/02/01, and it lives at ser2net(8). go forth and proxy those serial ports, you've got this ✨🫶