1ser2net.yaml(5) File Formats Manual ser2net.yaml(5)
2
6 /etc/ser2net/ser2net.yaml - Serial to network proxy configuration file
7
10 ser2net used to be a program for connection network connections to se‐
11 rial ports. It's now a program for connecting accepter gensio to con‐
12 necting gensios. See gensio(5) for details on gensios.
13 ser2net is configured with YAML, which is flexible and easy to use.
15 Look at yaml documentation on the internet for how that works.
16 However, there are two types of YAML files that ser2net can use: ver‐
18 sion 1 and version 2. Version 1 YAML files have more capability than
19 version 2 files, but they are non-standard YAML, a standard YAML parser
20 cannot read them. ser2net will autodetect the version based upon what
21 it finds.
22 In version 2, you can have multiple documents in a file and ser2net
24 will read all of them. YAML separates documents in a file with a sin‐
25 gle "---" by itself at the beginning of a line. Though you can only
26 have one set of defaults, defines, connections, etc. in a document, you
27 can have multiple documents in a file to allow more than one. You
28 might, for instance, group all the connections with a certain set of
29 defaults into its own document.
30
33 YAML has the ability to create aliases that can be used elsewhere in
34 the configuration file. These can be used for tying things together
35 between parts of the file, or (as an extension to YAML) for string sub‐
36 stitution.
37 You define an alias in version 1 with the following:
39 define: &aliasname alias text
41 This will create an alias with the given name. Then you can use it
43 elsewhere like:
44 banner: *aliasname
46 and the banner will be "alias text". Unlike standard YAML, you can
48 also use this inside strings using
49 *(aliasname)
51 so if you have
53 banner: My banner *(aliasname) is here
55 The banner will be "My banner alias text is here". See the YAML docu‐
57 mentation for how spaces are handled, but as a note, use quotes if you
58 are not sure, like:
59 define: &aliasname "alias text"
61 banner: "My banner *(aliasname) is here"
62 If you for some reason need "*(" in your text, use "*(*" for that.
64 For version 2 YAML files, the definition is:
66 defines:
68 aliasname: alias text
69 aliasname2: alias text 2
70 where you can list as many aliases as you like. In version 2, you al‐
72 ways refer to an alias with "=" instead of "*", like:
73 banner: "My banner =(aliasname) is here"
75 and if you for some reason need "=(" in your text, use "=(=" for that.
77 In version 2, per standard YAML, you can only have one defines section,
79 so they must all be together.
80
83 A YAML file may include another file at the main level, with:
84 include: <filename>
86 This filename can include globs, and all referenced files are included.
88 These must be full yaml files, but are included in context at this
89 point, with all the defines, connection names, etc. This can let you
90 have individual connections in individual files to ease management.
91 In version 2, You can only have one include in each document for legal
93 YAML, so if you need multiple includes you will have to have multiple
94 documents.
95
98 You may want to store passwords and such in external files for better
99 security. For version 1, putting "*{filename}" in a YAML scalar will
100 put the file's contents into the scalar at that point. If you need a
101 "*{" in the string for some reason, use "*{*".
102 For version 2, use "={filename}" instead. And "={=" to include a "={"
104 in a file.
105
108 A connection is a structure that describes how to connect an accepting
109 gensio to a connecting gensio.
110 An connection specification in version 1 starts with:
112 connection: &<alias>
114 <definition>
115 In version 2, it's specified as:
117 connections:
118 <alias>:
119 <definition>
120 In version 2, all the connections must occur together in one place.
122 The <definition> of a connection is the same for version 1 and version
124 2:
125 accepter: <accepter>
126 timeout: <number>
127 enable: on|off
128 connector: <connector>
129 options:
130 <option name>: <option value>
131 <option name>: <option value>...
132 An <accepter> is an accepting gensio specification. When ser2net re‐
134 ceives a connection on the accepter, it attempts to make a connection
135 to the <connector> gensio. The alias is required, it sets the name
136 that is used for the connection in the admin interface and for refer‐
137 encing from rotators.
138 If the connection receive no activity in <timeout> seconds, ser2net
140 will close the connection. Setting <timeout> to zero disables the
141 timeout. The timeout field is optional and defaults to zero.
142 The connection may be enabled or disabled with the enable. The enable
144 field is optional and defaults to on. This is useful for temporarily
145 disabling port by setting enable to off and sending a SIGHUP. If there
146 are users connected and you disable a port and send a SIGHUP, the users
147 will be kicked off.
148 An option is a configuration setting that doesn't have anything to do
150 with specific gensios, they are controls for ser2net in general. The
151 option section is optional.
152 See gensio(5) for a lot of information about the specific gensios
154 available.
155 To allow a TCP connection to a serial port and ignore modem control,
157 you can do:
158 connection: &toS0tcp
159 accepter: tcp,1234
160 connector: serialdev,/dev/ttyS0,local
161 Both accepting and connecting gensios stack, so if you want to add tel‐
163 net with RFC2217 support, you can do:
164 connection: &toS0telnet
165 accepter: telnet(rfc2217),tcp,1234
166 connector: serialdev,/dev/ttyS0,local
167 If you want to accept a telnet over SCTP connection only on IPv6 local‐
169 host and connect to a telnet connection with SSL over tcp, you can do:
170 connection: &tomyhost
171 accepter: telnet,sctp,::1,1234
172 connector: telnet,ssl,tcp,myhost.domain.org,1234
173 RFC2217 support only make sense with a serial-capable device as the
175 connector. Also note that IPv6 is fully supported. Accepters will
176 generally default to being both IPv4 and IPv6 unless otherwise speci‐
177 fied. See gensio(5) for details.
178 And yes, SCTP is supported and is highly recommended if you can use it.
180 Multi-homing alone is worth it.
181 You could create a secure login with telnet RFC2217 support that then
183 connects to an IPMI sol connection. Notice how splitting the connector
184 line is done with YAML.
185 connection: &authsol
186 accepter: telnet(rfc2217),mux,certauth,ssl,sctp,1234
187 connector: ipmisol,lan -U ipmiusr -P test -p 9001
188 ipmiserver.domain.org,9600
189 options:
190 banner: My banner
191 These are some examples. For SSL and certauth, I have ignored the au‐
193 thentication configuration, more on that later. Using authentication
194 is strongly recommended, it's easy now with gtlssh and if you need to
195 use it from a program, it's easy with gensio. There is even python
196 support. Adding support for other scripting languages shouldn't be too
197 hard.
198 SPECIAL STRING HANDLING
201 Some string values, like banners, have special formatting for inserting
202 various values. These are all prepended with '\'. This takes the
203 standard "C" \x characters.
204 \a - bell
206 \b - backspace
207 \f - form feed
208 \n - newline
209 \r - carriage return
210 \t - tab
211 \v - vertical tab
212 \\ - \
213 \? - ?
214 \' - '
215 \" - "
216 \nnn - octal value for nnn
217 \xXX - hex value for XX
218 \d - The connector string (/dev/ttyS0, etc.)
219 \o - The name of the connection.
220 \p - Network port number
221 \B - The serial port parameters (eg 9600N81) if applicable
222 \Y -> year
223 \y -> day of the year (days since Jan 1)
224 \M -> month (Jan, Feb, Mar, etc.)
225 \m -> month (as a number)
226 \A -> day of the week (Mon, Tue, etc.)
227 \D -> day of the month
228 \e -> epoc (seconds since Jan 1, 1970)
229 \U -> microseconds in the current second
230 \p -> local port number
231 \I -> remote IP address (in dot format)
232 \H -> hour (24-hour time)
233 \h -> hour (12-hour time)
234 \i -> minute
235 \S -> second
236 \q -> am/pm
237 \P -> AM/PM
238 These sequences may be used to make the filename unique per open and
240 identify which port/device the filename was for. Note that in file‐
241 names when using \d or \o, everything up to and including last / in the
242 device name is removed, because you can't have a / in a filename. So
243 in a filename /dev/ttyS0 would become just ttyS0.
244 Note that in banners and other strings going out (not filenames) you
246 must use \r\n to send a new line; this is raw handling and \n will only
247 go down one line, it will not return to the beginning of the line.
248 CONNECTION SPECIFICATION OPTIONS
251 kickolduser: true|false sets the port so that the previous user will be
252 kicked off if a new user comes in. Useful if you forget to log off
253 from someplace else a lot.
254 banner: <banner string> displays the given banner when a client con‐
256 nects. It uses string handling as described in "SPECIAL STRING HAN‐
257 DLING" above.
258 signature: <signature string> sends RFC2217 signature on clients re‐
260 quest. This may be an empty string.
261 openstr: <openstr name string> Send the given string to the device on
263 first open. This may be an empty string. It uses string handling as
264 described in "SPECIAL STRING HANDLING" above.
265 closestr: <closestr name> Send the given string to the device on final
267 close. This may be an empty string. It uses string handling as de‐
268 scribed in "SPECIAL STRING HANDLING" above.
269 closeon: <closeon string> If the given string is seen coming from the
271 connector side of the connection, close the connection. The comparison
272 here is, for simplicity, simplistic. Complex expressions with repeti‐
273 tive things may not compare correctly. For instance, if your closeon
274 strings is "ababc" and your input strings is "abababc", the comparison
275 will fail because the comparison algorithm will see "ababa" and will
276 fail on the final "a" and start over at "abc", which won't match. This
277 shouldn't cause a problem most cases, but if it does, contact the au‐
278 thors and it can be improved.
279 accepter-retry-time: <time in seconds> If the accepter does not come up
281 at startup, wait this many seconds and retry it.
282 connector-retry-time: <time in seconds> On a connect-back port, if the
284 connector does not come up or goes down. wait this many seconds and
285 retry it.
286 trace-read: <filename> When the acceptor is opened, open the given file
288 and store all data read from the physical device (and thus written to
289 the client's network/acceptor port) in the file. If the file already
290 exists, it is appended. The file is closed when the port is closed.
291 The filename uses string handling as described in "SPECIAL STRING HAN‐
292 DLING" above.
293 trace-write: <filename> Like tr, but traces data written to the con‐
295 necting gensio.
296 trace-both: <filename> trace both read and written data to the same
298 file. Note that this is independent of tr and tw, so you may be trac‐
299 ing read, write, and both to different files.
300 trace-hexdump: true|false turns on/off hexdump output to all trace
302 files. Each line in the trace file will be 8 (or less) bytes in canon‐
303 ical hex+ASCII format. This is useful for debugging a binary protocol.
304 trace-timestamp: true|false adds/removes a timestamp to all of the
306 trace files. A timestamp is prepended to each line if hexdump is active
307 for the trace file. A timestamped line is also recorded in the trace
308 file when a remote client connects or disconnects from the port.
309 [trace-read-|trace-write-|trace-both-]hexdump: true|false turns on/off
311 hexdump output for only one trace file. May be combined with hexdump.
312 Order is important.
313 [trace-read-|trace-write-|trace-both-]timestamp: true|false adds/re‐
315 moves a timestamp to only one the trace files May be combined with
316 [-]timestamp. Order is important.
317 telnet-brk-on-sync: true|false causes a telnet sync operation to send a
319 break. By default data is flushed until the data mark, but no break is
320 sent.
321 chardelay: true|false enables the small wait after each character re‐
323 ceived on the connecting gensio before sending data on the accepted
324 gensio. Normally ser2net will wait the time it takes to receive 2 se‐
325 rial port characters, or at least 1000us, before sending. This allows
326 more efficient use of network resources when receiving large amounts of
327 data, but gives reasonable interactivity. Default is true.
328 Note that this feature is designed to balance network efficiency and
330 interactivity. It is not designed to give guarantees of minimum chunk
331 of data size, as task scheduling and network stacks can modify these
332 things, too.
333 chardelay-scale: <number> sets the time, measured in tenths of serial
335 port characters, to wait after receiving from nothing from the connec‐
336 tion before sending to the accepted gensio. So setting this to 25 will
337 cause ser2net to wait the amount of time it takes to receive 2.5 serial
338 port characters after receiving the last character before sending the
339 data on to the TCP port. The default value is 20, max is 1000. This
340 is ignored for non-serial gensios.
341 chardelay-min: <number> is the same as chardelay-scale, but in mi‐
343 croseconds. The larger of chardelay-scale and chardelay-min is used.
344 The default value is 1000, max is 100000.
345 chardelay-max: <number> sets the maximum delay that ser2net will wait,
347 in microseconds, after receiving a character, before sending the data.
348 The default value is 20000, max is 1000000. This keeps the connection
349 working smoothly at slow speeds.
350 sendon: <sendon string> If the given string is seen coming from the
352 connector side of the connection, sends buffered data up to and includ‐
353 ing the string. Disabled by default. As an example, this can be set to
354 \r\n with appropriate chardelay settings to send one line at a time.
355 It uses string handling as described in "SPECIAL STRING HANDLING"
356 above. See the notes on the closeon string for important information
357 on how the comparison is done.
358 dev-to-net-bufsize: <number> sets the size of the buffer reading from
360 the connecting gensio and writing to the accepted gensio.
361 net-to-dev-bufsize: <number> sets the size of the buffer reading from
363 the accepted gensio and writing to the connecting gensio.
364 led-tx: <led-alias> use the previously defined led to indicate serial
366 tx traffic on this port. For version 2 this should be a YAML alias,
367 like *led2. For version 2 just use the name, like led2.
368 led-rx: <led-alias> use the previously defined led to indicate serial
370 rx traffic on this port. For version 2 this should be a YAML alias,
371 like *led2. For version 2 just use the name, like led2.
372 max-connections: <number> set the maximum number of connections that
374 can be made on this particular TCP port. If you make more than one
375 connection to the same port, each ports output goes to the device, and
376 the device output goes to all ports simultaneously. See "MULTIPLE CON‐
377 NECTIONS" below for details. The default is 1.
378 remaddr: <addr>[;<addr>[;...]] specifies the allowed remote connec‐
380 tions, where the addr is a standard address, generally in the form <ip
381 address>,<port>. Multiple addresses can be separated by semicolons,
382 and you can specify remaddr more than once.
383 If you set the port for an address to zero, ser2net will accept a con‐
385 nection from any port from the given network host.
386 no-con-to-acc: true|false If true, do not transfer any data from the
388 connector to the accepter. Throw any data received from the connecter
389 away.
390 no-acc-to-con: true|false If true, do not transfer any data from the
392 accepter to the connecter. Throw any data received from the accepter
393 away.
394 connback: <connector>[;<connector>[;...]] specifies reverse connec‐
396 tions that will be made when data comes in on the device. When data
397 comes in on the device side (the connection's main connector) ser2net
398 will connect to each connback specified. No connection is made until
399 data comes in, and normal connection timeouts apply.
400 Note that this will use one of the connection's connections all the
402 time. You may need to increase max-connections if you need more than
403 one or want to accept incoming connections, too.
404 Connect back addresses must match the format of the accepter address.
406 So, for instance, if your accepter is "telnet,tcp,1234" your connect
407 back address must be something like "telnet,tcp,hostname,1123".
408 The port will send no data to any connect back unless all the connect
410 backs are connected.
411 A connect back port can also have connections made to it if you set the
413 number of connections larger than the number of connect backs speci‐
414 fied. However, those connections will receive no data from the port
415 uness all connect backs have been established.
416 connback-timeout: <time in seconds> specifies a separate timeout for
418 connect back ports. Normally it uses the main timeout, this lets you
419 have a different one. Setting it to zero, like the main timeout, dis‐
420 ables the timeout.
421 authdir: <directory string> specified the authentication directory to
423 use for this connection.
424 pamauth: <service name> Enables PAM authentication and sets the PAM
426 service name.
427 allowed-users: <space separated list of names> The users that are al‐
429 lowed to use this connections. This has no meaning if authentication
430 is not enabled on the connections. If this is not set or defaulted,
431 all users are allowed. If this is set to an empty set of users, then
432 no users are allowed. This may be specified more than once, each one
433 adds more users.
434 mdns: true|false Enables/disables mdns support for the connection. If
436 you set this and mdns is available, ser2net will create a service on
437 mdns for the port.
438 mdns-interface: <num> Sets the specific network interface to advertise
440 the device. Defaults to -1, which means all network interfaces.
441 mdns-nettype: unspec|ipv4|ipv6 Sets which network type to provide for
443 the device advertisement. Defaults to unspec, which means do ipv4 and
444 ipv6.
445 mdns-name: <string> Sets the name in the mDNS advertisement. Defaults
447 to the connection name.
448 mdns-type: <string> Sets the type in the mDNS advertisement. Defaults
450 to "_iostream._xxx" where xxx is either tcp, udp # # or sctp base on
451 the gensio type.
452 mdns-domain: <string> Sets the name in the mDNS advertisement. De‐
454 faults to the system setting. Don't set this unless you really know
455 what you are doing.
456 mdns-host: <string> Sets the host in the mDNS advertisement. Defaults
458 to the system setting. Don't set this unless you really know what you
459 are doing.
460 mdns-txt: <string> Adds a text string to the mDNS advertisement. The
462 string should be in the form "name=value". You can put anything you
463 want in the strings. Two default strings are added by ser2net:
464 "provider=ser2net" and "gensiostack=..." where the stack of gensios is
465 added, like "telnet(rfc2217),tcp)". The idea of gensiostack is you can
466 just tack on the address to the end an make a connection using
467 str_to_gensio().
468 mdns-sysattrs: true|false On Linux adds system attributes from sysfs
470 for USB serial ports to the mDNS txt fields. If the serial port is
471 USB, it adds "devicetype=serialusb" and the following attributes from
472 sysfs: bInterfaceNumber, interface, idProduct, idVendor, serial, manu‐
473 facturer, product. If they are not present in sysfs, they are not
474 added. If the serial port is not USB, then "devicetype=serial" is
475 added.
476 Note: Be *very* careful when using a gensiostack with str_to_gensio().
478 Just blindly calling str_to_gensio() with it could result in signifi‐
479 cant security issues, as it can pass pty, stdio, trace, etc. gensios in
480 it. You must either validate that the stack is a safe set or just use
481 it for information. You have been warned. Be careful.
482
484 A rotator allows a single network connection to connect to one of a
485 number of connections.
486 A version 1 rotator specification starts with:
488 rotator: &<alias>
489 <definition>
490 A version 2 rotator specification starts with:
492 rotators:
494 <alias>:
495 <definition>
496 Just like connections, in version 2 you have to put all the rotators
498 together.
499 The definition of a rotator is almost the same between version 1 and
501 version 2:
502 accepter: <accepter>
504 connections: [
505 <connection alias>,
506 <connection alias>....
507 ]
508 options:
509 <option name>: <option val>
510 <option name>: <option val>...
511 A rotator has four possible options, "authdir", "pamauth", "allowed-
513 users", and "accepter-retry-time", both same as connections.
514 For version 1, you should use YAML aliases for the connections. For
516 version 2, just use the alias names.
517 Connections to the accepter will go through the set of connections and
519 find the first unused one and use that. The next connection will start
520 after the last connection used. Note that disabled connections are
521 still accessible through rotators.
522 Note that the security of the connection is NOT used, only the security
524 of the rotator.
525
528 To set a default in version 1, do:
529 default:
530 name: <default name>
531 value: <default value>
532 class: <default class>
533 In version 2, like other things, the defaults are all in one place in a
535 document, like:
536 defaults:
537 <name>:
538 value: <default value>
539 class: <default class>
540 <name2>:
541 value: <default value>
542 class: <default class>
543 The class is optional, if it is not there it sets the base default for
545 all classes that is used unelss overridden for a specific class. If
546 the class is there, it sets the default for a specific gensio class.
547 There is also a ser2net class that is for ser2net specific options.
548 The class is useful if you want different values for different gensio
550 types. For instance, if you wanted all serial ports to run at 9600
551 baud and all IPMI SOL connections to run at 115200 baud, you could do:
552 default:
553 name: speed
554 value: 9600
555 class: serialdev
556 default:
557 name: speed
558 value: 115200
559 class: ipmisol
560 The value is also optional, if it is not present a string value is set
562 to NULL and an integer value is set to 0.
563 The order in the file is important, you must set a default before it is
565 used, and you can change the value of the default. It will affect all
566 uses following the setting.
567 To delete a default value for class (so it will use the base default),
569 for version 1 do:
570 delete_default:
571 name: <default name>,
572 class: <default class>
573 For version 2, do:
575 delete_defaults:
576 <default name>: [ <class1>, <class2>, ... ]
577 <default name2>: [ <class1>, <class2>, ... ]
578 and it will delete the defaults for the classes in the list after it.
579 You must supply the class, you cannot delete base defaults.
581 The following default values are specific to ser2net, given with their
583 default values:
584 telnet-brk-on-sync: false
586 If a telnet sync is received, send a break on the connected gen‐
587 sio (if applicable). By default data is flushed until the data
588 mark, but no break is sent.
589 kickolduser: false
591 If a new user comes in on a connection that already has a user,
592 kick off the previous user.
593 chardelay: true
595 Enable asmall wait after each character received on the serial
596 port before sending data on the TCP port. Normally ser2net will
597 wait the time it takes to receive 2 serial port characters, or
598 at least 1000us, before sending on the TCP port. This allows
599 more efficient use of network resources when receiving large
600 amounts of data, but gives reasonable interactivity.
601 chardelay-scale: 20
603 sets the number of serial port characters, in tenths of a char‐
604 acter, to wait after receiving from the serial port and sending
605 to the TCP port. So setting this to 25 will cause ser2net to
606 wait the amount of time it takes to receive 2.5 serial port
607 characters before sending the data on to the TCP port. This can
608 range from 1-1000.
609 chardelay-min: 1000
611 sets the minimum delay that ser2net will wait, in microseconds.
612 If the calculation for chardelay-scale results in a value
613 smaller than this number, this number will be used instead. The
614 default value is 1000. This can range from 1-100000.
615 net-to-dev-bufsize: 64
617 sets the size of the buffer reading from the network port and
618 writing to the serial device.
619 dev-to-net-bufsize: 64
621 sets the size of the buffer reading from the serial device and
622 writing to the network port.
623 max-connections: 1
625 set the maximum number of connections that can be made on this
626 particular TCP port. If you make more than one connection to
627 the same port, each ports output goes to the device, and the de‐
628 vice output goes to all ports simultaneously. See "MULTIPLE
629 CONNECTIONS" below. for details.
630 remaddr: [!]<addr>[;[!]<addr>[;...]]
632 specifies the allowed remote connections, where the addr is a
633 standard address in the form (see "network port" above). Multi‐
634 ple addresses can be separated by semicolons, and you can spec‐
635 ify remaddr more than once. If you set the port for an address
636 to zero, ser2net will accept a connection from any port from the
637 given network host. If a "!" is given at the beginning of the
638 address, the address is a "connect back" address. If a connect
639 back address is specified, one of the network connections (see
640 max-connections) is reserved for that address. If data comes in
641 on the device, ser2net will attempt to connect to the address.
642 This works on TCP and UDP.
643 authdir: /usr/share/ser2net/auth
645 The authentication directory for ser2net. The AUTHENTICATION
646 for more details.
647 authdir-admin: /etc/ser2net/auth
649 The authentication directory for ser2net for admin connections.
650 The "ADMIN_CONNECTIONS" for more details.
651 pamauth: <NULL>
653 The PAM service name for ser2net PAM authentication (<NULL> for
654 disabled).
655 pamauth-admin: <NULL>
657 The PAM service name for ser2net admin connection PAM authenti‐
658 cation (<NULL> for disabled). See "ADMIN_CONNECTIONS" for more
659 details.
660 mdns-interface: -1
662 The default mDNS interface.
663 mdns-type: <NULL>
665 The default mDNS type.
666 mdns-domain: <NULL>
668 The default mDNS domain.
669 mdns-host: <NULL>
671 The default mDNS host.
672
674 There is an admin accepter that you can define for ser2net, it lets you
675 log in, look at status, and change some things. See "ADMIN INTERFACE"
676 in ser2net(8) for detail on how to use it. The format is:
677 admin: [&<name>]
678 accepter: <accepter>
679 options:
680 <option name>: <option value>
681 <option name>: <option value>...
682 The following authentications options available are "authdir-admin",
684 which sets the authentication directory for the admin port and "pa‐
685 mauth-admin" which sets the PAM service name and enables PAM authenti‐
686 cation. Both are different than "authdir" resp. "pamauth" for connec‐
687 tions, though you can set it to the same value.
688 In addition, the same mdns option are available for admin ports as are
690 available for connections. And you can set an optional alias that will
691 also set the mdna name.
692 Like connections, default mdns options work for "mdns-interface",
694 "mdna-type", "mdns-domain", and "mdns-host". Unlike connections, the
695 "mdns" boolean does not come from the default, you must specify it as
696 an admin option to turn on mdns for the admin port. This is to allow
697 it to be specified separately and maintain backwards compatibility.
698
701 ser2net can flash LEDs during serial activity. To create an LED in
702 version 1, do:
703 led: &<alias>
704 driver: sysfs
705 options:
706 <option name>: <option value>
707 <option name>: <option value>
708 In version 2, use:
710 leds:
711 <alias>:
712 driver: sysfs
713 options:
714 <option name>: <option value>
715 <option name>: <option value>
716 <alias>:
717 driver: sysfs
718 options:
719 <option name>: <option value>
720 <option name>: <option value>
721 The only supported driver is sysfs. Supported options are:
723 device: <sysfs device name> gives the name of the LED in
725 /sys/class/led. These generally have ":" in them, so you will need to
726 put the name in quotes. This is required.
727 duration: <time in ms> The time in milliseconds to flash the LED. De‐
729 faults to 10.
730 state: <number> The value to set the LED to to enable it. Defaults to
732 1, but may need to be a different value.
733 You reference the LED by alias in the connection options section, see
735 that for details. Make sure you have "modprobe ledtrig-transient" done
736 or the triggers will not work, they require the transient trigger.
737 You also probably need root access to access LED settings.
739
742 NOTE: yaml has it's own quoting mechanism, see below for more details.
743 Filenames, banners, open/close strings, closeon strings, and sendon
745 strings may contain normal "C" escape sequences and a large number of
746 other escape sequences, too:
747 \a - bell
749 \b - backspace
750 \f - form feed
751 \n - newline
752 \r - carriage return
753 \t - tab
754 \v - vertical tab
755 \\ - \
756 \? - ?
757 \' - '
758 \" - "
759 \nnn - octal value for nnn
760 \xXX - hex value for XX
761 \d - The connecting gensio string (serialdev,/dev/ttyS0, etc.)
762 \o - The device as specified on the config line (before DEVICE sub‐
763 stitution)
764 \N - The port name
765 \p - The accepter string
766 \B - The serial port parameters (eg 9600N81)
767 \Y -> year
768 \y -> day of the year (days since Jan 1)
769 \M -> month (Jan, Feb, Mar, etc.)
770 \m -> month (as a number)
771 \A -> day of the week (Mon, Tue, etc.)
772 \D -> day of the month
773 \e -> epoc (seconds since Jan 1, 1970)
774 \U -> microseconds in the current second
775 \p -> local port number
776 \I -> remote address of the accepter gensio
777 \H -> hour (24-hour time)
778 \h -> hour (12-hour time)
779 \i -> minute
780 \S -> second
781 \q -> am/pm
782 \P -> AM/PM
783 In addition, for backwards compatibility because filenames and banners
785 used to have different formatting, \s is the serial port parameters if
786 in a banner and seconds if in a filename. Use of this is discouraged
787 as it may change in the future.
788 These sequences may be used to make the filename unique per open and
790 identify which port/device the filename was for. Note that in file‐
791 names when using \d or \o, everything up to and including last / in the
792 device name is removed, because you can't have a / in a filename. So
793 in a filename /dev/ttyS0 would become just ttyS0.
794 HANDLING QUOTING AND STRING FORMATTING
797 yaml will process "\" escape sequences in double quotes, so use of dou‐
798 ble quotes is note recommended for the above. If you put the values in
799 single quotes, yaml will not process them and instead pass them through
800 where they can be processed by ser2net.
801
804 YAML and the accepter/connector processing interact when dealing with
805 quoting. By default, YAML ignores the number of spaces between ele‐
806 ments separated by spaces. Lines that are indented after an element
807 are considered a continuation of the element, so something like:
808 connector: serialdev,/dev/ttyUSB0,
809 9600n81
810 local nobreak
811 rtscts
812 is the same as
813 connector: serialdev,/dev/ttyUSB0, 9600n81 local nobreak rtscts
815 YAML has it's own standard quoting mechanisms, so if you do:
817 connector: "serialdev,/dev/ttyUSB0,9600n81 local"
819 the two spaces before "local" will be preserved when passed to the con‐
821 nector processing (though in this case it won't matter because the con‐
822 nector processing will ignore the extra spaces).
823 If you need a significant space, say in a filename passed to a key, You
825 cannot do:
826 accepter: ssl(CA=/etc/ser2net/my CA/),tcp,3000
828 because the accepter processing will split the arguments at the space
830 and won't recognize what "CA/" is. You also cannot do:
831 accepter: ssl(CA="/etc/ser2net/my CA/"),tcp,3000
833 because YAML will remove the quotes, this is functionally equivalent to
835 the previous example. And
836 accepter: ssl(CA="/etc/ser2net/my\ CA/"),tcp,3000
838 also will not work, inside of double quotes YAML will convert "\ " to a
840 space. You have a couple of options. You can do:
841 accepter: ssl(CA=/etc/ser2net/my\ CA/),tcp,3000
843 or
845 accepter: ssl(CA='/etc/ser2net/my\ CA/'),tcp,3000
847 because outside of quotes YAML will not process the "\ " and it will
849 not process it in single quotes. Or if you have a lot of spaces or
850 colons, too, you can do:
851 accepter: ssl(CA="\"/etc/ser2net/my CA/\""),tcp,3000
853 because inside the outside quotes YAML will convert the '\"' into a '"'
855 and pass it on to the accepter processing which will interpret the
856 quotes as you would expect.
857
860 UDP handling is a bit different than you might imagine, because it's
861 hard for ser2net to know where to send the data to. To handle this,
862 UDP ports still have the concept of a "connection". If a UDP port is
863 not connected, then if it receives a packet the remote address for that
864 packet is set to the remote end of the "connection". It will do all
865 the normal new connection operations. ser2net will accept new connec‐
866 tions up to "max-connections" then ignore packets from other addresses
867 until a disconnect occurs.
868 Unfortunately, there is no easy way to know when to disconnect. You
870 have two basic options:
871 • Set a timeout, if the remote end isn't heard from before the
873 timeout, then the port is disconnected and something else can
874 connect. This means anything that is using the port must peri‐
875 odically send a packet (empty is fine) to ser2net to keep the
876 connection alive.
877 • Use the kickolduser option on the port, any new connection that
879 comes in will replace the previous connection.
880 Note that UDP ports handle multiple connections just like TCP ports, so
882 you can have multiple UDP listeners.
883 You also have a third option. If you set a remote address (remaddr)
885 with a non-zero port and a connect back port (see discussion on remote
886 addresses above), ser2net will take one of the connections and assign
887 it to that port permanently. This is called a fixed remote address.
888 All the traffic from the device will go to that port. Every fixed re‐
889 mote address on a UDP port has to have a corresponding connection, so
890 if you have 3 fixed remote addresses, you must have at least 3 connec‐
891 tions.
892
895 As mentioned earlier, you can set max-connections=<n> on a port to al‐
896 low more than one connection at a time to the same serial port. These
897 connections will share all the settings. You cannot have two separate
898 TCP ports connect to the same port at the same time.
899 This has some significant interactions with other features:
901 flow control is not exactly a feature, but more an interaction between
903 the different connections. If a TCP port stops receiving data from
904 ser2net, all TCP ports connected will be flow-controlled. This means a
905 single TCP connection can stop all the others.
906 closeon will close all connections when the closeon sequence is seen.
908 openstr is only sent when the port is unconnected and the first connec‐
910 tions is made.
911 closestr is only sent when the last port disconnects and there are no
913 more connections to the port.
914 Any monitor ("monitor start" from a control connections) will catch in‐
916 put from all network connections.
917 kickolduser will kick off an existing connection if a connection comes
919 in on a port that already has a maximum number of connections. The
920 connection kicked off is arbitrarily chosen and the algorithm is sub‐
921 ject to change.
922 tracing will trace data from all network connections.
924 rfc2217 (remote telnet serial control) will change the connection set‐
926 tings on the device and will be accepted from any network connection.
927 reconfig on SIGHUP See ser2net(8) "SIGHUP" section for details.
929 ROTATOR will only choose a port if there are no connections at all on
931 the port. Note that the use of a rotator with a port with max-connec‐
932 tions > 1 will result in undefined behavior.
933 timeout will be per TCP port and will only disconnect that TCP port on
935 a timeout.
936 telnet_brk_on_sync will send a break for any TCP port that does a sync.
938 showport in the admin interface will show all possible connections, so
940 if you say max-connections=3 you will get three entries.
941 showshortport in the admin interface will only show the first live con‐
943 nection, or if no connection is present it will show whatever the first
944 one was the last time a connection was present.
945
948 TCP WRAPPERS
949 ser2net uses the tcp wrappers interface to implement host-based secu‐
950 rity. See hosts_access(5) for a description of the file setup. Two
951 daemons are used by ser2net, "ser2net" is for the data ports and
952 "ser2net-control" is for the control ports.
953 ENCRYPTION
956 ser2net supports SSL encryption using the ssl gensio. To enable en‐
957 cryption, use an accepter like:
958 telnet,ssl,tcp,1234
960 Then you can use gensiot to connect:
962 gensiot telnet,ssl,<server>,1234
964 or you can install telnet-ssl and do
966 telnet -z ssl,secure <server> 1234
968 The SSL connection is made using the provided keys. In this example
970 ser2net uses the default keys (as set in the default, see those below).
971 You can also set them using (key=<keyfile>,cert=<certfile>) after ssl
972 above, or modify the defaults.
973 If you do not have genuine certificates from a certificate authority,
975 the connection will fail due to certificate failure. Getting certifi‐
976 cates this way is very inconvenient, so there is another way. You can
977 do:
978 gtlssh-keygen --keydir /etc/ser2net --commonname "`host‐
980 name`-ser2net" serverkey ser2net
981 to generate the default keys in /etc/ser2net (or wherever). The cer‐
983 tificate/key will be named /etc/ser2net/ser2net.crt|key.
984 NOTE: If you compile ser2net yourself, by default autoconf sets the
986 system configuration directory (normally /etc) as /usr/etc. This is a
987 major annoyance with autoconf. So if you don't change it, you would
988 need /usr/etc above where it says /etc. However, generally the right
989 way to do this is to add "--sysconfdir=/etc" to the configure command
990 line when you configure ser2net. If a distro has compiled ser2net for
991 you, that should have done that by default, so no worries in that case.
992 Then copy ser2net.crt over to the user system and provide it to connec‐
994 tion commands, like:
995 gensiot telnet,ssl(CA=ser2net.crt),<server>,1234
997 or
999 telnet -z ssl,secure,cacert=ser2net.crt 1234
1001 Then you will have an encrypted connection. Just make sure your cer‐
1003 tificates are valid.
1004 Note that the "-ser2net" at the end of the key is important because it
1006 make the subject name of the certificate more unique. You can really
1007 put anything you want for what you provide to keygen, as long as you
1008 rename it properly. That will be the subject name of the certificate.
1009 AUTHENTICATION WITH SSL
1011 ser2net provides a way to authenticate with SSL. It's not the great‐
1012 est, but it does work. You must enable clientauth on ssl:
1013 telnet,ssl(clientauth),tcp,1234
1015 or set it in the default. Then you must create a certificate with the
1017 username as the common name. You can do this with:
1018 gtlssh-keygen --keydir outdir --commonname username keygen key‐
1020 name
1021 which will generate keyname.crt and keyname.key in outdir. Then put
1023 keyname.crt in ser2net's <authdir>/username/allowed_certs. By default
1024 <authdir> is /usr/share/ser2net/auth, but you can change that with the
1025 authdir default in the ser2net config file or by setting authdir on in‐
1026 dividual connections (in case you want different ones for different
1027 ports). You then must rehash the allowed_certs directory:
1028 gtlssh-keygen rehash <authdir>/username/allowed_certs
1030 Then restart/reload ser2net and use one of these very long lines to
1032 telnet into it:
1033 gensiot telnet,ssl(CA=ser2net.crt,cert=username.crt,key=user‐
1035 name.key),<server>,1234
1036 telnet -z ssl,secure,cacert=ser2net.crt,cert=user‐
1038 name.crt,key=username.key server 1234
1039 AUTHENTICATION WITH CERTAUTH (GTLSSH)
1041 All of the above is a big pain. Fortunately there is an easier way.
1042 gtlssh is a ssh-like program, but runs over TLS and it implements a
1043 ssh-like authentication protocol using the certauth gensio.
1044 ser2net supports this authentication system running on top of the ssl
1046 and certauth gensios. Those gensios provide the framework for handling
1047 authentication, ser2net itself controls it.
1048 This uses the same authdir and allowed keys directory as before, and
1050 still requires a server certificate, but the self-signed one generated
1051 with gtlssh-keygen works fine without doing anything special. Add cer‐
1052 tauth to the port line:
1053 telnet,mux,certauth,ssl,tcp,1234
1055 and *make sure* clientauth is disabled for ssl (or ssl will still at‐
1057 tempt to authenticate the client). Disabled is the default but in case
1058 you changed, the default...
1059 The mux entry is because gtlssh uses the mux gensio to allow multiple
1061 channels on the same session. It wasn't there with older (pre 1.2)
1062 version of gtlssh, but is required for newer one. gtlssh also has a
1063 --nomux option, just in case.
1064 The gtlssh program does its own certificate handling. Look at the
1066 gtlssh man page for detail on that. Take the certificate for gtlssh
1067 and put it in the authdir/username/allowed_certs directory and reshash
1068 it as before. gtlssh will *not* use the common name provided in the
1069 certificate, instead it users a username provided by gtlssh. Then con‐
1070 nect with gtlssh:
1071 gtlssh --nosctp --telnet username@server 1234
1073 The --nosctp thing keep gtlssh from trying sctp, which will fail be‐
1075 cause we put tcp in the port line. You could use sctp there and get
1076 all its advantages for free! Then --nosctp would no longer be required
1077 to avoid the nagging.
1078 The username is optional if it's the same as your current user. If you
1080 have not connected to that server/port before, gtlssh will ask you to
1081 verify it, much like ssh does. If certificates, IP address, etc.
1082 change, gtlssh will tell you about it.
1083 If you do not want to use a certificate (certificates are certainly
1085 preferred, but may not always be workable) you can use a password lo‐
1086 gin, too. You must set enable-password in the certauth gensio options
1087 for passwords to work. When you connect with gtlssh, if certificate
1088 validate fails, you will be prompted for the password. Password authen‐
1089 tication can be performed in two different ways. Both are mutually ex‐
1090 clusive, depending on whether pamauth is set or not:
1091 • To authenticate using the PAM library set the PAM service name
1093 via pamauth option.
1094 • Put a password in authdir/username/password. If it matches the
1096 first line in the password file and pamauth is not set, then au‐
1097 thentication will succeed.
1098 AUTHENTICATION AND ROTATORS
1100 Rotators are a special case. BE CAREFUL. A rotator has its own au‐
1101 thentication. If you set up authentication on a port that is part of a
1102 rotator, that port's authentication is not used. Only the rotator's
1103 authentication is used.
1104 ENCRYPTION, AUTHENTICATION, AND DEFAULT CERTIFICATES
1106 ser2net expects default certificates and public keys in /etc/ser2net,
1107 and these are set as gensio defaults. This means that any outgoing
1108 connection from ser2net, whether in a connector or in a connback, will
1109 use these keys. If they aren't there or have expired or something you
1110 will get confusing errors about not being able to open the certifi‐
1111 cates.
1112 To solve this, you can disable the certificates by adding "cert=" to
1114 the gensio specification for ssl and certauth on outgoing connections.
1115 This will disable the certificates for the specific gensio, and is
1116 probably what you want. If you are making connections and authenticat‐
1117 ing to the remote server, the default certificate and private key are
1118 probably not what you want, either.
1119
1121 SIGHUP
1122 If ser2net receives a SIGHUP, it will reread it configuration file
1123 and make the appropriate changes. If an inuse port is changed or
1124 deleted, the actual change will not occur until the port is dis‐
1125 connected.
1126
1129 Almost all error output goes to syslog, not standard output.
1130
1133 /etc/ser2net/ser2net.yaml, /etc/ser2net/ser2net.key,
1134 /etc/ser2net/ser2net.crt, /usr/share/ser2net
1135
1138 ser2net(8) telnet(1), hosts_access(5), gensio(5), gtlssh(1), gtlssh-
1139 keygen(1)
1140
1143 If they were known, they would be fixed :).
1144
1147 Corey Minyard <minyard@acm.org>
1148Serial to network proxy configuratio0n6/f0i2l/e01 ser2net.yaml(5)