1CONSERVER.CF(5) conserver CONSERVER.CF(5)
2
6 conserver.cf - console configuration file for conserver(8)
7
9 The format of the conserver.cf file is made up of named blocks of key‐
10 word/value pairs, comments, and optional whitespace for formatting
11 flexibility. The block types as well as the keywords are pre-defined
12 and explained in the BLOCKS section. A comment is an unquoted pound-
13 sign to a newline. See the PARSER section for full details on white‐
14 space and quoting.
15 Let me first show you a sample block with a couple of keyword/value
17 pairs to make the description a bit simpler to understand.
18 console simple { master localhost; type exec; rw *; }
20 This is actually a fully functional conserver.cf file (if certain con‐
22 ditions are met...and if you can list those conditions, you can proba‐
23 bly can skip to the BLOCKS section).
24 Our example is made of up of a console-block named ``simple'' with
26 three keyword/value pairs. What this does is define a console named
27 ``simple'', makes the master of that console the host ``localhost'',
28 makes the type an exec-style console, and gives every user read/write
29 permission. This is the generic format of the file:
30 block-type block-name { keyword value; ... }
32 To show the addition of comments and whitespace, here is the example
34 reformatted (but functionally equivalent):
35 # define a console named "simple"
37 console simple {
38 # setting all required values...
39 master localhost;
40 type exec; # exec-style console
41 rw *; # allow any username
42 }
43
45 The parser has six characters that it considers special. These are:
46 ``{'', ``}'', ``;'', ``#'', ``\'', and ``"''. The first three (hereby
47 called tokens) define the format of the configuration blocks and are
48 used as word separators, the next is the comment character, and the
49 last two are quoting characters.
50 Word separation occurs when the parser encounters an unquoted token
52 and, in certain cases, whitespace. Whitespace is only used as a word
53 separator when the parser is looking for a block-type or keyword. When
54 it's looking for a block-name or value, whitespace is like any other
55 character, which allows you to embed whitespace in a block-name or
56 value without having to quote it. Here is an example:
57 default my defs { rw *; include other defs ; }
59 The block-type is ``default'', the block-name is ``my defs'', and the
61 value for the keyword ``include'' is ``other defs''. Whitespace around
62 tokens are ignored so you get ``other defs'' instead of ``other defs
63 '' as the value.
64 The only way to use one of the special characters as part of a block-
66 name or value is to quote it.
67 Quoting is a simple matter of prefixing a character with a backslash or
69 surrounding a group of characters with double-quotes. If a character
70 is prefixed by a backslash, the next character is a literal (so ``\\''
71 produces a ``\'', ``\"'' produces ``"'', ``\{'' produces a ``{'',
72 etc.). For double-quoted strings, all characters are literal except
73 for ``\"'', which embeds a double-quote.
74 Adding a variety of quotes to our example without changing the meaning
76 of things, we have:
77 "defa"ult my\ defs { rw *; in\clude "other defs" ; }
79 There is one special line the parser recognizes: a ``#include'' state‐
81 ment. It is of the form:
82 #include filename
84 Any whitespace around filename is ignored, but whitespace embedded
86 inside is preserved. Everything in filename is taken literally, so
87 none of the normal parser quoting applies. The #include must begin in
88 ``column 0'' - no whitespace is allowed between it and the start of the
89 physical line. There is an include file depth limit of 10 to prevent
90 infinite recursion.
91
93 access hostname|ipaddr
94 Define an access block for the host named hostname or using the
95 address ipaddr. If the value of ``*'' is used, the access block
96 will be applied to all conserver hosts. Access lists are used
97 in a first match fashion (top down), so order is important.
98 admin [!]username[,...]|""
100 Define a list of users making up the admin list for the
101 console server. If username matches a previously defined
102 group name, all members of the previous group are applied
103 to the admin list (with access reversed if prefixed with
104 a `!'). If username doesn't match a previously defined
105 group and username begins with `@', the name (minus the
106 `@') is checked against the host's group database. All
107 users found in the group will be granted (or denied, if
108 prefixed with `!') access. If username doesn't match a
109 previous group and doesn't begin with `@', the users will
110 be granted (or denied, if prefixed with `!') access. If
111 the null string (``""'') is used, any users previously
112 defined for the console servers's admin list are removed.
113 allowed hostname[,...]
115 The list of hostnames are added to the ``allowed'' list,
116 which grants connections from the hosts but requires
117 username authentication.
118 include accessgroup
120 The access lists defined using the name accessgroup are
121 applied to the current access block. The included access
122 block must be previously defined.
123 limited [!]username[,...]|""
125 Define a list of users with limited functionality on the
126 console server. These users will not be allowed to sus‐
127 pend their connection, shift to another console, or
128 attach to a local command. If username matches a previ‐
129 ously defined group name, all members of the previous
130 group are applied to the admin list (with access reversed
131 if prefixed with a `!'). If username doesn't match a
132 previously defined group and username begins with `@',
133 the name (minus the `@') is checked against the host's
134 group database. All users found in the group will be
135 granted (or denied, if prefixed with `!') access. If
136 username doesn't match a previous group and doesn't begin
137 with `@', the users will be granted (or denied, if pre‐
138 fixed with `!') access. If the null string (``""'') is
139 used, any users previously defined for the console
140 server's limited list are removed.
141 rejected hostname[,...]
143 The list of hostnames are added to the ``rejected'' list,
144 which rejects connections from the hosts.
145 trusted hostname[,...]
147 The list of hostnames are added to the ``trusted'' list,
148 which grants connections from the hosts without username
149 authentication.
150 break n
152 Define a break sequence where 0 < n < 10. Break sequences are
153 accessed via the ``^Ecln'' client escape sequence.
154 delay n
156 Set the time delay for the \d sequence to n milliseconds.
157 The default time delay is 250ms.
158 string breakseq
160 Assign the string breakseq to the specified slot n. A
161 break sequence is a simple character string with the
162 exception of `\' and `^':
163 \a alert
165 \b backspace
166 \d delay specified by the delay option.
167 \f form-feed
168 \n newline
169 \r carriage-return
170 \t tab
171 \v vertical-tab
172 \z serial break
173 \\ backslash
174 \^ circumflex
175 \ooo octal representation of a character (where
176 ooo is one to three octal digits)
177 \c character c
178 ^? delete
179 ^c control character (c is ``and''ed with 0x1f)
180 config hostname|ipaddr
182 Define a configuration block for the host named hostname or
183 using the address ipaddr. If the value of ``*'' is used, the
184 configuration block will be applied to all conserver hosts.
185 autocomplete yes|true|on|no|false|off
187 Turn the console name autocompletion feature on or off.
188 If autocompletion is on, a client can use any unique
189 leading portion of a console name when connecting to a
190 console. Autocompletion is on by default.
191 defaultaccess rejected|trusted|allowed
193 Set the default access permission for all hosts not
194 matched by an access list (see the -a command-line flag).
195 daemonmode yes|true|on|no|false|off
197 Set whether or not to become a daemon when run (see the
198 -d command-line flag).
199 initdelay number
201 Set the number of seconds between console initializa‐
202 tions. All consoles with the same host value will be
203 throttled as a group (those without a host value are
204 their own group). In other words, each console within a
205 group will only be initialized after number seconds
206 passes from the previous initialization of a console in
207 that group. Different throttle groups are initialized
208 simultaneously. One warning: since consoles are split up
209 and managed by seperate conserver processes, it's possi‐
210 ble for more than one conserver process to have a throt‐
211 tle group based on a particular host value. If this hap‐
212 pens, each conserver process will throttle their groups
213 independently of the other conserver processes, which
214 results in a more rapid initialization (per host value)
215 than one might otherwise expect. If number is zero, all
216 consoles are initialized without delay.
217 logfile filename
219 Set the logfile to write to when in daemon mode (see the
220 -L command-line flag).
221 passwdfile filename
223 Set the password file location used for authentication
224 (see the -P command-line flag).
225 primaryport number|name
227 Set the port used by the master conserver process (see
228 the -p command-line flag).
229 redirect yes|true|on|no|false|off
231 Turn redirection on or off (see the -R command-line
232 flag).
233 reinitcheck number
235 Set the number of minutes used between reinitialization
236 checks (see the -O command-line flag).
237 secondaryport number|name
239 Set the base port number used by child processes (see the
240 -b command-line flag).
241 setproctitle yes|true|on|no|false|off
243 Set whether or not the process title shows master/group
244 functionality as well as the port number the process is
245 listening on and how many consoles it is managing. The
246 operating system must support the setproctitle() call.
247 sslcredentials filename
249 Set the SSL credentials file location (see the -c com‐
250 mand-line flag).
251 sslrequired yes|true|on|no|false|off
253 Set whether or not encryption is required when talking to
254 clients (see the -E command-line flag).
255 unifiedlog filename
257 Set the location of the unified log to filename. See the
258 -U command-line flag for details.
259 console name
261 Define a console identified as name. The keywords are the same
262 as the default block with the following addition.
263 aliases name[,...]|""
265 Define a list of console aliases. If the null string
266 (``""'') is used, any aliases previously defined for the
267 console are removed.
268 default name
270 Define a block of defaults identified as name. If name is
271 ``*'', the automatically applied default block is defined (basi‐
272 cally all consoles have an implicit ``include "*";'' at the
273 beginning of their definition).
274 baud 300|600|1800|2400|4800|9600|19200|38400|57600|115200
276 Assign the baud rate to the console. Only consoles of
277 type ``device'' will use this value.
278 break n
280 Assign the break sequence n as the default for the con‐
281 sole, which is used by the ``^Ecl0'' client escape
282 sequence.
283 device filename
285 Assign the serial device filename as the path to the con‐
286 sole. Only consoles of type ``device'' will use this
287 value.
288 devicesubst c=t[n]f[,...]|""
290 Perform character substitutions on the device value. A
291 series of replacements can be defined by specifying a
292 comma-separated list of c=t[n]f sequences where c is any
293 printable character, t specifies the replacement value, n
294 is a field length (optional), and f is the format string.
295 t can be one of the characters below, catagorized as a
296 string replacement or a numeric replacement, which dic‐
297 tates the use of the n and f fields.
298 String Replacement
300 c console name
301 h host value
302 r replstring value
303 Numeric Replacement
305 p config port value
306 P calculated port value
307 For string replacements, if the replacement isn't at
309 least n characters, it will be padded with space charac‐
310 ters on the left. f must be `s'. For numeric replace‐
311 ments, the value will be formatted to at least n charac‐
312 ters, padded with 0s if n begins with a 0, and space
313 characters otherwise. f must be either `d', `x', `X',
314 `a', or `A', specifying a decimal, lowercase hexadecimal
315 (0-9a-f), uppercase hexadecimal (0-9A-F), lowercase
316 alphanumeric (0-9a-z), or uppercase alphanumeric (0-9A-Z)
317 conversion. If the null string (``""'') is used, no
318 replacements will be done.
319 exec command|""
321 Assign the string command as the command to access the
322 console. Conserver will run the command by invoking
323 ``/bin/sh -ce "command"''. If the null string (``""'')
324 is used or no exec keyword is specified, conserver will
325 use the command ``/bin/sh -i''. Only consoles of type
326 ``exec'' will use this value.
327 execrunas [user][:group]|""
329 By default, the command invoked by exec is run with the
330 same privileges as the server. If the server is running
331 with root privileges, this option resets the user and/or
332 group of the invoked process to user and group respec‐
333 tively. user may be a username or numeric uid and group
334 may be a group name or numeric gid. Either one is
335 optional. If the server is not running with root privi‐
336 leges, these values are not used. If the null string
337 (``""'') is specified, the default of running with the
338 same privileges as the server is restored.
339 execsubst c=t[n]f[,...]|""
341 Perform character substitutions on the exec value. See
342 the devicesubst option for an explanation of the format
343 string. If the null string (``""'') is used, no replace‐
344 ments will be done.
345 host hostname
347 Assign hostname as the host to connect to for accessing
348 the console. You must also set the port option as well.
349 Normally, only consoles of type ``host'' will use this
350 value, however if the devicesubst, execsubst, or init‐
351 subst keywords are used in any console type, this value
352 is used.
353 idlestring string|""
355 Assign the string that is sent to the console once the
356 console is idle for an idletimeout amount of time. If
357 the null string (``""'') is used, the string is unset and
358 the default is used. The string is interpreted just as a
359 break string is interpreted (see the break configuration
360 items for details) where all delays specified (via
361 ``\d'') use the default delay time. The default string
362 is ``\n''.
363 idletimeout number[s|m|h]
365 Set the idle timeout of the console to number seconds.
366 If an `s', `m', or `h' is used after number, the speci‐
367 fied time is interpreted as seconds, minutes, or hours.
368 Set the timeout to zero to disable the idle timeout (the
369 default).
370 include default
372 The default block defined using the name default is
373 applied to the current console or default block. The
374 included default block must be previously defined.
375 initcmd command|""
377 Invoke command as soon as the console is brought up,
378 redirecting the console to stdin, stdout, and stderr of
379 command. The command is passed as an argument to
380 ``/bin/sh -ce''. If the null string (``""'') is used,
381 the command is unset and nothing is invoked.
382 initrunas [user][:group]|""
384 By default, the command invoked by initcmd is run with
385 the same privileges as the server. If the server is run‐
386 ning with root privileges, this option resets the user
387 and/or group of the invoked process to user and group
388 respectively. user may be a username or numeric uid and
389 group may be a group name or numeric gid. Either one is
390 optional. If the server is not running with root privi‐
391 leges, these values are not used. If the null string
392 (``""'') is specified, the default of running with the
393 same privileges as the server is restored.
394 initspinmax n|""
396 Set the maximum number of ``spins'' allowed for the con‐
397 sole to n, where 0 <= n <= 254. A console is determined
398 to be ``spinning'' if an attempt to initialize the con‐
399 sole occurs in under initspintimer seconds from its pre‐
400 vious initialization and this quick initialization occurs
401 initspinmax times in a row. If, at any point, the time
402 between initializations is greater than initspintimer,
403 the counter for reaching initspinmax resets to zero.
404 When a console is determined to be ``spinning'' it is
405 forced down. If the null string (``""'') is specified,
406 the default of 5 is used.
407 initspintimer t|""
409 Set the number of seconds a console must be ``up'' to not
410 be considered ``spinning'' to t, where 0 <= t <= 254.
411 See initspinmax for a full description of console ``spin‐
412 ning.'' If the null string (``""'') is specified, the
413 default of 1 is used.
414 initsubst c=t[n]f[,...]|""
416 Perform character substitutions on the initcmd value.
417 See the devicesubst option for an explanation of the for‐
418 mat string. If the null string (``""'') is used, no
419 replacements will be done.
420 logfile filename|""
422 Assign the logfile specified by filename to the console.
423 Any occurrence of ``&'' in filename will be replaced with
424 the name of the console. If the null string (``""'') is
425 used, the logfile name is unset and no logging will
426 occur.
427 logfilemax number[k|m]
429 Enable automatic rotation of logfile once its size
430 exceeds number bytes. Specifying k or m interpret number
431 as kilobytes and megabytes. number must be at least 2048
432 bytes. A value of zero will turn off automatic rotation
433 of logfile. The logfile filename will be renamed file‐
434 name-YYYYMMDD-HHMMSS, where the extension is the current
435 GMT year, month, day, hour, minute, and second (to pre‐
436 vent issues with clock rollbacks). File sizes are
437 checked every 5 minutes with an additional initial
438 pseudo-random delay of up to one minute (to help prevent
439 all processes checking all consoles simultaneously).
440 2.5% (minimum 100 bytes, maximum 4000 bytes) of the old
441 logfile is read from the end of the file. All data past
442 the first newline is moved (not copied) to the new log‐
443 file so that a replay of the console works and starts on
444 a line boundary.
445 master hostname|ipaddr
447 Define which conserver host manages the console. The
448 host may be specified by hostname or using the address
449 ipaddr.
450 motd message|""
452 Set the "message of the day" for the console to message,
453 which gets displayed when a client attaches to the con‐
454 sole. If the null string (``""'') is used, the MOTD is
455 unset and no message will occur.
456 options [!]option[,...]|""
458 You can negate the option by prefixing it with a ``!''
459 character. So, to turn off the hupcl flag, you would use
460 !hupcl. The following are valid options:
461 ixon Enable XON/XOFF flow control on output. Only
463 consoles of type ``device'' or ``exec'' will
464 use this value. Default is ixon.
465 ixany Enable any character to restart output. Only
466 consoles of type ``device'' or ``exec'' will
467 use this value. Default is !ixany.
468 ixoff Enable XON/XOFF flow control on input. Only
469 consoles of type ``device'' or ``exec'' will
470 use this value. Default is ixoff for con‐
471 soles of type ``device'' and !ixoff for con‐
472 soles of type ``exec''.
473 crtscts Enable RTS/CTS (hardware) flow control. Only
474 consoles of type ``device'' will use this
475 value. Default is !crtscts.
476 cstopb Set two stop bits, rather than one. Only
477 consoles of type ``device'' will use this
478 value. Default is !cstopb.
479 hupcl Lower modem control lines after last process
480 closes the device (hang up). Only consoles
481 of type ``device'' will use this value.
482 Default is !hupcl.
483 ondemand Initialize the console when a client requests
484 a connection to the console. When no clients
485 are connected, bring the console down. The
486 conserver option -i will set this flag for
487 all consoles. Default is !ondemand.
488 striphigh Strip the high bit off all data coming from
489 this console and all clients connected to
490 this console before processing occurs. The
491 conserver option -7 will set this flag for
492 all consoles. Default is !striphigh.
493 reinitoncc Automatically reinitialize (``bring up'') a
494 downed console when a client connects. With‐
495 out this option, a client will be attached to
496 the downed console and will need to manually
497 reinitialize the console with an escape
498 sequence. The conserver option -o will set
499 this flag for all consoles. Default is
500 !reinitoncc.
501 autoreinit Allow this console to be automatically reini‐
502 tialized if it unexpectedly goes down. If
503 the console doesn't come back up, it is
504 retried every minute. A console of type
505 ``exec'' that exits with a zero exit status
506 is automatically reinitialized regardless of
507 this setting. The conserver option -F will
508 unset this flag for all consoles. Default is
509 autoreinit.
510 unloved Enable the sending of this console's output
511 (prefixed with its name) to the daemon's std‐
512 out (or the logfile if in daemon mode) when
513 no clients are connected to the console. The
514 conserver option -u will set this flag for
515 all consoles. Default is !unloved.
516 login Allow users to log into this console. If
517 logins are not allowed, conserver will send a
518 generic message to the client saying so and
519 terminate the connection. You can override
520 the generic message by setting the motd mes‐
521 sage. Default is login.
522 parity even|mark|none|odd|space
524 Set the parity option for the console. Only consoles of
525 type ``device'' will use this value.
526 port number|name
528 Set the port used to access the console. The port may be
529 specified as a number or a name. A name will cause a
530 getservbyname(3) call to look up the port number. The
531 port, portbase, and portinc values are all used to calcu‐
532 late the final port number to connect to. The formula
533 used is finalport = portbase + portinc * port. By using
534 proper values in the formula, you can reference ports on
535 a terminal server by their physical numbering of 0..n or
536 1..n (depending on if you like zero-based or one-based
537 numbering). Warning: you can generate a -1 value with
538 this formula, which will become a very high numbered pos‐
539 itive value (since things are stored unsigned). You must
540 also set the host option as well. Normally, only con‐
541 soles of type ``host'' will use this value, however if
542 the devicesubst, execsubst, or initsubst keywords are
543 used in any console type, this value is used.
544 portbase number
546 Set the base value for the port calculation formula.
547 number must be 0 or greater. The default is zero. See
548 port for the details of the formula.
549 portinc number
551 Set the increment value for the port calculation formula.
552 number must be 0 or greater. The default is one. See
553 port for the details of the formula.
554 protocol telnet|raw
556 Set the protocol used to send and receive data from the
557 console. If raw is used, all data is sent ``as is'',
558 unprotected by any protocol specification. If telnet is
559 used (which is the default), data is encapsulated in the
560 telnet protocol. The striphigh console option still
561 applies when data is read by the server, and if enabled,
562 can impact the encapsulation process.
563 replstring string
565 A generic replacement string that can be used by the
566 devicesubst, execsubst, and initsubst keywords.
567 ro [!]username[,...]|""
569 Define a list of users making up the read-only access
570 list for the console. If username matches a previously
571 defined group name, all members of the previous group are
572 applied to the read-only access list (with access
573 reversed if prefixed with a `!'). If username doesn't
574 match a previously defined group and username begins with
575 `@', the name (minus the `@') is checked against the
576 host's group database. All users found in the group will
577 be granted (or denied, if prefixed with `!') read-only
578 access. If username doesn't match a previous group and
579 doesn't begin with `@', the users will be granted (or
580 denied, if prefixed with `!') read-only access. If the
581 null string (``""'') is used, any users previously
582 defined for the console's read-only list are removed.
583 rw [!]username[,...]|""
585 Define a list of users making up the read-write access
586 list for the console. If username matches a previously
587 defined group name, all members of the previous group are
588 applied to the read-write access list (with access
589 reversed if prefixed with a `!'). If username doesn't
590 match a previously defined group and username begins with
591 `@', the name (minus the `@') is checked against the
592 host's group database. All users found in the group will
593 be granted (or denied, if prefixed with `!') read-write
594 access. If username doesn't match a previous group and
595 doesn't begin with `@', the users will be granted (or
596 denied, if prefixed with `!') read-write access. If the
597 null string (``""'') is used, any users previously
598 defined for the console's read-write list are removed.
599 timestamp [number[m|h|d|l]][a][b]|""
601 Specifies the time between timestamps applied to the con‐
602 sole log file and whether to log read/write connection
603 actions. The timestamps look like ``[-- MARK -- Mon Jan
604 25 14:46:56 1999]''. The `m', `h', and `d' tags specify
605 ``minutes'' (the default), ``hours'', and ``days''. The
606 `l' tag specifies ``lines'' and will cause timestamps of
607 the form ``[Mon Jan 25 14:46:56 PST 1999]'' to be placed
608 every number lines (a newline character signifies a new
609 line). So, ``5h'' specifies every five hours and ``2l''
610 specifies every two lines. An `a' can be specified to
611 add logs of ``attached'', ``detached'', and ``bumped''
612 actions, including the user's name and the host from
613 which the client connection was made. A `b' can be spec‐
614 ified to add logging of break sequences sent to the con‐
615 sole.
616 type device|exec|host|noop|uds
618 Set the type of console. A type of ``device'' should be
619 used for local serial ports (also set the device value).
620 A type of ``exec'' should be used for command invocations
621 (perhaps also set the exec value). A type of ``host''
622 should be used for terminal servers and other TCP socket-
623 based interaction (also set the host and port values). A
624 type of ``noop'' should be used as a placeholder - it
625 does nothing, ignores any logfile value and forces the
626 !nologin option (so you might want to set the motd
627 value). A type of ``uds'' should be used for Unix domain
628 sockets (also set the uds option).
629 uds filename
631 Assign the Unix domain socket filename as the path to the
632 console. Only consoles of type ``uds'' will use this
633 value.
634 udssubst c=t[n]f[,...]|""
636 Perform character substitutions on the uds value. See
637 the devicesubst option for an explanation of the format
638 string. If the null string (``""'') is used, no replace‐
639 ments will be done.
640 group name
642 Define a user group identified as name
643 users [!]username[,...]|""
645 Define a list of users making up the group name. If
646 username matches a previously defined group name, all
647 members of the previous group are applied to the current
648 group (with access reversed if prefixed with a `!'). If
649 username doesn't match a previously defined group and
650 username begins with `@', the name (minus the `@') is
651 checked against the host's group database. All users
652 found in the group will be recorded with (or without, if
653 prefixed with `!') access. If username doesn't match a
654 previous group and doesn't begin with `@', the users will
655 be recorded with (or without, if prefixed with `!')
656 access. If the null string (``""'') is used, any users
657 previously defined for this group are removed.
658
660 Bryan Stansell, conserver.com
661
663 console(1), conserver.passwd(5), conserver(8)
664conserver-8.1.16 2007/04/02 CONSERVER.CF(5)