After the 1.4.13 release, the Nagios Plugins development team moved to Git for its code repositories. This document is a quick introduction to Git.
There are three projects:
You can see all the projects from the following web interface:
https://github.com/nagios-plugins/repositories
The following notes are for the "nagios-plugins" project, but can be substituted for any of the others.
To work on a project you first have to clone it. This creates your own local repository and until you want to distribute your change or merge changes from someone else everything that follows can happen offline.
If you have push access, run the command:
git clone git@github.com:nagios-plugins/nagios-plugins.git
If you just want a local copy or wish to clone it to your workstation, you can run this command instead:
git clone git://github.com/nagios-plugins/nagios-plugins.git
This will create a directory called "nagios-plugins" in your current directory with all the "master" code and history (this is roughly equivalent to CVS/SVN HEAD). Change directory to nagios-plugins.
You can edit the files in the working area. To check the status, use:
git status
This will show a list of changes in the working directory. Newly make changes appear in RED, while changes added to the index are shown in green. You can use git diff to see changes between the current working directory and the index (untracked files will not be shown)
Use git add to specify which new files/changes you want to commit; this will add the changes to the index. You can select only partial diffs with git add -p too. If you want to commit everything you can use git commit -a directly.
You can see the changes you are about to commit (difference between HEAD and the index) with git diff --cached, and then commit them with:
git commit
Add a comment (you have read the developers guidelines, right? :) ). This commit will be local (affecting only your own repository) so you will have to either push your changes, or have someone to pull them from you (in the latter case you will most likely still push to a publicly accessible clone of your local repository).
If the change is from a contributor, set the author at commit time:
git commit --author="Ton Voon <ton.voon@opsera.com>"
If you realize that you forgot something in your commit and haven't pushed it yet to a remote repository, you can amend your last commit with git commit --amend. You can also amend after a push and force the next update, however this will cause non-linear updates and should be done only if the developers using your repository are aware of it.
You can revert local modifications with the following steps.
First, if you have already staged the changes you will have to unstage them. As indicated in the "git status" message you can do so with the following command:
git reset HEAD <file>
Then you can revert unstaged changes with:
git checkout <file>
If you have already committed changes locally and need to undo your commit(s), you can use git reset. First find the commit names with git log and then do either one of these:
To keep local modifications (you can commit them again, stash them, etc.)
git reset --soft <commit>
Note that for the purpose of "re-doing" the last commit, git commit --amend will be much easier than a reset/commit with the same end result.
To discard local modifications (if you lose important changes with this command you may be able to recover them with git reflog and git checkout <commit>):
git reset --hard <file>
Do not reset changes that have already been pushed to remote repositories as this will cause non-linear updates. If you do so, developers using those repositories should be aware of it.
When you work on your local repository you'll need to keep it up to date with the development tree. This is very similar to svn update with the difference that it can't be done if the working tree has any unmerged changes. If you do, either commit them or put them aside (Tip: git stash). If you cloned from the main Git repository, this command will do a fetch then merge any new changes:
git pull
You can also merge changes from any other fork of the repository. This usually happens if someone ask you to pull from his own repo for some fix or enhancements. Together with --no-commit you will have a chance to review the changes and make any relevant correction before the merge. Ex:
git pull --no-commit git://host.xz/path/to/repo.git/ master
Once you're done with your commits and after pulling from the main repository, you can push you change back to it. If you cloned using the push url this command will push the master branch:
git push
It you're trying to push something that would generate merge conflicts, the push will be rejected. You will have yo do a pull first, fix the any conflicts locally and then push again.
If your commits are local (you haven't pulled them from someone else or published them somewhere) you can rebase to avoid a merge:
git pull --rebase
Like a merge, this may generate conflicts and let you fix them, but instead of creating a merge commit on top of the others, it will undo your commits, fast-forward and apply your commits again. This is cleaner but doesn't play well when it rewrites already published history.
If you are doing some development that you want to experiment with, you can create a new branch with:
git branch newbranchname
Switch to this branch with:
git checkout newbranchname
Show your current branch with:
git branch
This will list all branches with a * next to the current branch.
If you want to push a local branch up to a remote repository, run:
git push origin newbranchname:experimental/branchname
This tags the branch at the remote site with experimental/branchname.
This is a very quick introduction to Git. There are a lot more useful commands for manipulating changes and working with others. Be sure to have a look at the references below to better understand how git works. All standard commands are very well documented as well (git help [-a] for a list of commands, git help <cmd> or git <cmd> --help shows the man page).
I highly recommend reading Git for Computer Scientists (http://eagain.net/articles/git-for-computer-scientists/) to understand how rebase works.
The idea with the testing is to move as many functions as possible "lower down", ie to the lib/utils_*.c files. These functions can then be tested using the libtap routines in the lib/tests/test_*.c files. It is easier to do unit testing here than to try and do higher level plugin testing, because you can fake data easier at this level.
The routines available via libtap are equivalent to perl's Test::Simple ones.
The libtap tests are separated out from the plugins ones (in plugins/t) because:
* it is testing the files in lib/, so should reside there
* it requires compiling to run
Firstly, there is a distinction between a Nagios plugin and plugins from the Nagios Plugins project.
Although Nagios (the system) is licenced under the GPL, plugins are executed in their own environment so does not fall under the viral aspect of the GPL. Therefore, any plugin written for use by Nagios can be under any licence the copyright holder selects.
However, the plugins contained within the Nagios Plugins project are distributed under the GPL. If you distribute an application that includes the Nagios Plugins (modified or not), you are required to distribute a copy of the source code for the plugins under the terms of the GPL, regardless of the licensing for the rest of the application.
If you write a plugin which is a derivative work from code of the Nagios Plugins project, then your plugin must also be licenced under the GPL, although you own thecopyright for your modified portions.
Derivative work usually includes:
and does not usually include:
The developer guidelines provides the specifications for writing a Nagios plugin.
This is a document in DocBook format that is held in the Nagios Plugin subversion repository.
Nagiosmib is a set of MIBs for Nagios to allow traps sent from Nagios to be recognized by other NMSes.
To develop, the requirements are:
* make
* smistrip and smilint, part of the libsmi project (http://www.ibr.cs.tu-bs.de/projects/libsmi)
(On Debian Etch, apt-get install libsmi2 libsmi2-common to get the libsmi software.)
At the top level of nagiosmib, run make && make test.
If you get errors like:
./MIB/NAGIOS-ROOT-MIB:4: failed to locate MIB module `SNMPv2-SMI'
./MIB/NAGIOS-ROOT-MIB:6: failed to locate MIB module `SNMPv2-TC'
then you are missing some prerequisite MIBs. These need to be installed from the libsmi project.
Currently there are some warnings such as:
./MIB/NAGIOS-ROOT-MIB:35: warning: current type `NotifyType' is not referenced in this module
./MIB/NAGIOS-NOTIFY-MIB:153: warning: use Integer32 instead of INTEGER in SMIv2
I think these are okay.
To change the mib information, update the src-mib directory and run make to generate the MIBs. Run make test to check.
Update CHANGES file and commit.
To release, change the version number in Makefile and run make tarball. Publish tarball and md5sum on SF. Create news story on this site. Link back to here from tarball release.
We use libtap to test C routines that are in lib/utils_*.c. The tests are in lib/tests/test_*.c.
To start running tests with libtap, download the latest libtap. The latest version is currently 1.01. However, there is a bug with the thread implementation. To workaround, run:
CPPFLAGS="-UHAVE_LIBPTHREAD" ./configure
make
make check
make install
Now when you run the Nagios Plugins ./configure, it should find the libtap library and compile the tests and run them when you run "make test".
Gnulib provides replacement implementations of functions which are not available on all (Unix-like) operating systems. In order to sync with the latest Gnulib code, do something like:
$ git clone git://git.savannah.gnu.org/gnulib.git
$ cd gnulib
$ GNULIB_HEAD=$(git rev-parse --short HEAD)
$ cd ..
$ git clone git://nagiosplug.git.sourceforge.net/gitroot/nagiosplug/nagiosplug
$ cd nagiosplug
$ ../gnulib/gnulib-tool --update
$ find gl -name '*~' -o -name '.gitignore' | xargs rm
$ git status
$ git add gl
$ git commit -m "Sync with the latest Gnulib code ($GNULIB_HEAD)"
In order to make a given function available via Gnulib (on systems which don't provide it), the module must be imported using gnulib-tool, e.g. (in order to add the "strcase" module):
$ ../gnulib/gnulib-tool --no-vc-files --import strcase
$ find gl -name '*~' | xargs rm
$ git status
$ git add gl
$ git commit -m 'Add the Gnulib module "strcase"'
The Nagios::Plugin perl module can be obtained from two main locations:
If you install from the nagiosplug tarball, the perl module will be installed in $prefix/perl.
If you install from CPAN, the perl module will be installed by default into your perl's system directories.
To write your plugin, you should start it with:
use FindBin;
use lib "$FindBin::Bin/../perl/lib";
use Nagios::Plugin;
This bit of code tells perl to look for the Nagios::Plugin module in a directory relative to where the plugin is executed - this is a hard dependency. If Nagios::Plugin is not found there, perl's system directories will be searched.
This approach allows a system administrator to decide whether they want Nagios::Plugin installed via system directories or within the $prefix area of the plugins.
NPTest.pm is a perl module, originally written by Peter Bray, and provides some basic functions for testing the plugins. It has two main helpers:
Used to get parameters given in previous test runs. Use the 3 parameter version (the 4 parameter version is deprecated).
Saved parameters are put in /var/tmp/NPTest.cache. Unfortunately, there is no easy way of altering this - you will have to manually change this file to edit existing parameters
If you are adding new parameters, there are three values for the parameters that you need to be aware of:
You should try and ensure current tests are not affected when a new parameter is added. So it maybe better to say "NP_INTERNET_ACCESS", with information like 'default "yes", disable with "no"' and check for NP_INTERNET_ACCESS == "no" to skip the tests.
This runs a command and returns an NPTest object back. You can combine Test::More routines with the object to get the return code, output or perf data to test against expected values.
See plugins/t/check_disk.t as an example test script.
This page describes the Nagios Plugin routines that can be accessed from the internal library.
This page is in development, so these are not guaranteed to be available. As the API matures and is available in libraries, this information will be migrated to the developer guidelines.
Initialise the nagios plugin routines. Pass the plugin name and argc and argv from main().
A variable nagios_plugin will be created for internal use.
Sets the internally held argc and argv values.
Shouldn't really need this, but due to np_extra_opts, this is set after that call.
Used to cleanup allocated memory by the nagios_plugin variable. This is called by the die() routine before exiting.
Saving and restoring state allows a plugin to know the last results and thus work out differences. This is especially useful when a plugin is capturing counter information, which increases with every request.
This currently works by saving state information to a file, though the API doesn't care what the backend implementation is.
Note: Binary data is not currently supported
Some things to be aware of, if you use state information:
Enables the plugin state retention routines. Will set the filename for the state file to be .../{keyname}.
keyname will have any non alphanumerics replaced with "_".
If keyname is NULL, will generate an SHA1 keyname based on the argv of the plugin (using the extra-opts parsed version, if applicable).
Note: the keyname should be uniquely defined for a particular service, to avoid a 2nd invocation of the plugin to use the state information from a different invocation. If in doubt, set keyname=NULL and allow the routine to calculate the keyname.
Reads the state file and returns a state_data variable.
This routine will call die() with UNKNOWN if:
Returns NULL if:
Your plugin should always check for NULL. It is recommended that your plugin returns OK on NULL as this is similar to a "first run".
If valid data was read, a pointed will be returned which points to a struct of:
typedef struct state_data_struct {
time_t time;
void *data;
int length; /* Of binary data */
} state_data;
If data_time==0, use current time. Creates state file, with state format version. Writes data version, time, and data. Creates a temporary file and then renames into place. There is a possible loss of data if two things writing to same key at same time, but there will not be a corrupted state file.
Same as np_state_write_string, but writes binary data - currently unimplemented.