Using The Embedded Perl Interpreter


Introduction

Stephen Davies has contributed code that allows you to compile Nagios with an embedded Perl interpreter. This may be of interest to you if you rely heavily on plugins written in Perl.

Stanley Hopcroft has worked with the embedded Perl interpreter quite a bit and has commented on the advantages/disadvanges of using it. He has also given several helpful hints on creating Perl plugins that work properly with the embedded interpreter. The majority of this documentation comes from his comments.

It should be noted that "ePN", as used in this documentation, refers to embedded Perl Nagios, or if you prefer, Nagios compiled with an embedded Perl interpreter.

Advantages

Some advantages of ePN (embedded Perl Nagios) include:

Disadvantages

The disadvantages of ePN (embedded Perl Nagios) are much the same as Apache mod_perl (i.e. Apache with an embedded interpreter) compared to a plain Apache:

Target Audience

Things you should do when developing a Perl Plugin (ePN or not)

Things you must do to develop a Perl plugin for ePN

  1. <DATA> can not be used; use here documents instead e.g.

    my $data = <<DATA;
    portmapper 100000
    portmap 100000
    sunrpc 100000
    rpcbind 100000
    rstatd 100001
    rstat 100001
    rup 100001
    ..
    DATA
    
    %prognum = map { my($a, $b) = split; ($a, $b) } split(/\n/, $data) ;
    
  2. BEGIN blocks will not work as you expect. May be best to avoid.

  3. Ensure that it is squeaky clean at compile time i.e.



  4. Avoid lexical variables (my) with global scope as a means of passing __variable__ data into subroutines. In fact this is __fatal__ if the subroutine is called by the plugin more than once when the check is run. Such subroutines act as 'closures' that lock the global lexicals first value into subsequent calls of the subroutine. If however, your global is read-only (a complicated structure for example) this is not a problem. What Bekman recommends you do instead, is any of the following:


  5. Be aware of where you can get more information.

    Useful information can be had from the usual suspects (the O'Reilly books, plus Damien Conways "Object Oriented Perl") but for the really useful stuff in the right context start at Stas Bekman's mod_perl guide at http://perl.apache.org/guide/.

    This wonderful book sized document has nothing whatsoever about Nagios, but all about writing Perl programs for the embedded Perl interpreter in Apache (ie Doug MacEacherns mod_perl).

    The perlembed manpage is essential for context and encouragement.

    On the basis that Lincoln Stein and Doug MacEachern know a thing or two about Perl and embedding Perl, their book 'Writing Apache Modules with Perl and C' is almost certainly worth looking at.

  6. Be aware that your plugin may return strange values with an ePN and that this is likely to be caused by the problem in item #4 above

  7. Be prepared to debug via:


    perl -MO::Deparse <your_program>
  8. Be aware of what ePN is transforming your plugin too, and if all else fails try and debug the transformed version.

    As you can see below p1.pl rewrites your plugin as a subroutine called 'hndlr' in the package named 'Embed::<something_related_to_your_plugin_file_name>'.

    Your plugin may be expecting command line arguments in @ARGV so pl.pl also assigns @_ to @ARGV.

    This in turn gets 'eval' ed and if the eval raises an error (any parse error and run error), the plugin gets chucked out.

    The following output shows how a test ePN transformed the check_rpc plugin before attempting to execute it. Most of the code from the actual plugin is not shown, as we are interested in only the transformations that the ePN has made to the plugin). For clarity, transformations are shown in red:

    
                    package main;
                    use subs 'CORE::GLOBAL::exit';
                    sub CORE::GLOBAL::exit { die "ExitTrap: $_[0] 
    (Embed::check_5frpc)"; }
                    package Embed::check_5frpc; sub hndlr { shift(@_);
    @ARGV=@_;
    #! /usr/bin/perl -w
    #
    # check_rpc plugin for Nagios
    #
    # usage:
    #    check_rpc host service
    #
    # Check if an rpc serice is registered and running
    # using rpcinfo - $proto $host $prognum 2>&1 |";
    #
    # Use these hosts.cfg entries as examples
    #
    # command[check_nfs]=/some/path/libexec/check_rpc $HOSTADDRESS$ nfs
    # service[check_nfs]=NFS;24x7;3;5;5;unix-admin;60;24x7;1;1;1;;check_rpc
    #
    # initial version: 3 May 2000 by Truongchinh Nguyen and Karl DeBisschop
    # current status: $Revision: 1.26 $
    #
    # Copyright Notice: GPL
    #
    ... rest of plugin code goes here (it was removed for brevity) ...
    }
    


  9. Don't use 'use diagnostics' in a plugin run by your production ePN. I think it causes__all__ the Perl plugins to return CRITICAL.

  10. Consider using a mini embedded Perl C program to check your plugin. This is not sufficient to guarantee your plugin will perform Ok with an ePN but if the plugin fails this test it will ceratinly fail with your ePN. [ A sample mini ePN is included in the contrib/ directory of the Nagios distribution for use in testing Perl plugins. Change to the contrib/ directory and type 'make mini_epn' to compile it. It must be executed from the same directory that the p1.pl file resides in (this file is distributed with Nagios). ]

Compiling Nagios With The Embedded Perl Interpreter

Okay, you can breathe again now. So do you still want to compile Nagios with the embedded Perl interpreter? ;-)

If you want to compile Nagios with the embedded Perl interpreter you need to rerun the configure script with the addition of the --enable-embedded-perl option. If you want the embedded interpreter to cache internally compiled scripts, add the --with-perlcache option as well. Example:

	./configure --enable-embedded-perl --with-perlcache ...other options...

Once you've rerun the configure script with the new options, make sure to recompile Nagios. You can check to make sure that Nagios has been compile with the embedded Perl interpreter by executing it with the -m command-line argument. Output from executing the command will look something like this (notice that the embedded perl interpreter is listed in the options section):

	[nagios@firestore ]# ./nagios -m

	Nagios 1.0a0
	Copyright (c) 1999-2001 Ethan Galstad (nagios@nagios.org)
	Last Modified: 07-03-2001
	License: GPL

	External Data I/O
	-----------------
	Object Data:      DEFAULT
	Status Data:      DEFAULT
	Retention Data:   DEFAULT
	Comment Data:     DEFAULT
	Downtime Data:    DEFAULT
	Performance Data: DEFAULT


	Options
	-------
	* Embedded Perl compiler (With caching)