source: branches/confman-1.9/confman.8.in @ 589

.\" 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 8
.Os
.Sh NAME
.Nm confman
.Nd configuration file manager
.Sh SYNOPSIS
.Nm
.Op Fl h | Cm help
.Op Fl v | Cm version
.Nm
.Oo Ar flags Oc Ar command Oo Ar command_opts Oc Op Ar command_args
.Sh DESCRIPTION
The
.Nm
utility is designed to assist the System Administrator in managing
configuration files by leveraging
.Xr svn 1 .
.Ss GLOSSARY
.Bl -tag -width indent
.It repository
The repository refers to a subversion repository in which the history and
current copies of files and their meta data are stored.
.It filesystem
The filesystem refers to the system on which 
.Nm 
is being invoked. The term "live filesystem" is a synonym for filesystem
used for emphasis.
.It working copy
A
.Nm
working copy is a locally checked-out version of the repository. All changes
are made locally in the working copy before being checked in and rolled out
to the filesystem. The working copy defaults to "~/src/conf".
.It module
A module is a named set of files and directories that are managed in
.Nm .
Modules appear as top-level directories in your working copy. Within each
module, managed files are laid out like the filesystem. For example, if
you have a module named "ntpd" for your ntp servers, your working copy of 
"/etc/ntp.conf" would be "~/src/conf/ntpd/etc/ntp.conf".
.It recipe
A recipe is an ordered list of modules. Each host is configured to use
exactly one recipe. The contents of each module are "layered on" the
filesystem in order when committing changes to the filesystem. Thus copies
of files from later modules will overwrite those from earlier modules. 
.Pp
Blank lines and lines beginning with '#' are ignored in recipes. Recipe
files should list one module per line.
.It singularity
A singularity is a file that is constructed from components in each module
of the recipe. See the
.Sx SINGULARITIES
subsection of
.Sx EXAMPLES
for an example of how this works.
.It state
A system can either be in a dirty or clean state. 
A dirty system is one that has missed a 
.Xr confsync 8 operation in order to preserve changes made by installation
operations occurring between the repository's 
.Xr confexport 8 and the invocation of
.Cm confsync .
.Pp
Dirty systems may have out-of-date configuration files. Subsequent 
.Cm confsync 
or
.Nm
.Cm commit
operations can bring the system up-to-date.
.El
.Ss FLAGS
.Bl -tag -width "FLAGS "
.It Global flags
The following flags can be specified before the commands:
.Bl -tag -width indent
.It Fl h Op Ar command 
Synonymous to the
.Ar help
command below.
.It Fl v
Causes
.Nm
to print the version string and exit.
.El
.It Log flags
The following flags can be used where
.Ar log_flags
appears in the usage statements (See
.Sx COMMANDS ) :
.Bl -tag -width indent
.It Fl m Ar message
The string in the
.Ar message
argument will be used instead of prompting the user for a log message for
.Cm commit
and
.Cm install
operations.
.It Fl F Ar filename
Like
.Fl m ,
except the log's contents are read from
.Ar filename
instead of the command line.
.El
.El
.Ss COMMANDS
The following commands are supported by 
.Nm :
.Bl -tag -width indent
.It Cm help [ Ar command ]
With no argument, displays usage statement including supported commands.
Specify a 
.Ar command 
for more detailed help.
.It Cm setup
The setup command is intended to be run the first time you use 
.Nm .
It will check out your working copy. setup takes no additional arguments.
.It Cm update [ -a ] [ -r Ar revision_string ] [ Ar recipe ]
The update command will update all the modules in your working copy by default,
or, if given a Ar recipe, update all the files relevant to the given recipe.

If the UPDATE_RELEVANT_ONLY flag has been set in 
.Xr confman.conf 5 ,
the default behavior 
of Cm update is to update only the files relevant to the host's recipe.  
The 
.Fl a 
flag will override this behavior and update the entire working copy.

.Fl r Ar revision_string
can be used, as in 
.Xr svn 1 ,
to retrieve an older copy of the working copy, e.g. 
.Cm update -r PREV
to retrieve the previous commit of the working copy.

Note that before any install or commit operation, there is an implicit update
that will cause the latest repository revision to be reflected in your working
copy. This command does not alter the repository or the system.
.It Cm commit Oo log_flags Oc
The commit command causes your changes to take effect. 
.Bl -bullet
.It
Firstly, your working copy will be updated to prevent out-of-date
conflicts and the installation of stale files.
.It
Secondly, your working copy for all of the modules in the current recipe
will be committed back to the repository.
.It
Once 
.Nm
is satisfied that all of your changes have been propagated to
the repository, we will roll-out your working copy to the live filesystem.
Every module appearing in the current recipe will be rolled out in the
order they are listed.
.El
.It Cm diff [ Ar working_copy ]
Displays the changes uncommitted changes in 
.Ar working_copy .
.It Cm audit
Shows differences between the working copy and the live filesystem.
.It Cm log [ Ar working_copy ]
Displays the log entires for the file or directory specified by 
.Ar working_copy .
.It Cm create Ar module [ Ar module Ar ... ]
Creates one or more modules for the
.Ar module
arguments provided.  New modules will appear in the top-level-directory of
your working copy.  This change will also be committed to the repository
at the same time.
.It Cm rmmod Ar module [ Ar module Ar ... ]
Delete the modules corresponding to the specified 
.Ar module 
arguments from your working copy. Follow this action with a revert or
commit operation.
.It Cm rename Ar oldmodule newmodule
Rename 
.Ar oldmodule 
to 
.Ar newmodule , 
updating all singularities and headers.
.It Cm import Ar module Ar 
Add the specified files or directories from the live filesystem to your 
working copy of
.Ar module .
.It Cm install Oo Ar log_flags Oc Ar
Roll out the specified working files and directories to the live filesystem.
Note that recipe ordering will be respected, so using install in a low-priority
module will still cause the highest priority module's copy of the file to
ultimately be installed.
.It Cm status Oo Ar working_copy Oc
Look at the status entries for the file or directory specified by 
.Ar working_copy .
.It Cm state
This command indicates whether the system is "dirty" or "clean."
.It Cm recipe 
.Brq Cm get | list
.It Cm recipe create Oo Fl R Ar filename Oc Oo Ar log_flags Oc Ar recipe
.It Cm recipe print Oo Ar recipe Oc
.It Cm recipe edit Oo Ar log_flags Oc Oo Ar recipe Oc
.It Cm recipe Bro Cm remove Brc Oo Ar log_flags Oc Ar recipe 
.It Cm recipe set Ar recipe
.Bl -tag -width indent
.It Cm create
Create a recipe named 
.Ar recipe. 
Use -R to specify a file with the recipe's contents to bypass interactive 
mode.
.It Cm edit
Open
.Ar recipe
in a text editor
.It Cm get
Print the name of the host's current recipe
.It Cm list
List all recipes
.It Cm print
Display the contents of
.Ar recipe .
Defaults to the host's current recipe.
.It Cm remove
Delete 
.Ar recipe
.It Cm set
Configure this host to use
.Ar recipe
.El
.It Cm ls Ar
List files or directories in modified long form, including confman meta-data
such as ownership and permissions.
.It Cm lsattr Ar
List out the confman attributes of files in the repository. These attributes
can be used to store information such as file permissions, ownership, comment
characters.
.It Cm chattr Ar attr Ar value Ar
Assign the attribute
.Ar attr
the value
.Ar value
for the
.Ar file
arguments provided.
.It Cm rmattr Ar attr Ar
Delete the attribute named
.Ar attr
from the
.Ar file
arguments specified.
.It Cm rm Ar
The remove subcommand removes a file from version control. It will NOT remove 
the file from the live filesystem.
.It Cm cp Ar source destination
Copy 
.Ar source 
to 
.Ar destination . 
Arguments must be working copies.
.It Cm mv Ar source destination
Rename 
.Ar source 
to 
.Ar destination . 
Arguments must be working copies.
.It Cm link [ Fl f ] Ar target link_name 
The link command creates a symbolic link (See 
.Xr ln 1) pointing to the 
.Ar target 
file or directory. If 
.Ar link_name 
is a 
directory, the link will be created with the same 
.Xr basename 1 as 
.Ar target . 
The most common use of repository symlinks is to reconcile path differences
between operatings systems. You can create freebsd/usr/local/etc/sudoers as
a normal file. You can then create the link linux/etc/sudoers to point
to the former file (in the freebsd module). This allows you to have a
single copy of the file in different locations for different modules.
.It Cm mkdir Ar directory
Create a new version-controlled directory in your working copy. Parent
directories do not have to exist; they will be created automatically. This
command only affects your working copy. It does not commit the change.
.It Cm touch Ar file
Create a new version-controlled file in your working copy. Parent directories
must exist. This command only affects your working copy. It does not commit the
change.
.It Cm revert Ar
Restore the working copy files to the state before you began making edits.
.It Cm chown [ Fl R ] Ar owner Ar
Change the owner of working copy files. 
.Fl -R 
enables recursion. user:group notation is not yet supported.
.It Cm chgrp [ Fl R ] Ar group Ar
Change the group of working copy files. -R enables recursion.
.It Cm chmod [ Fl R ] Ar mode Ar
Change the permissions for the working copy files. -R enables recursion. Only
octal permissions are supported (e.g., 0640 but not ug+rx).
.It Cm chcom Ar string Ar
.Nm
stores the string that begins comments for a given file. This will be used
to automatically generate confman headers on file installation in a future
release. For now, this command exists in case confman guesses wrong.
.It Cm chln Ar target link_name
Update the simulated symlink, link_name, to point to target on the live 
filesystem. This works for "simulated" symlinks to files on the live
filesystem, not on actual symlinks within your confman working copy.
.It Cm checklook Ar module
Peek into the checkpoints for the specified module and gives you a listing of
current checkpoints with some other cool info.  This command does not alter the
repository.
.It Cm checknew Ar module name
Create a named checkpoint for the specified module. This change is committed
to the repository immediately.
.It Cm checkclear Ar module name
Clear a named checkpoint from the specified module. This change is committed 
to the repository immediately.
.It Cm rollback Ar module [ checkpoint | YYYYMMDD [ HHMM ] ]
Rolls your working copy of module back to the named checkpoint. You can
optionally roll-back to a specific point in time using a date (and optionally
time) as specified in the usage statement. A commit is made to the filesystem
from the rolled back working copy.
.El
.Sh FILES
.Bl -tag -width @sysconfdir@/confman.conf -compact
.It Pa @sysconfdir@/confman.conf
system-wide configurations for
.Nm
.It Pa ~/.confmanrc
user-specific configurations for
.Nm
.El
.Sh EXAMPLES
This small set of examples should be enough to demonstrate some common use
cases for new users. We assume a default working copy location of 
"~/src/conf", and paths in these examples will be relative to this directory.
.Ss MODULES
First, we will create a module named core:
.Pp
.Dl "confman create core"
.Pp
By convention, we will use the core module first in all of our recipes. This
is the set of files that we generally want to be the same across all of our
machines.
.Pp
There are some files that we are going to want to configure specifically
for our server, marvin, so we'll create a module for those files too:
.Pp
.Dl "confman create marvin"
.Ss RECIPES
Now let's generate marvin's recipe:
.Pp
.Dl "confman recipe create marvin"
.Pp
The recipe opens in our text editor. We enter the following contents:
.Pp
.Dl "# Configurations common across all machines"
.Dl "core"
.Dl "# Configurations specific to marvin"
.Dl "marvin"
.Pp
And we configure marvin to use the recipe named marvin:
.Pp
.Dl "confman recipe set marvin"
.Ss WORKING WITH FILES
Files have to be imported into
.Nm
before you can work with them:
.Pp
.Dl "confman import core /etc/resolv.conf"
.Dl "confman import core /etc/periodic.conf"
.Pp
In order to make a change to /etc/resolv.conf, we will modify the working
copy found in core/etc/resolv.conf. We'll add a domain to our
search path. Next, we'll also make some changes to core/etc/periodic.conf. 
Once we're all set, we will commit our changes:
.Pp
.Dl "confman commit"
.Pp
The new versions of both files are checked into the repository and rolled
out onto the filesystem. Note that these changes are now available in the
repository for other servers to see, but until some action is taken, they
will not be rolled out.
.Ss SINGULARITIES
Now let's assume that we have configured /etc/rc.conf as a singularity 
(See
.Xr confman.conf 5) . We 
want to work with a global portion of the file in core and a host-specific
portion of the file in our marvin module:
.Pp
.Dl "confman import core /etc/rc.conf"
.Dl "confman import marvin /etc/rc.conf"
.Pp
We will put our globally relevant options in the core portion 
(core/etc/rc.conf-core):
.Pp
.Dl sshd_enable="YES"
.Dl usbd_enable="YES"
.Dl accounting_enable="YES"
.Pp
And our host-specific configurations in the marvin portion
(marvin/etc/rc.conf-marvin):
.Pp
.Dl apache22_enable="YES"
.Pp
The resulting "/etc/rc.conf" that will be installed upon an install or commit
operation is the concatenation of the pieces:
.Pp
.Dl sshd_enable="YES"
.Dl usbd_enable="YES"
.Dl accounting_enable="YES"
.Dl apache22_enable="YES"
.Sh SEE ALSO
.Xr confman.conf 5 ,
.Xr sudo 8 ,
.Xr svn 1
.Sh BUGS
.Nm
can be incredibly slow with large repositories. There are plans to cause
working copies to only check out the modules relevant to the current system,
but as yet this hasn't been completed.
.Pp
It should be assumed that
.Nm
will break in weird and mysterious ways if files or recipes have spaces in
their names. While support for all filenames is an eventual goal, it has
not been prioritized into any specific milestone.
.Pp
This release of
.Nm
has a known issue where filesystem symlinks will not commit on an install
operation and require the use of commit. This issue should be resolved
in the next major release of
.Nm .
.Pp
If you are managing your
.Xr confman.conf 5
file in
.Nm ,
the process of changing a file to become a singularity requires two commits;
the first to get the new confman.conf onto the filesystem and the second to
actually install the pieces as a unit. A redesign for how singularity 
metadata is stored is planned for the next major release.
.Sh SECURITY CONSIDERATIONS
.Nm 
is intended to be run by a normal user and not by root. When needed,
.Nm 
makes calls to 
.Xr sudo 8 
to escalate privileges. This only works if the user has full root access via
the 
.Xr sudoers 5
file. This model is designed to encourage individual accountability in an
environment with several System Administrators; your own login is recorded
in the subversion logs and recorded by sudo in the logs.
.Pp
While the typical use of
.Nm
has a shared repository for all of your machines, this may not make sense in
all environments. Unless you are taking out-of-band measures to secure 
various directories in your subversion repository (possibly through the use
of access control hooks), any account making changes to the repository can
effect changes on other machines. It would generally be a good idea to only
share a repository with machines in a similar security tier.
.Sh AUTHORS
.An Chris Cowart Aq ccowart@timesinks.net