/ 
ZConf-2.0.0
River stage zero No dependents
/ ZConf

NAME

ZConf - A configuration system allowing for either file or LDAP backed storage.

VERSION

Version 2.0.0

SYNOPSIS

This is currently mostly done and is largely being released as I want to get to writing some small desktop apps using it. Still needing implementation is fall through on error, syncing between backends, and listing of configs.

    use ZConf;

	#creates a new instance
    my $zconf = ZConf->new();
    ...

FUNCTIONS

new

my $zconf=ZConf->(\%args);

This initiates the ZConf object. If it can't be initiated, a value of undef is returned. The hash can contain various initization options.

When it is run for the first time, it creates a filesystem only config file.

args hash

file

The default is 'xdf_config_home/zconf.zml', which is generally '~/.config/zconf.zml'.

This is incompatible with the sys option.

sys

This turns system mode on. And sets it to the specified system name.

This is incompatible with the file option.

my $zconf=ZConf->new();
if((!defined($zconf)) || ($zconf->{error})){
    print "Error!\n";
}

chooseSet

This chooses what set should be used using the associated chooser string for the config in question.

This function does fail safely. If a improper configuration is returned by chooser string, it uses the value the default set.

It takes one arguement, which is the configuration it is for.

If the chooser errors, is blank, or is just a newline, the default is returned.

	my $set=$zconf->chooseSet("foo/bar");
    if($zconf->{error}){
        print "Error!\n";
    }

config2dn

This function converts the config name into part of a DN string. IT is largely only for internal use and is used by the LDAP backend.

	my $partialDN = $zconf->config2dn("foo/bar");
    if($zconf->{error}){
        print "Error!\n";
    }

configExists

This function is used for checking if a config exists or not.

It takes one option, which is the configuration to check for.

The returned value is a perl boolean value.

    $zconf->configExists("foo/bar")
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

configExistsFile

This function functions exactly the same as configExists, but for the file backend.

No config name checking is done to verify if it is a legit name or not as that is done in configExists. The same is true for calling errorBlank.

    $zconf->configExistsFile("foo/bar")
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

configExistsLDAP

This function functions exactly the same as configExists, but for the LDAP backend.

No config name checking is done to verify if it is a legit name or not as that is done in configExists. The same is true for calling errorBlank.

    $zconf->configExistsLDAP("foo/bar")
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

configNameCheck

This checks if the name of a config is legit or not. See the section CONFIG NAME for more info on config naming.

my ($error, $errorString) = $zconf->configNameCheck($config);
if(defined($error)){
	warn("zconf configExists:".$error.": ".$errorString);
	$self->{error}=$error;
	$self->{errorString}=$errorString;
	return undef;
};

createConfig

This function is used for creating a new config.

One arguement is needed and that is the config name.

The returned value is a perl boolean.

    $zconf->createConfig("foo/bar")
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	};

createConfigFile

This functions just like createConfig, but is for the file backend. This is not really meant for external use. The config name passed is not checked to see if it is legit or not.

    $zconf->createConfigFile("foo/bar")
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	};

createConfigLDAP

This functions just like createConfig, but is for the LDAP backend. This is not really meant for external use. The config name passed is not checked to see if it is legit or not.

    $zconf->createConfigLDAP("foo/bar")
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	};

defaultSetExists

This checks to if the default set for a config exists. It takes one arguement, which is the name of the config. The returned value is a Perl boolean.

my $returned=$zconf->defaultSetExists('someConfig');
if($zconf->{error}){
    print "Error!\n";
}
if($returned){
    print "It exists.\n";
}

delConfig

This removes a config. Any sub configs will need to removes first. If any are present, this function will error.

#removes 'foo/bar'
$zconf->delConfig('foo/bar');
if(defined($zconf->{error})){
    print 'error!';
}

delConfigFile

This removes a config. Any sub configs will need to removes first. If any are present, this function will error.

#removes 'foo/bar'
$zconf->delConfig('foo/bar');
if(defined($zconf->{error})){
    print 'error!';
}

delConfigLDAP

This removes a config. Any sub configs will need to removes first. If any are present, this function will error.

#removes 'foo/bar'
$zconf->delConfig('foo/bar');
if($zconf->{error}){
    print 'error!';
}

delSet

This deletes a specified set.

Two arguements are required. The first one is the name of the config and the and the second is the name of the set.

$zconf->delSetFile("foo/bar", "someset");
if($zconf->{error}){
    print "delSet failed\n";
}

delSetFile

This deletes a specified set, for the filesystem backend.

Two arguements are required. The first one is the name of the config and the and the second is the name of the set.

$zconf->delSetFile("foo/bar", "someset");
if($zconf->{error}){
    print "delSet failed\n";
}

delSetLDAP

This deletes a specified set, for the LDAP backend.

Two arguements are required. The first one is the name of the config and the and the second is the name of the set.

$zconf->delSetLDAP("foo/bar", "someset");
if($zconf->{error}){
    print "delSet failed\n";
}

errorBlank

This blanks the error storage and is only meant for internal usage.

It does the following.

$zconf->{error}=undef;
$zconf->{errorString}="";

getAutoupdate

This gets if a config should be automatically updated or not.

One arguement is required and it is the config. If this is undefined or a matching one is not found, the global is used.

The return value is a boolean.

#fetches the global
my $autoupdate=$zconf->getAutoupdate();

#fetches it for 'some/config'
my $autoupdate=$zconf->getAutoupdate('some/config');

getAvailableSets

This gets the available sets for a config.

The only arguement is the name of the configuration in question.

my @sets = $zconf->getAvailableSets("foo/bar");
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

getAvailableSetsFile

This is exactly the same as getAvailableSets, but for the file back end. For the most part it is not intended to be called directly.

my @sets = $zconf->getAvailableSetsFile("foo/bar");
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

getAvailableSetsLDAP

This is exactly the same as getAvailableSets, but for the file back end. For the most part it is not intended to be called directly.

my @sets = $zconf->getAvailableSetsLDAP("foo/bar");
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

getDefault

This gets the default set currently being used if one is not choosen.

my $defaultSet = $zml->getDefault();

getComments

This gets a list of variables that have comments.

my @keys = $zconf->getComments("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

getConfigRevision

This fetches the revision for the speified config.

my $revision=$zconf->getConfigRevision('some/config');
if($zconf->{error}){
    print "Error!\n";
}

getConfigRevisionFile

This fetches the revision for the speified config using the file backend.

A return of undef means that the config has no sets created for it yet or it has not been read yet by 2.0.0 or newer.

my $revision=$zconf->getConfigRevision('some/config');
if($zconf->{error}){
    print "Error!\n";
}
if(!defined($revision)){
    print "This config has had no sets added since being created or is from a old version of ZConf.\n";
}

getConfigRevisionLDAP

This fetches the revision for the speified config using the LDAP backend.

A return of undef means that the config has no sets created for it yet or it has not been read yet by 2.0.0 or newer.

my $revision=$zconf->getConfigRevision('some/config');
if($zconf->{error}){
    print "Error!\n";
}
if(!defined($revision)){
    print "This config has had no sets added since being created or is from a old version of ZConf.\n";
}

getCtime

This fetches the mtime for a variable.

Two arguements are required. The first is the config and the second is the variable.

The returned value is UNIX time value for when it was last changed. If it is undef, it means the variable has not been changed since ZConf 2.0.0 came out.

my $time=$zconf->getMtime('some/config', 'some/var');
if($zconf->{error}){
    print "Error!\n";
}
if(defined($time)){
    print "variable modified at".$time." seconds past 1970-01-01.\n";
}else{
    print "variable not modifined since ZConf 2.0.0 came out.\n";
}

getKeys

This gets gets the keys for a loaded config.

my @keys = $zconf->getKeys("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

getLoadedConfigRevision

This gets the revision of the specified config, if it is loaded.

my $rev=$zconf->getLoadedConfigRevision;
if($zconf->{error}){
    print "Error!\n";
}

getLoadedConfigs

This gets gets the keys for a loaded config.

my @configs = $zconf->getLoadedConfigs("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

getMetas

This gets a list of variables that have meta variables.

my @keys = $zconf->getComments("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

getMtime

This fetches the mtime for a variable.

Two arguements are required. The first is the config and the second is the variable.

The returned value is UNIX time value for when it was last changed. If it is undef, it means the variable has not been changed since ZConf 2.0.0 came out.

my $time=$zconf->getMtime('some/config', 'some/var');
if($zconf->{error}){
    print "Error!\n";
}
if(defined($time)){
    print "variable modified at".$time." seconds past 1970-01-01.\n";
}else{
    print "variable not modifined since ZConf 2.0.0 came out.\n";
}

getOverrideChooser

This will get the current override chooser for a config.

If no chooser is specified for the loaded config

One arguement is required it is the name of the config.

This method is basically a wrapper around regexMetaGet.

my $orchooser=$zconf->getOverrideChooser($config);
if($zconf->{error}){
    print "Error!\n";
}

getSet

This gets the set for a loaded config.

my $set = $zconf->getSet("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

getSubConfigs

This gets any sub configs for a config. "" can be used to get a list of configs under the root.

One arguement is accepted and that is the config to look under.

#lets assume 'foo/bar' exists, this would return
my @subConfigs=$zconf->getSubConfigs("foo");
if($zconf->{error}){
    print "There was some error.\n";
}

getSubConfigsFile

This gets any sub configs for a config. "" can be used to get a list of configs under the root.

One arguement is accepted and that is the config to look under.

#lets assume 'foo/bar' exists, this would return
my @subConfigs=$zconf->getSubConfigs("foo");
if($zconf->{error}){
    print "There was some error.\n";
}

getSubConfigsLDAP

This gets any sub configs for a config. "" can be used to get a list of configs under the root.

One arguement is accepted and that is the config to look under.

#lets assume 'foo/bar' exists, this would return
my @subConfigs=$zconf->getSubConfigs("foo");
if($zconf->{error}){
    print "There was some error.\n";
}

isLoadedConfigLocked

This returns if the loaded config is locked or not.

Only one arguement is taken and that is the name of the config.

my $returned=$zconf->isLoadedConfigLocked('some/config');
if($zconf->{error}){
    print "Error!\n";
}

isConfigLocked

This checks if a config is locked or not.

One arguement is required and it is the name of the config.

The returned value is a boolean value.

my $locked=$zconf->isConfigLocked('some/config');
if($zconf->{error}){
    print "Error!\n";
}
if($locked){
    print "The config is locked\n";
}

isConfigLockedFile

This checks if a config is locked or not for the file backend.

One arguement is required and it is the name of the config.

The returned value is a boolean value.

my $locked=$zconf->isConfigLockedFile('some/config');
if($zconf->{error}){
    print "Error!\n";
}
if($locked){
    print "The config is locked\n";
}

isConfigLockedLDAP

This checks if a config is locked or not for the LDAP backend.

One arguement is required and it is the name of the config.

The returned value is a boolean value.

my $locked=$zconf->isConfigLockedLDAP('some/config');
if($zconf->{error}){
    print "Error!\n";
}
if($locked){
    print "The config is locked\n";
}

LDAPconnect

This generates a Net::LDAP object based on the LDAP backend.

my $ldap=$zconf->LDAPconnect();
if($zconf->{error}){
    print "error!";
}

LDAPgetConfMessage

Gets a Net::LDAP::Message object that was created doing a search for the config with the scope set to base.

#gets it for 'foo/bar'
my $mesg=$zconf->LDAPgetConfMessage('foo/bar');
#gets it using $ldap for the connection
my $mesg=$zconf->LDAPgetConfMessage('foo/bar', $ldap);
if($zconf->{error}){
    print "error!";
}

LDAPgetConfMessageOne

Gets a Net::LDAP::Message object that was created doing a search for the config with the scope set to one.

#gets it for 'foo/bar'
my $mesg=$zconf->LDAPgetConfMessageOne('foo/bar');
#gets it using $ldap for the connection
my $mesg=$zconf->LDAPgetConfMessageOne('foo/bar', $ldap);
if($zconf->{error}){
    print "error!";
}

LDAPgetConfEntry

Gets a Net::LDAP::Message object that was created doing a search for the config with the scope set to base.

It returns undef if it is not found.

#gets it for 'foo/bar'
my $entry=$zconf->LDAPgetConfEntry('foo/bar');
#gets it using $ldap for the connection
my $entry=$zconf->LDAPgetConfEntry('foo/bar', $ldap);
if($zconf->{error}){
    print "error!";
}

override

This runs the overrides for a config.

This overrides various variables in the config by running the chooser stored in '#!zconf=override/chooser'. If it fails, the profile 'default' is used.

Once a profile name has been picked, everything under '#!zconf=override/profiles/<profile>/' has /^override\/profiles\/<profile>\// removed and it is set as a regular variable.

One arguement is taken and it is a hash.

args hash

config

This is the config to operate on.

profile

If this is not specified, the chooser stored in the meta is '#!zconf=override/chooser'.

read

This reads a config. The only accepted option is the config name.

It takes one arguement, which is a hash.

hash args

config

The config to load.

override

This specifies if override should be ran not.

If this is not specified, it defaults to 1, true.

set

The set for that config to load.

    $zconf->read({config=>"foo/bar"})
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

readFile

readFile functions just like read, but is mainly intended for internal use only. This reads the config from the file backend.

hash args

config

The config to load.

override

This specifies if override should be ran not.

If this is not specified, it defaults to 1, true.

set

The set for that config to load.

    $zconf->readFile({config=>"foo/bar"})
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

readLDAP

readFile functions just like read, but is mainly intended for internal use only. This reads the config from the LDAP backend.

hash args

config

The config to load.

override

This specifies if override should be ran not.

If this is not specified, it defaults to 1, true.

set

The set for that config to load.

    $zconf->readLDAP({config=>"foo/bar"})
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

readChooser

This reads the chooser for a config. If no chooser is defined "" is returned.

The name of the config is the only required arguement.

my $chooser = $zconf->readChooser("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

readChooserFile

This functions just like readChooser, but functions on the file backend and only really intended for internal use.

my $chooser = $zconf->readChooserFile("foo/bar");
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

readChooserLDAP

This functions just like readChooser, but functions on the LDAP backend and only really intended for internal use.

my $chooser = $zconf->readChooserLDAP("foo/bar");
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

regexCommentDel

This searches through the comments for variables in a loaded config for any that match the supplied regex and removes them.

One arguement is taken and it is a hash.

A hash of hash containing copies of the deleted variables are returned.

args hash

config

This is the config search.

varRegex

The variable to search for matching comment names.

commentRegex

The regex use for matching comment names.

    my %deleted=$zconf->regexCommentDel({
                                         config=>"foo/bar",
                                         varRegex=>"^some/var$",
                                         commentRegex=>"^monkey\/";
                                        });
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

regexCommentGet

This searches through the comments for variables in a loaded config for any that match the supplied regex and returns them.

One arguement is taken and it is a hash.

A hash of hash containing copies of the deleted variables are returned.

args hash

config

This is the config search.

varRegex

The variable to search for matching comment names.

commentRegex

The regex use for matching comment names.

    my %deleted=$zconf->regexCommentGet({
                                         config=>"foo/bar",
                                         varRegex=>"^some/var$",
                                         commentRegex=>"^monkey\/";
                                        });
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

regexMetaDel

This searches through the meta variables in a loaded config for any that match the supplied regex and removes them.

One arguement is taken and it is a hash.

A hash of hash containing copies of the deleted variables are returned.

args hash

config

This is the config search.

varRegex

The variable to search for matching comment names.

metaRegex

The regex use for matching meta variables.

    my %deleted=$zconf->regexMetaDel({
                                      config=>"foo/bar",
                                      varRegex=>"^some/var$",
                                      metaRegex=>"^monkey\/";
                                     });
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

regexMetaGet

This searches through the meta variables in a loaded config for any that match the supplied regex and removes them.

One arguement is taken and it is a hash.

A hash of hash containing copies of the deleted variables are returned.

args hash

config

This is the config search.

varRegex

The variable to search for matching comment names.

metaRegex

The regex use for matching meta variables.

    my %deleted=$zconf->regexMetaGet({
                                      config=>"foo/bar",
                                      varRegex=>"^some/var$",
                                      metaRegex=>"^monkey\/";
                                     });
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

regexVarDel

This searches through the variables in a loaded config for any that match the supplied regex and removes them.

Two arguements are required. The first is the config to search. The second is the regular expression to use.

#removes any variable starting with the monkey
my @deleted = $zconf->regexVarDel("foo/bar", "^monkey");
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

regexVarGet

This searches through the variables in a loaded config for any that match the supplied regex and returns them in a hash.

Two arguements are required. The first is the config to search. The second is the regular expression to use.

#returns any variable begining with monkey
my %vars = $zconf->regexVarGet("foo/bar", "^monkey");
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

regexVarSearch

This searches through the variables in a loaded config for any that match the supplied regex and returns a array of matches.

Two arguements are required. The first is the config to search. The second is the regular expression to use.

#removes any variable starting with the monkey
my @matched = $zconf->regexVarSearch("foo/bar", "^monkey")
if($zconf->{error})){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

reread

This rereads the specified config file. This requires it to be already loaded.

$zconf->reread('some/config');
if($zconf->{error}){
    print "Error!\n";
}

setAutoupdate

This sets if a value for autoupdate.

It takes two optional arguements. The first is a name for a config and second is a boolean value.

If a config name is not specified, it sets the global value for it.

#set the global auto update value to false
$zconf->setAutoupdate(undef, '0');

#sets it to true for 'some/config'
$zconf->setAutoupdate('some/config', '1');

setComment

This sets a comment variable in a loaded config.

Four arguements are required. The first is the name of the config. The second is the name of the variable. The third is the comment variable. The fourth is the value.

$zconf->setComment("foo/bar" , "somethingVar", "someComment", "eat more weazel\n\nor something"
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

setDefault

This sets the default set to use if one is not specified or choosen.

my $returned = $zconf->setDefault("something")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

setExists

This checks if the specified set exists.

Two arguements are required. The first arguement is the name of the config. The second arguement is the name of the set. If no set is specified, the default set is used. This is done by calling 'defaultSetExists'.

my $return=$zconf->setExists("foo/bar", "fubar");
if($zconf->{error}){
    print "Error!\n";
}else{
    if($return){
        print "It exists.\n";
    }
}

setLockConfig

This unlocks or logs a config.

Two arguements are taken. The first is a the config name, required, and the second is if it should be locked or unlocked

#lock 'some/config'
$zconf->setLockConfig('some/config', 1);
if($zconf->{error}){
    print "Error!\n";
}

#unlock 'some/config'
$zconf->setLockConfig('some/config', 0);
if($zconf->{error}){
    print "Error!\n";
}

#unlock 'some/config'
$zconf->setLockConfig('some/config');
if($zconf->{error}){
    print "Error!\n";
}

setLockConfigFile

This unlocks or logs a config for the file backend.

Two arguements are taken. The first is a the config name, required, and the second is if it should be locked or unlocked

#lock 'some/config'
$zconf->setLockConfigFile('some/config', 1);
if($zconf->{error}){
    print "Error!\n";
}

#unlock 'some/config'
$zconf->setLockConfigFile('some/config', 0);
if($zconf->{error}){
    print "Error!\n";
}

#unlock 'some/config'
$zconf->setLockConfigFile('some/config');
if($zconf->{error}){
    print "Error!\n";
}

setLockConfigLDAP

This unlocks or logs a config for the LDAP backend.

Two arguements are taken. The first is a the config name, required, and the second is if it should be locked or unlocked

#lock 'some/config'
$zconf->setLockConfigLDAP('some/config', 1);
if($zconf->{error}){
    print "Error!\n";
}

#unlock 'some/config'
$zconf->setLockConfigLDAP('some/config', 0);
if($zconf->{error}){
    print "Error!\n";
}

#unlock 'some/config'
$zconf->setLockConfigLDAP('some/config');
if($zconf->{error}){
    print "Error!\n";
}

setMeta

This sets a meta variable in a loaded config.

Four arguements are required. The first is the name of the config. The second is the name of the variable. The third is the meta variable. The fourth is the value.

$zconf->setMeta("foo/bar" , "somethingVar", "someComment", "eat more weazel\n\nor something"
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

setNameLegit

This checks if a setname is legit.

There is one required arguement, which is the set name.

The returned value is a perl boolean value.

my $set="something";
if(!$zconf->setNameLegit($set)){
	print "'".$set."' is not a legit set name.\n";
}

setOverrideChooser

This will get the current override chooser for a config.

If no chooser is specified for the loaded config

Two arguements are required. The first is the config and th e second is the chooser string.

This method is basically a wrapper around setMeta.

$zconf->setOverrideChooser($config, $chooser);
if($zconf->{error}){
    print "Error!\n";
}

setVar

This sets a variable in a loaded config.

Three arguements are required. The first is the name of the config. The second is the name of the variable. The third is the value.

$zconf->setVar("foo/bar" , "something", "eat more weazel\n\nor something"
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

unloadConfig

Unloads a specified configuration. The only required value is the set name. The return value is a Perl boolean value.

if(!$zconf->unloadConfig($config)){
    print "error: ".$zconf->{error}."\n";
}

updatable

This checks if the loaded config on disk has a different revision ID than the saved one.

The return value is a boolean value. A value of true indicates the config has been changed on the backend.

my $updatable=$zconf->updatable('some/config');
if($zconf->{error}){
    print "Error!";
}

updateIfNeeded

If a loaded config is updatable, reread it.

The returned value is a boolean value indicating if it was updated or not. A value of true indicates it was.

args hash

autocheck

This tells it to check getAutoupdate. If it returns false, it will return.

clearerror

If $zconf->{error} is set, clear it. This is primarily meant for being used internally.

config

This config to check.

This is required.

my $updated=$zconf->updateIfNeeded({config=>'some/config'});
if($zconf->{error}){
    print "Error!\n";
}
if($updated){
    print "Updated!\n";
}

varNameCheck

This checks if a there if the specified variable name is a legit one or not.

	my ($error, $errorString) = $zconf->varNameCheck($config);
	if(defined($error)){
        print $error.': '.$errorString."\n";
	}

writeChooser

This writes a string into the chooser for a config.

There are two required arguements. The first is the config name. The second is chooser string.

No error checking is done currently on the chooser string.

Setting this to '' or "\n" will disable the chooser fuction and the default will be used when chooseSet is called.

my $returned = $zconf->writeChooser("foo/bar", $chooserString)
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

writeChooserFile

This function is a internal function and largely meant to only be called writeChooser, which it functions the same as. It works on the file backend.

$zconf->writeChooserFile("foo/bar", $chooserString)
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
}

writeChooserLDAP

This function is a internal function and largely meant to only be called writeChooser, which it functions the same as. It works on the LDAP backend.

    $zconf->writeChooserLDAP("foo/bar", $chooserString)
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

writeSetFromHash

This takes a hash and writes it to a config. It takes two arguements, both of which are hashes.

The first hash contains

The second hash is the hash to be written to the config.

args hash

config

The config to write it to.

This is required.

set

This is the set name to use.

If not defined, the one will be choosen.

revision

This is the revision string to use.

This is primarily meant for internal usage and is suggested that you don't touch this unless you really know what you are doing.

    $zconf->writeSetFromHash({config=>"foo/bar"}, \%hash)
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

writeSetFromHashFile

This takes a hash and writes it to a config for the file backend. It takes two arguements, both of which are hashes.

The first hash contains

The second hash is the hash to be written to the config.

args hash

config

The config to write it to.

This is required.

set

This is the set name to use.

If not defined, the one will be choosen.

revision

This is the revision string to use.

This is primarily meant for internal usage and is suggested that you don't touch this unless you really know what you are doing.

    $zconf->writeSetFromHashFile({config=>"foo/bar"}, \%hash)
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

writeSetFromHashLDAP

This takes a hash and writes it to a config for the file backend. It takes two arguements, both of which are hashes.

The first hash contains

The second hash is the hash to be written to the config.

args hash

config

The config to write it to.

This is required.

set

This is the set name to use.

If not defined, the one will be choosen.

revision

This is the revision string to use.

This is primarily meant for internal usage and is suggested that you don't touch this unless you really know what you are doing.

    $zconf->writeSetFromHashLDAP({config=>"foo/bar"}, \%hash)
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

writeSetFromLoadedConfig

This function writes a loaded config to a to a set.

One arguement is required.

args hash

config

The config to write it to.

This is required.

set

This is the set name to use.

If not defined, the one will be choosen.

revision

This is the revision string to use.

This is primarily meant for internal usage and is suggested that you don't touch this unless you really know what you are doing.

    $zconf->writeSetFromLoadedConfig({config=>"foo/bar"});
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

writeSetFromLoadedConfigFile

This function writes a loaded config to a to a set, for the file backend.

One arguement is required.

args hash

config

The config to write it to.

This is required.

set

This is the set name to use.

If not defined, the one will be choosen.

revision

This is the revision string to use.

This is primarily meant for internal usage and is suggested that you don't touch this unless you really know what you are doing.

    $zconf->writeSetFromLoadedConfigFile({config=>"foo/bar"}, %hash)
	if($zconf->{error}){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

writeSetFromLoadedConfigLDAP

This function writes a loaded config to a to a set, for the LDAP backend.

One arguement is required.

args hash

config

The config to write it to.

This is required.

set

This is the set name to use.

If not defined, the one will be choosen.

revision

This is the revision string to use.

This is primarily meant for internal usage and is suggested that you don't touch this unless you really know what you are doing.

    $zconf->writeSetFromLoadedConfigLDAP({config=>"foo/bar"});
	if(defined($zconf->{error})){
		print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
	}

CONFIG NAME

Any configuration name is legit as long as it does not match any of the following.

undef
/./
/\/\./
/\.\.\//
/\/\//
/\.\.\//
/\/\.\./
/^\.\//
/\/$/
/^\//
/\n/

SET NAME

Any set name is legit as long as it does not match any of the following.

undef
/\//
/^\./
/^ /
/ $/
/\.\./

VARIABLE NAME

Any variable name is legit as long it does not match any of the following. This also covers comments and meta variables.

/,/
/\/\./
/\/\//
\.\.\//
/\/\.\./
/^\.\//
/\/$/	
/^\//
/\n/
/=/

ERROR CODES

Since version '0.6.0' any time '$zconf->{error}' is true, there is an error.

1

config name contains ,

2

config name contains /.

3

config name contains //

4

config name contains ../

5

config name contains /..

6

config name contains ^./

7

config name ends in /

8

config name starts with /

9

could not sync to file

10

config name contains a \n

11

LDAP entry already exists

12

config does not exist

13

Expected LDAP DN not found

14

file/dir does not exist

15

file/dir open failed

16

file/dir creation failed

17

file write failed

18

No variable name specified.

19

config key starts with a ' '

20

LDAP entry has no sets

21

set not found for config

22

LDAPmakepathSimple failed

23

skilling variable as it is not a legit name

24

set is not defined

25

Config is undefined.

26

Config not loaded.

27

Set name is not a legit name.

28

ZML->parse error.

29

Could not unlink the unlink the set.

30

The sets exist for the specified config.

31

Did not find a matching set.

32

Unable to choose a set.

33

Unable to remove the config as it has sub configs.

34

LDAP connection error

35

Can't use system mode and file together.

36

Could not create '/var/db/zconf'. This is a permanent error.

37

Could not create '/var/db/zconf/<sys name>'. This is a permanent error.

38

Sys name matched /\//.

39

Sys name matched /\./.

40

No chooser string specified.

41

No comment specified.

42

No meta specified.

43

Failed to open the revision file for the set.

44

Failed to open or unlink lock file.

45

Config is locked.

ERROR CHECKING

This can be done by checking $zconf->{error} to see if it is defined. If it is defined, The number it contains is the corresponding error code. A description of the error can also be found in $zconf->{errorString}, which is set to "" when there is no error.

zconf.zml

The default is 'xdf_config_home/zconf.zml', which is generally '~/.config/zconf.zml'. See perldoc ZML for more information on the file format. The keys are listed below.

General Keys

backend

This is the backend to use for storage. Current values of 'file' and 'ldap' are supported.

backendChooser

This is a Chooser string that chooses what backend should be used.

defaultChooser

This is a chooser string that chooses what the name of the default to use should be.

fileonly

This is a boolean value. If it is set to 1, only the file backend is used.

readfallthrough

If this is set, if any of the functions below error when trying the LDAP backend, it will fall through to the file backend.

configExists
getAvailableSets
getSubConfigs
read
readChooser

LDAP Backend Keys

LDAPprofileChooser

This is a chooser string that chooses what LDAP profile to use. If this is not present, 'default' will be used for the profile.

ldap/<profile>/bind

This is the DN to bind to the server as.

ldap/<profile>/cafile

When verifying the server's certificate, either set capath to the pathname of the directory containing CA certificates, or set cafile to the filename containing the certificate of the CA who signed the server's certificate. These certificates must all be in PEM format.

ldap/<profile>/capath

The directory in 'capath' must contain certificates named using the hash value of the certificates' subject names. To generate these names, use OpenSSL like this in Unix:

ln -s cacert.pem `openssl x509 -hash -noout < cacert.pem`.0

(assuming that the certificate of the CA is in cacert.pem.)

ldap/<profile>/checkcrl

If capath has been configured, then it will also be searched for certificate revocation lists (CRLs) when verifying the server's certificate. The CRLs' names must follow the form hash.rnum where hash is the hash over the issuer's DN and num is a number starting with 0.

ldap/<profile>/clientcert

This client cert to use.

ldap/<profile>/clientkey

The client key to use.

Encrypted keys are not currently supported at this time.

ldap/<profile>/homeDN

This is the home DN of the user in question. The user needs be able to write to it. ZConf will attempt to create 'ou=zconf,ou=.config,$homeDN' for operating out of.

ldap/<profile>/host

This is the server to use for LDAP connections.

ldap/<profile>/password

This is the password to use for when connecting to the server.

ldap/<profile>/passwordfile

Read the password from this file. If both this and password is set, then this will write over it.

ldap/<profile>/starttls

This is if it should use starttls or not. It defaults to undefined, 'false'.

ldap/<profile>/SSLciphers

This is a list of ciphers to accept. The string is in the standard OpenSSL format. The default value is 'ALL'.

ldap/<profile>/SSLversion

This is the SSL versions accepted.

'sslv2', 'sslv3', 'sslv2/3', or 'tlsv1' are the possible values. The default is 'tlsv1'.

ldap/<profile>/TLSverify

The verify mode for TLS. The default is 'none'.

ZConf LDAP Schema

    # 1.3.6.1.4.1.26481 Zane C. Bowers
    #  .2 ldap
    #   .7 zconf
    #    .0 zconfData
    #    .1 zconfChooser
    #    .2 zconfSet
    #    .3 zconfRev
    #    .4 zconfLock
    
    attributeType ( 1.3.6.1.4.1.26481.2.7.0
	    NAME 'zconfData'
        DESC 'Data attribute for a zconf entry.'
	    SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
	    EQUALITY caseExactMatch
        )
    
    attributeType ( 1.3.6.1.4.1.26481.2.7.1
        NAME 'zconfChooser'
        DESC 'Chooser attribute for a zconf entry.'
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        EQUALITY caseExactMatch
        )
    
    attributeType ( 1.3.6.1.4.1.26481.2.7.2
        NAME 'zconfSet'
        DESC 'A zconf set name available in a entry.'
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        EQUALITY caseExactMatch
        )
    
    attributeType ( 1.3.6.1.4.1.26481.2.7.3
        NAME 'zconfRev'
        DESC 'The revision number for a ZConf config. Bumped with each update.'
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        EQUALITY caseExactMatch
        )
    
    attributeType ( 1.3.6.1.4.1.26481.2.7.4
        NAME 'zconfLock'
        DESC 'If this is present, this config is locked.'
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        EQUALITY caseExactMatch
        )
    
    objectclass ( 1.3.6.1.4.1.26481.2.7
        NAME 'zconf'
        DESC 'A zconf entry.'
        MAY ( cn $ zconfData $ zconfChooser $ zconfSet $ zconfRev $ zconfLock )
        )

SYSTEM MODE

This is for deamons or the like. This will read '/var/db/zconf/$sys/zconf.zml' for it's options and store the file backend stuff in '/var/db/zconf/$sys/'.

It will create '/var/db/zconf' or the sys directory, but not '/var/db'.

UTILITIES

There are several scripts installed with this module. Please see the perldocs for the utilities listed below.

zcchooser-edit
zcchooser-get
zcchooser-run
zcchooser-set
zccreate
zcget
zcls
zcrm
zcset
zcvdel
zcvls

AUTHOR

Zane C. Bowers, <vvelox at vvelox.net>

BUGS

Please report any bugs or feature requests to bug-zconf at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ZConf. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc ZConf

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2009 Zane C. Bowers, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.