NAME

MkConf - Superclass for configuration file generation libraries

MODULE

base

SYNOPSIS

  use MkConf;
  require MkConf::hosts;  # to generate "/etc/hosts", for example

  %ok_args = MkConf::hosts->allowed_args;
  # returns something like ( obj => 1, sysarch => 1)

  $conf = MkConf::hosts->new($obj);
  $conf = MkConf::hosts->new(obj => $obj);
  $conf = MkConf::hosts->new(sysarch => $sysarch);

  $retval = $conf->generate;

  $conf->print();
  $conf->print(*STDOUT);

  @filelist = $conf->files;

  $retval = $conf->write();

  $conf->restart;

DESCRIPTION

This package provides a framework and commonly used methods for generating configuration files based on the contents of the CIToolkit database. It should also support non-file based configurations, such as calling external tools to modify kernel settings.

MkConf should not be used directly. Rather, each configuration type should be generated by a subclass.

PUBLIC METHODS

new - Create a new Config File object

Should be called with a parameter hash as:

  $conf = MkConf::dhcpd->new(obj => $obj);

where 'obj' and 'sysarch' are commonly used keys, or with a single Device object as the only parameter:

  $conf = MkConf::dhcpd->new($obj);

allowed_args - Return the arguments new() will accept

Called as:

  %args = MkConf::pxelinux->allowed_args();

Returns a hash, where the keys are all the valid keys for the new() parameter hash. May be useful when trying to decide how to create a MkConf object for a given config file type.

By default, only ``obj'' args are allowed, but some config types may add ``sysarch'', etc.

generate - Determine the file contents

No input parameters.

Process the device (and arguments passed via the new call) to determine the file contents.

Returns ``0'' on successfull completion. On error, returns nonzero string describing the problem.

DEVELOPERS NOTE: generate is NOT IMPLEMENTED in the MkConf superclass, and MUST be overridden by ALL subclasses.

print - Display the file contents

Optional input parameter of file handle to print to. If none is given, prints to STDOUT.

Keeps track of files printed, so as to only print each one ONCE.

print implies generate

files - Return a list of changed files

No input parameters.

Simply returns an array of filenames, with the paths used on the NFS server for the diskless hierarchy.

SOMETIMES files implies generate, but the rest of the time it isn't necessary to generate anyway.

write - Commit the generated config to disk

No input parameters.

Try to make sure currently running on a admin node at the top of the diskless hierarchy (ie. nfs host) and then write the appropriate file or files to disk.

Returns ``0'' on successfull completion. On error, returns nonzero string describing the problem.

Keeps track of files written, so as to only create each one ONCE.

write implies generate

restart - Run a command to make the new config take effect

No input parameters.

By default this is actually a no-op. For restart to know what to do, subclasses must define the _restart_script method, and optionally the _restart_args and _restart_output_ok methods. (Described below.)

restart returns ``0'' on successfull completion. Returns nonzero on error, possibly as a string describing the problem.

Keeps track of restart commands run, so as to only execute each one ONCE.

PRIVATE METHODS

These methods should not be used directly by parent scripts. They exist primarily so that MkConf subclasses can easily override them and change how or where configurations are generated.

_restart_script - The restart command to run: This method must be defined for the public restart() method to have any effect.; Returns a string of the command name, absolute path.
_restart_args - optional args to restart command: Returns a string of arguments to be passed to the command specified by _restart_script.
_restart_output_ok - Check if restart succeeded.: Single input parameter is the command output in string form. Returns 1 to indicate success, 0 to indicate failure.
_init - parse arguments for new(): Parse the arguments passed to new() and set the appropriate MkConf object attributes.
_location_dir - Relative config file path: Specifies the directory where the config file will be created, relative to it's ``root'' directory. For example, for the /etc/hosts config file, _location_dir() == ``etc''.; DEVELOPERS NOTE: _location_dir is NOT IMPLEMENTED in the MkConf superclass, and MUST be overridden by ALL subclasses.
_location_required - Part of config file path that must already exist: Used by write(), to decide when to create the destination directory for a config file, and when to bail out.; Returns a string.; Unless overridden by a subclass, returns the same thing as _location_dir, meaning the whole path must already be present and no subdirs will be created.
_location_keys - How to find a config file's root directory.: Returns a list of keywords that can be used (by _location) to determine a config file's ``root'' directory.; The Keywords are as follows:; self - write into a node-specific directory; image - write into the current node's image dir; leader - apply the config to the node's leader (should be followed by self or image); By default, returns an array with just one entry: ``self''.

NOTES

Need to describe the structure of:

  the "parameter hash" for new()

  $self->{files}