CONSERVER.CF(5)

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"  ; }

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 `!'). Otherwise, 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.

    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 0 < n < 10. Break sequences are accessed via the ``^Eln'' client escape sequence.

    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.

    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).

    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 seconds 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).

    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.

    device
        filename
        Assign the serial device filename as the access 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
            h   host value
            c   console name

            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' or `X', specifying a decimal, lower-case hexadecimal, or an uppercase hexadecimal 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.

    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 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.

    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).

    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.

    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 it's 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 it's 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.

    parity
        [ even | mark | none | odd | space ]
        Set the parity option for the console. Only consoles of type ``device'' will use this value.

    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.

    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 `!'). Otherwise, 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 `!'). Otherwise, 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.

    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 | exec | host ]
        Set the type of console. The type ``device'' should be used for local serial ports (also set the device option), the type ``exec'' should be used for command invocations (perhaps also set the exec option), and the type ``host'' should be used for terminal servers and other socket-based interaction (also set the host and port options).

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 `!'). Otherwise, 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.

AUTHORS
Bryan Stansell, conserver.com

SEE ALSO
console(1), conserver.passwd(5), conserver(8)