ASSUMPTIONS & EXPLANATIONS

As cfm-1 is coded I will attempt to reflect on the assumptions made and explain them here.


******* SECURITY WARNING *******

Cfm is intended for use by a system admin. This implies control and manipulation of password and other security files for a network of hosts. Transfer of such files should NEVER be carried out over an unsecure network without encryption. It is presumed that all unsecured network activity utilizes ssh or some other secure encryption mechanism. If you are not sure that your network activity is secure DO NOT use cfm to access security related files in any fashion.


CONSTRAINTS

  1. Supported filenames can NOT end with these strings:
     *`.cfmsl'  # These are used internally to id symlink info files.
  2. Operating system dirs, ie those in the $os_dirs var of
     CFMROOT/config are expected to be mounted, not mapped. Symlinks
     are therefor captured rather than followed by default. You
     have a degree of control over this with the `cfm -D' option.


PRIVILEGES

Cfm is primarily intended for use by a sysadmin in maintaining a local network of hosts. This is, of course, a task that normally requires superuser privilege. The documentation may presume this. Never-the-less, cfm will support use by ordinary users for managing their own config files. It works for me; I use it to manage my home dir config files. Users may need the sysadmin's assistance in setting up their top level dir ($CFMROOT/home/<user> with 2775 privs owned by the user. Use of user private groups simplifies security needs.


HOST-CENTRIC vs DATABASE-CENTRIC

The cfm cmd tends to be host-centric. Ie, it is intended to maintain the files that live on the executing host. If you want to know about a file on a host use the cfm cmd to rcsdiff it against other versions in the cfmdb.

The cfmdb cmd tends to be database-centric. Ie, it deals with those things pertinent to the structure, organization, and statistics about the cfmdb. If you want to know something about the cfmdb or its rcsfiles use the cfmdb cmd. The cfmdb cmd is also the correct choice for initializing sets of, or individual files in the cfmdb. In this case it should be executed on the host holding working copies of the files since those will be uploaded to the cfmdb.


FILES, SYMLINKS, DIRS, & NON-EXISTANCE

Cfm accomodates regular files and symlinks. When given either the default behavior is to determine the type by examining the file or symlink on the executing host. You can use the -F or -L options to work with non-existant files or symlinks on the executing host.

Dir arguments imply the use of an existing dir in the cfmdb. The content of the cfmdb dir is used to form a list of files and symlinks for cmd action. If the -r option is specified the cmd will recurse thru the list of all files and symlinks in subdirs of this cfmdb dir as well. Note that cfm cmds never create dirs outside of the cfmdb. In general, if a dir doesn't exist in the supported dir tree on the executing host cfm assumes that files in that dir are not supported on that host. A cmdline file or symlink arg requiring use of a non-existant dir on the executing host generates an err msg.


OS DIR TREES, DATACLASSES, & ARCHITECTURES

000423-dam. This section needs reviewed and probably broken out into a separate page. Problems with these topics have been a long standing problem for system admins especially in heterogeneous environments. Techniques here have been successfully used over a period of many years.

Not all dir trees should be included for cfm support. The dir tree holding the cfm database files should not be included in the supported list. NFS mounted dir trees are only supported on the server where they reside.

The mechanisms described here address sysadmin problems that are not normally encountered by ordinary users. They preclude some difficult problems for servers in heterogeneous environments. You might want to understand the issues described below to preclude future trouble if you do or will work in such environments. I discourage you from circumventing the dir tree restriction by simply adding whatever dir trees you want supported to the os_dirs config var.

os proper dirs

  Most os proper dir trees should be supported. The list intended to
  id these is defined in $CFMROOT/CFMROOT/config using the $os_dirs
  variable. A controversial dir NOT included in the os proper dirs is
  the /home dir. This dir is not rqd by the os, it is for those
  bothersome users (sysadmin's view) and should designate a
  dataclass. See below. If a top level dir is in the os_dirs list no
  further validation is done.
/mnt<partition> (mount points) and dataclasses

  On busy systems users and applications frequently tend to outgrow
  the disk resources initially assigned to them. Bringing down the
  system to add or reallocate disk resources is not a viable option in
  many cases.  One method of precluding this is to use dedicated mount
  points for partitions and to forbid use of these mount point dir
  names by users and applications. The users see the 2nd level dir
  uniquely mapped by the sysadmin as a dataclass dir at the top of
  their dir tree. These 2nd level dataclass dirs may be mapped using
  either NIS or symlinks. When the situation requires the sysadmin
  adds or reallocates disk resources, moves data, and manipulates the
  dataclass mapping without disrupting the users or breaking
  applications. Dataclasses also offer an added opportunity to
  classify the filesystem content in support of other sysadmin
  activity, eg backups. Cfm supports use of /mnt<partition> dirs as
  dedicated mount point dirs. If the path starts with /mnt<partition>
  cfm strips the top level dir and uses the remainder of the path for a
  2nd validation check described next.
archs (architectures)

  In a heterogeneous server environment you may need to serve a named
  application in multiple flavors, eg Linux-2, SunOS-5, and IRIX-6.
  One scheme for supporting this uses the 2nd level dir to distinguish
  the architectural needs. This moves the dataclass dir down another
  level. The extra architecture level dir can be taken into account by
  the NIS or symlink mapping on the client usually by a wrapper script.
  The supported 2nd level dirs on a server below a /mnt<partition> mount
  point are identified in $CFMROOT/CFMROOT/config using the $archs
  variable. They are normally os-major_version as indicated above.
dcs (dataclass)

  The 2nd (or 3rd with an arch level) is the dataclass. In an NIS 
  automounter environment this is usually taken from the name of the
  automounter map, eg /home with map auto.home. Supported dataclasses
  are identified in $CFMROOT/CFMROOT/config using the $dcs variable.
  In non-NIS automounter environments it is a good idea to set up
  symlinks just as the the NIS automounter environment would to 
  allow easy transition to that configuration.

All dir trees with names in the os_dirs list are supported without further tesing. Top level /mnt<partition> dirs are discarded and the 2nd level dir is tested. In this case the 2nd level dir must be in either the archs or dcs list. The config file with the dir lists is CFMROOT/config.


SETS in RCSFILES

The cfmdb holds all versions of files of a given name in a single rcsfile versions file. The rcsfile is created by the cfmdb cmd when it initializes the first set that uses the file. For each set it creates a new rcs branch and symbol of the form 1.1.x.1. Subsequent uploads advance the version level on the set's branch and move the tag to it.


SETS, RPMS, & FILES

  Cfm deals with files based on their membership in sets managed using
the cfmdb cmd. To find a host's cfmdb master copy of a file cfm does
the following:
  1. First it navigates the sparsely populated mirror of its own
filesystem rooted under $CFMROOT to find the rcs versions file.  The
$CFMROOT dir tree excludes some legs of the filesystem, eg the 
$CFMROOT leg itself.
  2. Having found the versions file corresponding to the sought after
file and version, it sequences thru its set name list until it finds
the first of its setnames which identifies a version in this versions
file. If this fails cfm tries three additional default set names:
the rpm name that owns the file, all, and conditionally, the $LOGNAME 
associated with the executing account.


ADDING SETS TO CFMDB

  You can enable cfm control of an rpm's config files by executing 
the `cfmdb -ir <rpm>' cmd to initialize the set named for the rpm.
This uploads the initial copy of the rpm's config files to the cfmdb 
rcsfiles. Using the -a option will initialize sets for all rpms.
  To control a config file that does not belong to an rpm you must
first initialize a set to contain it using the `cfmdb -is <set>
<file>' cmd.  The <set> name must then be added to each host's set
list that will share this version of the file. Use the `cfmdb -h
<host> -a <set>' cmd. Note that if you add files to an existing rpm 
set they will NOT be found in the default set. You could add the rpm 
name to the hosts' set lists.  Thus you may see rpm names used in the 
preemptive set name lists if rpm names have been used as set names for 
non-rpm config files.
  Re-executing the `cfmdb --initdb' cmd will resyncronize the 
CFMROOT/allfiles config list by insuring all of files listed have 
been initailized.


REPORTS

Cfm's objective is monitoring and comparing. In theory you can do any and all of this manually or with existing tools. Such theory doesn't take into account the amount of time needed to examine a couple of million files by hand. When nothing is wrong you should be able to determine that at a glance. To support this cfm can be used with cron to generate reports containing the number of files examined on each host with the type and number of errs on each. See the cfmsr cmd.

 one host sample:
 ================  DATABASE relative reports  ============================
 ==    Errs reported here are for missing files or uncaptured changes.
 ## 000331 tcs1       cfmd report:  chkd     811 files,  found      0 errs
 ================  HOST relative reports  ================================
 ==    Errs reported here are for uncontrolled files or uncaptured changes
 ## 000331 tcs1       cfmh report:  chkd     858 files,  found      7 errs
 ================  VERIFY (filtered) reports  ============================
 ==    Errs reported here are for uncontrolled changes to file params.
 ## 000331 tcs1       cfmv report:  chkd   70212 files,  found      0 errs

 From the above: 
  All files known about by the cfmdb are ok.
  There are 7 identified config files (using rpm and the /etc dirtree)
  which are present but not controlled.
  All of the files installed by rpm either match the params in the rpmdb
  or have been identified to cfm as acceptable alterations.


SPACE REQUIRED (SCALE/SIZE)

A cfmdb is assumed to handle about 1000 rcsfiles. Because config files are assumed to be text files and cfm uses rcs to store diffs rather than to add whole new file versions the size of the cfmdb should grow relatively slowly. 15MB is a good estimate for space required. There is nothing preventing the upload of binaries but the size estimate will change abruptly if you add binaries to the cfmdb.


DEFINITIONS

You may encounter these in reading the documentation or the code.

cfm

  One of two definitions from context:
    1. The Configuration File Manager package
    2. The cfm cmd used to rcsdiff and upload/download config files
cfmdb

  One of two definitions from context:
    1. The Configuration File Manager DataBase containing the admin
       files all the rcsfiles for an instance of the cfm pkg.
    2. The cfmdb cmd used to initialize and configure a cfm 
       database instance.
dbf

  A cfmdb rcsfile.
fn

  A filename as seen by the sysadmin on a host.
  Contrast with hfn.
hfn

  The host side filename used to do the rcsdiff against the dbf.
  If the fn is a symlink this will include a .cfmsl suffix.
set

  1. A cfm set is an rcs symbol used to tag a version of a file to be 
     shared by a group hosts. The default set name is the name of the 
     rpm that owns the file.
  2. A cfm set is a collection of files with the further restriction that
     for each file it is that version of the file specifically identified
     by the set name.
  3. A set is a collection of ordered pairs whose first element is an
     rcs versions filename and whose second element is the set name
     that idetifies a specific version within the rcsfile. The filename
     elements are disjoint while the set name elements are identical.


See Also

cfmintro, assumptions, overview, examples, design-history