NAME

SoftConf - Describe and apply Software Configuration changes to a filesystem.


MODULE

distros


SYNOPSIS

  use SoftConf;
  $c = SoftConf->new();
  $conf = SoftConf->new(
                $directive1 => { $target1 => $value1 },
                $directive2 => {
                        $targetA => $valueA,
                        $targetB => $valueB
                }
        );
  @can_do = $conf->directives;
  @can_do = $conf->get;
  @targets = $conf->get($directive);
  $value = $conf->get($directive, $target);
  $conf->set($directive, $target, $value);
  $conf->set($directive, $value); # sets all targets
  $conf->remove($directive);
  $conf->remove($directive, $target);
  $conf->merge($c);
  $conf->base_dir("/cluster/machine/suse-9.1-i586/image");
  $conf->rc_script_dir("/etc/init.d");
  $conf->rc_start_dirs("/etc/rc.d/rc3.d");
  $conf->rc_stop_dirs("/etc/rc.d/rc0.d", "/etc/rc.d/rc6.d");
  $conf->search_dirs("/cluster/lib/Distro/RPM/image", "/");
  $conf->peer_dirs("/cluster/machine/suse-9.1-i586/image",
        "/cluster/machine/suse-9.1-i586/overlay/common");
  $conf->doit();


DESCRIPTION

This package provides the ``SoftConf'' object for use in modifying a filesystem tree. Capabilities include creating and removing files, links and directories, searching for and installing files into place, modifying files according to simple substitution rules, and enabling and disabling services.

SoftConf objects contain a set of directives (described below) which may contain one or more target/value pairs. The directive indicates the task to be done (install, delete, edit, etc.), the target specifies the pathname to act on, and the value indicates how to perform the task (file mode, make a backup, or do nothing at all).

SoftConf is primarily used by the Distro hierarchy.


METHODS

new - create a new SoftConf object
Can pass in a hash of directives, where the keys name the directive and the values are references to target/value pair hashes, like this:
  $c = SoftConf->new(delete => {'/etc/mtab' => 1});

directives - get a list of all available directives
get - retrieve conf information
With no args, return the list of directives in use. With one arg, return the list of targets for the given directive. With two args, return the value for directive ARG1, target ARG2

set - create or modify conf information
With two args, set ALL targets for directive ARG1 to value ARG2. With three args, set directive ARG1, target ARG2 to value ARG3.

remove - clear conf information
With one arg, remove directive ARG1. With two args, remove target ARG2 from directive ARG1.

merge - combine two SoftConf objects
Given a single argument, which is another SoftConf object, combine the two configurations. Settings in the current object (not ARG1) take precidence.

base_dir - set/get path to install into
With one arg, set the absolute path to the filesystem to configure. With no args, just return that path.

rc_script_dir - set/get path to init scripts
rc_start_dirs - set/get paths to dir with startup links
rc_stop_dirs - set/get paths to dir with shutdown links
search_dirs - set/get install source dirs
This defines the list of absolute paths in which to search for files named in the install directive.

To clear the array, pass a single undefined argument.

search_dirs - set/get reference dirs
This defines the list of absolute paths in which to search when looking for services to disable (for example). The first item in the array should usually be the ``image'' path.

To clear the array, pass a single undefined argument.

doit - modify the filesystem
Run through all the currently defined directives (in the order listed below) and perform the specified action.


DIRECTIVES

Any entry with an undefined value will be ignored.

delete - Files or Directories to remove
Targets are absolute path names. Possible values are:
  "1"  - delete the file or directory
  "2"  - move to a backup copy
  "0"  - skip the entry
  "ext" - extension to use for backup copy(???)

If the target is a directory, it will be recursively deleted, even if not empty.

Backup copies will named as the original file or directory with a ``.cit_orig'' extension. Backups will only be created once.

dir - Directories to be created
Targets are absolute path names. Possible values are:
  "1"  - create the directory
  "0"  - skip the entry
  "mode" - create with the given permissions (eg: "1777")

install - Files or Directories to install (copy) into place
Targets are absolute path names. Possible values are:
  "1" - install the file or directory
  "0" - skip the entry
  "path" - copy from the given absolute path on the
           current node instead of from the directories
           listed by the search_dirs() method.

If the target is a directory, it will be copied recursively.

file - Files to be created (touched)
Targets are absolute path names. Possible values are:
  "1"  - create the file
  "0"  - skip the entry
  "mode" - create with the given permissions (eg: "0644")

If the file exists already and the value is a ``mode'', then the permissions will be changed to the specified mode.

link - Symbolic links to be created
Targets are absolute paths of the links to be created.

Possible values are:

  "0" - skip the entry
  "path" - real file to point to

Paths of the values may be absolute or relative.

service - Services for the init process
Targets are service names. Possible values are:
  "1" - service should be enabled
  "0" - skip the entry
  "-1" - service should be disabled, using a
         link to /dev/null.
  "Snn" - service should be enabled, using the
          given startup sequence number.
          shutdown will not be modified.
  "Knn" - service should be enabled, using the
          given shutdown sequence number.
          startup will not be modified.
  "Snn,Knn" - define both startup and shutdown numbers

Symlinks will be created in /etc/init.d, or whatever directory is appropriate for the given distribution.

If startup and shutdown sequence numbers are not given, SoftConf (and the Distro libs) will try to determine what to use. This will be based on links already in place on the current node, and clues in the init scripts themselves. As a fallback, it will be started after, and stopped before, all existing services.

strip - Files from which to remove entire lines.
Targets are absolute path names of the files to be edited.

Possible values are:

  "1" - strip all lines from the file
  "0" - skip this entry, leaving file as is
  "regex" - strip lines matching the regular expression.

Do not include leading and trailing ``/'' (or other quote operators) in your regex. Anchors, embeded control chars like ``(?i)'' are allowed.

append - Files to append lines to.
Targets are absolute path names of the files to be edited.

Possible values are:

  "0" - skip this entry
  "string" - text to add to the end of the file

Files that don't already exist will be created.

edit - Files to modify.
Targets are absolute path names of the files to be edited.

Possible values are:

  "0" - skip this entry
  "1" - modify the file

In the future, this directive may be updated to perform more generic modifications of files. In the meantime, the following simple keyword substitutions are made:

  CIT_HOME_HERE - The top level CIT install directory
        eg. "/cluster" 
  CLUSTER_NAME_HERE - Identifying name for the system
        eg. "ACME"
  DISTRO_DIR_HERE - Directory where image, overlays
                    and individual node dirs can be found
        eg. "/cluster/machine/suse-9.1-i586"


SEE ALSO

Distro

Filesys::Clone

distro_mgr

build_distro