From 7b0fa5d642466e7cdd0d326658c3c06c27f8a1ec Mon Sep 17 00:00:00 2001 From: Holger Weiss Date: Sat, 11 Jan 2014 17:38:18 +0100 Subject: Import most FAQ items from old web site Import most of the FAQ entries from our old web site. A few outdated questions have been omitted, many of the imported ones were updated in one way or another, and the order of the development-related questions has been changed. Also, the phrasing of some questions has been modified (just to make the headings shorter). For the record, this is the original list of questions from the old web site: General ------- * Who controls the Nagios Plugins project? * What license is Nagios Plugins distributed under? * Who owns the copyright for the Nagios Plugin code? * Can I submit a patch to this project? * Do you accept donations? Compiling --------- * ./configure appears to hang * check_ldap, check_radius or check_pgsql don't compile even though configure output says the required libraries are present * How come check_http/check_tcp doesn't work with --ssl? * How do I compile the Nagios::Plugin perl module? * I can't compile check_mysql on solaris * I get '":types" is not exported by the Params::Validate module' when running tests * Why does Solaris use pst3 for check_procs? Installing ---------- * Some of the root plugins (check_dhcp and check_icmp) haven't been installed. What's happening? * Why aren't my plugins installed as the nagios user? And what about root plugins? Development ----------- * How do I use Git? * Can I add extra tests to the C routines? * Can I use the Nagios Plugins in my own project? * How can I find out more about writing a plugin? * How do I make changes on nagiosmib? * How do I prove the C routines work? * How do I use and update Gnulib? * How do I use the Nagios::Plugin perl module? * How do the test parameters in NPTest.pm work? * Private C APIs diff --git a/web/input/development.md b/web/input/development.md index 9a1a72f..41d4a52 100644 --- a/web/input/development.md +++ b/web/input/development.md @@ -19,9 +19,8 @@ These projects are maintained in separate repositories on [GitHub][github]: Contributions are always welcome! If you'd like to provide patches, please [fork][fork] the desired repository and submit a [pull request][pull]. In -case you're not familiar with Git, you might want to look into [Scott -Chacon][scott]'s [Pro Git][book] book available on the [Git web site][git] -first. +case you're not familiar with Git, you might want to look into our [short +introduction][git-intro] or [some other Git documentation][git-ref], first. ## Development Guidelines @@ -42,6 +41,8 @@ commands: $ make $ make test +Also see our testing-related [development FAQs][dev-faq]. + Regular tests of the latest code are scheduled automatically on various platforms, the results can be [viewed online][tests]. @@ -50,11 +51,11 @@ platforms, the results can be [viewed online][tests]. [github]: https://github.com/ "GitHub" [fork]: https://help.github.com/articles/fork-a-repo "Fork Documentation" [pull]: https://help.github.com/articles/using-pull-requests "Pull Request Documentation" -[scott]: http://scottchacon.com/ "Scott Chacon" -[book]: http://git-scm.com/book "Pro Git" -[git]: http://git-scm.com/ "Git" +[git-intro]: doc/faq/git.html "Quick Git Introduction" +[git-ref]: doc/faq/git.html#references "Git References" [guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines" [libtap]: http://jc.ngo.org.uk/trac-bin/trac.cgi/wiki/LibTap "LibTap Homepage" +[dev-faq]: doc/faq/#development "Development FAQs" [tests]: tests.html "Test Results" diff --git a/web/input/doc/faq/build-perl-module.md b/web/input/doc/faq/build-perl-module.md new file mode 100644 index 0000000..0ec97ac --- /dev/null +++ b/web/input/doc/faq/build-perl-module.md @@ -0,0 +1,15 @@ +title: Building Nagios::Plugin +parent: FAQ +--- + +# How do I build Nagios::Plugin? + +This is currently an optional setting at configure time. You need to run: + + ./configure --enable-perl-modules + +Then, `make`, `make` `install`, `make` `test`, and `make` `clean` will include +the Perl modules that are in the `perlmods/` directory as expected. They are +installed into `$prefix/perl`. + + diff --git a/web/input/doc/faq/compilation.md b/web/input/doc/faq/compilation.md new file mode 100644 index 0000000..b58566a --- /dev/null +++ b/web/input/doc/faq/compilation.md @@ -0,0 +1,18 @@ +title: Building Nagios Plugins +parent: FAQ +--- + +# How do I compile the plugins? + +To compile version `1.x` of the plugins, you run: + + gzip -dc nagios-plugins-1.x.tar.gz | tar -xf - + cd nagios-plugins-1.x + ./configure + make + +You can then [install the plugins][installation]. + +[installation]: doc/faq/installation.html "Installation" + + diff --git a/web/input/doc/faq/configure-hangs.md b/web/input/doc/faq/configure-hangs.md new file mode 100644 index 0000000..7c934cd --- /dev/null +++ b/web/input/doc/faq/configure-hangs.md @@ -0,0 +1,21 @@ +title: Configure hangs +parent: FAQ +--- + +# The configure script appears to hang + +If you find that the configure script appears to hang on this line: + + checking for redhat spopen problem... + +Then you probably have a badly configured DNS server. This part of configure +is testing for a pthread problem in BIND that is a kernel problem on some Red +Hat derived versions of Linux (around kernel 2.6.9-11). It runs 10 x 100 +nslookup calls to see if your kernel has this problem. If it does, then at +least one of those calls will fail. Failure rate could be anywhere between 1% +and 50%. + +To force the workaround and ignore the test, run `./configure` with the +`--enable-redhat-pthread-workaround` switch. + + diff --git a/web/input/doc/faq/contribute.md b/web/input/doc/faq/contribute.md new file mode 100644 index 0000000..fe97a80 --- /dev/null +++ b/web/input/doc/faq/contribute.md @@ -0,0 +1,26 @@ +title: Can I submit a patch? +parent: FAQ +--- + +# Can I submit a patch? + +Of course you can! This is an open source project! + +Ideally, [fork][fork] our [repository][repo] and create a [pull request][pull] +on [GitHub][github], so your patch doesn't get lost. Then chase up via the +[development mailing list][list], if nothing happens. But be aware, this +project is run by volunteers, so there is not necessarily immediate response! + +By submitting a pull request, you are stating that this is your own work or +you have full rights to it. If your pull request is accepted, we will (of +course) retain the Git author name and email address, and we'll add your name +to the list of contributors in the [THANKS][thanks] file. + +[repo]: https://github.com/nagios-plugins/repositories "Our Repositories" +[fork]: https://help.github.com/articles/fork-a-repo "Fork Documentation" +[pull]: https://help.github.com/articles/using-pull-requests "Pull Request Documentation" +[github]: https://github.com/ "GitHub" +[list]: list/listinfo/devel/ "Development Mailing List" +[thanks]: repositories/nagios-plugins/plain/THANKS.in "THANKS File" + + diff --git a/web/input/doc/faq/control.md b/web/input/doc/faq/control.md new file mode 100644 index 0000000..37a811f --- /dev/null +++ b/web/input/doc/faq/control.md @@ -0,0 +1,16 @@ +title: Who controls the project? +parent: FAQ +--- + +# Who controls the Nagios Plugins project? + +[Nagios Enterprises][enterprises] own the Nagios Plugins project, hence the +domain names of the site belong to Nagios Enterprises. However, the [Nagios +Plugins Development Team][team] are responsible for the running of the +project. This means that decisions about the web site and the development of +code related to the project are handled independently by the team. + +[enterprises]: http://www.nagios.com/about/company "Nagios Enterprises" +[team]: team.html "Nagios Plugins Development Team" + + diff --git a/web/input/doc/faq/donations.md b/web/input/doc/faq/donations.md new file mode 100644 index 0000000..0cfb7c0 --- /dev/null +++ b/web/input/doc/faq/donations.md @@ -0,0 +1,16 @@ +title: Do you accept donations? +parent: FAQ +--- + +# Do you accept donations? + +The [Nagios Plugins Development Team][team] accepts donations for the project. +We have a separate Paypal account that is used for donations, which is +administered by the team leader. + +Donations go towards paying for the small administrative charges we have. We +might also use some of the funds for team beer when we meet up in person. + +[team]: team.html "Nagios Plugins Development Team" + + diff --git a/web/input/doc/faq/extra-tests.md b/web/input/doc/faq/extra-tests.md new file mode 100644 index 0000000..b508195 --- /dev/null +++ b/web/input/doc/faq/extra-tests.md @@ -0,0 +1,26 @@ +title: Testing C routines +parent: FAQ +--- + +# Can I add extra tests to the C routines? + +The idea with the testing is to move as many functions as possible "lower +down"; i.e., 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][libtap] are equivalent to Perl's +[Test::Simple][test-simple] ones. + +The libtap tests are separated out from the plugins ones (in `plugins/t`) +because: + +1. They are testing the files in `lib/`, so should reside there. +2. They require [compiling][compilation] to run. + +[libtap]: http://jc.ngo.org.uk/trac-bin/trac.cgi/wiki/LibTap "libtap" +[test-simple]: http://search.cpan.org/dist/Test-Simple/lib/Test/Simple.pm "Test::Simple Module" +[compilation]: doc/faq/compilation.html "Compilation" + + diff --git a/web/input/doc/faq/git.md b/web/input/doc/faq/git.md new file mode 100644 index 0000000..05fd533 --- /dev/null +++ b/web/input/doc/faq/git.md @@ -0,0 +1,197 @@ +title: Git +parent: FAQ +--- + +# How do I use Git? + +After the 1.4.13 release, the [Nagios Plugins Development Team][team] moved to +[Git][git] for its code repositories. This document is a quick introduction +to Git. + +## Differences Between Git and SVN + +There is one huge difference between Git and SVN: Git is a distributed SCM +(Source Code Management system) while SVN is a centralized one. This doesn’t +mean we can’t have a central shared Git repository (and we indeed have one), +this means distributed development can occur around that central repository. +Another visible difference is that Git have more stages between the working +directory and the repository. When you want to add files or changes, you use +**git add**. This adds the changes to the repository index, which can be seen +as a staging area. When you commit with **git commit**, only the changes in +the index are considered. After committing, the changes are still local. To +share it with others, you have to push it to a remote repository, or gave +someone pull from your publicly accessible repository (in most case you will +still have to push changes there, unless if you were running a git daemon +straight off your working repository). Finally you can’t miss the fact that +there is no more revision numbers, and the distributed nature of Git is the +reason for that: there is absolutely no way a single number could be tracked +in a distributed way. Instead Git uses SHA1 hashes to identify commits (as +well as other objects in the repository). Each branch and tag refer to an +object name (SHA1 hash), and each commits have one or more parents (commit +objects). Although SHA1 hashes are 40 digits long, with Git you only have to +type a handful of digits to reference one. + +## Cloning a Project + +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`. + +## Editing Files + +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 made 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). + +## Committing Files + +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 [Development Guidelines][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="Jane Doe " + +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. + +## Reverting Local Modifications + +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 + +Then you can revert unstaged changes with: + + git checkout + +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 + +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 +**): + + git reset --hard + +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. + +## Merging Remote Changes + +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. Example: + + git pull --no-commit git://example.com/path/to/repo.git master + +## Merging Back to the Main Repository + +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. + +## Going Further + +This is a very quick introduction to Git. There are a lot more useful +commands for manipulating changes and working with others. They are all very +well documented (see **git help [-a]** for a list of commands, **git help +** or **git --help** shows the man page). You might also want to +look into some of the references listed below, or into a book such as [Scott +Chacon][scott]'s [Pro Git][book]. + +## References + +- Intro to Distributed Version Control (Illustrated) + +- A tutorial introduction to Git + +- Everyday Git With 20 Commands Or So + +- Git User’s Manual + +- Git - SVN Crash Course + +- Git QuickStart + +- Git CheatSheet + +- Understanding Git Conceptually + +- The Git Parable + +- Git for Computer Scientists + + +[team]: team.html "Nagios Plugins Development Team" +[guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines" +[git]: http://git-scm.com/ "Git" +[scott]: http://scottchacon.com/ "Scott Chacon" +[book]: http://git-scm.com/book "Pro Git" + + diff --git a/web/input/doc/faq/gnulib.md b/web/input/doc/faq/gnulib.md new file mode 100644 index 0000000..328dfeb --- /dev/null +++ b/web/input/doc/faq/gnulib.md @@ -0,0 +1,36 @@ +title: Gnulib +parent: FAQ +--- + +# How do I use and update Gnulib? + +[Gnulib][gnulib] provides replacement implementations of functions that 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@github.com:nagios-plugins/nagios-plugins.git + cd nagios-plugins + ../gnulib/gnulib-tool --update + find gl -name '*~' -o -name '.gitignore' | xargs rm + git status + git add gl + git commit -m "Sync with latest Gnulib code ($GNULIB_HEAD)" + +In order to make a given function available via Gnulib (on systems which don't +provide that function), the [corresponding module][modules] 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 Gnulib module "strcase"' + +[gnulib]: http://www.gnu.org/software/gnulib/ "Gnulib" +[modules]: http://www.gnu.org/software/gnulib/MODULES.html "Gnulib Modules" + + diff --git a/web/input/doc/faq/guidelines.md b/web/input/doc/faq/guidelines.md new file mode 100644 index 0000000..acc73f7 --- /dev/null +++ b/web/input/doc/faq/guidelines.md @@ -0,0 +1,12 @@ +title: Guidelines +parent: FAQ +--- + +# How should a plugin be written? + +The [Nagios Plugin Development Guidelines][guidelines] provide the +specifications for writing a plugin. + +[guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines" + + diff --git a/web/input/doc/faq/index.md b/web/input/doc/faq/index.md index 18584f2..35f6e75 100644 --- a/web/input/doc/faq/index.md +++ b/web/input/doc/faq/index.md @@ -4,6 +4,66 @@ parent: Documentation # FAQ -The list of Frequently Asked Questions (FAQ) will come back soon. +This is a list of Frequently Asked Questions (FAQ) regarding the Nagios +Plugins. + +## General + +* [Who controls the Nagios Plugins project?][control] +* [What license is the code distributed under?][license] +* [Can I submit a patch?][contribute] +* [Do you accept donations?][donations] + +## Compiling + +* [How do I compile the plugins?][compilation] +* [The configure script appears to hang][configure-hangs] +* [Why doesn't the --ssl option work?][ssl] +* [How do I build the Nagios::Plugin module?][build-perl-module] +* [Building check\_mysql fails on Solaris][mixing-compilers] +* [Why use pst3 for check\_procs on Solaris?][ps-on-solaris] + +## Installing + +* [How do I install the plugins?][installation] +* [Why aren't the root plugins installed?][root-plugins] +* [Which user owns the installed plugins?][ownership] + +## Development + +* [How do I use Git?][git] +* [How should a plugin be written?][guidelines] +* [Private C APIs][c-apis] +* [How do I prove the C routines work?][libtap] +* [Can I add extra tests to the C routines?][extra-tests] +* [How do the NPTest parameters work?][nptest] +* [How do I use and update Gnulib?][gnulib] +* [How do I use the Nagios::Plugin module?][use-perl-module] +* [How do I modify NagiosMIB?][nagiosmib] +* [Can I use Nagios Plugins in my project?][reuse] + +[control]: doc/faq/control.html +[license]: doc/faq/license.html +[contribute]: doc/faq/contribute.html +[donations]: doc/faq/donations.html +[compilation]: doc/faq/compilation.html +[configure-hangs]: doc/faq/configure-hangs.html +[ssl]: doc/faq/ssl.html +[build-perl-module]: doc/faq/build-perl-module.html +[mixing-compilers]: doc/faq/mixing-compilers.html +[ps-on-solaris]: doc/faq/ps-on-solaris.html +[installation]: doc/faq/installation.html +[root-plugins]: doc/faq/root-plugins.html +[ownership]: doc/faq/ownership.html +[git]: doc/faq/git.html +[guidelines]: doc/faq/guidelines.html +[c-apis]: doc/faq/private-c-api.html +[libtap]: doc/faq/libtap.html +[extra-tests]: doc/faq/extra-tests.html +[nptest]: doc/faq/nptest.html +[gnulib]: doc/faq/gnulib.html +[use-perl-module]: doc/faq/use-perl-module.html +[nagiosmib]: doc/faq/nagiosmib.html +[reuse]: doc/faq/reuse.html diff --git a/web/input/doc/faq/installation.md b/web/input/doc/faq/installation.md new file mode 100644 index 0000000..f426f35 --- /dev/null +++ b/web/input/doc/faq/installation.md @@ -0,0 +1,14 @@ +title: Installing Nagios Plugins +parent: FAQ +--- + +# How do I install the plugins? + +After [compiling][compilation] the plugins, you can run the following command +to install them: + + make install + +[compilation]: doc/faq/compilation.html "Compilation" + + diff --git a/web/input/doc/faq/libtap.md b/web/input/doc/faq/libtap.md new file mode 100644 index 0000000..29cd357 --- /dev/null +++ b/web/input/doc/faq/libtap.md @@ -0,0 +1,26 @@ +title: libtap +parent: FAQ +--- + +# How do I prove the C routines work? + +We use [libtap][libtap] to test C routines that are in `lib/utils_*.c`. The +tests are in `lib/tests/test_*.c`. + +The latest libtap 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` script, it should find the +libtap library and compile the tests and run them when you run `make` `test`. + +*Update:* These days, the Nagios Plugins tarball includes a copy of libtap +which is used if you run `./configure` `--enable-libtap`. + +[libtap]: http://jc.ngo.org.uk/trac-bin/trac.cgi/wiki/LibTap "libtap" + + diff --git a/web/input/doc/faq/license.md b/web/input/doc/faq/license.md new file mode 100644 index 0000000..d4a369c --- /dev/null +++ b/web/input/doc/faq/license.md @@ -0,0 +1,19 @@ +title: What license is used? +parent: FAQ +--- + +# What license is the code distributed under? + +The Nagios Plugins code is currently distributed using the [GNU General Public +License, Version 3][gpl] (GPLv3). + +This is because some C code that we depend upon, from the [Gnulib][gnulib] +project, is distributed under the GPLv3; and therefore, some of our plugins +also need to be GPLv3 licensed. The team has decided, rather than having a +mixed license, we'll distribute all of the core Nagios Plugins code under the +GPLv3. + +[gpl]: http://www.gnu.org/licenses/gpl.html "GPLv3" +[gnulib]: http://www.gnu.org/software/gnulib/ "Gnulib" + + diff --git a/web/input/doc/faq/mixing-compilers.md b/web/input/doc/faq/mixing-compilers.md new file mode 100644 index 0000000..8c7bad6 --- /dev/null +++ b/web/input/doc/faq/mixing-compilers.md @@ -0,0 +1,20 @@ +title: Mixing compilers +parent: FAQ +--- + +# Building check\_mysql fails on Solaris + +If you are using GCC and your MySQL version was compiled using Sun's C +compiler (or the other way round), then it is likely that the configure +options will fail, as the configure script will run `mysql_config` to get the +appropriate `CFLAGS`. + +There are various options: + +* Disable `check_mysql` by running `./configure` `--without-mysql`. +* Allow `./configure` to finish, but manually amend `plugins/Makefile` and + remove any non-GCC flags in `MYSQLCFLAGS`. +* Use Sun's C compiler to compile the plugins. +* Use a GCC-compiled version of MySQL. + + diff --git a/web/input/doc/faq/nagiosmib.md b/web/input/doc/faq/nagiosmib.md new file mode 100644 index 0000000..b2f34ae --- /dev/null +++ b/web/input/doc/faq/nagiosmib.md @@ -0,0 +1,45 @@ +title: Modifying NagiosMIB +parent: FAQ +--- + +# How do I modify NagiosMIB? + +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][libsmi] + +On Debian, you'd run: + + apt-get install smistrip smitools + +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 + +These are probably okay. + +To change the MIB information, update the `src-mib` directory and run `make` +to generate the MIBs. Run `make` `test` to check. + +Update the `CHANGES` file and commit. + +To release, change the version number in the `Makefile` and run `make` +`tarball`. Publish the tarball and md5sum. Create a news story on this site. +Link back to here from the tarball release. + +[libsmi]: http://www.ibr.cs.tu-bs.de/projects/libsmi/ "libsmi" + + diff --git a/web/input/doc/faq/nptest.md b/web/input/doc/faq/nptest.md new file mode 100644 index 0000000..71fda44 --- /dev/null +++ b/web/input/doc/faq/nptest.md @@ -0,0 +1,42 @@ +title: NPTest +parent: FAQ +--- + +# How do the NPTest parameters work? + +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: +`getTestParameter` and `testCmd`. + +## getTestParameter + +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: + +* default value +* the value that you check against in the test script +* an empty string, which is returned by getTestParameter when the test is run + via automated testing (technically, when no terminal is associated to the + test run) + +You should try and ensure current tests are not affected when a new parameter +is added. So it may be 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. + +## testCmd + +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. + + diff --git a/web/input/doc/faq/ownership.md b/web/input/doc/faq/ownership.md new file mode 100644 index 0000000..58bc311 --- /dev/null +++ b/web/input/doc/faq/ownership.md @@ -0,0 +1,25 @@ +title: Ownership +parent: FAQ +--- + +# Which user owns the installed plugins? + +If you run `./configure` `--with-user=nagios`, then at `make` `install` time, +the installation will set the ownership of the plugins to the nagios user +(similarly for `--with-group`). If these options are not set, the plugins +will be installed with the install user's owner and group permissions - it is +your responsibility to set other permissions, if required. + +The only exception are root plugins. These are under `plugins-root/` and are +also installed with the install user's owner and group permissions. + +If you run: + + make install-root + +This will set permissions to root, assuming you are either root or using +fakeroot. If not, the setuid bit is still set, but the plugin may not work +correctly. This is the behaviour used by coreutils for the `su` binary and is +duplicated in this project. + + diff --git a/web/input/doc/faq/private-c-api.md b/web/input/doc/faq/private-c-api.md new file mode 100644 index 0000000..585ca42 --- /dev/null +++ b/web/input/doc/faq/private-c-api.md @@ -0,0 +1,116 @@ +title: Private C APIs +parent: FAQ +--- + +# Private C APIs + +This page describes the Nagios Plugins 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 [Development Guidelines][guidelines]. + +## Basic Functions + +### np\_init(char \*plugin\_name, int argc, char \*\*argv) + +Initialize the Nagios Plugins routines. Pass the plugin name and `argc` and +`argv` from `main()`. + +A variable `nagios_plugin` will be created for internal use. + +### np\_set\_args(int argc, char \*\*argv) + +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. + +### np\_cleanup(void) + +Used to clean up allocated memory by the `nagios_plugin` variable. This is +called by the `die()` routine before exiting. + +## State Information + +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: + +* There will be problems if a remote host is checked from two different Nagios + instances, as the state file on the remote host will be updated twice as + often. +* Binary data may not restore on a program compiled with different options + from the program that saved it (e.g., 32 or 64 bit). +* Binary data may include a structure containing a pointer. Pointer values + may not be used in the reading program - i.e., you need to overwrite the + value with something `malloc(3)`ed in the current run of the program. +* State files could be left lying around. We recommend you run a regular job + to remove unmodified state files older than 1 week. + +### np\_enable\_state(char \*keyname, int data\_version) + +Enables the plugin state retention routines. Will set the filename for the +state file to be `.../{keyname}`. + +The `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][extra-opts] parsed version, if applicable). + +*Note:* The `keyname` should be uniquely defined for a particular service, to +avoid a second 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`. + +### np\_state\_read(void) + +Reads the state file and returns a `state_data` variable. + +This routine will call `die()` with `UNKNOWN` if: + +* There was a problem reading the state file. + +Returns `NULL` if: + +* No state file exists - this is possible on the first run. +* The state file format (internally held by the plugin) does not match. +* The state data format (passed in `np_enable_state()`) does not match. + +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 pointer 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; + +### np\_state\_write\_string(time\_t data\_time, char \*string) + +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. + +### np\_state\_write\_binary(time\_t data\_time, char \*start, int length) + +Same as `np_state_write_string()`, but writes binary data. *Currently +unimplemented.* + +[guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines" +[extra-opts]: doc/extra-opts.html "Extra-Opts" + + diff --git a/web/input/doc/faq/ps-on-solaris.md b/web/input/doc/faq/ps-on-solaris.md new file mode 100644 index 0000000..801c695 --- /dev/null +++ b/web/input/doc/faq/ps-on-solaris.md @@ -0,0 +1,38 @@ +title: Process listings on Solaris +parent: FAQ +--- + +# Why use pst3 for check\_procs on Solaris? + +Solaris systems restrict the information that is available when you run `ps`. +On other Unix systems, running `ps` will list you the entire arguments, but +Solaris restricts the arguments to the first 64 characters at the kernel. + +This is a problem if you need to access the arguments to find out a specific +process (common for listing Java programs). + +`/usr/ucb/ps` does list the full arguments, but only for your own processes. +If you are root, then running `/usr/ucb/ps` can get the full arguments for all +processes. However, the columns for `RSS` and `VSZ` merge together when the +values are too large and check\_procs cannot pull the value out correctly. + +The chosen approach is to create our own `ps`-like command, `pst3`. This +outputs the required information in a known format for `check_procs` to parse. +This is the default if you run `./configure` on a Solaris system. + +Because `pst3` needs access to some kernel structures, it needs to be compiled +in 32 and 64 bit modes. + +If you are comfortable with the limitations, it is possible to use a Solaris +`ps` command by specifying these options to `./configure`: + + --with-ps-command="/usr/bin/ps -eo 's uid pid ppid vsz rss pcpu etime comm args'" \ + --with-ps-format="%s %d %d %d %d %d %f %s %s %n" \ + --with-ps-cols=10 \ + --with-ps-varlist="procstat,&procuid,&procpid,&procppid,\ + &procvsz,&procrss,&procpcpu,procetime,procprog,&pos" + +The `--with-ps-varlist` should be on one line - separated here for +readability. + + diff --git a/web/input/doc/faq/reuse.md b/web/input/doc/faq/reuse.md new file mode 100644 index 0000000..6c8e7b0 --- /dev/null +++ b/web/input/doc/faq/reuse.md @@ -0,0 +1,44 @@ +title: Code reuse +parent: FAQ +--- + +# Can I use Nagios Plugins in my project? + +Firstly, there is a distinction between a Nagios plugin and plugins from the +Nagios Plugins project. + +Although Nagios (the system) is licensed under the GPL, plugins are executed +in their own environment, so they [do not fall][aggregation] under the "viral" +aspect of the GPL. Therefore, any plugin written for use by Nagios can be +under any license the copyright holder selects. + +However, the plugins contained within the Nagios Plugins project are +distributed under the [GPL][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 licensed under the GPL, +although you own the copyright for your modified portions. + +*Derivative work* usually includes: + +* modified versions of the plugins +* other software that contains code (modified or not) copied from the plugins +* other software that `#include`s header files from the plugins +* other software that has linked against library files from the plugins + +and does not usually include: + +* other software that parses the output of a plugin run from the command line, + exit status, etc. +* software that provides a "wrapper" for command line execution of the plugin +* software that uses status codes and other values which are in the header + files, but also described in the documentation (though not including or + linking to the source) + +[aggregation]: http://www.gnu.org/licenses/gpl-faq.html#MereAggregation "GPL FAQ: Mere Aggregation" +[gpl]: http://www.gnu.org/licenses/gpl.html "GPLv3" + + diff --git a/web/input/doc/faq/root-plugins.md b/web/input/doc/faq/root-plugins.md new file mode 100644 index 0000000..b5db74d --- /dev/null +++ b/web/input/doc/faq/root-plugins.md @@ -0,0 +1,27 @@ +title: Root plugins +parent: FAQ +--- + +# Why aren't the root plugins installed? + +There are a few plugins which require root access, namely check\_dhcp and +check\_icmp. These are compiled under the `plugins-root` subdirectory. A +`make` `install` will install them with the install user's owner and group +permissions. However, if you run `make` `install` without being root, this +message will appear: + + WARNING: insufficient access; not installing setuid plugins + NOTE: to install setuid plugins, run 'make install-root' as root + +To install, run as root: + + make install-root + +Even if you are not root, the plugins will still be installed. This is for +packagers which can then alter the permissions of the plugins before +packaging. + +This behaviour is used by coreutils for the `su` binary and is duplicated for +this project. + + diff --git a/web/input/doc/faq/ssl.md b/web/input/doc/faq/ssl.md new file mode 100644 index 0000000..4f8b2cc --- /dev/null +++ b/web/input/doc/faq/ssl.md @@ -0,0 +1,15 @@ +title: SSL libraries +parent: FAQ +--- + +# Why doesn't the --ssl option work? + +To get the SSL features, you need to have the SSL libraries available. Either +[OpenSSL][openssl] or [GntTLS][gnutls] is suitable. + +Check the `./configure` output to see if the SSL libraries have been detected. + +[openssl]: http://www.openssl.org/ "OpenSSL" +[gnutls]: http://www.gnutls.org/ "GnuTLS" + + diff --git a/web/input/doc/faq/use-perl-module.md b/web/input/doc/faq/use-perl-module.md new file mode 100644 index 0000000..64ba18a --- /dev/null +++ b/web/input/doc/faq/use-perl-module.md @@ -0,0 +1,37 @@ +title: Using Nagios::Plugin +parent: FAQ +--- + +# How do I use the Nagios::Plugin module? + +The Nagios::Plugin Perl module can be obtained from two main locations: + +* from the Nagios Plugins tarball with an + [extra configure option][configure-module] +* from [CPAN][cpan-module] + +If you install from the Nagios Plugins tarball, the Perl module will be +installed in `$prefix/perl`. + +If you install from CPAN, the Perl module will be installed into your Perl's +system directories by default. + +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. + +[configure-module]: doc/faq/build-perl-module.html "configure with Nagios::Plugin" +[cpan-module]: http://search.cpan.org/dist/Nagios-Plugin/ "Nagios::Plugin on CPAN" + + -- cgit v0.10-9-g596f