/ 
Provision-Unix-0.35
River stage zero No dependents
/ Provision::Unix

NAME

Provision::Unix - provision accounts on unix systems

VERSION

Version 0.30

SYNOPSIS

Provision::Unix is an application to create, modify, and destroy accounts on Unix systems in a reliable and consistent manner.

prov_user.pl --action=create --username=matt --pass='neat0app!'
prov_dns.pl  --action=create --zone=example.com
prov_web.pl  --action=create --vhost=www.example.com

The types of accounts that can be provisioned are organized by class with each class including a standard set of operations. All classes support at least create and destroy operations. Additional common operations are: modify, enable, and disable.

Each class (DNS, Mail, User, VirtualOS, Web) has a general module that contains the logic for selecting and dispatching requests to sub-classes which are implementation specific. Selecting and dispatching is done based on the environment and configuration file settings at run time.

For example, Provision::Unix::Mail contains all the general logic for email operations (create a vhost, mailbox, alias, etc). Subclasses contain specific information such as how to provision a mailbox for sendmail, postfix, qmail, ezmlm, or vpopmail.

Browse the perl modules to see which modules are available.

use Provision::Unix;

my $foo = Provision::Unix->new();
...

Programming Conventions

All functions/methods adhere to the following:

Exception Handling

Errors throw exceptions. This can be overridden by calling the method with fatal=>0. If you do so, you must write code to handle the errors.

This call will throw an exception since it cannot find the file.

$util->file_read(file=>'/etc/oopsie_a_typo');

Setting fatal will cause it to return undef instead:

$util->file_read(file=>'/etc/oopsie_a_typo', fatal=>0);

Warnings and Messages

Methods have an optional debug parameter that defaults to enabled. Often, that means methods spit out more messages than you want to see. You can supress them by setting debug=>0.

Supressed messages are not lost! All error messages are stored in $prov->errors and all status messages are in $prov->audit. You can dump those arrays any time to to inspect the status or error messages. A handy way to do so is:

$prov->error(message=>'test breakpoint');

That will dump the contents of $prov->audit and $prov->errors and then terminate your program. If you want your program to continue after calling $prov->error, just set fatal=>0.

FUNCTIONS

new

Creates and returns a new Provision::Unix object.

As part of initialization, new() finds and reads in provision.conf from /[opt/usr]/local/etc, /etc, and the current working directory.

find_config

Searches in common etc directories for a named configuration file.

my $config = $self->find_config( file => 'provision.conf', debug=>0 );

error

Whenever a method runs into an unexpected condition, it should call $prov->error with a human intelligible error message. It should also specify whether the error is merely a warning or a fatal condition. Errors are considered fatal unless otherwise specified.

Examples:

$prov->error( message => 'could not write to file /etc/passwd' );

This error is fatal and will throw an exception, after dumping the contents of $prov->audit and the last error message from $prov->errors to stderr.

A very helpful thing to do is call error with a location as well:

$prov->error( 
   message  => 'could not write to file /etc/passwd',
   location => join( ", ", caller ),
);

Doing so will tell you where the error message was encountered as well as what called the method. The latter is more likely where the error exists, making location a very beneficial thing to pass along.

audit

audit is a method that appends messages to an internal audit log. Rather than spewing messages to stdout or stderr, they all get appended to an array. They can then be inspected whenever desired by calling $prov->audit and examining the result. I expect to add additional support to that method for logging the messages to a file or SQL table.

returns an arrayref of audit messages.

AUTHOR

Matt Simerson, <matt at tnpi.net>

BUGS

Please report any bugs or feature requests to bug-unix-provision at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Provision-Unix. 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 Provision::Unix

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008 Matt Simerson, all rights reserved.

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