Provided by: conserver-server_8.1.18-2.2ubuntu2_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)