1;

=head1 NAME

p1.pl - Perl program to provide Perl code persistence for the Nagios project (http://www.Nagios.Org).

This program provides an API for calling Nagios Perl plugins from Nagios when it is built with embedded Perl support. The
intent is to tradeoff memory usage (see BUGS) against repeated context switches to recompile Perl plugins.

=head1 SYNOPSIS


B<From C>

  /* 1 Initialise Perl - see perlembed - maintaining a persistent interpreter> */
  /* 2 Push the arguments (char *args[]) of call_pv() onto the Perl stack */
  /* 3 Compile the plugin - char *args[] is an array of pointers to strings required by p1.pl */

  call_pv("Embed::Persistent::eval_file", G_SCALAR | G_EVAL)

  /* 4 if (SvTrue(ERRSV)) */
    goto outahere ;

  /* 5 Pop the code reference to the Perl sub (corresp to the plugin) returned by Perl */
  /* 6 Push the arguments (char *args[]) of call_pv() onto the Perl stack */
  /* 7 Run the plugin */

  call_pv("Embed::Persistent::run_package", G_ARRAY)

  /* 8 example arguments for call_ functions */

  args = {  "check_rcp",       /* pointer to plugin file name          */
            "1",               /* 1 to recompile plugins each time     */
            "",                /* temporary file name - no longer used */
            "-H sundev -C nfs" /* pointer to plugin argument string    */
         }

B<From Perl>

  my ($plugin_file, $plugin_args) = split(/\s+/, $_, 2) ;
  my $plugin_hndlr_cr ;
  eval {

    # 'eval {}' simulates the G_EVAL flag to perl_call_argv('code', 'flags')
    # Otherwise, die in 'eval_file' will end the caller also.

    $plugin_hndlr_cr = Embed::Persistent::eval_file($plugin_file, 0, '', $plugin_args) ;

  } ;

  if ( $@) {
    print "plugin compilation failed.\n" ;
  } else {
    my ($rc, $output) = Embed::Persistent::run_package($plugin_file, 0, $plugin_hndlr_cr, $plugin_args) ;
    printf "embedded perl plugin return code and output was: %d & %s\n", $rc, $output) ;

In the p1.pl text, 'use constant' statements set the log path and the log level.

The log level flags determine the amount and type of messages logged in the log path.

The default log level results in similar behaviour to former versions of p1.pl -
log files will B<not> be opened.

If you want to enable logging

=over 4

=item 1 Choose log options (see below)

=item 2 Choose a log path

=item 3 Edit p1.pl

=back

Set the values of (the 'use constant' statements) the log path, B<DEBUG_LOG_PATH>, and set the B<DEBUG_LEVEL> constant to
one or more of the log options (B<LEAVE_MSG> and friends ) or'ed together.
The default is to log nothing and to use S<<path_to_Nagios>/var/epn_stderr.log> as the log path.

=head1 DESCRIPTION

Nagios is a program to monitor service availability by scheduling 'plugins' - discrete programs
that check a service (by for example simulating a users interaction with a web server using WWW::Mechanize)  and output a line of
text (the summary of the service state) for those responsible for the service, and exit with a coded value to relay the same information to Nagios.

Each plugin is run in a new child process forked by Nagios.

Plugins, like CGIs, can be coded in Perl. The persistence framework embeds a Perl interpreter in Nagios to

=over 4

=item * reduce the time taken for the Perl compile and execute cycle.

=item * eliminate the need for Nagios to fork a process (with popen) to run the Perl code.

=item * eliminate reloading of frequently used modules.

=back