view release on metacpan or  search on metacpan

README.pod  view on Meta::CPAN

=head1 NAME

Csistck - Perl system consistency check framework

=head1 SYNOPSIS

    use Csistck;
    
    sub sig_hup_mysql { $ENV{'MAINT_HUP_MYSQL'} = 1; }

    for (qw/a b/) {
        host "$_.example.com" => role('mysql');
    }

    host 'c' => role('mysql');
    
    role 'mysql' => 
        pkg({
            dpkg => 'mysql-server',
            emerge => 'mysql'
        }),
        template(
            '/etc/mysql/my.cnf',
            src => 'mysql/my.cnf', 
            mysql => {
                bind => '127.0.0.1',
                keysize => '1G'
            },
            mode => '0644',
            uid => 100,
            gid => 100,
            on_restart => \&sig_hup_mysql
        ),
        script('services.sh');
            
    check;

The script can then be called directly, using command line arguments below

=head1 DESCRIPTION

Csistck is a small Perl framework for writing scripts to maintain system 
configuration and consistency. The focus of csistck is to stay lightweight,
simple, and flexible.

=head1 EXTENDING ROLES

Roles can be defined using the C<role> keyword syntax, however a more flexible
method is to extend a new object from L<Csistck::Role>:

    use Csistck;
    use base 'Csistck::Role';

    sub defaults {
        my $self = shift;
        $self->{config} = '/etc/example.conf';
    }

    sub tests {
        my $self = shift;
        $self->add(pkg({
            dpkg => 'test-server',
            pkg_info => 'net-test'
        }),
        template(
            $self->{config},
            src => 'files/example.conf',
            example => $self
        );

    }

    1;

See L<Csistck::Role> for information on extending roles

=head1 METHODS

=head2 host($host, $checks)

Add tests to host C<$host> test array. Tests are Csistck::Test blessed references, code
references, or arrays of either. To process host tests, use C<check()>.

=head2 role($role, $checks)

Define a weak role. Constructed similar to a host check, however roles are not
called directly, rather they are used to define groups of common tests that can
be used by multiple hosts.

See L<EXTENDING ROLES> above for an object-based style of defining roles, which
allows for passing role configuration.

=head2 check($target)

Runs processing on C<$target>. If C<$target> is C<undef>, then look up the
system's full hostname. If C<$target> is a string, use that string for a
hostname lookup. If C<$target> is a C<Csistck::Test> reference, a coderef, or an
arrayref, then process that object directly. This is useful for writing scripts
where hostname is not important.

=head1 EXPORTED METHODS

=head2 option($name, $value)

Set option to specified value.

=head3 Available Options

=over 3

=item *

pkg_type [string]

Set default package type

=item *

domain_name [string]

Set default domain name to append to hosts

=back

=head2 host($hostname, [@tests]);

Append test or array of tests to host definition. Most examples use the fat
comma delimiter syntax, however this is a subjective choice. 

    host('hostname', noop(1));
    host 'hostname' => noop(1), noop(1);
    host 'hostname' => noop(0);

Returns a reference to the host object.

=head2 role($rolename, [@tests]);

Append test or array of tests to role definition.
    
    role 'test' => noop(0);
    host 'hostname' => role('test');

Returns a reference to the role object.

=head2 noop($return)

"No operation" test, used only for testing or placeholders.

    role 'test' => noop(1);

=head2 file($target, :$src, :$mode, :$uid, :$gid)

Copy file C<$src> to C<$target>, setting additional options with named arguments 
such as mode and uid.

    role 'test' => file(
        '/etc/lighttpd/lighttpd.conf',
        src => 'lighttpd/lighttpd.conf',
        mode => '0644'
    );

See L<Csistck::Test::File>

=head2 template($target, :$src, :$mode, :$uid, :$gid, [:$args])

Process file C<$src> as a Template Toolkit template, output to path C<$target>.
Optional named arguments can be used to alter the mode, uid, etc. All parameters
passed into the C<Csistck::Test::Template> object are available in the actual
template, so any additional named arguments are available in the template using
the argument's name -- these arguments should be hasrefs.

    role 'test' => template(
        '/etc/motd',
        src => 'sys/motd',
        foo => { bar => 1 },
        uid => 0,
        gid => 0,
        mode => '0640'
    );

See L<Csistck::Test::Template>

=head2 script($script, [@arguments])

Call script with specified arguments 

    role 'test' => script("apache2/mod-check", "rewrite");

See L<Csistck::Test::Script>

=head2 pkg($package, [$type])

Check for package using system package manager. The C<$package> argument may be
specified as a string, or as a hashref to specify package names for multiple
package managers. The package manager will be automatically detected if no
package manager is specified.

    option 'pkg_type' => 'dpkg';
    role 'test' => 
        pkg("lighttpd", 'dpkg'),
        pkg({
            dpkg => 'snmp-server',
            pkg_info => 'net-snmp'
        });

See L<Csistck::Test::Pkg> for more information

=head1 SCRIPT USAGE

Scripts based on Csistck will run in an interactive mode by default. 
The following command line options are recognized in a csistck based script

=over

=item *

B<--[no]repair>

Automate repair mode, do not run in interactive mode.

=item *

B<--[no]verbose>

Toggle verbose reporting of events

=item *

B<--[no]debug>

Toggle debug reporting of events

=item *

B<--[no]quiet>

Toggle event reporting of errors