|The repository refers to a subversion repository in which the history and current copies of files and their meta data are stored.|
|The filesystem refers to the system on which confman is being invoked. The term "live filesystem" is a synonym for filesystem used for emphasis.|
|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".|
|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".|
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.
Blank lines and lines beginning with # are ignored in recipes. Recipe files should list one module per line.
|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.|
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 repositorys
confexport 8 and the invocation of
Dirty systems may have out-of-date configuration files. Subsequent confsync or confman commit operations can bring the system up-to-date.
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 logs contents are read from filename instead of the command line.
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 hosts 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 filesystem. 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 working 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 arguments 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 Add the specified files or directories from the live filesystem to your working copy of module. install[log_flags] 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 modules 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
.Brq Cm get | list
recipe create[-R filename[log_flagsrecipe]]
recipe Bro remove Brc[log_flagsrecipe]
recipe set recipe
create Create a recipe named recipe. Use -R to specify a file with the recipes contents to bypass interactive mode. edit Open recipe in a text editor get Print the name of the hosts current recipe list List all recipes Display the contents of recipe. Defaults to the hosts current recipe. remove Delete recipe set Configure this host to use recipe
ls List files or directories in modified long form, including confman meta-data such as ownership and permissions. lsattr 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. chattr attr value Assign the attribute attr the value value for the file arguments provided. rmattr attr Delete the attribute named attr from the file arguments specified. rm 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 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. 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 Restore the working copy files to the state before you began making edits. chown[-R -] owner Change the owner of working copy files. --R enables recursion. user:group notation is not yet supported. chgrp[-R -] group Change the group of working copy files. -R enables recursion. chmod[-R -] mode 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 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 confman 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.
/usr/local/etc/confman.conf system-wide configurations for confman ~/.confmanrc user-specific configurations for confman
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.
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 well create a module for those files too:
confman create marvin
Now lets generate marvins recipe:
confman recipe create marvin
The recipe opens in our text editor. We enter the following contents:
# Configurations common across all machines
# Configurations specific to marvin
And we configure marvin to use the recipe named marvin:
confman recipe set marvin
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. Well add a domain to our search path. Next, well also make some changes to core/etc/periodic.conf. Once were all set, we will commit our changes:
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.
Now lets 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):
And our host-specific configurations in the marvin portion (marvin/etc/rc.conf-marvin):
The resulting "/etc/rc.conf" that will be installed upon an install or commit operation is the concatenation of the pieces:
confman.conf(5), sudo(8), svn(1)
confman 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 hasnt 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 specific 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 actually install the pieces as a unit. A redesign for how singularity metadata is stored is planned for the next major release.
confman 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 environment 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 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.
.An Chris Cowart Aq email@example.com