.TH CONMAN.CONF 5 "2022-10-17" "conman-0.3.1" "ConMan: The Console Manager"

.SH NAME
conman.conf \- ConMan daemon configuration file

.SH DESCRIPTION
The \fBconman.conf\fR configuration file is used to specify the consoles
being managed by \fBconmand\fR.
.PP
Comments are introduced by a hash sign (#), and continue until the end
of the line.  Blank lines and white-space are ignored.  Directives are
terminated by a newline, but may span multiple lines by escaping it (i.e.,
immediately preceding the newline with a backslash).  Strings may be
either single-quoted or double-quoted, but they may not contain newlines.
Keywords are case-insensitive.

.SH SERVER DIRECTIVES
These directives begin with the \fBSERVER\fR keyword followed by one of the
following key/value pairs:
.TP
\fBcoredump\fR \fB=\fR (\fBon\fR|\fBoff\fR)
Specifies whether the daemon should generate a core dump file.  This file
will be created in the current working directory (or '/' when running in the
background) unless you also set \fBcoredumpdir\fR.  The default is \fBoff\fR.
.TP
\fBcoredumpdir\fR \fB=\fR "\fIdirectory\fR"
Specifies the directory where the daemon tries to write core dump files.
The default is empty, meaning the current working directory (or '/' when
running in the background) will be used.
.TP
\fBexecpath\fR \fB=\fR "\fIdir1:dir2:dir3...\fR"
Specifies a colon-separated list of directories in which to search for external
process-based console executables that are not defined by an absolute or
relative pathname.  The default is empty.
.TP
\fBkeepalive\fR \fB=\fR (\fBon\fR|\fBoff\fR)
Specifies whether the daemon will use TCP keep-alives for detecting dead
connections.  The default is \fBon\fR.
.TP
\fBlogdir\fR \fB=\fR "\fIdirectory\fR"
Specifies a directory prefix for log files that are not defined via an
absolute pathname.  This affects the \fBserver logfile\fR, \fBglobal log\fR,
and \fBconsole log\fR directives.
.TP
\fBlogfile\fR \fB=\fR "\fIfile\fR[,\fIpriority\fR]"
Specifies the file to which log messages are appended if the daemon is
not running in the foreground.  This string undergoes conversion specifier
expansion (see \fBCONVERSION SPECIFICATIONS\fR) each time the file is opened.
If an absolute pathname is not given, the file's location is relative
to either \fBlogdir\fR (if defined) or the current working directory.
Intermediate directories will be created as needed.  The filename may
optionally be followed by a comma and a minimum priority at which messages
will be logged.  Refer to \fBsyslog.conf(5)\fR for a list of priorities.
The default priority is \fBinfo\fR.  If this keyword is used in conjunction
with the \fBsyslog\fR keyword, messages will be sent to both locations.
.TP
\fBloopback\fR \fB=\fR (\fBon\fR|\fBoff\fR)
Specifies whether the daemon will bind its socket to the loopback address,
thereby only accepting local client connections directed to that address
(127.0.0.1).  The default is \fBon\fR.
.TP
\fBnofile\fR \fB=\fR \fIinteger\fR
Specifies the maximum number of open files for the daemon.  If set to 0, use
the current (soft) limit.  If set to \-1, use the the maximum (hard) limit.
The default is 0.
.TP
\fBpidfile\fR \fB=\fR "\fIfile\fR"
Specifies the file to which the daemon's PID is written.  Intermediate
directories will be created as needed.  The use of a pidfile is recommended
if you want to use the daemon's '\fB\-k\fR', '\fB\-q\fR', or '\fB\-r\fR'
options.
.TP
\fBport\fR \fB=\fR \fIinteger\fR
Specifies the port on which the daemon will listen for client connections.
.TP
\fBresetcmd\fR \fB=\fR "\fIstring\fR"
Specifies a command string to be invoked by a subshell upon receipt
of the client's "reset" escape.  Multiple commands within a string
may be separated with semicolons.  This string undergoes conversion
specifier expansion (see \fBCONVERSION SPECIFICATIONS\fR) and will be
invoked multiple times if the client is connected to multiple consoles.
.TP
\fBsyslog\fR \fB=\fR "\fIfacility\fR"
Specifies that log messages are to be sent to the system logger
(\fBsyslogd\fR) at the given facility.  Refer to \fBsyslog.conf(5)\fR for a
list of facilities.  If this keyword is used in conjunction with the
\fBlogfile\fR keyword, messages will be sent to both locations.
.TP
\fBtcpwrappers\fR \fB=\fR (\fBon\fR|\fBoff\fR)
Specifies whether the daemon will use TCP-Wrappers when accepting client
connections.  Support for this feature must be enabled at compile-time (via
configure's "\-\-with\-tcp\-wrappers" option).  Refer to \fBhosts_access(5)\fR
and \fBhosts_options(5)\fR for more details.  The default is \fBoff\fR.
.TP
\fBtimestamp\fR \fB=\fR \fIinteger\fB (\fBm\fR|\fBh\fR|\fBd\fR)
Specifies the interval between timestamps written to the individual
console log files.  The interval is an integer that may be followed by a
single-character modifier; '\fBm\fR' for minutes (the default), '\fBh\fR'
for hours, or '\fBd\fR' for days.  The default is 0 (i.e., no timestamps).

.SH GLOBAL DIRECTIVES
These directives begin with the \fBGLOBAL\fR keyword followed by one of the
following key/value pairs:
.TP
\fBlog\fR \fB=\fR "\fIfile\fR"
Specifies the default log file to use for each \fBconsole\fR
directive.  This string undergoes conversion specifier expansion (see
\fBCONVERSION SPECIFICATIONS\fR) each time the file is opened; it must
contain either '\fB%N\fR' or '\fB%D\fR'.  If an absolute pathname is
not given, the file's location is relative to either \fBlogdir\fR (if
defined) or the current working directory.  Intermediate directories
will be created as needed.
.TP
\fBlogopts\fR \fB=\fR "(\fBlock\fR|\fBnolock\fR),(\fBsanitize\fR|\fBnosanitize\fR),(\fBtimestamp\fR|\fBnotimestamp\fR)"
Specifies global options for the console log files.  These options can be
overridden on a per-console basis by specifying the \fBCONSOLE\fR \fBlogopts\fR
keyword.  Note that options affecting the output of the console's logfile also
affect the output of the console's log-replay escape.  The valid \fBlogopts\fR
include the following:
.br
.sp
\fBlock\fR or \fBnolock\fR - locked logs are protected with a write lock.
.br
.sp
\fBsanitize\fR or \fBnosanitize\fR - sanitized logs convert non-printable
characters into 7-bit printable characters.
.br
.sp
\fBtimestamp\fR or \fBnotimestamp\fR - timestamped logs prepend each line
of console output with a timestamp in "YYYY\-MM\-DD HH:MM:SS" format.  This
timestamp is generated when the first character following the line break is
output.
.br
.sp
The default is "\fBlock\fR,\fBnosanitize\fR,\fBnotimestamp\fR".
.TP
\fBseropts\fR \fB=\fR "\fIbps\fR[,\fIdatabits\fR[\fIparity\fR[\fIstopbits\fR]]]"
Specifies global options for local serial devices.  These options can be
overridden on a per-console basis by specifying the \fBCONSOLE\fR
\fBseropts\fR keyword.
.br
.sp
\fIbps\fR is an integer specifying the baud rate in bits-per-second.  If
this exact value is not supported by the system, it will be rounded down to
the next supported value.
.br
.sp
\fIdatabits\fR is an integer from 5-8.
.br
.sp
\fIparity\fR is a single case-insensitive character: '\fBn\fR'
for none, '\fBo\fR' for odd, and '\fBe\fR' for even.
.br
.sp
\fIstopbits\fR is an integer from 1-2.
.br
.sp
The default is "9600,8n1" for 9600 bps, 8 data bits, no parity, and 1 stop bit.
.TP
\fBipmiopts\fR \fB=\fR "\fBU\fR:\fIstr\fR,\fBP\fR:\fIstr\fR,\fBK\fR:\fIstr\fR,\fBC\fR:\fIint\fR,\fBL\fR:\fIstr\fR,\fBW\fR:\fIflag\fR"
Specifies global options for IPMI Serial-Over-LAN devices.  These options can
be overridden on a per-console basis by specifying the \fBCONSOLE\fR
\fBIPMIOPTS\fR keyword.  This directive is only available if configured using
the "\-\-with\-freeipmi" option.
.br
.sp
The \fBIPMIOPTS\fR string is parsed into comma-delimited substrings
where each substring is of the form "\fIX\fR:\fIVALUE\fR".  "\fIX\fR" is
a single-character case-insensitive key specifying the option type, and
"\fIVALUE\fR" is its corresponding value.  The IPMI default will be used if
a key is not specified.  The \fB/etc/freeipmi/libipmiconsole.conf\fR file
can contain alternate default values; see \fBlibipmiconsole.conf(5)\fR.
Note that since the \fBIPMIOPTS\fR string is delimited by commas, substring
values cannot contain commas.
.br
.sp
The valid \fBIPMIOPTS\fR substrings include the following (in any order):
.br
.sp
\fBU\fR:\fIusername\fR - a string of at most 16 bytes for the username.
.br
.sp
\fBP\fR:\fIpassword\fR - a string of at most 20 bytes for the password.
.br
.sp
\fBK\fR:\fIK_g\fR - a string of at most 20 bytes for the K_g key.
.br
.sp
\fBC\fR:\fIcipher_suite\fR - an integer for the IPMI cipher suite ID.
Refer to \fBipmiconsole(8)\fR for a list of supported IDs.
.br
.sp
\fBL\fR:\fIprivilege_level\fR - the string "user", "op", or "admin".
.br
.sp
\fBW\fR:\fIworkaround_flag\fR - a string or integer for an IPMI workaround.
The following strings are recognized: "authcap", "integritycheckvalue",
"intel20", "nochecksumcheck", "opensesspriv", "serialalertsdeferred",
"solchannelsupport", "solpacketseq", "solpayloadsize", "solport", "solstatus",
"sun20", "supermicro20", "default", and "none".  Refer to \fBipmiconsole(8)\fR
for more information on these workarounds.  This substring may be repeated
in order to specify multiple workarounds.
.br
.sp
Both the \fIpassword\fR and \fIK_g\fR values can be specified in either ASCII
or hexadecimal; in the latter case, the string should begin with "0x" and
contain at most 40 hexadecimal digits.  A \fIK_g\fR key entered in hexadecimal
may contain embedded null characters, but any characters following the first
null character in the \fIpassword\fR key will be ignored.

.SH CONSOLE DIRECTIVES
This directive defines an individual console being managed by the daemon.
The \fBCONSOLE\fR keyword is followed by one or more of the following
key/value pairs:
.TP
\fBname\fR \fB=\fR "\fIstring\fR"
Specifies the name used by clients to refer to the console.  This keyword is
required.
.TP
\fBdev\fR \fB=\fR "\fIstring\fR"
Specifies the type and location of the device.  This keyword is required.
.br
.sp
A local serial port connection is defined by the pathname of the character
device file.
.br
.sp
A remote terminal server connection using the telnet protocol is defined by
the "\fIhost\fR:\fIport\fR" format (where \fIhost\fR is the remote hostname
or IPv4 address, and \fIport\fR is the remote port number).
.br
.sp
An external process-based connection is defined by the "\fIpath\fR \fIargs\fR"
format (where \fIpath\fR is the pathname to an executable file/script, and
any additional \fIargs\fR are space-delimited); the \fI/usr/share/conman/exec\fR
directory contains scripts for various console types.
.br
.sp
A local Unix domain socket connection is defined by the "unix:\fIpath\fR"
format (where "unix:" is the literal character string prefix and \fIpath\fR
is the pathname of the local socket).
.br
.sp
An IPMI Serial-Over-LAN connection is defined by the "ipmi:\fIhost\fR" format
(where "ipmi:" is the literal string and \fIhost\fR is a hostname or IPv4
address).
.br
.sp
The '\fB%N\fR' character sequence will be replaced by the console name.
.TP
\fBlog\fR \fB=\fR "\fIfile\fR"
Specifies the file where console output is logged.  This string undergoes
conversion specifier expansion (see \fBCONVERSION SPECIFICATIONS\fR) each
time the file is opened.  If an absolute pathname is not given, the file's
location is relative to either \fBlogdir\fR (if defined) or the current
working directory.  Intermediate directories will be created as needed.
An empty log string (i.e., \fBlog\fR="") disables logging, overriding the
\fBglobal log\fR name.
.TP
\fBlogopts\fR \fB=\fR "\fIstring\fR"
This keyword is optional (see \fBGLOBAL DIRECTIVES\fR).
.TP
\fBseropts\fR \fB=\fR "\fIstring\fR"
This keyword is optional (see \fBGLOBAL DIRECTIVES\fR).
.TP
\fBipmiopts\fR \fB=\fR "\fIstring\fR"
This keyword is optional (see \fBGLOBAL DIRECTIVES\fR).

.SH CONVERSION SPECIFICATIONS
A conversion specifier is a two-character sequence beginning with
a '\fB%\fR' character.  The second character in the sequence specifies the
type of conversion to be applied.  The following specifiers are supported:
.TP
\fB%d\fR
The day of the month as a 2-digit number (01-31).
.TP
\fB%D\fR
The console device basename (from the \fBdev\fR string),
with leading directory components removed.
.TP
\fB%g\fR
The ISO 8601 week-based year as a 2-digit number without the century.
See \fB%V\fR for the corresponding ISO 8601 week number.
.TP
\fB%G\fR
The ISO 8601 week-based year as a 4-digit number with the century.
See \fB%V\fR for the corresponding ISO 8601 week number.
.TP
\fB%H\fR
The hour as a 2-digit number (00-23).
.TP
\fB%j\fR
The day of the year as a 3-digit number (001-366).
.TP
\fB%m\fR
The month as a 2-digit number (01-12).
.TP
\fB%M\fR
The minute as a 2-digit number (00-59).
.TP
\fB%N\fR
The console name (from the \fBname\fR string).
.TP
\fB%P\fR
The daemon's process ID.
.TP
\fB%s\fR
The number of seconds since the Epoch (1970-01-01 00:00:00 UTC).
.TP
\fB%S\fR
The second as a 2-digit number (00-60).  (The range is up to 60 to allow for
occasional leap seconds.)
.TP
\fB%u\fR
The day of the week as a number (1-7), with Monday being 1.  See also \fB%w\fR.
.TP
\fB%U\fR
The week number as a 2-digit number (00-53), starting with the first Sunday
of the year as the first day of week 01; previous days in the new year are
in week 00.  See also \fB%V\fR and \fB%W\fR.
.TP
\fB%V\fR
The ISO 8601 week number (01-53).  Weeks start on a Monday.  Week 01 is
the first week where four or more days fall within the new year.  When the
first calendar week has fewer than four days, it is counted as the last
week of the previous year.  See \fB%g\fR or \fB%G\fR for the corresponding
ISO 8601 week-based year.
.TP
\fB%w\fR
The day of the week as a number (0-6), with Sunday being 0.  See also \fB%u\fR.
.TP
\fB%W\fR
The week number as a 2-digit number (00-53), starting with the first Monday
of the year as the first day of week 01; previous days in the new year are
in week 00.  See also \fB%U\fR and \fB%V\fR.
.TP
\fB%y\fR
The year as a 2-digit number without the century.
.TP
\fB%Y\fR
The year as a 4-digit number with the century.
.TP
\fB%%\fR
A single '%' character.
.PP
The console name (\fB%N\fR) and device (\fB%D\fR) specifiers are "sanitized"
in that non-printable characters and the forward-slash (/) character are
replaced with underscores.
.PP
Conversion specifiers within console log filenames are evaluated when the file
is opened; this occurs when \fBconmand\fR first starts and whenever it receives
a \fBSIGHUP\fR.

.SH FILES
.I /etc/conman.conf

.SH AUTHOR
Chris Dunlap <cdunlap@llnl.gov>

.SH COPYRIGHT
Copyright (C) 2007-2022 Lawrence Livermore National Security, LLC.
.br
Copyright (C) 2001-2007 The Regents of the University of California.

.SH LICENSE
ConMan is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.

.SH "SEE ALSO"
.BR conman (1),
.BR conmand (8).
.PP
\fBhttps://dun.github.io/conman/\fR