source: branches/confman-1.9/confman.conf.5.in @ 594

.\" Copyright (c) 2008, Christopher Cowart and contributors
.\" All rights reserved.
.\" 
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions 
.\" are met:
.\" * Redistributions of source code must retain the above copyright 
.\"   notice, this list of conditions and the following disclaimer.
.\" * Redistributions in binary form must reproduce the above copyright 
.\"   notice, this list of conditions and the following disclaimer in the 
.\"   documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 
.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\" 
.\" $Id$
.\"
.Dd May 06, 2009
.Dt CONFMAN.CONF 5
.Os
.Sh NAME
.Nm confman.conf
.Nd confman configuration file
.Sh SYNOPSIS
.Nm @sysconfdir@/confman.conf
.Nm ${HOME}/.confmanrc
.Sh DESCRIPTION
System-wide configurations for
.Xr confman 8 are read from @sysconfdir@/confman.conf. Per-user 
configurations can be added to ${HOME}/.confmanrc.
.Ss FORMAT
Both files are standard 
.Xr bash 1
files that will be sourced by the 
.Xr confman 8 executable. 
In general, you will use simple assignments,
though there is nothing preventing you from adding more creative logic.
.Ss REQUIRED VALUES
These values must be defined:
.Bl -tag -width indent
.It REPO_PROTOCOL
This is the protocol portion of the 
.Xr svn 1 repository's URI. Possible examples include "https://", "file://",
and "svn+ssh://".
.It REPO_HOSTNAME
For all values of REPO_PROTOCOL except "file://", REPO_HOSTNAME must be
set. This value should be the empty string ("") for "file://" URIs.
.It REPO_PATH
This is the path portion of the repository URI.
.El
.Ss CONFSYNC OPTIONS
These options control the behavior of 
.Xr confsync 8 ,
.Xr confexport 8 , and
.Xr confaudit 8 .
.Bl -tag -width indent
.It CONF_EXPORT_FILE
This option is used by 
.Xr confexport 8
as the location to write the tarball used with the
.Xr confsync 8
utility. 
.It CONF_EXPORT_USER
The owner of the 
.Xr confexport 8
export. Defaults to the user running
.Cm confexport ,
but when running as root, the file ownership can be changed with this
configuration option.
.It CONF_EXPORT_GROUP
The group of the
.Xr confexport 8
export. Defaults to wheel.
.It CONF_EXPORT_MODE
The permissions, in octal format, for the 
.Xr confexport 8
export. Defaults to 0640.
.It EXPORT_REPO_PROTOCOL, EXPORT_REPO_HOSTNAME, EXPORT_REPO_PATH
These options are analagous to their counterparts above (without the
EXPORT prefixes). Use these to tell
.Xr confexport 8 to look in an alternate location for the repository when
automated access is provided by a separate mechanism from the interactive
toolset. It can often be useful to have the repository accessible over
"svn+ssh://" in interactive use (e.g., 
.Xr confman 5 ), but to have local "file://" access for
.Xr confexport 5 . These default to unset, in which case the repository
will be found using the REPO_* configurations.
.It CONF_EXPORT_URI
The URI used by
.Xr confsync 8 to find an export generated by
.Xr confexport 8 . There are URI handlers for "file://", "http://", https://",
"ftp://", "sftp://", and "scp://". Port numbers are not handled correctly
in sftp and scp URIs.
.It CONF_EXPORT_WORK_PATH
If specified, this option is used by
.Xr confexport 8 as the location to store a persistent working copy.
.It CONF_EXPORT_STYLE
The export style to be used by
.Xr confexport 8 . Valid options are: repository, module, recipe.
.It CONF_EXPORT_INCREMENTAL
This option optimizes
.Xr confexport 8 performance.  When enabled,
.Xr confexport 8 will only export the changes made to the
.Xr confman 8 repository since the last
.Xr confexport 8 run.  This option has no effect when using repository-style
exports.
.It CONF_EXPORT_INCREMENTAL_LN
This option further optimizes
.Xr confexport 8 performance when using CONF_EXPORT_INCREMENTAL.  When enabled,
.Xr confexport 8 will use
.Xr ln 1 to copy unchanged exports into the new export rather than
.Xr cp 1 .  This option can only be used if temporary files are created
on the same filesystem partition as CONF_EXPORT_FILE.
.It CONF_EXPORT_FILEDB
This option optimizes
.Xr confexport 8 and
.Xr confsync 8 performance.  When enabled,
.Xr confexport 8 will convert repository metadata from Subversion metadata
into a proprietary file-backed metadata format and exclude all Subversion
working-copy-related files from exports.  This significantly reduces the
file size of export tarballs.  This also eliminates the previous requirement
that the version of Subversion be matched between
.Xr confexport 8 and
.Xr confsync 8 machines.
.It CONF_EXPORT_FILEDB_PLUS_SVN
When enabled,
.Xr confexport 8 will also include Subversion metadata in export tarballs.
This allows multiple versions of confsync clients to be supported in parallel
by a single confexport server.  Upgraded confsync clients will automatically
prefer to use the filedb metadata when it is available.  This option has no
effect unless CONF_EXPORT_FILEDB is also enabled.
.It CONF_FETCH_SSH_KEY
This is a private SSH keyfile for use with "sftp://" and "scp://" URIs above.
.It CONF_FETCH_SSH_FLAGS
This options allows you to specify custom parameters to the 
.Xr ssh 1
client for
.Cm confsync .
.It CONF_SYNC_SLEEP
The number of seconds for
.Xr confsync 8
to sleep when running in sleep mode.
.It CONF_AUDIT_SLEEP
The number of seconds for
.Xr confaudit 8
to sleep when running in sleep mode.
.It CONF_SSH_KEY
This option is deprecated and will be removed in a future release. See 
CONF_FETCH_SSH_KEY.
.El
.Ss MISCELLANEOUS OPTIONS
.Bl -tag -width indent
.It WORK_PATH 
Defaults to "${HOME}/src/conf". Can be used to change the location of the
working copy.
.It REPO_REMOTE_USER
Defaults to "", using the underlying 
.Xr svn 1
behavior. Use this to override the username for the repository host.
.It SINGULARITIES
Defaults to "". This is a white-space delimited list of all files that are to
be treated as singularities by
.Xr confman 8 .
.It CONF_GROUP
Defaults to "wheel". Specify which 
.Xr group 5 
should have access to various state files.
.It CONF_WARNING
This is the first line of confman banners for managed files.
.It LOG_TEMPLATE
If defined, the contents of this file will be the default log message visible
in a user's editor for repository commits. This can be useful if you use
hooks to log commits into an external issue tracker and you want to remind
your users to fill in the ticket number.
.It RECIPE_TEMPLATE
When new recipes are created, the contents of this file will be used. The
string 
.Ar __NAME__ 
will be replaced with the name of the recipe. This defaults to 
@sysconfdefaultsdir@/recipe.template. 
.It DEFAULT_MODE_DIRECTORY
Defaults to "0555". When new directories are created in
.Xr confman 8 , they will have these permissions. Note that if the directory
exists on the live filesystem, its real permissions will override this
default value. 
.It DEFAULT_MODE_FILE
Defaults to "0444". When new files are created in
.Xr confman 8 , they will have these permissions. Note that if the file 
exists on the live filesystem, its real permissions will override this 
default value. Regardless of this value or the live file's mode, the write
bits will be masked out, causing the live file to become read-only after
a commit or install operation. This is to discourage users from bypassing
revision control of the file. You can use 
.Cm confman chmod 
on a file to restore the write bits if you need them.
.It DEFAULT_OWNER
Which username should own new files and directories.
.It DEFAULT_GROUP
Which group should own new files and directories.
.It DEFAULT_COMMENT
Which character typically begins comments.
.It DEBUG
Defaults to "false". Set to "true" to enable some verbose messages. Mostly
only useful for developers.
.It NFS_HACK
If your working copy lives on an NFS export with root_squash enabled, the 
super user will be unable to read your working copy with its default 
permissions. Set this to "true" to make your working copy world-readable
when necessary. Note that the word HACK in the name of this option should
be taken to heart, and there are probably better ways of getting around
this challenge.
.It LIVE_ROOT
This option causes 
.Xr confman 8
to use an alternate path to "/" for rolling out files. This is a great way
to set up a sandbox and test things out before managing your live system.
.It UPDATE_RELEVANT_ONLY
Defaults to "false".  Set it to "true" to cause
.Xr confman 8
to update only the files relevant to the host's recipe when running a commit 
or an install.  Additionally, 
.Cm confman update
will update only the recipe-relevant files when given no additional arguments.
.It CONF_COMMIT_REPO_ONLY
Defaults to "false".  Set it to "true" to change the behavior of
.Xr confman 8
"commit" to a repository-only operation, with no regard for the current
machine's recipe or the subsequent rollout to the filesystem.  This is
useful in centrally managed confexport/confsync environments.
.El
.Sh AUTHORS
.An Chris Cowart Aq ccowart@timesinks.net