CONFMAN(8) BSD System Manager's Manual CONFMAN(8)NAMEconfman — configuration file manager
SYNOPSISconfman [-h | help] [-v | version]
confman [flags] command [command_opts] [command_args]
DESCRIPTION
The confman utility is designed to assist the System Administrator in
managing configuration files by leveraging svn(1).
GLOSSARY
repository
The repository refers to a subversion repository in which the
history and current copies of files and their meta data are
stored.
filesystem
The filesystem refers to the system on which confman is being
invoked. The term "live filesystem" is a synonym for filesystem
used for emphasis.
working copy
A confman 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".
module A module is a named set of files and directories that are managed
in confman. 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".
recipe A recipe is an ordered list of modules. Each host is configured
to use exactly one recipe. The contents of each module are "lay‐
ered on" the filesystem in order when committing changes to the
filesystem. Thus copies of files from later modules will over‐
write those from earlier modules.
Blank lines and lines beginning with '#' are ignored in recipes.
Recipe files should list one module per line.
singularity
A singularity is a file that is constructed from components in
each module of the recipe. See the SINGULARITIES subsection of
EXAMPLES for an example of how this works.
state A system can either be in a dirty or clean state. A dirty system
is one that has missed a confsync(8) operation in order to
preserve changes made by installation operations occurring
between the repository's confexport(8) and the invocation of
confsync.
Dirty systems may have out-of-date configuration files. Subse‐
quent confsync or confman commit operations can bring the system
up-to-date.
FLAGS
Global flags
The following flags can be specified before the commands:
-h [command]
Synonymous to the help command below.
-v Causes confman to print the version string and exit.
Log flags
The following flags can be used where log_flags appears in the
usage statements (See COMMANDS):
-m message
The string in the message argument will be used instead
of prompting the user for a log message for commit and
install operations.
-F filename
Like -m, except the log's contents are read from filename
instead of the command line.
COMMANDS
The following commands are supported by confman:
help [command]
With no argument, displays usage statement including supported
commands. Specify a command for more detailed help.
setup The setup command is intended to be run the first time you use
confman. It will check out your working copy. setup takes no
additional arguments.
update [-a] [-r revision_string] [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 confman.conf(5),
the default behavior of Cm update is to update only the files
relevant to the host's recipe. The -a flag will override this
behavior and update the entire working copy.
-r revision_string can be used, as in svn(1), to retrieve an
older copy of the working copy, e.g. 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.
commit [log_flags]
The commit command causes your changes to take effect.
· Firstly, your working copy will be updated to prevent out-of-
date conflicts and the installation of stale files.
· Secondly, your working copy for all of the modules in the
current recipe will be committed back to the repository.
· Once confman 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.
diff [working_copy]
Displays the changes uncommitted changes in working_copy.
audit Shows differences between the working copy and the live filesys‐
tem.
log [working_copy]
Displays the log entires for the file or directory specified by
working_copy.
create module [module ...]
Creates one or more modules for the module arguments provided.
New modules will appear in the top-level-directory of your work‐
ing copy. This change will also be committed to the repository
at the same time.
rmmod module [module ...]
Delete the modules corresponding to the specified module argu‐
ments from your working copy. Follow this action with a revert or
commit operation.
rename oldmodule newmodule
Rename oldmodule to newmodule, updating all singularities and
headers.
import module file ...
Add the specified files or directories from the live filesystem
to your working copy of module.
install [log_flags] file ...
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 high‐
est priority module's copy of the file to ultimately be
installed.
status [working_copy]
Look at the status entries for the file or directory specified by
working_copy.
state This command indicates whether the system is "dirty" or "clean."
recipe {get | list}
recipe create [-R filename] [log_flags] recipe
recipe print [recipe]
recipe edit [log_flags] [recipe]
recipe {remove} [log_flags] recipe
recipe set recipe
create Create a recipe named recipe. Use -R to specify a file
with the recipe's contents to bypass interactive mode.
edit Open recipe in a text editor
get Print the name of the host's current recipe
list List all recipes
print Display the contents of recipe. Defaults to the host's
current recipe.
remove Delete recipe
set Configure this host to use recipe
ls file ...
List files or directories in modified long form, including conf‐
man meta-data such as ownership and permissions.
lsattr file ...
List out the confman attributes of files in the repository. These
attributes can be used to store information such as file permis‐
sions, ownership, comment characters.
chattr attr value file ...
Assign the attribute attr the value value for the file arguments
provided.
rmattr attr file ...
Delete the attribute named attr from the file arguments speci‐
fied.
rm file ...
The remove subcommand removes a file from version control. It
will NOT remove the file from the live filesystem.
cp source destination
Copy source to destination. Arguments must be working copies.
mv source destination
Rename source to destination. Arguments must be working copies.
link [-f] target link_name
The link command creates a symbolic link (See ln(1)) pointing to
the target file or directory. If link_name is a directory, the
link will be created with the same basename(1) as target. The
most common use of repository symlinks is to reconcile path dif‐
ferences between operatings systems. You can create free‐
bsd/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.
mkdir 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.
touch 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.
revert file ...
Restore the working copy files to the state before you began mak‐
ing edits.
chown [-R] owner file ...
Change the owner of working copy files. --R enables recursion.
user:group notation is not yet supported.
chgrp [-R] group file ...
Change the group of working copy files. -R enables recursion.
chmod [-R] mode file ...
Change the permissions for the working copy files. -R enables
recursion. Only octal permissions are supported (e.g., 0640 but
not ug+rx).
chcom string file ...
confman 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.
chln 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 conf‐
man working copy.
checklook 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.
checknew module name
Create a named checkpoint for the specified module. This change
is committed to the repository immediately.
checkclear module name
Clear a named checkpoint from the specified module. This change
is committed to the repository immediately.
rollback 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.
FILES
/usr/local/etc/confman.conf system-wide configurations for confman
~/.confmanrc user-specific configurations for confmanEXAMPLES
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 direc‐
tory.
MODULES
First, we will create a module named core:
confman create core
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.
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:
confman create marvin
RECIPES
Now let's generate marvin's recipe:
confman recipe create marvin
The recipe opens in our text editor. We enter the following contents:
# Configurations common across all machines
core
# Configurations specific to marvin
marvin
And we configure marvin to use the recipe named marvin:
confman recipe set marvin
WORKING WITH FILES
Files have to be imported into confman before you can work with them:
confman import core /etc/resolv.conf
confman import core /etc/periodic.conf
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:
confman commit
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.
SINGULARITIES
Now let's assume that we have configured /etc/rc.conf as a singularity
(See 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:
confman import core /etc/rc.conf
confman import marvin /etc/rc.conf
We will put our globally relevant options in the core portion
(core/etc/rc.conf-core):
sshd_enable="YES"
usbd_enable="YES"
accounting_enable="YES"
And our host-specific configurations in the marvin portion (mar‐
vin/etc/rc.conf-marvin):
apache22_enable="YES"
The resulting "/etc/rc.conf" that will be installed upon an install or
commit operation is the concatenation of the pieces:
sshd_enable="YES"
usbd_enable="YES"
accounting_enable="YES"
apache22_enable="YES"
SEE ALSOconfman.conf(5), sudo(8), svn(1)BUGSconfman 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.
It should be assumed that confman 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 spe‐
cific milestone.
This release of confman 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 confman.
If you are managing your confman.conf(5) file in confman, 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 actu‐
ally install the pieces as a unit. A redesign for how singularity meta‐
data is stored is planned for the next major release.
SECURITY CONSIDERATIONSconfman is intended to be run by a normal user and not by root. When
needed, confman makes calls to sudo(8) to escalate privileges. This only
works if the user has full root access via the sudoers(5) file. This
model is designed to encourage individual accountability in an environ‐
ment with several System Administrators; your own login is recorded in
the subversion logs and recorded by sudo in the logs.
While the typical use of confman 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 subver‐
sion 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.
AUTHORS
Chris Cowart ⟨ccowart@timesinks.net⟩
BSD May 06, 2009 BSD
