bionic (8) conserver.8.gz

Provided by: conserver-server_8.2.1-1_amd64 bug

NAME

       conserver - console server daemon

SYNOPSIS

       conserver  [-7dDEFhinoRSuvV] [-a type] [-m max] [-M master] [-p port] [-b port] [-c cred] [-C config] [-P
       passwd] [-L logfile] [-O min] [-U logfile]

DESCRIPTION

       Conserver is the daemon that manages  remote  access  to  system  consoles  by  multiple  users  via  the
       console(1)  client program and (optionally) log the console output.  It can connect to consoles via local
       serial ports, Unix domain sockets, TCP sockets (for terminal servers  and  the  like),  or  any  external
       program.

       When  started,  conserver  reads the conserver.cf(5) file for details of each console.  The console type,
       logging options, serial or network parameters, and user access levels are just a few of the  things  that
       can  be  specified.  Command-line options are then applied, possibly overriding conserver.cf(5) settings.
       Conserver categorizes consoles into two types: those it should actively manage, and those it should  just
       know  about,  so  it  can  refer  clients to other conserver instances.  If the master value of a console
       matches the hostname or ip address of the local machine, conserver  will  actively  manage  the  console.
       Otherwise,  it's  considered  a  ``remote'' console and managed by a different server.  Conserver forks a
       child for each group of consoles it must manage and assigns each process a port number to listen on.  The
       maximum  number  of  consoles  managed  by each child process is set using the -m option.  The console(1)
       client program communicates with the master console server process to find  the  port  (and  host,  in  a
       multi-server configuration) on which the appropriate child is listening.  Conserver restricts connections
       from clients based on the host access section of its conserver.cf(5) file, restricts users based  on  the
       console access lists of the conserver.cf(5) file, and authenticates users against its conserver.passwd(5)
       file.  Conserver can also restrict clients using the tcp-wrappers package (enabled using --with-libwrap).
       This authentication is done before consulting the conserver.cf(5) access list.

       When   Unix  domain  sockets  are  used  between  the  client  and  server  (enabled  using  --with-uds),
       authentication checks are done on the hardcoded address ``127.0.0.1''.  Automatic client  redirection  is
       also  disabled  (as  if  the -R option was used) since the client cannot communicate with remote servers.
       The directory used to hold the sockets is checked to make sure it's empty when the  server  starts.   The
       server  will  not  remove  any  files in the directory itself, just in case the directory is accidentally
       specified as ``/etc'' or some other critical location.  The server will do its best  to  remove  all  the
       sockets  when  it  shuts  down,  but it could stop ungracefully (crash, ``kill -9'', etc) and leave files
       behind.  It would then be up to the admin (or a creative startup script) to clean up the directory before
       the server will start again.

       Conserver  completely  controls  any  connection to a console.  All escape sequences given by the user to
       console are passed to the server without interpretation.  The server recognizes and processes all  escape
       sequences.

       The  conserver  parent  process  will  automatically  respawn any child process that dies.  The following
       signals are propagated by the parent process to its children.

       SIGTERM   Close all connections and exit.

       SIGHUP    Reread the configuration file.  New consoles are managed by forking off new  children,  deleted
                 consoles  (and  their  clients)  are  dropped,  and  changes  to  consoles are done "in place",
                 resetting the console port (bringing it down and up) only when necessary.  The console name  is
                 used  to  determine  when  consoles  have been added/removed/changed.  All actions performed by
                 SIGUSR2 are also performed.

       SIGUSR1   Try to connect to any consoles marked as down.  This can come in handy if you  had  a  terminal
                 server  (or more) that wasn't accepting connections at startup and you want conserver to try to
                 reconnect to all those downed ports.

       SIGUSR2   Close and reopen all console logfiles and, if in daemon mode (-d  option),  the  error  logfile
                 (see the -L option).  All actions performed by SIGUSR1 are also performed.

       Consoles  which  have  no  current client connection might produce important error messages.  With the -u
       option, these ``unloved'' errors are labeled with a machine name and output  on  stdout  (or,  in  daemon
       mode,  to the logfile).  This allows a live operator or an automated log scanner to find otherwise unseen
       errors by watching in a single location.

       Conserver must be run as root if it is to bind to a port under 1024 or if it must read protected password
       files  (like shadow passwords) for authentication (see conserver.passwd(5)).  Otherwise, it may be run by
       any user, with -p used to specify a port above 1024.

       If encryption has been built into  the  code  (--with-openssl),  encrypted  client  connections  (without
       certificate  exchanges)  happen  by  default.   To  add certificate exchanges, use the -c option with the
       client and server.  For authentication of the certificates to  work,  the  signing  certificate  must  be
       properly trusted, which usually means the public portion is in OPENSSL_ROOT/ssl/certs (on both the client
       and server sides).  See the sample  self-signing  certificate  making  script  contrib/maketestcerts  for
       further  clues.  To allow non-encrypted client connections (in addition to encrypted client connections),
       use the -E option.

OPTIONS

       Options may be given as separate arguments (e.g., -n -d) or clustered (e.g.,  -nd).   Options  and  their
       arguments  may  be  separated  by  optional  white  space.   Option  arguments containing spaces or other
       characters special to the shell must be quoted.

       -7          Strip the high bit off of all data received, whether from the  console  client  or  from  the
                   console device, before any processing occurs.

       -atype      Set  the  default  access type for incoming connections from console clients: `r' for refused
                   (the default), `a' for allowed, or `t' for trusted.  This  applies  to  hosts  for  which  no
                   matching entry is found in the access section of conserver.cf(5).

       -bport      Set  the  base  port  for children to listen on.  Each child starts looking for free ports at
                   port and working upward, trying a maximum number of ports equal to twice the  maximum  number
                   of  groups.   If  no  free  ports  are available in that range, conserver exits.  By default,
                   conserver lets the operating system choose a free port.

       -ccred      Load an SSL certificate and key from the PEM encoded file cred.

       -Cconfig    Read configuration information from the file config.  The default config may  be  changed  at
                   compile time using the --with-cffile option.

       -d          Become  a  daemon.  Disconnects from the controlling terminal and sends all output (including
                   any debug output) to the logfile (see -L).

       -D          Enable debugging output, sent to stderr.  Multiple -D options increases debug output.

       -E          If encryption has been built into the code (--with-openssl), encrypted client connections are
                   a  requirement.   This  option allows non-encrypted clients (as well as encrypted clients) to
                   connect to consoles.

       -F          Do not automatically reinitialize failed (unexpectedly closed) consoles.  If the console is a
                   program  (`|'  syntax)  and  it  closes with a zero exit status, the console is reinitialized
                   regardless of this option.  Without this option, a console is immediately  reopened,  and  if
                   that  fails,  retried every minute until successful.  This option has no effect on the -o and
                   -O options.

       -h          Output a brief help message.

       -i          Initiate console connections on demand (and close them when not used).

       -Llogfile   Log errors and informational messages to logfile after startup in  daemon  mode  (-d).   This
                   option does not apply when not running in daemon mode.  The default logfile may be changed at
                   compile time using the --with-logfile option.

       -mmax       Set the maximum consoles managed per process.  The default max may be changed at compile time
                   using the --with-maxmemb option.

       -Mmaster    Normally, this allows conserver to bind to a particular IP address (like `127.0.0.1') instead
                   of all interfaces.  The default is to bind to all addresses.  However, if --with-uds was used
                   to  enable  Unix domain sockets for client/server communication, this points conserver to the
                   directory  where   it   should   store   the   sockets.    The   default   master   directory
                   (``/tmp/conserver'') may be changed at compile time using the --with-uds option.

       -n          Obsolete (now a no-op); see -u.

       -o          Normally, a client connecting to a ``downed'' console does just that.  Using this option, the
                   server will automatically attempt  to  open  (``bring  up'')  the  console  when  the  client
                   connects.

       -Omin       Enable  periodic  attempts  (every  min  minutes)  to open (``bring up'') all downed consoles
                   (similar to sending a SIGUSR1).  Without this option, or if min is zero, no periodic attempts
                   occur.

       -pport      Set  the TCP port for the master process to listen on.  This may be either a port number or a
                   service name.  The default port, ``conserver'' (typically 782), may  be  changed  at  compile
                   time  using  the  --with-port  option.   If  the  --with-uds  option was used, this option is
                   ignored.

       -Ppasswd    Read the table of authorized user data from the file  passwd.   The  default  passwd  may  be
                   changed at compile time using the --with-pwdfile option.

       -R          Disable  automatic  client  redirection  to  other conserver hosts.  This means informational
                   commands like -w and -i will only show the status of the local conserver host and attempts to
                   connect to remote consoles will result in an informative message to the user.

       -S          Do not run the server, just perform a syntax check of configuration file and exit with a non-
                   zero value if there is an error.  Using more than one  -S  will  cause  conserver  to  output
                   various information about each console in 5 colon-separated fields, enclosed in curly-braces.
                   The philosophy behind the output is to provide information to  allow  external  detection  of
                   multiple  consoles access the same physical port.  Since this is highly environment-specific,
                   conserver cannot do the check internally.

                   name     The name of the console.

                   master   The hostname of the master conserver host for the console.

                   aliases  The console aliases in a comma-separated list.

                   type     The type of console.  Values will be a `/' for a local device, `|'  for  a  command,
                            `!' for a remote port, `%' for a Unix domain socket, and `#' for a noop console.

                   details  Multiple  values  are  comma-separated and depend on the type of the console.  Local
                            devices will have the values of the device file and baud rate/parity.  Commands will
                            have string to invoke.  Remote ports will have the values of the remote hostname and
                            port number.  Unix domain sockets will have the path to the socket.   Noop  consoles
                            will have nothing.

       -u          Send  unloved  console  output to conserver's stdout (which, in daemon mode, is redirected to
                   the logfile).  This applies to all consoles to which no  user  is  attached,  independent  of
                   whether logging of individual consoles is enabled via conserver.cf entries.

       -Ulogfile   Copy  all  console data to the ``unified'' logfile.  The output is the same as the -u output,
                   but all consoles, not just those without a user, are logged.  Each line of output is prefixed
                   with  the  console  name.  If a user is attached read/write, a `*' is appended to the console
                   name, to allow log watching utilites to ignore potential user-introduced alarms.

       -v          Echo the configuration as it is being read (be verbose).

       -V          Output the version number and settings of the conserver program and then exit.

PROTOCOL

       The protocol used to interact with the conserver daemon has two basic styles.  The  first  style  is  the
       initial line-based mode, which occurs before connecting to a console.  The second style is the character-
       based, escape-sequence mode, while connected to a console.

       The initial line-based mode begins the same for both  the  master  process  and  its  children.   Upon  a
       successful (non-rejected) client connection, an ``ok'' is sent.  The client then issues a command and the
       server responds to it with a result string (``ok'' being the sign of success  for  most  commands).   The
       commands  available  are  ``help'',  ``ssl''  (if  SSL was built into the code), ``login'', and ``exit''.
       Using the ``login'' command, the client authenticates and gains access to the extended command set.  This
       is  where  the  master  process  and  its children differ.  The master process gives the client access to
       global commands, and the child provides commands for interacting  with  the  consoles  it  manages.   The
       ``help'' command, in both cases, will provide a complete list of commands and a short description of what
       they do.

       The second, character-based, style of interaction occurs when the client issues the ``call'' command with
       a  child  process.   This command connects the client to a console and, at that point, relays all traffic
       between the client and the console.  There is no more command-based interaction between  the  client  and
       the server, any interaction with the server is done with the default escape sequence.

       This  is, by no means, a complete description of the entire client/server interaction.  It is, however, a
       brief explanation in order to give a idea of what the  program  does.   See  the  PROTOCOL  file  in  the
       distribution for further details.

FILES

       The  following  default  file  locations may be overridden at compile time or by the command-line options
       described above.  Run conserver -V to see the defaults set at compile time.

       /etc/conserver.cf        description of console  terminal  lines  and  client  host  access  levels;  see
                                conserver.cf(5).
       /etc/conserver.passwd    users allowed to access consoles; see conserver.passwd(5).
       /var/run/conserver.pid   the master conserver process ID
       /var/log/conserver       log of errors and informational messages
       /tmp/conserver           directory to hold Unix domain sockets (if enabled)

       Additionally,   output   from   individual  consoles  may  be  logged  to  separate  files  specified  in
       conserver.cf(5).

BUGS

       I'm sure there are bugs, I just don't know where they are.  Please let me know if you find any.

AUTHORS

       Thomas A. Fine, Ohio State Computer Science
       Kevin S Braunsdorf, Purdue University Computing Center
       Bryan Stansell, conserver.com

SEE ALSO

       console(1), conserver.cf(5), conserver.passwd(5)