view release on metacpan or  search on metacpan

Framework.pod  view on Meta::CPAN

%DATA	= (
	
	## Mandatory Information ########################

	#the configNamspace to load this data under in the Config::Framework object
	'configNamespace'	=> $configNamespace,
	
	#throw an error if this configNamespace is attempted to be overwritten (by loading
	#annother config with the same configNamespace) if set to non-zero value.
	'protectNamespace'	=> 1 | 0,
	
	#revision of this configuration
	'Version'			=> $version_number,
	
	
	## Optional Config Meta Data ####################
	
	#date corresponding to the last revision of this configuration
	'Date'				=> $date_in_epoch_format,
	
	#automatically load these files and nest their configNamespaces underneath this one.
	'children'			=> [$file_name, $file_name, ... ]
	
	
	## Author Data ##################################
	
	#name of the lead developer for this project
	'Lead Developer'		=> $lead_developer_name,
	
	#lead developer's email address
	'Lead Developer Email'	=> $lead_developer_email,
	
	#the others in the development team
	'Developers'			=> [ 'array','of','other','developers' ],
	
	
	## Program Specific Keys ########################
	
	#would go here. Any goofy thing you want.
	
);

And that's pretty much it.



=head1	Passwords

Passwords are one special kind of config data that programs frequently need to load. For instance,
do you have a program that needs to talk to a database? How about one which needs to talk to an
SSL Website? Well then it probably needs to have a username and password. It's kind of bad form to
have passwords and usernames hard-coded into programs. Especially if you have lots of programs, then
you have both the nightmare of updating all of the hard-coded passwords in each program when the 
password gets changed, as well as the security risk of having a password in perhaps tens or hundreds
of individual files. One option is to stick those usernames and passwords in a configuration file
or course, so that many programs can access the same file. However, you've still got your passwords 
hanging out 'in the nude' in a file somewhere waiting to be discovered. Config::Framework provides 
some built-in options to help you, if not eliminate, to at least to mitigate that risk.

Config::Framework knows how to decrypt a file encrypted with any of the Crypt::* modules
which is Crypt::CBC compliant. When you specify the 'GetSecure' option at object instantiation, 
Config::Framework knows to look for a file called 'passwds.xml' located at the root level of the 
config directory.

When you build Config::Framework, the Makefile.PL will ask you for a Crypt::* module to use to
and a passphrase to use to decrypt and encrypt this file. Sure, the passphrase is still 'in the nude'
somewhere buried in your perl distributions lib/ directory, and theoretically, someone could go
digging through that directyory, and find the passphrase, then use it to get all of the passwords in
your passwds.txt. However, it's better than nothing. Like I said this mitigates the risk a bit, it
dosen't eliminate it. At the moment there really aren't any good systems available to perl to handle
passwords securely. At least this way, you have your password access abstracted a bit, so when 
something like that comes along, we can add support to Config::Framework.


=head1	Logging / Alerts

Ok something that's not config file related, but is none-the-less important, and so is therefore
included in the one-stop-shop that is Config::Framework is the ability to keep log files, and to let
someone know when something bad has happened with your program.

When you build Config::Framework, you are prompted to enter the email address of someone who
should be notified when a program using Config::Framework dies unexpectedly. This is a bit misleading.
An alert will not be sent to this address automatically, you must catch your own exceptions and 
call the AlertAdmin function with your alert message.

As with all of the other default parameters gathered durring the build process, this address can
be overridden at object instantiation. To override the admin address send a new email address on the
'admin' object at instatiation.

Config::Framework also provides support for appending messages to alert files via the 'Log' method.






=head1	Alrighty Then
Ok so that's pretty much what Config::Framework does. How about the specifics?
Read on courageous programmer!



=head1	new	(constructor)

This creates a new Config::Framework

my $object = new Config::Framework( [options] ) || die $Config::Framework::errstr

=head2	options

=over

=item	program

This is the 'name' of the program. This defailts to the name of the executable file if you don't
specify it explicitly.

=item	v_root

This is the 'Virtual Root': the directory under which all of the external things your program will 
need to live happily reside. (See above section: 'Virtual Root'). If not specified explicitly, this
value defaults to the virtual root specified when the module wad built.

=item	config_loc

This is the directory beneath 'v_root' which contains all Config::Framework loadable config files
as well as the ApplicationFramework directories (see above section 'The Config Location'). If not 
specified explicitly, this value defaults to the 'config_loc' specified when the module was built.

=item	sendmail

This is the path to the sendmail executable, which we pipe directly to when sending alerts via the
AlertAdmin method. If not explicitly defined, this value defaults to the path to sendmail given when
the module was built.

=item	admin

This is the email address of the person whom we should send email alerts to by deefault when the
AlertAdmin method is called. If not explicitly defined, this value defaults to the admin address 
given when the module was built.

=item	Crypt

This is the Crypt::* module to use when encrypting or decrypting encrypted configuration files, such
as the infamous passwds.txt. (See the 'Passwords' section above). Keep in mind that whatever Crypt::*
module you specify must be Crypt::CBC compliant, and of course, you must have it installed already!
If not explicitly defined, this value defaults to the Crypt::* module specified when the module was
built.

=item	Key

This would be the passphrase to use when encrtpying or decrpting encrypted configuration files,
again, such as that infamous passwds.txt (see 'Passwords' section above). If not explicitly defined,
this value defaults to the passphrase given when the module was built.
 
=item	EnvExportList

This is a sticky-wicket, thrown in for backward compatibility. This is an array conaining a list of
strings which are data keys which you would like to have exported to the shell environment. There
are 5 default members of this list:
	'SYBASE',
	'ORACLE_HOME',
	'ORACLE_SID',
	'ARTCPPORT',
	'LD_LIBRARY_PATH'
This means that if you happen to have defined any of these options, either explicity at 
instantiation, or through the build process as a default option, the values associated with these
options will be exported to your sheel environment. Mucking with this is hardly ever worthwhile, if
you're looking for a quick and easy way to export stuff to the shell environment, check out the 
'Export' option.


=item	Export

This is a hash refrence of variable names and values that you would like to have exported to the 
processes shell environment. For example to set the 'BLAH' variable to "ain't it grand?", you could
do this:

$object = new Config::Framework( Export => { 'BLAH' => "ain't it grand?" } );

=item	SYBASE

if you have a sybase client libraries installed, and you would like to set the environment variable
SYBASE to this value, you can specify it here and it will be exported. (it's part of the default
'EnvExportLIst'). If you don't explicity define this, and you did define it duirring the build
process, it will be exported to your shell environment by default. This is meant to be the path to
the Sybase client library distribution.

=item	ORACLE_HOME

the path to the oracle client librarry distribution. Like SYBASE, this is in the default 
EnvExportList, so if you define it, expect for it to be exported to the processes shell environment

=item	ORACLE_SID

the SID of an oracle database you would like to connect to. A default member of EnvExportList
(see above).

=item	ARTCPPORT

the port that you would like to talk to a Remedy ARS server on. A default member of EnvExportList
(see above).

=item	LD_LIBRARY_PATH

linker library path. believe it or not, you need to have this defined for a whole lot of things to

Framework.pod  view on Meta::CPAN

if set to a non-zero value will automatically load all child configs specified in any config that
is loaded into the object. The default value for this object is 1. To override this behaviour, just
set the option to 0.

=back



=head1	LoadConfig

This loads a configuration file into the object under the configNamespace specified in the file.
If there is already data loaded under this configNamespace in the object, and the protectNamespace
option is set in the existing config data, an error will be thrown.

$object->LoadConfig(File => $file_name) || die $object->{'errstr'};

=head2	options

=over

=item	File

this should be a string containing the filename of the file containing configuration data that you
would like to load. The file is looked for in the following locations: IF the file exists as you have
specified it (that is if you specified the full path to some file, and it exists there) then the 
file will be loaded. Otherwise, if it exists in the root level of v_root/config_loc (the location for
global configuration files) it will be loded from there. Else if it exists in
v_root/config_loc/ApplicationFrameworks/$object->{'program'} (where $object->{'program'} is the name
of the program (see 'new (constructor)' above), then it loaded from that directory. Lastly, if
the file is not found in any of those locations, we look in the home directorry of the user executing
the process (this is determined via $ENV{'HOME'}). Using this precendenc allowes a great deal of
flexibility ... just remember to keep tour config file names unique! ;-)

=item	configNamespace

IF the file you are loading DOES NOT specify it's own configNamespace, you can specify one explicity
in the function call using this parameter. This should be a string you would like to use for the 
configNamespace-less file you are loading.

=item	Parent

you may specify a parent namespace under which to nest the configNamespace of the file you are
loading. For instance. If I have an application called 'Daleks' which has a config file with a
configNamespace of 'Dalek' and a user preferences file which specifies the configNamespace
'usersDalekConfig', then I might do something like:


$object->LoadCondfig(
	File	=> "usersDalekConfig.xml",
	Parent	=> "Dalek"
);

this would load the user-specific config file UNDER the 'Dalek' configNamespace, so that I could 
access the user-specific data thusly

$object->{'Dalek'}->{'usersDalekConfig'}->{'someKey'};

=item	Crypt

LoadConfig has the capability to decrypt and load config files encrypted via one of the CBC compliant
Crypt::* modules. This option specifies the Crypt::* subclass that you would like to use to decrypt
the specified config file (presuming it is encrypted). For instance, if you wanted to load 
the file "mySecretConfig.xml" which was encrypted using the Crypt::Rijndael module you would do
something like:

$object->LoadConfig(
	File	=> "mySecretConfig.xml",
	Crypt	=> "Rijndael",
	Key		=> $mySecretKey
) || die $object->{'errstr'};

NOTE: this option defaults to the Crypt::* subclass specified when the module was built, if not
explicitly defined either at this function call or at object instantiation.

=item	Key

(see Crypt option above). This is the passphrase to be used to decrypt the configuration file using
the Crypt::* subclass specified on the 'Crypt' option.

NOTE: this option defaults to the passphrase specified when the module was built, if not
explicitly defined either at this function call or at object instantiation.

=back



=head1	WriteConfig 

This will write the data under some configNamespace in the object to the file it was loaded out of, 
or alternately to a different specified file. Encrypted data is handled transparently.

$object->WriteConfig(configNamespace => "usersDalekConfig.xml") || die $object->{'errstr'};

=head2	options

=over

=item	configNamespace (required)

This should be a string indicating the configNamespace that you want to dump back into the spcified
file. Obviously, the configNamespace that you specify must already exist in the current object.

=item	File

This is the file that you want to write the data contained in the specified 'configNamespace' back
out to. If this option is not specified explicitly, then the file from which the specified 
configNamespace was loaded is used. The same file location precidence that is used in LoadConfig
is maintained here. That if the file as specified is not writeable, then we look first under
v_root/config_loc, then v_root/config_loc/ApplicationFrameworks/$object->{'program'} and lastly
in the user's home directory.

=item	Encrypt

if set to a non-zero value, this will cause the file which is being written out to be encrypted with
either the specified Key and Crypt or the default options given when the module was built.
NOTE: setting this option is not necessary if you are writing data back to a file which was encrypted
when you originally loaded it, this option is only necesary if you are encrypting a file which was
not previously encrypted, or if you are creating a new encrypted file.

=item	Crypt

This should be the CBC compliant Crypt::* subclass that you would like to use encrypt the data.
If not specified, this option defaults to the value givne when the module was built. For more 
information, see ReadConfig.

=item	Key

This should be a string contining the passphrase you want to use to encrypt the data with the
specified CBC compliant Crypt::* subclass. For more information, see ReadConfig.

=back



=head1	LoadXMLConfig

This function will load any specified file in the Data::DumpXML DTD. If a binary file is specified
it is presumed to be encrypted. Encrypted files are decrypted using either a specified Crypt::*
module and passphrase, or the default options specified when the module was built. Data is returned
via a hash reference, and is NOT loaded directly into the object.

$data = $object->LoadXMLConfig(File => "path/to/some/file.xml") || die $object->{'errstr'};

This is the backend to LoadConfig which handles inserting config data into the object under the
correct configNamespace, and also handles child configs and nested namespaces. If you just want to
get some raw data out of a file in the Data::DumpXML dtd, which might possibly be encrypted using 
a Crypt::* module which is CBC compliant, then this is the method you're looking for.

=head2	options

=over

=item	File

again, this is a string containing the complete path to and name of the file you would like to load.
No location precidence mathing occurs here, you must specify the entire path and file you want to 
load.

=item	Crypt

This would be the CBC compliant Crypt::* subclass that you would like to use to decrypt the given 
file, presuming it is, in fact, encrypted. (See LoadConfig method)

=item	Key

This would be the passphrase you'd like to use to decrypt the (presumably encrypted) config data 
using the CBC compliant Crypt::* sublcass you specified above. (see LoadConfig method)

=back



=head1	AlertAdmin

This will email an alert to the address specified by either the 'To' option, or the default address
specified when the object was built. Additionally, the method can optionally copy the message to a
group of addresses, log the message to a file, or call the die() routine. This is accomplished
via a piped shell process which calls the sendmail binary. If we are unable to open a pipe to the
sendmail process, as a last resort we will attempt to append the specified message to a logfile
located at v_root/var/log/last_resort.log.

$object->AlertAdmin(
	Message	=> "I can't log in to the database, bailing out!",
	Log		=> "copy/this/message/to/my/log/file.txt",
	Die		=> 1
) || die $object->{'errstr'};

=head2	options

=over

=item	To	(optional)

a string containing the address to send the 'Message' to, or alternately, a reference to an array
containing a list of multiple addresses to use. If not explicitly specified, this option defaults to
the admin address given when the module was built.

=item	Message	(required)

a string (possibly a very long one) which contains the data you would like to send.

=item	Log

if specified, this will cause the method to attempt to append the 'Message' to the specified
log file, tagged with the current date and time.

=item	Die

if set to a non-zero value, this will cause the program to terminate itself after sending the
'Message'

=item	ENV

if set to a non-zero value, this will cause the method to append the entire contents of the global
%ENV hash to the end of the 'Message'

=back



=head1	Log

This will append the given 'Message' to the specified 'Log' file. The log file is presumed to
live beneath v_root somewhere. If you want to use system-wide loging locations, you might want to
use sym-links to accomplish that.

TO DO: add syslog support via Net::Syslog or Sys::Syslog so that messages can be logged to a remote