Provided by: conserver-server_8.2.7-2_amd64 
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
utilities 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)