NAME

Slaughter::API::generic - Perl Automation Tool Helper generic implementation

SYNOPSIS

This module implements most of our primitives in a portable fashion, allowing other modules in the Slaughter::API:: namespace to implement the rest.

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.

AUTHOR

Steve
--
http://www.steve.org.uk/

LICENSE

Copyright (c) 2010-2012 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.

Alert

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:

From [default: "root"]

The sender address of the email.

Message [mandatory]

The content of the message to send

Sendmail [default: "/usr/lib/sendmail -t"]

The path to the sendmail binary.

Subject [mandatory]

The subject to send.

To [mandatory]

The recipient of the message.

AppendIfMissing

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 following parameters are available:

File [mandatory]

The filename which should be examined and potentially updated.

Line [mandatory]

The line which should be searched for and potentially appended.

CommentLinesMatching

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 following parameters are available:

Comment [default: "#"]

The value to comment out the line with.

File [mandatory]

The filename which should be examined and potentially updated.

Pattern [mandatory]

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.

DeleteFilesMatching

This primitive will delete files with names matching a particular pattern, recursively.

#
#  Delete *.dpkg-old - recursively
#
DeleteFilesMatching( Root    => "/etc",
                     Pattern => "\\.dpkg-old\$" );

The following parameters are available:

Root [mandatory]

The root directory from which the search begins.

Pattern [mandatory]

The regular expression applied to filenames.

The return value of this function is the number of files deleted.

DeleteOldFiles

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 following parameters are available:

Age [mandatory]

The age of files which should be deleted.

Root [mandatory]

The root directory from which the search begins.

The return value of this function is the number of files deleted.

IdenticalContents

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 following parameters are available:

File1 [mandatory]

The first file to complare.

File2 [mandatory]

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.

FetchFile

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.

The following is an example of usage:

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 following parameters are available:

Dest [mandatory]

The destination file to write to, on the local system.

Expand [default: false]

This is used to enable template-expansion, documented later.

Group

The unix group which should own the file.

Mode

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.

Owner

The Unix owner who should own the file.

Source [default: value of Dest]

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:

/etc/motd.$fqdn

/etc/motd.$hostname

/etc/motd.$os

/etc/motd.$arch

/etc/motd

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.

FileMatches

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 following parameters are available:

File [mandatory]

The name of the file to test.

Line [or Pattern mandatory]

A line to look for within the file literally.

Pattern [or Line mandatory]

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.

FindBinary

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 following parameters are available:

Binary [mandatory]

The name of the binary file to find.

Path [default: $ENV{'PATH'}]

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.

InstallPackage

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.

LogMessage

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 following parameters are available:

Level [default: "normal"]

The log-level of the message. You may choose whichever level you prefer.

Message [mandatory]

The content of the message to send

Mounts

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.

PackageInstalled

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.

PercentageUsed

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:

Path

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.

RemovePackage

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.

ReplaceRegexp

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 following parameters are available:

File [mandatory]

The filename which should be examined and potentially updated.

Pattern [mandatory]

The pattern to test and potentially replace.

Replace [mandatory]

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.

RunCommand

This primitive will execute a system command.

RunCommand( Cmd => "/usr/bin/id" );

The following parameters are available:

Cmd [mandatory]

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.

SetPermissions

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 following parameters are supported:

File [mandatory]

The filename to work with.

Group

The group to set as the owner for the file.

User

The username to set as the files owner.

Mode

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"

UserDetails

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 following parameters are available:

User [mandatory]

The unix username to retrieve details of.

The return value of this function is a hash of data conprising of the following Keys/Values

Home

The user's home directory

UID

The user's UID

GID

The user's GID

Quota

The user's quota.

Comment

The user's comment

Shell

The user's login shell.

Login

The user's username.

Undef will be returned on failure.

UserExists

This primitive will test to see whether the given local user exists.

if ( UserExists( User => "skx" ) )
{
   # skx exists
}

The following parameters are available:

User [mandatory]

The unix username to test for.

The return value of this function is 1 if the user exists, and 0 otherwise.

UserCreate

Create a new user for the system.

# TODO

The following parameters are required:

Login

The username to create.

UID

The UID for the user.

GID

The primary GID for the user.

You may optionally specify the GCos field to use.

cpanm Slaughter::API::linux

perl -MCPAN -e shell
install Slaughter::API::linux