Provided by: conserver-server_8.2.1-1_amd64 
NAME
conserver.cf - console configuration file for conserver(8)
DESCRIPTION
The format of the conserver.cf file is made up of named blocks of keyword/value pairs,
comments, and optional whitespace for formatting flexibility. The block types as well as
the keywords are pre-defined and explained in the BLOCKS section. A comment is an
unquoted pound-sign to a newline. See the PARSER section for full details on whitespace
and quoting.
Let me first show you a sample block with a couple of keyword/value pairs to make the
description a bit simpler to understand.
console simple { master localhost; type exec; rw *; }
This is actually a fully functional conserver.cf file (if certain conditions are met...and
if you can list those conditions, you can probably can skip to the BLOCKS section).
Our example is made of up of a console-block named ``simple'' with three keyword/value
pairs. What this does is define a console named ``simple'', makes the master of that
console the host ``localhost'', makes the type an exec-style console, and gives every user
read/write permission. This is the generic format of the file:
block-type block-name { keyword value; ... }
To show the addition of comments and whitespace, here is the example reformatted (but
functionally equivalent):
# define a console named "simple"
console simple {
# setting all required values...
master localhost;
type exec; # exec-style console
rw *; # allow any username
}
PARSER
The parser has six characters that it considers special. These are: ``{'', ``}'', ``;'',
``#'', ``\'', and ``"''. The first three (hereby called tokens) define the format of the
configuration blocks and are used as word separators, the next is the comment character,
and the last two are quoting characters.
Word separation occurs when the parser encounters an unquoted token and, in certain cases,
whitespace. Whitespace is only used as a word separator when the parser is looking for a
block-type or keyword. When it's looking for a block-name or value, whitespace is like
any other character, which allows you to embed whitespace in a block-name or value without
having to quote it. Here is an example:
default my defs { rw *; include other defs ; }
The block-type is ``default'', the block-name is ``my defs'', and the value for the
keyword ``include'' is ``other defs''. Whitespace around tokens are ignored so you get
``other defs'' instead of ``other defs '' as the value.
The only way to use one of the special characters as part of a block-name or value is to
quote it.
Quoting is a simple matter of prefixing a character with a backslash or surrounding a
group of characters with double-quotes. If a character is prefixed by a backslash, the
next character is a literal (so ``\\'' produces a ``\'', ``\"'' produces ``"'', ``\{''
produces a ``{'', etc.). For double-quoted strings, all characters are literal except for
``\"'', which embeds a double-quote.
Adding a variety of quotes to our example without changing the meaning of things, we have:
"defa"ult my\ defs { rw *; in\clude "other defs" ; }
There is one special line the parser recognizes: a ``#include'' statement. It is of the
form:
#include filename
Any whitespace around filename is ignored, but whitespace embedded inside is preserved.
Everything in filename is taken literally, so none of the normal parser quoting applies.
The #include must begin in ``column 0'' - no whitespace is allowed between it and the
start of the physical line. There is an include file depth limit of 10 to prevent
infinite recursion.
BLOCKS
access hostname|ipaddr
Define an access block for the host named hostname or using the address ipaddr. If
the value of ``*'' is used, the access block will be applied to all conserver
hosts. Access lists are used in a first match fashion (top down), so order is
important.
admin [!]username[,...]|""
Define a list of users making up the admin list for the console server. If
username matches a previously defined group name, all members of the
previous group are applied to the admin list (with access reversed if
prefixed with a `!'). If username doesn't match a previously defined group
and username begins with `@', the name (minus the `@') is checked against
the host's group database. All users found in the group will be granted (or
denied, if prefixed with `!') access. If username doesn't match a previous
group and doesn't begin with `@', the users will be granted (or denied, if
prefixed with `!') access. If the null string (``""'') is used, any users
previously defined for the console servers's admin list are removed.
allowed hostname[,...]
The list of hostnames are added to the ``allowed'' list, which grants
connections from the hosts but requires username authentication.
include accessgroup
The access lists defined using the name accessgroup are applied to the
current access block. The included access block must be previously defined.
limited [!]username[,...]|""
Define a list of users with limited functionality on the console server.
These users will not be allowed to suspend their connection, shift to
another console, or attach to a local command. If username matches a
previously defined group name, all members of the previous group are applied
to the admin list (with access reversed if prefixed with a `!'). If
username doesn't match a previously defined group and username begins with
`@', the name (minus the `@') is checked against the host's group database.
All users found in the group will be granted (or denied, if prefixed with
`!') access. If username doesn't match a previous group and doesn't begin
with `@', the users will be granted (or denied, if prefixed with `!')
access. If the null string (``""'') is used, any users previously defined
for the console server's limited list are removed.
rejected hostname[,...]
The list of hostnames are added to the ``rejected'' list, which rejects
connections from the hosts.
trusted hostname[,...]
The list of hostnames are added to the ``trusted'' list, which grants
connections from the hosts without username authentication.
break n
Define a break sequence where (1 <= n <= 9) or (a <= n <= z). Break sequences are
accessed via the ``^Ecln'' client escape sequence.
confirm yes|true|on|no|false|off
Set whether or not to ask the client for confirmation before sending the
break sequence. The default is ``no''.
delay n
Set the time delay for the \d sequence to n milliseconds. The default time
delay is 250ms.
string breakseq
Assign the string breakseq to the specified slot n. A break sequence is a
simple character string with the exception of `\' and `^':
\a alert
\b backspace
\d delay specified by the delay option.
\f form-feed
\n newline
\r carriage-return
\t tab
\v vertical-tab
\z serial break
\\ backslash
\^ circumflex
\ooo octal representation of a character (where ooo is one to three
octal digits)
\c character c
^? delete
^c control character (c is ``and''ed with 0x1f)
config hostname|ipaddr
Define a configuration block for the host named hostname or using the address
ipaddr. If the value of ``*'' is used, the configuration block will be applied to
all conserver hosts.
autocomplete yes|true|on|no|false|off
Turn the console name autocompletion feature on or off. If autocompletion
is on, a client can use any unique leading portion of a console name when
connecting to a console. Autocompletion is on by default.
defaultaccess rejected|trusted|allowed
Set the default access permission for all hosts not matched by an access
list (see the -a command-line flag).
daemonmode yes|true|on|no|false|off
Set whether or not to become a daemon when run (see the -d command-line
flag).
initdelay number
Set the number of seconds between console initializations. All consoles
with the same host value will be throttled as a group (those without a host
value are their own group). In other words, each console within a group
will only be initialized after number seconds passes from the previous
initialization of a console in that group. Different throttle groups are
initialized simultaneously. One warning: since consoles are split up and
managed by seperate conserver processes, it's possible for more than one
conserver process to have a throttle group based on a particular host value.
If this happens, each conserver process will throttle their groups
independently of the other conserver processes, which results in a more
rapid initialization (per host value) than one might otherwise expect. If
number is zero, all consoles are initialized without delay.
logfile filename
Set the logfile to write to when in daemon mode (see the -L command-line
flag).
passwdfile filename
Set the password file location used for authentication (see the -P command-
line flag).
primaryport number|name
Set the port used by the master conserver process (see the -p command-line
flag).
redirect yes|true|on|no|false|off
Turn redirection on or off (see the -R command-line flag).
reinitcheck number
Set the number of minutes used between reinitialization checks (see the -O
command-line flag).
secondaryport number|name
Set the base port number used by child processes (see the -b command-line
flag).
setproctitle yes|true|on|no|false|off
Set whether or not the process title shows master/group functionality as
well as the port number the process is listening on and how many consoles it
is managing. The operating system must support the setproctitle() call.
sslcredentials filename
Set the SSL credentials file location (see the -c command-line flag).
sslcacertificatefile filename
Load the valid CA certificates for the SSL connection from the PEM encoded
file. This option overrides the global CA list.
sslreqclientcert yes|true|on|no|false|off
Set whether or not a certificate is required by the client to connect. The
default is ``no''.
sslrequired yes|true|on|no|false|off
Set whether or not encryption is required when talking to clients (see the
-E command-line flag).
unifiedlog filename
Set the location of the unified log to filename. See the -U command-line
flag for details.
console name
Define a console identified as name. The keywords are the same as the default
block with the following addition.
aliases name[,...]|""
Define a list of console aliases. If the null string (``""'') is used, any
aliases previously defined for the console are removed.
default name
Define a block of defaults identified as name. If name is ``*'', the automatically
applied default block is defined (basically all consoles have an implicit ``include
"*";'' at the beginning of their definition).
baud 300|600|1800|2400|4800|9600|19200|38400|57600|115200
Assign the baud rate to the console. Only consoles of type ``device'' will
use this value.
break n
Assign the break sequence n as the default for the console, which is used by
the ``^Ecl0'' client escape sequence.
breaklist n[,...]|""
Associate a list of break sequences referenced by n with the console. If
``*'' is used (the default), all defined break sequences will be available.
If the null string (``""'') is used, no sequences will be available.
device filename
Assign the serial device filename as the path to the console. Only consoles
of type ``device'' will use this value.
devicesubst c=t[n]f[,...]|""
Perform character substitutions on the device value. A series of
replacements can be defined by specifying a comma-separated list of c=t[n]f
sequences where c is any printable character, t specifies the replacement
value, n is a field length (optional), and f is the format string. t can be
one of the characters below, catagorized as a string replacement or a
numeric replacement, which dictates the use of the n and f fields.
String Replacement
c console name
h host value
r replstring value
Numeric Replacement
p config port value
P calculated port value
For string replacements, if the replacement isn't at least n characters, it
will be padded with space characters on the left. f must be `s'. For
numeric replacements, the value will be formatted to at least n characters,
padded with 0s if n begins with a 0, and space characters otherwise. f must
be either `d', `x', `X', `a', or `A', specifying a decimal, lowercase
hexadecimal (0-9a-f), uppercase hexadecimal (0-9A-F), lowercase alphanumeric
(0-9a-z), or uppercase alphanumeric (0-9A-Z) conversion. If the null string
(``""'') is used, no replacements will be done.
exec command|""
Assign the string command as the command to access the console. Conserver
will run the command by invoking ``/bin/sh -ce "command"''. If the null
string (``""'') is used or no exec keyword is specified, conserver will use
the command ``/bin/sh -i''. Only consoles of type ``exec'' will use this
value.
execrunas [user][:group]|""
By default, the command invoked by exec is run with the same privileges as
the server. If the server is running with root privileges, this option
resets the user and/or group of the invoked process to user and group
respectively. user may be a username or numeric uid and group may be a
group name or numeric gid. Either one is optional. If the server is not
running with root privileges, these values are not used. If the null string
(``""'') is specified, the default of running with the same privileges as
the server is restored.
execsubst c=t[n]f[,...]|""
Perform character substitutions on the exec value. See the devicesubst
option for an explanation of the format string. If the null string (``""'')
is used, no replacements will be done.
host hostname
Assign hostname as the host to connect to for accessing the console. You
must also set the port option for consoles of type ``host''. Normally, only
consoles of type ``host'' and ``ipmi'' will use this value, however if the
devicesubst, execsubst, or initsubst keywords are used in any console type,
this value is used.
idlestring string|""
Assign the string that is sent to the console once the console is idle for
an idletimeout amount of time. If the null string (``""'') is used, the
string is unset and the default is used. The string is interpreted just as
a break string is interpreted (see the break configuration items for
details) where all delays specified (via ``\d'') use the default delay time.
The default string is ``\n''.
idletimeout number[s|m|h]
Set the idle timeout of the console to number seconds. If an `s', `m', or
`h' is used after number, the specified time is interpreted as seconds,
minutes, or hours. Set the timeout to zero to disable the idle timeout (the
default).
ipmiciphersuite number
Set the IPMI cipher suite. Syntactically valid values are -1 (the default)
and greater. Check the FreeIPMI documentation for usable values.
ipmikg string|""
Set the BMC authentication key K_g to string. A K_g value is a simple
character string with the exception of `\':
\\ backslash
\ooo octal representation of a character (where ooo is one to three
octal digits)
\c character c
The resulting value must be no more than 20 characters. The null string
(``""'') is the default.
impiworkaround [!]option[,...]|""
You can turn off a workaround by prefixing it with a ``!'' character. So,
to turn off the integrity workaround, you would use !integrity. The
following are valid options and their mapping to FreeIPMI settings:
activation-status SKIP_SOL_ACTIVATION_STATUS
auth-capabilites AUTHENTICATION_CAPABILITIES
channel-payload SKIP_CHANNEL_PAYLOAD_SUPPORT
checksum NO_CHECKSUM_CHECK
default DEFAULT
ignore-payload-size IGNORE_SOL_PAYLOAD_SIZE
ignore-port IGNORE_SOL_PORT
integrity NON_EMPTY_INTEGRITY_CHECK_VALUE
intel-session INTEL_2_0_SESSION
packet-sequence INCREMENT_SOL_PACKET_SEQUENCE
privilege OPEN_SESSION_PRIVILEGE
serial-alerts SERIAL_ALERTS_DEFERRED
sun-session SUN_2_0_SESSION
supermicro-session SUPERMICRO_2_0_SESSION
If no ipmiworkaround is specified, the ``default'' workaround will be used.
The null string (``""'') unsets all workarounds, including ``default''. See
the FreeIPMI documentation for details on what workarounds affect.
ipmiprivlevel user|operator|admin
Set the privilege level for the username used during IPMI authentication.
The default privilege level is ``admin''.
include default
The default block defined using the name default is applied to the current
console or default block. The included default block must be previously
defined.
initcmd command|""
Invoke command as soon as the console is brought up, redirecting the console
to stdin, stdout, and stderr of command. The command is passed as an
argument to ``/bin/sh -ce''. If the null string (``""'') is used, the
command is unset and nothing is invoked.
initrunas [user][:group]|""
By default, the command invoked by initcmd is run with the same privileges
as the server. If the server is running with root privileges, this option
resets the user and/or group of the invoked process to user and group
respectively. user may be a username or numeric uid and group may be a
group name or numeric gid. Either one is optional. If the server is not
running with root privileges, these values are not used. If the null string
(``""'') is specified, the default of running with the same privileges as
the server is restored.
initspinmax n|""
Set the maximum number of ``spins'' allowed for the console to n, where 0 <=
n <= 254. A console is determined to be ``spinning'' if an attempt to
initialize the console occurs in under initspintimer seconds from its
previous initialization and this quick initialization occurs initspinmax
times in a row. If, at any point, the time between initializations is
greater than initspintimer, the counter for reaching initspinmax resets to
zero. When a console is determined to be ``spinning'' it is forced down.
If the null string (``""'') is specified, the default of 5 is used.
initspintimer t|""
Set the number of seconds a console must be ``up'' to not be considered
``spinning'' to t, where 0 <= t <= 254. See initspinmax for a full
description of console ``spinning.'' If the null string (``""'') is
specified, the default of 1 is used.
initsubst c=t[n]f[,...]|""
Perform character substitutions on the initcmd value. See the devicesubst
option for an explanation of the format string. If the null string (``""'')
is used, no replacements will be done.
logfile filename|""
Assign the logfile specified by filename to the console. Any occurrence of
``&'' in filename will be replaced with the name of the console. If the
null string (``""'') is used, the logfile name is unset and no logging will
occur.
logfilemax number[k|m]
Enable automatic rotation of logfile once its size exceeds number bytes.
Specifying k or m interpret number as kilobytes and megabytes. number must
be at least 2048 bytes. A value of zero will turn off automatic rotation of
logfile. The logfile filename will be renamed filename-YYYYMMDD-HHMMSS,
where the extension is the current GMT year, month, day, hour, minute, and
second (to prevent issues with clock rollbacks). File sizes are checked
every 5 minutes with an additional initial pseudo-random delay of up to one
minute (to help prevent all processes checking all consoles simultaneously).
2.5% (minimum 100 bytes, maximum 4000 bytes) of the old logfile is read from
the end of the file. All data past the first newline is moved (not copied)
to the new logfile so that a replay of the console works and starts on a
line boundary.
master hostname|ipaddr
Define which conserver host manages the console. The host may be specified
by hostname or using the address ipaddr.
motd message|""
Set the "message of the day" for the console to message, which gets
displayed when a client attaches to the console. If the null string
(``""'') is used, the MOTD is unset and no message will occur.
options [!]option[,...]|""
You can negate the option by prefixing it with a ``!'' character. So, to
turn off the hupcl flag, you would use !hupcl. The following are valid
options:
ixon Enable XON/XOFF flow control on output. Only consoles of type
``device'' or ``exec'' will use this value. Default is ixon.
ixany Enable any character to restart output. Only consoles of type
``device'' or ``exec'' will use this value. Default is !ixany.
ixoff Enable XON/XOFF flow control on input. Only consoles of type
``device'' or ``exec'' will use this value. Default is ixoff
for consoles of type ``device'' and !ixoff for consoles of type
``exec''.
crtscts Enable RTS/CTS (hardware) flow control. Only consoles of type
``device'' will use this value. Default is !crtscts.
cstopb Set two stop bits, rather than one. Only consoles of type
``device'' will use this value. Default is !cstopb.
hupcl Lower modem control lines after last process closes the device
(hang up). Only consoles of type ``device'' will use this
value. Default is !hupcl.
ondemand Initialize the console when a client requests a connection to
the console. When no clients are connected, bring the console
down. The conserver option -i will set this flag for all
consoles. Default is !ondemand.
striphigh Strip the high bit off all data coming from this console and all
clients connected to this console before processing occurs. The
conserver option -7 will set this flag for all consoles.
Default is !striphigh.
reinitoncc Automatically reinitialize (``bring up'') a downed console when
a client connects. Without this option, a client will be
attached to the downed console and will need to manually
reinitialize the console with an escape sequence. The conserver
option -o will set this flag for all consoles. Default is
!reinitoncc.
autoreinit Allow this console to be automatically reinitialized if it
unexpectedly goes down. If the console doesn't come back up, it
is retried every minute. A console of type ``exec'' that exits
with a zero exit status is automatically reinitialized
regardless of this setting. The conserver option -F will unset
this flag for all consoles. Default is autoreinit.
unloved Enable the sending of this console's output (prefixed with its
name) to the daemon's stdout (or the logfile if in daemon mode)
when no clients are connected to the console. The conserver
option -u will set this flag for all consoles. Default is
!unloved.
login Allow users to log into this console. If logins are not
allowed, conserver will send a generic message to the client
saying so and terminate the connection. You can override the
generic message by setting the motd message. Default is login.
parity even|mark|none|odd|space
Set the parity option for the console. Only consoles of type ``device''
will use this value.
password password|""
Use password during IPMI authentication. If the null string (``""'') is
used (the default), no password will be used.
port number|name
Set the port used to access the console. The port may be specified as a
number or a name. A name will cause a getservbyname(3) call to look up the
port number. The port, portbase, and portinc values are all used to
calculate the final port number to connect to. The formula used is
finalport = portbase + portinc * port. By using proper values in the
formula, you can reference ports on a terminal server by their physical
numbering of 0..n or 1..n (depending on if you like zero-based or one-based
numbering). Warning: you can generate a -1 value with this formula, which
will become a very high numbered positive value (since things are stored
unsigned). You must also set the host option as well. Normally, only
consoles of type ``host'' will use this value, however if the devicesubst,
execsubst, or initsubst keywords are used in any console type, this value is
used.
portbase number
Set the base value for the port calculation formula. number must be 0 or
greater. The default is zero. See port for the details of the formula.
portinc number
Set the increment value for the port calculation formula. number must be 0
or greater. The default is one. See port for the details of the formula.
protocol telnet|raw
Set the protocol used to send and receive data from the console. If raw is
used, all data is sent ``as is'', unprotected by any protocol specification.
If telnet is used (which is the default), data is encapsulated in the telnet
protocol. The striphigh console option still applies when data is read by
the server, and if enabled, can impact the encapsulation process.
replstring string
A generic replacement string that can be used by the devicesubst, execsubst,
and initsubst keywords.
ro [!]username[,...]|""
Define a list of users making up the read-only access list for the console.
If username matches a previously defined group name, all members of the
previous group are applied to the read-only access list (with access
reversed if prefixed with a `!'). If username doesn't match a previously
defined group and username begins with `@', the name (minus the `@') is
checked against the host's group database. All users found in the group
will be granted (or denied, if prefixed with `!') read-only access. If
username doesn't match a previous group and doesn't begin with `@', the
users will be granted (or denied, if prefixed with `!') read-only access.
If the null string (``""'') is used, any users previously defined for the
console's read-only list are removed.
rw [!]username[,...]|""
Define a list of users making up the read-write access list for the console.
If username matches a previously defined group name, all members of the
previous group are applied to the read-write access list (with access
reversed if prefixed with a `!'). If username doesn't match a previously
defined group and username begins with `@', the name (minus the `@') is
checked against the host's group database. All users found in the group
will be granted (or denied, if prefixed with `!') read-write access. If
username doesn't match a previous group and doesn't begin with `@', the
users will be granted (or denied, if prefixed with `!') read-write access.
If the null string (``""'') is used, any users previously defined for the
console's read-write list are removed.
tasklist c[,...]|""
Associate a list of tasks referenced by c with the console. If ``*'' is
used (the default), all defined tasks will be available. If the null string
(``""'') is used, no tasks will be available.
timestamp [number[m|h|d|l]][a][b]|""
Specifies the time between timestamps applied to the console log file and
whether to log read/write connection actions. The timestamps look like
``[-- MARK -- Mon Jan 25 14:46:56 1999]''. The `m', `h', and `d' tags
specify ``minutes'' (the default), ``hours'', and ``days''. The `l' tag
specifies ``lines'' and will cause timestamps of the form ``[Mon Jan 25
14:46:56 PST 1999]'' to be placed every number lines (a newline character
signifies a new line). So, ``5h'' specifies every five hours and ``2l''
specifies every two lines. An `a' can be specified to add logs of
``attached'', ``detached'', and ``bumped'' actions, including the user's
name and the host from which the client connection was made. A `b' can be
specified to add logging of break sequences sent to the console.
type device|ipmi|exec|host|noop|uds
Set the type of console. A type of ``device'' should be used for local
serial ports (also set the device value). A type of ``ipmi'' should be used
for IPMI serial over LAN consoles (also set the host value and possibly the
username, password, and ipmi* values). A type of ``exec'' should be used
for command invocations (perhaps also set the exec value). A type of
``host'' should be used for terminal servers and other TCP socket-based
interaction (also set the host and port values). A type of ``noop'' should
be used as a placeholder - it does nothing, ignores any logfile value and
forces the !nologin option (so you might want to set the motd value). A
type of ``uds'' should be used for Unix domain sockets (also set the uds
option).
uds filename
Assign the Unix domain socket filename as the path to the console. Only
consoles of type ``uds'' will use this value.
udssubst c=t[n]f[,...]|""
Perform character substitutions on the uds value. See the devicesubst
option for an explanation of the format string. If the null string (``""'')
is used, no replacements will be done.
username username|""
Use username during IPMI authentication. If the null string (``""'') is
used (the default), the ``null'' user will be used.
group name
Define a user group identified as name.
users [!]username[,...]|""
Define a list of users making up the group name. If username matches a
previously defined group name, all members of the previous group are applied
to the current group (with access reversed if prefixed with a `!'). If
username doesn't match a previously defined group and username begins with
`@', the name (minus the `@') is checked against the host's group database.
All users found in the group will be recorded with (or without, if prefixed
with `!') access. If username doesn't match a previous group and doesn't
begin with `@', the users will be recorded with (or without, if prefixed
with `!') access. If the null string (``""'') is used, any users previously
defined for this group are removed.
task c
Define a task where c is a lowercase alphanumeric (0-9a-z). Tasks are invoked via
the ``^Ec!c'' client escape sequence.
cmd command|""
Invoke command on the server when instructed by the client. All file
descriptors are closed, except for stderr (which is inherited from the
server). The command is passed as an argument to ``/bin/sh -ce'' and is a
``fire and forget'' methodology (you need to check logs for any issues). If
the null string (``""'') is used, the entire task definition is ignored.
confirm yes|true|on|no|false|off
Set whether or not to ask the client for confirmation before invoking the
task. The default is ``no''.
description string
Set a description for the task. When a client lists tasks, string will be
printed instead of the command defined above. If the null string (``""'')
is used, the command defined above will be printed.
runas [user][:group]|""
By default, the command invoked by cmd is run with the same privileges as
the server. If the server is running with root privileges, this option
resets the user and/or group of the invoked process to user and group
respectively. user may be a username or numeric uid and group may be a
group name or numeric gid. Either one is optional. If the server is not
running with root privileges, these values are not used. If the null string
(``""'') is specified, the default of running with the same privileges as
the server is restored.
subst c=t[n]f[,...]|""
Perform character substitutions on the cmd value. See the devicesubst
option for an explanation of the format string. If the null string (``""'')
is used, no replacements will be done.
AUTHORS
Bryan Stansell, conserver.com
SEE ALSO
console(1), conserver.passwd(5), conserver(8)