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

NAME

Provision::Unix - provision hosting accounts on unix systems

VERSION

version 1.08

SYNOPSIS

use Provision::Unix;

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

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

DESCRIPTION

Provision::Unix is a suite of applications to create, modify, and destroy accounts on Unix systems in a reliable and consistent manner.

Command line scripts are provided for humans to perform provisioning actions by hand. See the documentation included in each of the prov_* scripts. Programmers and automated systems should be loading the Provision::Unix modules and calling the methods directly. The API provided by each method is stable and only changes when additional parameters are added.

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

Each class (DNS, 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::DNS contains all the general logic for dns operations (create a zone, record, alias, etc). Subclasses contain specific information such as how to provision a DNS record for nictool, BIND, or tinydns.

Not all specific modules are fully implemented yet. Ex: Provision::Unix::VirtualOS::Linux::Xen is fully implemented, where Provision::Unix::VirtualOS::FreeBSD::Jail is not.

Browse the perl modules to see which modules are available.

NAME

Provision::Unix - provision accounts on unix systems

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('/etc/oopsie_a_typo');

Setting fatal will cause it to return undef instead:

$util->file_read('/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. 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('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.

$prov->error('test breakpoint', 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.

audit

audit is a method that appends messages to an internal audit log. Rather than spewing messages to stdout or stderr, they are stored as a list. The list can can be inspected by calling $prov->audit or it can be printed by calling $prov->dump_audit.

$prov->audit("knob fitzerbaum twiddled to setting 5");

If the debug option is set ($prov->{debug}), audit messages are also printed to stderr.

returns an arrayref of audit messages.

dump_audit

dump_audit prints out any audit/status messages that have accumulated since the last time dump_audit was called. It is particularly useful for RPC agents that poll for status updates during long running processes.

dump_error

Same as dump_audit, except dumps the error history report.

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( 'could not write to file /etc/passwd' );

This error is fatal and will throw an exception, after printing the contents of the audit log and the last error message to stderr.

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

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

Doing so will tell reveal in the error log exactly where the error was encountered as well as who called the method. The latter is more likely where the error exists, making location a very beneficial parameter.

find_config

This sub is used to determine which configuration file to use. The general logic is as follows:

If the etc dir and file name are provided and the file exists, use it.

If that fails, then go prowling around the drive and look in all the usual places, in order of preference:

/opt/local/etc/
/usr/local/etc/
/etc

Finally, if none of those work, then check the working directory for the named .conf file, or a .conf-dist.

Example: my $conf = $util->find_config ( file => 'example.conf', etcdir => '/usr/local/etc', )

arguments required:
  file - the .conf file to read in

arguments optional:
  etcdir - the etc directory to prefer
  debug
  fatal

result:
  0 - failure
  the path to $file

get_last_error

prints and returns the last error encountered.

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

AUTHOR

Matt Simerson <msimerson@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by The Network People, Inc..

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