Steve.org.uk: Slaughter Primitives

Slaughter

Introduction
Examples
Primitives
Variables

Slaughter Primitives

Alert

The Alert primitive is used to send an email, sample usage:
Alert( Message => "Server on fire: $hostname",
            To => 'steve[at]steve.org.uk',
      Subject  => "Alert: $fqdn");
(Notice how we use $hostname, $fqdn, etc. For the full list of supported variables please see the variable list.)

Valid parameters are:

Name Usage Mandatory?

To The email address to send the message to. Yes

From The email address to send the message from. Yes

Subject The subject of the email.

Message The message body of the email.

AppendIfMissing

This function will append a single line to a file, unless that line is already contained in the file.
AppendIfMissing(
                 File => "/etc/hosts.allow",
                 Line => "All: 1.2.3.4" );
Valid parameters are:

Name Usage Mandatory?

File The file to examine/update. Yes

Line The line to search for or append. Yes

The function will return 1 if it appended the line, 0 if it didn't because the line was already present and -1 if there was an error.

CommentLinesMatching

Given a regular expression this function will add comments to any lines in a specified file which match that regular expression.

Sample usage:
if ( CommentLinesMatching( Pattern => "telnet|ftp",
                           File    => "/etc/inetd.conf" ) )
{
        RunCommand( "/etc/init.d/inetd restart" );
}
The following parameters are accepted:

Name Usage Mandatory?

Pattern The regular expression to match with. Yes

File The file to examine. Yes

Comment The string to prefix to lines. Default is "#"

The function returns the number of comments applied, or zero if none.

DeleteFilesMatching

Given a regular expression this function will remove any files upon the local system which match that pattern.

Sample usage:
#
#  Delete *.dpkg-old - recursively
#
DeleteFilesMatching( Root    => "/etc",
                     Pattern => "\\.dpkg-old\$" );
The following parameters are accepted:

Name Usage Mandatory?

Pattern The regular expression to match with. Yes

Root The file to search beneath. Yes

The function returns the number of files deleted.

DeleteOldFiles

The DeleteOldFiles function is used to remove files which are older than a given number of days. It is not recursive, and doesn't touch directories at all.

Sample usage:
DeleteOldFiles( Root => "/tmp",
                Age  => 10 );
Name Usage Mandatory?

Age The age of files above which should be removed. Yes

Root The file to search beneath. Yes

The function returns the number of files deleted.

FetchFile

The FetchFile primitive is used to copy a file from the remote HTTP server to the local system. The file will have be moved into place if the local file is missing, or contains different contents.
if ( FetchFile(
            Source => "/etc/motd",
              Dest => "/etc/motd",
             Owner => "root",
             Group => "root",
              Mode => "0644" ) )
{
    # File was updated.
}
else
{
    # File already existed locally with the same contents.
}
Valid parameters are:

Name Usage Mandatory?

Source
The path on the HTTP server.

The path is beneath http://server.example.org/slaughter/files.)
Yes

Dest Where, on the local system, to copy the file to. Yes

Expand Should templat expansion occur? Values are true/false.

Owner The username who should "own" the file, post-copy.

Group The group who should "own" the file, post-copy.

Mode The mode of the file, post-copy.

Note: If you make a request for the Source /etc/motd then three requests will be tried - upon success of any of these files the fetch will be terminated.

http://you.example.com/slaughter/files/etc/motd.client.host.name

http://you.example.com/slaughter/files/etc/motd.client

http://you.example.com/slaughter/files/etc/motd

This assumes the client which runs the policy has the fully qualified domain name of client.host.name.

Template Expansion
If you configure a copy with "Expand => true" the input file will be passed through the Text::Template perl module.

This means that content such as this:
# This is the config file for foo on {$fqdn}
Will end up as:
# This is the config file for foo on gold.my.flat
Any of supported variables may be expanded just by wrapping them in "{" and "}".

If you'd like to get clever you can update the values used in template expansion first:
$template{"name"} = 'root';
$template{"date"} = scalar localtime;
FetchFile ..
This will make "{$name}" and "{$date}" available for you to use too.

FileMatches

FileMatches allows you to test the contents of a specific file to see if they contain a literal line, or if they match a given regular expression.

Sample usage:
if ( FileMatches( File    => "/etc/sudoers",
                  Pattern => "steve" ) )
{
   # OK "steve" is in sudoers.  Somewhere.
}
The method accepts the following parameters - note that you may only specify one of Pattern and Line.

Name Usage Mandatory?

File
The filename to examine.
Yes

Line
Look for the specified line literally.
Yes

Pattern
Look for matches of the given regular expression.
Yes

If the file matches then the return will be the number of matches. 0 will be returned on zero matches.

InstallPackage

The InstallPackage primitive will allow you to install a system package. Currently apt-get and yum are supported.

Sample usage:
foreach my $package ( qw! bash tcsh ! )
{
    if ( PackageInstalled( Package => $package ) )
    {
        print "$package installed\n";
    }
    else
    {
        InstallPackage( Package => $package );
    }
}
The only argument accepted to this method is the parameter Package.

Mounts

Mounts returns all the currently mounted devices upon your local system, ignoring those that are tempfs or otherwise unreal.

Sample usage:
  my @mounts = Mounts();
There are no arguments used in this primitive.

PackageInstalled

The PackageInstalled primitive will allow you to test whether a given system package is installed.

Sample usage:
foreach my $package ( qw! bash sh fish ! )
{
    if ( PackageInstalled( Package => $package ) )
    {
        print "$package installed\n";
    }
    else
    {
        print "$package not installed\n";
    }
}
The only argument accepted to this method is the parameter Package.

PercentageUsed

The PercentageUsed primitive will tell you how much space is used upon a given mount-point.

Sample usage:
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 only argument accepted to this method is the parameter Path.

RemovePackage

The RemovePackage primitive will allow you to remove a system package, supporting both rpm and apt-get based systems.

Sample usage:
if ( PackageInstalled( Package => "telnetd" ) )
{
        RemovePackage( Package => "telnetd" );
}
The only supported argument is the mandatory "Package".

RunCommand

RunCommand allows you to execute an arbitrary command upon the system, just like system.

Sample usage:
  RunCommand( Cmd => "id" );
The only argument accepted to this method is the parameter Cmd.

UserExists

Allows you to determine if the specified user exists upon the local system.

Sample usage:
  if ( UserExists( User => "skx" ) )
  {
       RunCommand( "/bin/echo 'skx is alive'" );
  }
Valid parameters are:

Name Usage Mandatory?

User
The username to test.
Yes

UserDetails

Return data, such as the home directory, of the specified username.

Sample usage:
  if ( UserExists( User => "skx" ) )
  {
       my $data = UserDetails( User => "skx" );
       my $home = $data->{'Home'};
  }
Valid parameters are:

Name Usage Mandatory?

User
The username to fetch details on.
Yes

This function returns undef on failure.

[ Sitemap | Contact Me | Reward me | Edinburgh Amateur Photography ]