Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  CONFMAN (8)


confman - configuration file manager


     Working With Files
See Also
Security Considerations


confman [-h-| help] [-v-| version] confman [flagscommand[command_opts[command_args]]]


The confman utility is designed to assist the System Administrator in managing configuration files by leveraging svn(1).


  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.
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".
  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.
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. 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 log’s 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 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.

  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.
  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.
  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."
.Brq Cm get | list
recipe create[-R filename[log_flagsrecipe]]
recipe print[recipe]
recipe edit[log_flags[recipe]]
recipe Bro remove Brc[log_flagsrecipe]
recipe set recipe
  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.
  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.
  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.
  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.


  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 we’ll create a module for those files too:

    confman create marvin


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


    # 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. 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.


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 (marvin/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


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 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 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
Search for    or go to Top of page |  Section 8 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.