Provision::Unix - provision hosting accounts on unix systems
version 1.08
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
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.
Provision::Unix - provision accounts on unix systems
All functions/methods adhere to the following:
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);
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);
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 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 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.
Same as dump_audit, except dumps the error history report.
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.
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
prints and returns the last error encountered.
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.
bug-unix-provision at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Provision::Unix
Matt Simerson <msimerson@cpan.org>
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.
To install Provision::Unix, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Provision::Unix
CPAN shell
perl -MCPAN -e shell install Provision::Unix
For more information on module installation, please visit the detailed CPAN module installation guide.