1ser2net(8) System Manager's Manual ser2net(8)
2
6 ser2net - Serial to network proxy
7
10 ser2net [-c configfile] [-C configline] [-p controlport] [-n] [-d] [-b]
11 [-v] [-P pidfile]
12
15 The ser2net daemon allows telnet and tcp sessions to be established
16 with a unit's serial ports or with an IPMI Serial Over LAN (SOL) inter‐
17 face.
18 The program comes up normally as a daemon, opens the network ports
20 specified in the configuration file, and waits for connections. Once a
21 connection occurs, the program attempts to set up the connection and
22 open the serial port. If another user is already using the connection
23 or serial port, the connection is refused with an error message.
24
27 -c config-file
28 Set the configuration file to one other than the default of
29 /etc/ser2net.conf
30 -C config-line
32 Handle a single configuration line. This may be specified mul‐
33 tiple times for multiple lines. This is just like a line in the
34 config file. This disables the default config file, you must
35 specify a -c after the last -C to have it read a config file,
36 too.
37 -n Stops the daemon from forking and detaching from the con‐
39 trolling terminal. This is useful for running from init.
40 -d Like -n, but also sends the system logs to standard output. This
42 is most useful for debugging purposes.
43 -P pidfile
45 If specified, put the process id (pid) of ser2net in the pid‐
46 file, replacing whatever was in that file previously. A pidfile
47 is not created by default, you must specify this to create one.
48 Note also that this filename must be specific with the full
49 path, as ser2net will change directory to "/" when it becomes a
50 daemon. when it
51 -u If UUCP locking is enabled, this will disable the use of UUCP
53 locks.
54 -b Cisco IOS uses a different mechanism for specifying the baud
56 rates than the mechanism described in RFC2217. This option sets
57 the IOS version of setting the baud rates. The default is
58 RFC2217's. Note that this capability is now handled automati‐
59 cally and this option is ignored.
60 -v Prints the version of the program and exits.
62 -t <num threads>
64 Spawn the given number of threads for ser2net to use. The
65 default is 1. Only valid if pthreads is enabled at build time.
66 -p controlport
68 Enables the control port and sets the TCP port to listen to for
69 the control port. A port number may be of the form [host,]port,
70 such as 127.0.0.1,2000 or localhost,2000. If this is specified,
71 it will only bind to the IP address specified for the port.
72 Otherwise, it will bind to all the addresses on the machine.
73 If the port number is zero, that means that standard in/out will
75 be used for the only input/output, and only one port should be
76 specified in the config. This way, it can be used from inetd.
77 -s signature
79 Specifies the default RFC2217 signature.
80
83 The control port provides a simple interface for controlling the ports
84 and viewing their status. To accomplish this, it has the following com‐
85 mands:
86 showport [<network port>]
88 Show information about a port. If no port is given, all ports
89 are displayed.
90 showshortport [<network port>]
92 Show information about a port, each port on one line. If no port
93 is given, all ports are displayed. This can produce very wide
94 output.
95 help Display a short list and summary of commands.
97 exit Disconnect from the control port.
99 version
101 Display the version of this program.
102 monitor <type> <network port>
104 Display all the input for a given port on the calling control
105 port. Only one direction may be monitored at a time. The type
106 field may be tcp or term and specifies whether to monitor data
107 from the network port or from the serial port Note that data
108 monitoring is best effort, if the controller port cannot keep up
109 the data will be silently dropped. A controller may only moni‐
110 tor one thing and a port may only be monitored by one con‐
111 troller.
112 monitor stop
114 Stop the current monitor.
115 disconnect <network port>
117 Disconnect the tcp connection on the port.
118 setporttimeout <network port> <timeout>
120 Set the amount of time in seconds before the port connection
121 will be shut down if no activity has been seen on the port.
122 setportconfig <network port> <config>
124 Set the port configuration as in the device configuration in the
125 /etc/ser2net.conf file. If conflicting options are specified,
126 the last option will be the one used. Note that these will not
127 change until the port is disconnected and connected again.
128 Options 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
129 set the various baud rates. The following speed may be avail‐
130 able if your system has the values defined and your hardware
131 supports it: 230400, 460800, 500000, 576000, 921600, 1000000,
132 1152000, 1500000, 2000000, 2500000, 3000000, 3500000, 4000000.
133 EVEN, ODD, NONE (MARK and SPACE if supported) set the parity.
134 1STOPBIT, 2STOPBITS set the number of stop bits. 7DATABITS,
135 8DATABITS set the number of data bits. [-]XONXOFF turns on (-
136 off) XON/XOFF support. [-]RTSCTS turns on (- off) hardware flow
137 control. [-]LOCAL ignores (- checks) the modem control lines
138 (DCD, DTR, etc.)
139 setportcontrol <network port> <controls>
141 Modify dynamic port controls. These do not stay between connec‐
142 tions. Controls are: DTRHI, DTRLO Turns on and off the DTR
143 line. RTSHI, RTSLO Turns on and off the RTS line.
144 setportenable <network port> <enable state>
146 Sets the port operation state. Valid states are: off to shut
147 the network port down, raw to enable the network port transfer
148 all I/O as-is, rawlp to enable the network port input and device
149 output without termios setting, and telnet to enable the network
150 port is up run the telnet negotiation protocol on the port.
151
154 Configuration is accomplished through the file /etc/ser2net.conf. A
155 file with another name or path may be specified using the -c option, or
156 individual config lines may be specified with the -C option. This
157 file consists of one or more entries with the following format:
158 <network port>:<state>:<timeout>:<device>:<options>
160 or
162 BANNER:<banner name>:<banner text>
164 or
166 SIGNATURE:<signature name>:<signature text>
168 or
170 OPENSTR:<openstr name>:<openstr text>
172 or
174 CLOSESTR:<closestr name>:<closestr text>
176 or
178 CLOSEON:<closeon name>:<closeon text>
180 or
182 TRACEFILE:<tracefile name>:<tracefile>
184 or
186 CONTROLPORT:<port spec>
188 or
190 DEVICE:<name>:<device>
192 or
194 DEFAULT:<parm>:<defaultval>
196 or
198 ROTATOR:<TCP port>:<port list>
200 or
202 LED:<led-name>:<driver>:<parameters>
204 A line that ends in '\' (it must be the very last character) is contin‐
206 ued on the next line. There is no arbitrary maximum line length.
207 FIELDS
210 network port
211 Name or number of the network port to accept connections from
212 for this device. A port number may be of the form
213 [ipv4,|ipv6,][tcp,|udp,][host,]port, such as 127.0.0.1,2000 or
214 ipv4,localhost,2000, or udp,::,2000. If host is specified, it
215 will only bind to the IP address specified for the port. Other‐
216 wise, it will bind to all the ports on the machine. You can
217 specify an IPV6 address in the port, any colon before the comma
218 is ignored for parsing fields. If ipv4 or ipv6 is specified, it
219 will only bind to that network type.
220 If udp is specified, any data received on the port from a remote
222 source is considered a "connection" and the data for that port
223 will go back to the remote source address. See the later sec‐
224 tion on UDP for details.
225 state Either raw or rawlp or telnet or off. off disables the port
227 from accepting connections. It can be turned on later from the
228 control port. raw enables the port and transfers all data as-is
229 between the port and the long. rawlp enables the port and
230 transfers all input data to device, device is open without any
231 termios setting. It allow to use /dev/lpX devices and printers
232 connected to them. telnet enables the port and runs the telnet
233 protocol on the port to set up telnet parameters. This is most
234 useful for using telnet.
235 timeout
237 The time (in seconds) before the port will be disconnected if
238 there is no activity on it. A zero value disables this func‐
239 tion.
240 device The name of the device to connect to. This must be in the
242 form of /dev/<device> or sol.<solparms>. For SOL parameters,
243 see the solterm man page that is part of openipmi. This may be
244 specified in a DEVICE directive, then you can use the name in
245 the DEVICE directive to specify the device in the DEVICE direc‐
246 tive. This can be used to give shorter and/or meaningful names
247 for devices, or to allow special characters (like a colon) in
248 the device name.
249 device configuration options
251 Sets operational parameters for the serial port. Values are be
252 separated by spaces. Options 300, 1200, 2400, 4800, 9600,
253 19200, 38400, 57600, 115200 set the various baud rates for
254 serial device and SOL ports. The following speed may be avail‐
255 able if your system has the values defined and your hardware
256 supports it: 230400, 460800, 500000, 576000, 921600, 1000000,
257 1152000, 1500000, 2000000, 2500000, 3000000, 3500000, 4000000.
258 Note that only a limited set are available on SOL. [-]NOBREAK
259 disables automatic clearing of the break setting of the port.
260 Available on serial device and SOL ports.
261 EVEN, ODD, NONE (MARK and SPACE if supported) set the parity.
263 (serial device only) Note that MARK and SPACE are not available
264 on all systems or hardware, if it is not supported then it will
265 be silently set to ODD or EVEN parity. 1STOPBIT, 2STOPBITS set
266 the number of stop bits. (serial device only) 5DATABITS,
267 6DATABITS, 7DATABITS, 8DATABITS set the number of data bits.
268 (serial device only) [-]XONXOFF turns on (- off) XON/XOFF sup‐
269 port. (serial device only) [-]RTSCTS turns on (- off) hardware
270 flow control. (serial device only) [-]LOCAL ignores (- checks)
271 the modem control lines (DCD, DTR, etc.) (serial device only)
272 [-]HANGUP_WHEN_DONE lowers (- does not lower) the modem control
273 lines (DCD, DTR, etc.) when the connection closes. (serial
274 device only) [-]remctl allows remote control of the serial port
275 parameters via RFC 2217. See the README for more info.
276 [-]kickolduser sets the port so that the previous user will be
277 kicked off if a new user comes in. Useful if you forget to log
278 off from someplace else a lot. <banner name> displays the given
279 banner when a user connects to the port. <signature name> sends
280 RFC2217 signature on clients request. <openstr name> Send the
281 given string to the device when the port is opened. <closestr
282 name> Send the given string to the device when the port is
283 closed.
284 tr=<filename> When the port is opened, open the given tracefile
286 and store all data read from the physical device (and thus writ‐
287 ten to the user's TCP port) in the file. The actual filename is
288 specified in the TRACEFILE directive. If the file already
289 exists, it is appended. The file is closed when the port is
290 closed.
291 tw=<filename> Like tr, but traces data written to the device.
293 tb=<filename> trace both read and written data to the same file.
295 Note that this is independent of tr and tw, so you may be trac‐
296 ing read, write, and both to different files.
297 [-]hexdump turns on (- turns off) hexdump output to all trace
299 files. Each line in the trace file will be 8 (or less) bytes in
300 canonical hex+ASCII format. This is useful for debugging a
301 binary protocol.
302 [-]timestamp adds (- removes) a timestamp to all of the trace
304 files. A timestamp is prepended to each line if hexdump is
305 active for the trace file. A timestamped line is also recorded
306 in the trace file when a remote client connects or disconnects
307 from the port.
308 [-][tr-|tw-|tb-]hexdump turns on (- turns off) hexdump output
310 for only one trace file. May be combined with [-]hexdump.
311 Order is important.
312 [-][tr-|tw-|tb-]timestamp adds (- removes) a timestamp to only
314 one the trace files May be combined with [-]timestamp. Order is
315 important.
316 [-]telnet_brk_on_sync causes a telnet sync operation to send a
318 break. By default data is flushed until the data mark, but no
319 break is sent.
320 [-]disable-chardelay disables the small wait after each charac‐
322 ter received on the serial port before sending data on the TCP
323 port. Normally ser2net will wait the time it takes to receive 2
324 serial port characters, or at least 1000us, before sending on
325 the TCP port. This allows more efficient use of network
326 resources when receiving large amounts of data, but gives rea‐
327 sonable interactivity.
328 chardelay-scale=<number> sets the number of serial port charac‐
330 ters, in tenths of a character, to wait after receiving from the
331 serial port and sending to the TCP port. So setting this to 25
332 will cause ser2net to wait the amount of time it takes to
333 recieve 2.5 serial port characters before sending the data on to
334 the TCP port. The default value is 20.
335 chardelay-min=<number> sets the minimum delay that ser2net will
337 wait, in microseconds. If the calculation for chardelay-scale
338 results in a value smaller than this number, this number will be
339 used instead. The default value is 1000.
340 chardelay-max=<number> sets the maximum delay that ser2net will
342 wait, in microseconds, before sending the data. The default
343 value is 20000. This keeps the connection working smoothly at
344 slow speeds.
345 dev-to-net-bufsize=<number> sets the size of the buffer reading
347 from the serial device and writing to the network port.
348 net-to-dev-bufsize=<number> sets the size of the buffer reading
350 from the network port and writing to the serial device.
351 [-]authenticated enable (-disable) authentication on the link.
353 (SOL only)
354 [-]encrypted enable (-disable) encryption on the link. (SOL
356 only)
357 shared_serial_alert_fail fail the connection if the serial port
359 is in use through hardware. (SOL only)
360 shared_serial_alert_deferred if the serial port is already in
362 use through hardware, wait until it is released. (SOL only)
363 shared_serial_alert_deferred if the serial port is already in
365 use via hardware, take over the connection. (SOL only)
366 [-]deassert_CTS_DCD_DSR_on_connect deassert (- do not deassert)
368 the given serial signals on a SOL connection. (SOL only)
369 ack-timeout=n set the timeout for resending to n microseconds.
371 (SOL only)
372 ack-retries=n set the number of retries before failure to n
374 times. (SOL only)
375 <parm> is a parameter to set a default for. When you set a
377 default, it sets the default value for all following config
378 lines. Available parameters are: speed, databits, stopbits,
379 parity, xonxoff, rtscts, local, hangup_when_done, nobreak, rem‐
380 ctl, telnet_brk_on_sync, kickolduser, chardelay, chardelay-
381 scale, chardelay-min, and chardelay-max. See ser2net.conf for
382 details.
383 <defaultval> The default value to set the parameter.
385 <port list> A space separated list of ports. When connecting to
387 the given TCP port, ser2net will go through the port list until
388 it finds a free one and attempt to connect to that port.
389 led-tx=<led-name> use the previously defined led to indicate
391 serial tx traffic on this port.
392 led-rx=<led-name> use the previously defined led to indicate
394 serial rx traffic on this port.
395 max-connections=<number> set the maximum number of connections
397 that can be made on this particular TCP port. If you make more
398 than one connection to the same port, each ports output goes to
399 the device, and the device output goes to all ports simultane‐
400 ously. See "MULTIPLE CONNECTIONS" below for details. The
401 default is 1.
402 remaddr=<addr>[;<addr>[;...]] specifies the allowed remote con‐
404 nections, where the addr is a standard address in the form (see
405 "network port" above). Multiple addresses can be separated by
406 semicolons, and you can specify remaddr more than once. If you
407 set the port for an address to zero, ser2net will accept a con‐
408 nection from any port from the given network host.
409 banner name
412 A name for the banner; this may be used in the options of a
413 port.
414 banner text
416 The text to display as the banner. It takes escape sequences
417 for substituting strings, see "FILENAME, BANNER, AND STRING FOR‐
418 MATTING" for details.
419 tracefile name
422 A name for the tracefile, this is used in the tw, tr, and tb
423 options of a port.
424 tracefile
426 The file to send the trace into. Note that this takes escape
427 sequences for substituting strings, see "FILENAME, BANNER, AND
428 STRING FORMATTING" for details. Note that when using the time
429 escape sequences, the time is read once at port startup, so if
430 you use both tw and tr they will have the same date and time.
431 port spec
433 The control port specification as defined by the [-p] option on
434 the command line. This lets the control port be specified in
435 the configuration file. The command line will override this,
436 and only the first port specified is used.
437 led Define an LED with given name. At the moment, the only avail‐
439 able driver is "sysfs" which uses a Linux's LED class device
440 (/sys/class/leds/<device>) and configures it for transient LED
441 trigger. It knows about the required parameter "device" which
442 specifies which LED class device to use (the directory name of
443 the LED below /sys/class/leds). The optional "duration" parame‐
444 ter controls the length of the flash pulse in milliseconds and
445 defaults to 10. The optional parameter "state" controls whether
446 the LED is off/on when the timer is active. It takes 0 or 1 as
447 values and defaults to 1. See ledtrig-transient.txt in Linux
448 kernel documentation for more details.
449 The transient trigger must be compiled into the kernel or
451 already loaded as kernel module.
452 Individual network ports can refer to this LED and thus trigger
454 flashing of this LED when tx/rx traffic is seen.
455 Blank lines and lines starting with `#' are ignored.
458
461 Filenames, banners, and open/close string may contain normal "C" escape
462 sequences and a large number of other escape sequences, too:
463 \a - bell
465 \b - backspace
466 \f - form feed
467 \n - newline
468 \r - carriage return
469 \t - tab
470 \v - vertical tab
471 \\ - \
472 \? - ?
473 \' - '
474 \" - "
475 \nnn - octal value for nnn
476 \xXX - hex value for XX
477 \d - The device name (/dev/ttyS0, etc.)
478 \p - Network port number
479 \B - The serial port parameters (eg 9600N81)
480 \Y -> year
481 \y -> day of the year (days since Jan 1)
482 \M -> month (Jan, Feb, Mar, etc.)
483 \m -> month (as a number)
484 \A -> day of the week (Mon, Tue, etc.)
485 \D -> day of the month
486 \e -> epoc (seconds since Jan 1, 1970)
487 \U -> microseconds in the current second
488 \p -> local port number
489 \d -> local device name
490 \I -> remote IP address (in dot format)
491 \H -> hour (24-hour time)
492 \h -> hour (12-hour time)
493 \i -> minute
494 \S -> second
495 \q -> am/pm
496 \P -> AM/PM
497 In addition, for backwards compatibility because filenames and banners
499 used to have different formatting, \s is the serial port parameters if
500 in a banner and seconds if in a filename. Use of this is discouraged
501 as it may change in the future.
502 These sequences may be used to make the filename unique per open and
504 identify which port/device the filename was for. Note that in file‐
505 names when using \d, everything up to and including last / in the
506 device name is removed, because you can't have a / in a filename. So
507 in a filename /dev/ttyS0 would become just ttyS0.
508
511 UDP handling is a bit different than you might imagine, because it's
512 hard for ser2net to know where to send the data to. To handle this,
513 UDP ports still have the concept of a "connection". If a UDP port is
514 not connected, then if it received a packet the remote address for that
515 packet is set to the remote end of the "connection". It will do all
516 the normal new connection operations. ser2net will then ignore packets
517 from other addresses until a disconnect occurs.
518 Unfortunately, there is no easy way to know when to disconnect. You
520 have two basic options:
521 Set a timeout, if the remote end isn't heard from before the
523 timeout, then the port is disconnected and something else can
524 connect. This means anything that is using the port must peri‐
525 odically send a packet (empty is find) to ser2net to keep the
526 connection alive.
527 Use the kickolduser option on the port, any new connection that
529 comes in will replace the previous connection.
530 Note that UDP ports handle multiple connections just like TCP ports, so
532 you can have multiple UDP listeners.
533 You also have a third option. If you set a remote address (remaddr)
535 with a non-zero port, ser2net will take one of the connections and
536 assign it to that port permanently. This is called a fixed remote
537 address. All the traffic from the device will go to that port. Every
538 fixed remote address on a UDP port has to have a corresponding connec‐
539 tion, so if you have 3 fixed remote addresses, you must have at least 3
540 connections.
541
544 As mentioned earlier, you can set max-connections=<n> on a port to
545 allow more than one connection at a time to the same serial port.
546 These connections will share all the settings. You cannot have two
547 separate TCP ports connect to the same port at the same time.
548 This has some significant interactions with other features:
550 flow control is not exactly a feature, but more an interaction between
552 the different connections. If a TCP port stops receiving data from
553 ser2net, all TCP ports connected will be flow-controlled. This means a
554 single TCP connection can stop all the others.
555 closeon will close all connections when the closeon sequence is seen.
557 openstr is only sent when the port is unconnected and the first connec‐
559 tions is made.
560 closestr is only sent when the last port disconnects and there are no
562 more connections to the port.
563 Any monitor ("monitor start" from a control connections) will catch
565 input from all network connections.
566 kickolduser will kick off all connections if a connection comes in on a
568 port that already has a maximum number of connections.
569 tracing will trace data from all network connections.
571 remctl (remote telnet serial control) will change the connection set‐
573 tings on the device and will be accepted from any network connection.
574 ROTATOR will only choose a port if there are no connections at all on
576 the port. Note that the use of a rotator with a port with max-connec‐
577 tions > 1 will result in undefined behavior.
578 timeout will be per TCP port and will only disconnect that TCP port on
580 a timeout.
581 telnet_brk_on_sync will send a break for any TCP port that does a sync.
583 showport will show all possible connections, so if you say max-connec‐
585 tions=3 you will get three entries.
586 showshortport will only show the first live connection, or if no con‐
588 nection is present it will show whatever the first one was the last
589 time a connection was present.
590
593 ser2net uses the tcp wrappers interface to implement host-based secu‐
594 rity. See hosts_access(5) for a description of the file setup. Two
595 daemons are used by ser2net, "ser2net" is for the data ports and
596 "ser2net-control" is for the control ports.
597
600 SIGHUP
601 If ser2net receives a SIGHUP, it will reread it configuration file
602 and make the appropriate changes. If an inuse port is changed or
603 deleted, the actual change will not occur until the port is dis‐
604 connected.
605
608 Almost all error output goes to syslog, not standard output.
609
612 /etc/ser2net.conf
613
616 telnet(1), hosts_access(5)
617
620 None.
621
624 Corey Minyard <minyard@acm.org>
625Serial to network proxy 06/02/01 ser2net(8)