1ser2net(8)                  System Manager's Manual                 ser2net(8)
2
3
4

NAME

6       ser2net - Serial to network proxy
7
8

SYNOPSIS

10       ser2net [-c configfile] [-C configline] [-p controlport] [-n] [-d] [-b]
11       [-v] [-P pidfile]
12
13

DESCRIPTION

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
19       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
25

OPTIONS

27       -c config-file
28              Set the configuration file to one  other  than  the  default  of
29              /etc/ser2net.conf
30
31       -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
38       -n     Stops  the  daemon  from  forking  and  detaching  from the con‐
39              trolling terminal. This is useful for running from init.
40
41       -d     Like -n, but also sends the system logs to standard output. This
42              is most useful for debugging purposes.
43
44       -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
52       -u     If UUCP locking is enabled, this will disable the  use  of  UUCP
53              locks.
54
55       -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
61       -v     Prints the version of the program and exits.
62
63       -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
67       -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
74              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
78       -s signature
79              Specifies the default RFC2217 signature.
80
81

CONTROL PORT

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
87       showport [<network port>]
88              Show information about a port. If no port is  given,  all  ports
89              are displayed.
90
91       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
96       help   Display a short list and summary of commands.
97
98       exit   Disconnect from the control port.
99
100       version
101              Display the version of this program.
102
103       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
113       monitor stop
114              Stop the current monitor.
115
116       disconnect <network port>
117              Disconnect the tcp connection on the port.
118
119       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
123       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
140       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
145       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
152

CONFIGURATION

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
159              <network port>:<state>:<timeout>:<device>:<options>
160
161       or
162
163              BANNER:<banner name>:<banner text>
164
165       or
166
167              SIGNATURE:<signature name>:<signature text>
168
169       or
170
171              OPENSTR:<openstr name>:<openstr text>
172
173       or
174
175              CLOSESTR:<closestr name>:<closestr text>
176
177       or
178
179              CLOSEON:<closeon name>:<closeon text>
180
181       or
182
183              TRACEFILE:<tracefile name>:<tracefile>
184
185       or
186
187              CONTROLPORT:<port spec>
188
189       or
190
191              DEVICE:<name>:<device>
192
193       or
194
195              DEFAULT:<parm>:<defaultval>
196
197       or
198
199              ROTATOR:<TCP port>:<port list>
200
201       or
202
203              LED:<led-name>:<driver>:<parameters>
204
205       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
208
209   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
221              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
226       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
236       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
241       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
250       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
262              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
285              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
292              tw=<filename> Like tr, but traces data written to the device.
293
294              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
298              [-]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
303              [-]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
309              [-][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
313              [-][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
317              [-]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
321              [-]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
329              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
336              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
341              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
346              dev-to-net-bufsize=<number> sets the size of the buffer  reading
347              from the serial device and writing to the network port.
348
349              net-to-dev-bufsize=<number>  sets the size of the buffer reading
350              from the network port and writing to the serial device.
351
352              [-]authenticated enable (-disable) authentication on  the  link.
353              (SOL only)
354
355              [-]encrypted  enable  (-disable)  encryption  on  the link. (SOL
356              only)
357
358              shared_serial_alert_fail fail the connection if the serial  port
359              is in use through hardware. (SOL only)
360
361              shared_serial_alert_deferred  if  the  serial port is already in
362              use through hardware, wait until it is released. (SOL only)
363
364              shared_serial_alert_deferred if the serial port  is  already  in
365              use via hardware, take over the connection.  (SOL only)
366
367              [-]deassert_CTS_DCD_DSR_on_connect  deassert (- do not deassert)
368              the given serial signals on a SOL connection.  (SOL only)
369
370              ack-timeout=n set the timeout for resending to  n  microseconds.
371              (SOL only)
372
373              ack-retries=n  set  the  number  of  retries before failure to n
374              times. (SOL only)
375
376              <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
384              <defaultval> The default value to set the parameter.
385
386              <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
390              led-tx=<led-name> use the previously  defined  led  to  indicate
391              serial tx traffic on this port.
392
393              led-rx=<led-name>  use  the  previously  defined led to indicate
394              serial rx traffic on this port.
395
396              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
403              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
410
411       banner name
412              A name for the banner; this may be used  in  the  options  of  a
413              port.
414
415       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
420
421       tracefile name
422              A  name  for  the  tracefile, this is used in the tw, tr, and tb
423              options of a port.
424
425       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
432       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
438       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
450              The  transient  trigger  must  be  compiled  into  the kernel or
451              already loaded as kernel module.
452
453              Individual network ports can refer to this LED and thus  trigger
454              flashing of this LED when tx/rx traffic is seen.
455
456
457       Blank lines and lines starting with `#' are ignored.
458
459

FILENAME, BANNER, AND STRING FORMATTING

461       Filenames, banners, and open/close string may contain normal "C" escape
462       sequences and a large number of other escape sequences, too:
463
464         \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
498       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
503       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
509

UDP

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
519       Unfortunately,  there  is  no easy way to know when to disconnect.  You
520       have two basic options:
521
522              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
528              Use the kickolduser option on the port, any new connection  that
529              comes in will replace the previous connection.
530
531       Note that UDP ports handle multiple connections just like TCP ports, so
532       you can have multiple UDP listeners.
533
534       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
542

MULTIPLE CONNECTIONS

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
549       This has some significant interactions with other features:
550
551       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
556       closeon will close all connections when the closeon sequence is seen.
557
558       openstr is only sent when the port is unconnected and the first connec‐
559       tions is made.
560
561       closestr  is  only sent when the last port disconnects and there are no
562       more connections to the port.
563
564       Any monitor ("monitor start" from a  control  connections)  will  catch
565       input from all network connections.
566
567       kickolduser will kick off all connections if a connection comes in on a
568       port that already has a maximum number of connections.
569
570       tracing will trace data from all network connections.
571
572       remctl (remote telnet serial control) will change the  connection  set‐
573       tings on the device and will be accepted from any network connection.
574
575       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
579       timeout  will be per TCP port and will only disconnect that TCP port on
580       a timeout.
581
582       telnet_brk_on_sync will send a break for any TCP port that does a sync.
583
584       showport will show all possible connections, so if you say  max-connec‐
585       tions=3 you will get three entries.
586
587       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
591

SECURITY

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
598

SIGNALS

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
606

Error

608       Almost all error output goes to syslog, not standard output.
609
610

FILES

612       /etc/ser2net.conf
613
614

SEE ALSO

616       telnet(1), hosts_access(5)
617
618

KNOWN PROBLEMS

620       None.
621
622

AUTHOR

624       Corey Minyard <minyard@acm.org>
625
626
627
628Serial to network proxy            06/02/01                         ser2net(8)
Impressum