Slaughter::API::generic - Perl Automation Tool Helper generic implementation
This module implements most of our primitives in a portable fashion, allowing other modules in the Slaughter::API:: namespace to implement the rest.
Slaughter::API::
When this module is loaded it promotes each of the subroutines in the package into the main:: namespace, to allow calling code to use the functions directly without needing an OO-interface.
main::
Now follows documentation on the available methods.
Export all subs in this package into the main namespace.
The alert primitive is used to send an email. Sample usage is:
Alert( Message => "Server on fire: $hostname", To => 'steve[at]steve.org.uk', Subject => "Alert: $fqdn" );
The following parameters are available:
The sender address of the email.
The content of the message to send
The path to the sendmail binary.
The subject to send.
The recipient of the message.
This primitive will open a local file, and append a line to it if it is not already present.
AppendIfMissing( File => "/etc/hosts.allow", Line => "All: 1.2.3.4" );
The filename which should be examined and potentially updated.
The line which should be searched for and potentially appended.
This primitive will open a local file, and comment out any line which matches the specified regular expression.
if ( CommentLinesMatching( Pattern => "telnet|ftp", File => "/etc/inetd.conf" ) ) { RunCommand( Cmd => "/etc/init.d/inetd restart" ); }
The value to comment out the line with.
The regular expression to match with.
The return value of this function is the number of lines updated, or -1 if the file could not be opened.
This primitive will delete files with names matching a particular pattern, recursively.
# # Delete *.dpkg-old - recursively # DeleteFilesMatching( Root => "/etc", Pattern => "\\.dpkg-old\$" );
The root directory from which the search begins.
The regular expression applied to filenames.
The return value of this function is the number of files deleted.
This primitive will delete files older than the given number of days from the specified directory.
Note unlike "DeleteFilesMatching" this function is not recursive.
# # Delete files older than ten days from /tmp. # DeleteFilesMatching( Root => "/tmp", Age => 10 );
The age of files which should be deleted.
The IdenticalContents primitive is used to compare whether two filenames have identical contents.
The following is an example of usage:
# # If the current contents don't match then move into place. # if ( 1 != IdenticalContents( File1 => $tmp, File2 => $dest ) ) { system( "cp", $tmp, $dest ); } else { unlink( $tmp ); }
The first file to complare.
The second file to compare.
The return value will depend on the matching:
-1 Returned on error; either missing parameters, or non-existing files.
0 The files are different.
1 The files are identical.
The FetchFile primitive is used to copy a file from the remote server to the local system. The file will have be moved into place if the local file is missing OR if it exists but contains different contents to the remote version.
if ( FetchFile( Source => "/etc/motd", Dest => "/etc/motd", Owner => "root", Group => "root", Mode => "644" ) ) { # File was created/updated. } else { # File already existed locally with the same contents. }
The destination file to write to, on the local system.
This is used to enable template-expansion, documented later.
The unix group which should own the file.
The Unix mode to set for the file. NOTE If this doesn't start with "0" it will be passed through the perl "oct" function.
The Unix owner who should own the file.
The path to the remote file. This is relative to the /files/ prefix beneath the transport root. If no value is specified the destination path is used.
When a file fetch is attempted several variations are attempted, not just the literal filename. The first file which exists and matches is returned, and the fetch is aborted:
Template template expansion involves the use of the Text::Template module, of "Expand => true". This will convert the following text:
# This is the config file for SSHD on {$fqdn}
To the following, assuming the local host is called "precious.my.flat":
# This is the config file for SSHD on precious.my.flat
The return value of this function is will depend upon the action carried out:
-1 - Returned on error; either missing parameters, or failure to perform the fetch.
0 - The fetch resulted in no change.
1 - The local file was replaced with the remote one.
This allows you to test whether the contents of a given file match either a literal line of text, or a regular expression.
if ( FileMatches( File => "/etc/sudoers", Pattern => "steve" ) ) { # OK "steve" is in sudoers. Somewhere. }
The name of the file to test.
A line to look for within the file literally.
A regular expression to match against the file contents.
The return value of this function will be the number of matches found - regardless of whether a regular expression or literal match is in use.
This method allows you to search for an executable upon your system $PATH, or a supplied alternative string.
if ( FindBinary( Binary => "ls" ) ) { # we have ls! }
The name of the binary file to find.
This is assumed to be a semi-colon deliminated list of directories to search for the binary within.
If the binary is found the full path will be returned, otherwise undef.
This method is a stub which does nothing but output a line of text to inform the caller that the method is not implemented.
For an implementation, and documentation, please consult Slaughter::API::linux.
Slaughter::API::linux
This primitive is used to store a log-worthy message. Whenever slaughter finishes executing it will output a summary of all log-messages which were encountered, sorted by priority.
LogMessage( Message => "Server on fire: $hostname", Level => "normal" );
The log-level of the message. You may choose whichever level you prefer.
Return a list of all the mounted filesystems upon the current system.
my @mounts = Mounts();
No parameters are required or supported in this method, and the return value is an array of all mounted filesystems upon this host.
NOTE: This primitive invoke mount and parses the output. This is reasonably portable, but will fail upon systems which have no "mount" binary. In that case the method will output a stub message to complain that the function is not implemented.
mount
Return the percentage of space used in in the given mounted-device.
foreach my $point ( Mounts() ) { if ( PercentageUsed( Path => $point ) > 80 ) { Alert( To => "root", From => "root", Subject => "$server is running out of space on $point", Message => "This is a friendly warning." ); } }
The following parameters are supported:
The mount-point to the filesystem in question.
The return value will be a percentage in the range 0-100.
NOTE: This primitive invokes df and parses the output. This is reasonably portable, but will fail upon systems which have no "df" binary. In that case the method will output a stub message to complain that the function is not implemented.
df
This primitive will open a local file, and replace any lines matching a given regular expression.
ReplaceRegexp( File => "/etc/ssh/sshd_config", Pattern => "^PermitRootLogin.*yes.*", Replace => "PermitRootLogin no" );
The pattern to test and potentially replace.
The replacement text to use.
The return value of this function is the number of lines updated, 0 if none, or -1 if the file could not be opened.
This primitive will execute a system command.
RunCommand( Cmd => "/usr/bin/id" );
The command to execute. If no redirection is present in the command to execute then STDERR will be redirected to STDOUT automatically.
The return value of this function is the result of the perl system function.
This method allows the file owner,group, and mode-bits of a local file to be changed.
SetPermissions( File => "/etc/motd" , Owner => "root", Group => "root", Mode => "644" );
The filename to work with.
The group to set as the owner for the file.
The username to set as the files owner.
The permissions bits to set for the file. NOTE if this doesn't start with a leading "0" then it will be passed through the "oct" function - this allows you to use the obvious construct :
Mode => "755"
This primitive will return a hash of data about the local Unix user specified, if it exists.
if ( UserExists( User => "skx" ) ) { my %data = UserDetails( User => "skx" ); }
The unix username to retrieve details of.
The return value of this function is a hash of data conprising of the following Keys/Values
The user's home directory
The user's UID
The user's GID
The user's quota.
The user's comment
The user's login shell.
The user's username.
Undef will be returned on failure.
This primitive will test to see whether the given local user exists.
if ( UserExists( User => "skx" ) ) { # skx exists }
The unix username to test for.
The return value of this function is 1 if the user exists, and 0 otherwise.
Create a new user for the system.
# TODO
The following parameters are required:
The username to create.
The UID for the user.
The primary GID for the user.
You may optionally specify the GCos field to use.
Steve Kemp <steve@steve.org.uk>
Copyright (c) 2010-2015 by Steve Kemp. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.
To install App::Slaughter, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Slaughter
CPAN shell
perl -MCPAN -e shell install App::Slaughter
For more information on module installation, please visit the detailed CPAN module installation guide.