home | help 
ser2net(8)		     System Manager's Manual		      ser2net(8)

NAME
     ser2net - Serial to network proxy

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

DESCRIPTION
     The ser2net daemon allows telnet and tcp sessions to be established with  a
     unit's serial ports or with an IPMI Serial Over LAN (SOL) interface.

     The  program  comes up normally as a daemon, opens the network ports speci-
     fied in the configuration file, and waits for connections.  Once a  connec-
     tion occurs, the program attempts to set up the connection and open the se-
     rial port.  If another user is already using the connection or serial port,
     the connection is refused with an error message.

OPTIONS
     -c config-file
	    Set  the  configuration  file  to  one  other  than  the  default of
	    sysconfdir/ser2net/ser2net.yaml.  If the config-file is - then stan-
	    dard input is  read  as  the  config  file.   See  -C  for	info  on
	    sysconfdir

     -C sysconfdir
	    Set  the  directory  where	the  configuration file and ssl keys are
	    stored.  This is generally /usr/local/etc/ser2net on Unix-type  sys-
	    tems,  on  Windows	it  is	../usr/local/etc/ser2net  from	the exe-
	    cutable's location by default.

     -a authdir
	    Set  the  default  directory  where  authentication  information  is
	    stored.   This is generally /usr/share/ser2net on Unix-type systems,
	    on Windows it is ../share/ser2net from the executable's location  by
	    default.   This  can  be  overridden  in  the  config file.  See the
	    ser2net.yaml.5 for info on what this does.

     -A admin-authdir
	    Set the default directory where the  administrator's  authentication
	    information  is  stores.   This is sysconfdir/auth by default.  This
	    can be overridden in the config file.  See	the  ser2net.yaml.5  for
	    info on what this does.

     -Y yaml-config-string
	    Add  a  yaml  config  string  to the end of strings to be processed.
	    This may be specified multiple times for  multiple	strings.   These
	    are  appended  onto the end of a yaml config file; though if this is
	    specified, the default config file is disabled and you have  to  en-
	    able it with the -c option.

	    To	make things easier to handle, any # in the config string that is
	    not inside quotes (what would normally start a comment in  yaml)  is
	    converted  to a new line.  Plus a new line is added after each sepa-
	    rate config string.  So, for instance:

	      -Y 'connection: &con01#  accepter: tcp,2013'
	      -Y '  connector: serialdev,/dev/ttyEcho0,9600n81,local'
	      -Y '  options:#	 banner: "### A Banner ###\r\n"'

	    can be put on the ser2net command line.

     -n     Stops  the	daemon	from  forking  and  detaching from the	control-
	    ling terminal. This is useful for running from init.

     -d     Like  -n, but also sends the system logs to standard output. This is
	    most useful for debugging purposes.

     -P pidfile
	    If specified, put the process id (pid) of ser2net  in  the	pidfile,
	    replacing  whatever  was  in that file previously.	A pidfile is not
	    created by default, you must specify this to create one.  Note  also
	    that  this	filename must be specific with the full path, as ser2net
	    will change directory to "/" when it becomes a daemon.

     -u     If UUCP locking is enabled, this will disable the use of UUCP locks.

     -b     Cisco IOS uses a different mechanism for specifying the  baud  rates
	    than  the  mechanism described in RFC2217.	This option sets the IOS
	    version of setting the baud rates.	The default is RFC2217's.   Note
	    that this capability is now handled automatically and this option is
	    ignored.

     -v     Prints the version of the program and exits.

     -t <num threads>
	    Spawn  the	given number of threads for ser2net to use.  The default
	    is 1.  Only valid if pthreads is enabled at build time.

     -p <admin-accepter>
	    Enables the admin interface on  the  given	accepter  specification.
	    See "ADMIN CONNECTION" in ser2net.yaml(5) for more details on how to
	    configure  this,  and  "ADMIN INTERFACE" below for details on how to
	    use it.

     -s signature
	    Specifies the default RFC2217 signature.

ADMIN INTERFACE
     The admin interface provides a simple interface for controlling  the  ports
     and  viewing  their  status.  To accomplish this, it has the following com-
     mands:

     showport [<network port>]
	    Show information about a port. If no port is given,  all  ports  are
	    displayed.

     showshortport [<network port>]
	    Show  information about a port, each port on one line. If no port is
	    given, all ports are displayed.  This can produce very wide output.

     help   Display a short list and summary of commands.

     exit   Disconnect from the control port.

     yaml   Go into yaml output mode.  See YAML MODES below.

     version
	    Display the version of this program.

     monitor <type> <network port>
	    Display all the input for a given port on the calling control  port.
	    Only  one  direction may be monitored at a time.  The type field may
	    be tcp or term and specifies whether to monitor data from  the  net-
	    work  port or from the serial port Note that data monitoring is best
	    effort, if the controller port cannot  keep  up  the  data	will  be
	    silently  dropped.	 A  controller	may only monitor one thing and a
	    port may only be monitored by one controller.

     monitor stop
	    Stop the current monitor.

     disconnect <network port>
	    Disconnect the tcp connection on the port.

     setporttimeout <network port> <timeout>
	    Set the amount of time in seconds before the port connection will be
	    shut down if no activity has been seen on the port.

     setportconfig <network port> <config>
	    Set the port configuration as in the  device  configuration  in  the
	    /usr/local/etc/ser2net/ser2net.yaml  file.	 If  conflicting options
	    are specified, the last option will be  the  one  used.   Note  that
	    these  will  not change until the port is disconnected and connected
	    again.  Options 300, 1200, 2400, 4800, 9600,  19200,  38400,  57600,
	    115200  set  the  various  baud  rates.   The following speed may be
	    available if your system has the values defined  and  your	hardware
	    supports  it:  230400,  460800,  500000,  576000,  921600,	1000000,
	    1152000, 1500000, 2000000, 2500000, 3000000, 3500000, 4000000.  Par-
	    ity, databits, and stopbits may be specified in the classical manner
	    after the speed, as in 9600N81.   This  has  the  following  format:
	    <speed>[N|E|O|M|S[5|6|7|8[1|2]]].	Setting  serial options this way
	    does not work on SOL, SOL has fixed N81 serial options.  EVEN,  ODD,
	    NONE (MARK and SPACE if supported) set the parity.	1STOPBIT, 2STOP-
	    BITS set the number of stop bits.  7DATABITS, 8DATABITS set the num-
	    ber  of  data  bits.   [-]XONXOFF turns on (- off) XON/XOFF support.
	    [-]RTSCTS turns on (- off) hardware flow control.  [-]LOCAL  ignores
	    (- checks) the modem control lines (DCD, DTR, etc.)

     setportcontrol <network port> <controls>
	    Modify  dynamic  port  controls.   These do not stay between connec-
	    tions.  Controls are: DTRHI, DTRLO Turns on and off  the  DTR  line.
	    RTSHI, RTSLO Turns on and off the RTS line.

     setportenable <network port> <enable state>
	    Sets  the  port  operation state.  Valid states are: off to shut the
	    network port down, raw to enable the network port transfer	all  I/O
	    as-is,  rawlp  to  enable  the  network port input and device output
	    without termios setting, and telnet to enable the network port is up
	    run the telnet negotiation protocol on the port.

     reload
	    Causes ser2net to reload its configuration.  Any error  output  will
	    come out in the output, along with going to syslog.

   YAML MODES
     If  the "yaml" command is issued, echo is turned off and all output is YAML
     compliant.  The form is basically the same as  the  non-YAML  output,  with
     some  minor  adjustments  to  make it YAML compliant.  In addition, all re-
     sponses are in the form:

       %YAML 1.1
       ---
       response:
	 <response info here>
       ...

     If there is an error, it is returned in the response with the "error"  key.
     If  the  command  succeeded, no "error" key will be present in the response
     mapping.  The "..." will be at the end of all responses.

     The following commands are available in yaml output  mode:  exit,	version,
     showport,	disconnect,  setporttimeout,  setportenable, setportcontrol, re-
     load,

     If "%YAML" is seen in the input, YAML input and output modes are activated,
     echo is disabled, and all input is expected to be in the form:

       ---
       command:
	 name: <command name>
	 id: <optional id>
	 parms: [ parm1 [, parm2 [...]]]
       ...

     The id is optional and will just be returned in the  response.   The  parms
     are  optional,  too, unless the command requires them.  Extra parms are ig-
     nored, along with unknown keys in the main mapping.

     Note that you have to deal with the "->" that is issued when the connection
     is made, before going into YAML mode, YAML doesn't handle that well.

     In YAML output mode, you will get asynchronous reports of	connections  and
     disconnections in the form:

       %YAML 1.1
       ---
       new connection:
	 name: !!str 'con1'
	 remaddr: !!str 'ipv6,::1,59072'
       ...

       %YAML 1.1
       ---
       disconnect:
	 name: !!str 'con1'
	 remaddr: !!str 'ipv6,::1,59072'
       ...

CONFIGURATION
     Configuration     is     accomplished    through	 the	file	/usr/lo-
     cal/etc/ser2net/ser2net.yaml.  A file with another  name  or  path  may  be
     specified using the -c option.

     The yaml configuration file is described in ser2net.yaml(5)

SIGNALS
     SIGHUP
	  If ser2net receives a SIGHUP, it will reread it configuration file and
	  make	the  appropriate changes.  If an in use connection is changed or
	  deleted, the actual change will not occur until the  port  is  discon-
	  nected, except that if you disable a connection it will kick the users
	  off.

	  ser2net uses the name (the connection alias) of the connection to tell
	  if it is new, changed or deleted.  If the new configuration file has a
	  connection with the same name, it is treated as a change.

	  This	has  some  unusual interactions with connections that allow more
	  than one simultaneous connection.  It works just like the other  port,
	  but  the accepter is disabled and new connections will not be accepted
	  until all the existing connections are closed.

ERRORS
     All error output after startup goes to syslog, not standard output,  unless
     you use the -d option.

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

SEE ALSO
     telnet(1), ser2net.yaml(5), hosts_access(5)

KNOWN PROBLEMS
     None.

AUTHOR
     Corey Minyard <minyard@acm.org>

Serial to network proxy 	    06/02/01			      ser2net(8)
home | help