summaryrefslogtreecommitdiffstats
path: root/web/input
diff options
context:
space:
mode:
authorHolger Weiss <holger@zedat.fu-berlin.de>2014-01-11 16:38:18 (GMT)
committerHolger Weiss <holger@zedat.fu-berlin.de>2014-01-11 16:38:18 (GMT)
commit7b0fa5d642466e7cdd0d326658c3c06c27f8a1ec (patch)
tree1bd1fe366d4063f29ed6930b0750c6bd7a72b7e9 /web/input
parent16bf58546355690e0d9cf4e7d181255aac73b5c6 (diff)
downloadsite-7b0fa5d642466e7cdd0d326658c3c06c27f8a1ec.tar.gz
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
Diffstat (limited to 'web/input')
-rw-r--r--web/input/development.md13
-rw-r--r--web/input/doc/faq/build-perl-module.md15
-rw-r--r--web/input/doc/faq/compilation.md18
-rw-r--r--web/input/doc/faq/configure-hangs.md21
-rw-r--r--web/input/doc/faq/contribute.md26
-rw-r--r--web/input/doc/faq/control.md16
-rw-r--r--web/input/doc/faq/donations.md16
-rw-r--r--web/input/doc/faq/extra-tests.md26
-rw-r--r--web/input/doc/faq/git.md197
-rw-r--r--web/input/doc/faq/gnulib.md36
-rw-r--r--web/input/doc/faq/guidelines.md12
-rw-r--r--web/input/doc/faq/index.md62
-rw-r--r--web/input/doc/faq/installation.md14
-rw-r--r--web/input/doc/faq/libtap.md26
-rw-r--r--web/input/doc/faq/license.md19
-rw-r--r--web/input/doc/faq/mixing-compilers.md20
-rw-r--r--web/input/doc/faq/nagiosmib.md45
-rw-r--r--web/input/doc/faq/nptest.md42
-rw-r--r--web/input/doc/faq/ownership.md25
-rw-r--r--web/input/doc/faq/private-c-api.md116
-rw-r--r--web/input/doc/faq/ps-on-solaris.md38
-rw-r--r--web/input/doc/faq/reuse.md44
-rw-r--r--web/input/doc/faq/root-plugins.md27
-rw-r--r--web/input/doc/faq/ssl.md15
-rw-r--r--web/input/doc/faq/use-perl-module.md37
25 files changed, 919 insertions, 7 deletions
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]:
19 19
20Contributions are always welcome! If you'd like to provide patches, please 20Contributions are always welcome! If you'd like to provide patches, please
21[fork][fork] the desired repository and submit a [pull request][pull]. In 21[fork][fork] the desired repository and submit a [pull request][pull]. In
22case you're not familiar with Git, you might want to look into [Scott 22case you're not familiar with Git, you might want to look into our [short
23Chacon][scott]'s [Pro Git][book] book available on the [Git web site][git] 23introduction][git-intro] or [some other Git documentation][git-ref], first.
24first.
25 24
26## Development Guidelines 25## Development Guidelines
27 26
@@ -42,6 +41,8 @@ commands:
42 $ make 41 $ make
43 $ make test 42 $ make test
44 43
44Also see our testing-related [development FAQs][dev-faq].
45
45Regular tests of the latest code are scheduled automatically on various 46Regular tests of the latest code are scheduled automatically on various
46platforms, the results can be [viewed online][tests]. 47platforms, the results can be [viewed online][tests].
47 48
@@ -50,11 +51,11 @@ platforms, the results can be [viewed online][tests].
50[github]: https://github.com/ "GitHub" 51[github]: https://github.com/ "GitHub"
51[fork]: https://help.github.com/articles/fork-a-repo "Fork Documentation" 52[fork]: https://help.github.com/articles/fork-a-repo "Fork Documentation"
52[pull]: https://help.github.com/articles/using-pull-requests "Pull Request Documentation" 53[pull]: https://help.github.com/articles/using-pull-requests "Pull Request Documentation"
53[scott]: http://scottchacon.com/ "Scott Chacon" 54[git-intro]: doc/faq/git.html "Quick Git Introduction"
54[book]: http://git-scm.com/book "Pro Git" 55[git-ref]: doc/faq/git.html#references "Git References"
55[git]: http://git-scm.com/ "Git"
56[guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines" 56[guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines"
57[libtap]: http://jc.ngo.org.uk/trac-bin/trac.cgi/wiki/LibTap "LibTap Homepage" 57[libtap]: http://jc.ngo.org.uk/trac-bin/trac.cgi/wiki/LibTap "LibTap Homepage"
58[dev-faq]: doc/faq/#development "Development FAQs"
58[tests]: tests.html "Test Results" 59[tests]: tests.html "Test Results"
59 60
60<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %--> 61<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Building Nagios::Plugin
2parent: FAQ
3---
4
5# How do I build Nagios::Plugin?
6
7This is currently an optional setting at configure time. You need to run:
8
9 ./configure --enable-perl-modules
10
11Then, `make`, `make` `install`, `make` `test`, and `make` `clean` will include
12the Perl modules that are in the `perlmods/` directory as expected. They are
13installed into `$prefix/perl`.
14
15<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Building Nagios Plugins
2parent: FAQ
3---
4
5# How do I compile the plugins?
6
7To compile version `1.x` of the plugins, you run:
8
9 gzip -dc nagios-plugins-1.x.tar.gz | tar -xf -
10 cd nagios-plugins-1.x
11 ./configure
12 make
13
14You can then [install the plugins][installation].
15
16[installation]: doc/faq/installation.html "Installation"
17
18<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Configure hangs
2parent: FAQ
3---
4
5# The configure script appears to hang
6
7If you find that the configure script appears to hang on this line:
8
9 checking for redhat spopen problem...
10
11Then you probably have a badly configured DNS server. This part of configure
12is testing for a pthread problem in BIND that is a kernel problem on some Red
13Hat derived versions of Linux (around kernel 2.6.9-11). It runs 10 x 100
14nslookup calls to see if your kernel has this problem. If it does, then at
15least one of those calls will fail. Failure rate could be anywhere between 1%
16and 50%.
17
18To force the workaround and ignore the test, run `./configure` with the
19`--enable-redhat-pthread-workaround` switch.
20
21<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Can I submit a patch?
2parent: FAQ
3---
4
5# Can I submit a patch?
6
7Of course you can! This is an open source project!
8
9Ideally, [fork][fork] our [repository][repo] and create a [pull request][pull]
10on [GitHub][github], so your patch doesn't get lost. Then chase up via the
11[development mailing list][list], if nothing happens. But be aware, this
12project is run by volunteers, so there is not necessarily immediate response!
13
14By submitting a pull request, you are stating that this is your own work or
15you have full rights to it. If your pull request is accepted, we will (of
16course) retain the Git author name and email address, and we'll add your name
17to the list of contributors in the [THANKS][thanks] file.
18
19[repo]: https://github.com/nagios-plugins/repositories "Our Repositories"
20[fork]: https://help.github.com/articles/fork-a-repo "Fork Documentation"
21[pull]: https://help.github.com/articles/using-pull-requests "Pull Request Documentation"
22[github]: https://github.com/ "GitHub"
23[list]: list/listinfo/devel/ "Development Mailing List"
24[thanks]: repositories/nagios-plugins/plain/THANKS.in "THANKS File"
25
26<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Who controls the project?
2parent: FAQ
3---
4
5# Who controls the Nagios Plugins project?
6
7[Nagios Enterprises][enterprises] own the Nagios Plugins project, hence the
8domain names of the site belong to Nagios Enterprises. However, the [Nagios
9Plugins Development Team][team] are responsible for the running of the
10project. This means that decisions about the web site and the development of
11code related to the project are handled independently by the team.
12
13[enterprises]: http://www.nagios.com/about/company "Nagios Enterprises"
14[team]: team.html "Nagios Plugins Development Team"
15
16<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Do you accept donations?
2parent: FAQ
3---
4
5# Do you accept donations?
6
7The [Nagios Plugins Development Team][team] accepts donations for the project.
8We have a separate Paypal account that is used for donations, which is
9administered by the team leader.
10
11Donations go towards paying for the small administrative charges we have. We
12might also use some of the funds for team beer when we meet up in person.
13
14[team]: team.html "Nagios Plugins Development Team"
15
16<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Testing C routines
2parent: FAQ
3---
4
5# Can I add extra tests to the C routines?
6
7The idea with the testing is to move as many functions as possible "lower
8down"; i.e., to the `lib/utils_*.c` files. These functions can then be tested
9using the libtap routines in the `lib/tests/test_*.c` files. It is easier to
10do unit testing here than to try and do higher level plugin testing, because
11you can fake data easier at this level.
12
13The routines available via [libtap][libtap] are equivalent to Perl's
14[Test::Simple][test-simple] ones.
15
16The libtap tests are separated out from the plugins ones (in `plugins/t`)
17because:
18
191. They are testing the files in `lib/`, so should reside there.
202. They require [compiling][compilation] to run.
21
22[libtap]: http://jc.ngo.org.uk/trac-bin/trac.cgi/wiki/LibTap "libtap"
23[test-simple]: http://search.cpan.org/dist/Test-Simple/lib/Test/Simple.pm "Test::Simple Module"
24[compilation]: doc/faq/compilation.html "Compilation"
25
26<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Git
2parent: FAQ
3---
4
5# How do I use Git?
6
7After the 1.4.13 release, the [Nagios Plugins Development Team][team] moved to
8[Git][git] for its code repositories. This document is a quick introduction
9to Git.
10
11## Differences Between Git and SVN
12
13There is one huge difference between Git and SVN: Git is a distributed SCM
14(Source Code Management system) while SVN is a centralized one. This doesn’t
15mean we can’t have a central shared Git repository (and we indeed have one),
16this means distributed development can occur around that central repository.
17Another visible difference is that Git have more stages between the working
18directory and the repository. When you want to add files or changes, you use
19**git add**. This adds the changes to the repository index, which can be seen
20as a staging area. When you commit with **git commit**, only the changes in
21the index are considered. After committing, the changes are still local. To
22share it with others, you have to push it to a remote repository, or gave
23someone pull from your publicly accessible repository (in most case you will
24still have to push changes there, unless if you were running a git daemon
25straight off your working repository). Finally you can’t miss the fact that
26there is no more revision numbers, and the distributed nature of Git is the
27reason for that: there is absolutely no way a single number could be tracked
28in a distributed way. Instead Git uses SHA1 hashes to identify commits (as
29well as other objects in the repository). Each branch and tag refer to an
30object name (SHA1 hash), and each commits have one or more parents (commit
31objects). Although SHA1 hashes are 40 digits long, with Git you only have to
32type a handful of digits to reference one.
33
34## Cloning a Project
35
36To work on a project you first have to clone it. This creates your own local
37repository and until you want to distribute your change or merge changes from
38someone else everything that follows can happen offline. If you have push
39access, run the command:
40
41 git clone git@github.com:nagios-plugins/nagios-plugins.git
42
43If you just want a local copy or wish to clone it to your workstation, you can
44run this command instead:
45
46 git clone git://github.com/nagios-plugins/nagios-plugins.git
47
48This will create a directory called `nagios-plugins` in your current directory
49with all the `master` code and history (this is roughly equivalent to CVS/SVN
50`HEAD`). Change directory to `nagios-plugins`.
51
52## Editing Files
53
54You can edit the files in the working area. To check the status, use:
55
56 git status
57
58This will show a list of changes in the working directory. Newly made changes
59appear in *red*, while changes added to the index are shown in green. You can
60use **git diff** to see changes between the current working directory and the
61index (untracked files will not be shown).
62
63## Committing Files
64
65Use **git add** to specify which new files/changes you want to commit; this
66will add the changes to the index. You can select only partial diffs with
67**git add -p** too. If you want to commit everything you can use **git commit
68-a** directly. You can see the changes you are about to commit (difference
69between HEAD and the index) with **git diff --cached**, and then commit them
70with:
71
72 git commit
73
74Add a comment (you have read the [Development Guidelines][guidelines], right?
75:-)). This commit will be local (affecting only your own repository) so you
76will have to either push your changes, or have someone to pull them from you
77(in the latter case you will most likely still push to a publicly accessible
78clone of your local repository). If the change is from a contributor, set the
79author at commit time:
80
81 git commit --author="Jane Doe <jane@example.com>"
82
83If you realize that you forgot something in your commit and haven’t pushed it
84yet to a remote repository, you can amend your last commit with **git commit
85--amend**. You can also amend after a push and force the next update, however
86this will cause non-linear updates and should be done only if the developers
87using your repository are aware of it.
88
89## Reverting Local Modifications
90
91You can revert local modifications with the following steps. First, if you
92have already staged the changes you will have to unstage them. As indicated
93in the **git status** message you can do so with the following command:
94
95 git reset HEAD <file>
96
97Then you can revert unstaged changes with:
98
99 git checkout <file>
100
101If you have already committed changes locally and need to undo your commit(s),
102you can use **git reset**. First find the commit names with **git log** and
103then do either one of these: To keep local modifications (you can commit them
104again, stash them, etc.)
105
106 git reset --soft <commit>
107
108Note that for the purpose of “re-doing” the last commit, **git commit
109--amend** will be much easier than a reset/commit with the same end result.
110To discard local modifications (if you lose important changes with this
111command you may be able to recover them with **git reflog** and **git checkout
112<commit\>**):
113
114 git reset --hard <file>
115
116Do not reset changes that have already been pushed to remote repositories as
117this will cause non-linear updates. If you do so, developers using those
118repositories should be aware of it.
119
120## Merging Remote Changes
121
122When you work on your local repository you’ll need to keep it up to date with
123the development tree. This is very similar to **svn update** with the
124difference that it can’t be done if the working tree has any unmerged changes.
125If you do, either commit them or put them aside (Tip: **git stash**). If you
126cloned from the main Git repository, this command will do a fetch then merge
127any new changes:
128
129 git pull
130
131You can also merge changes from any other fork of the repository. This
132usually happens if someone ask you to pull from his own repo for some fix or
133enhancements. Together with **--no-commit** you will have a chance to review
134the changes and make any relevant correction before the merge. Example:
135
136 git pull --no-commit git://example.com/path/to/repo.git master
137
138## Merging Back to the Main Repository
139
140Once you’re done with your commits and after pulling from the main repository,
141you can push you change back to it. If you cloned using the *push* url this
142command will push the master branch:
143
144 git push
145
146It you’re trying to push something that would generate merge conflicts, the
147push will be rejected. You will have yo do a pull first, fix the any
148conflicts locally and then push again. If your commits are local (you haven’t
149pulled them from someone else or published them somewhere) you can rebase to
150avoid a merge:
151
152 git pull --rebase
153
154Like a merge, this may generate conflicts and let you fix them, but instead of
155creating a merge commit on top of the others, it will undo your commits,
156fast-forward and apply your commits again. This is cleaner but doesn’t play
157well when it rewrites already published history.
158
159## Going Further
160
161This is a very quick introduction to Git. There are a lot more useful
162commands for manipulating changes and working with others. They are all very
163well documented (see **git help [-a]** for a list of commands, **git help
164<cmd\>** or **git <cmd\> --help** shows the man page). You might also want to
165look into some of the references listed below, or into a book such as [Scott
166Chacon][scott]'s [Pro Git][book].
167
168## References
169
170- Intro to Distributed Version Control (Illustrated)
171 <http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/>
172- A tutorial introduction to Git
173 <https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html>
174- Everyday Git With 20 Commands Or So
175 <http://www.kernel.org/pub/software/scm/git/docs/everyday.html>
176- Git User’s Manual
177 <http://www.kernel.org/pub/software/scm/git/docs/user-manual.html>
178- Git - SVN Crash Course
179 <http://git.or.cz/course/svn.html>
180- Git QuickStart
181 <http://git.or.cz/gitwiki/QuickStart>
182- Git CheatSheet
183 <http://git.or.cz/gitwiki/GitCheatSheet>
184- Understanding Git Conceptually
185 <http://www.eecs.harvard.edu/~cduan/technical/git/>
186- The Git Parable
187 <http://tom.preston-werner.com/2009/05/19/the-git-parable.html>
188- Git for Computer Scientists
189 <http://eagain.net/articles/git-for-computer-scientists/>
190
191[team]: team.html "Nagios Plugins Development Team"
192[guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines"
193[git]: http://git-scm.com/ "Git"
194[scott]: http://scottchacon.com/ "Scott Chacon"
195[book]: http://git-scm.com/book "Pro Git"
196
197<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Gnulib
2parent: FAQ
3---
4
5# How do I use and update Gnulib?
6
7[Gnulib][gnulib] provides replacement implementations of functions that are
8not available on all (Unix-like) operating systems. In order to sync with the
9latest Gnulib code, do something like:
10
11 git clone git://git.savannah.gnu.org/gnulib.git
12 cd gnulib
13 GNULIB_HEAD=$(git rev-parse --short HEAD)
14 cd ..
15 git clone git@github.com:nagios-plugins/nagios-plugins.git
16 cd nagios-plugins
17 ../gnulib/gnulib-tool --update
18 find gl -name '*~' -o -name '.gitignore' | xargs rm
19 git status
20 git add gl
21 git commit -m "Sync with latest Gnulib code ($GNULIB_HEAD)"
22
23In order to make a given function available via Gnulib (on systems which don't
24provide that function), the [corresponding module][modules] must be imported
25using `gnulib-tool`, e.g. (in order to add the `strcase` module):
26
27 ../gnulib/gnulib-tool --no-vc-files --import strcase
28 find gl -name '*~' | xargs rm
29 git status
30 git add gl
31 git commit -m 'Add Gnulib module "strcase"'
32
33[gnulib]: http://www.gnu.org/software/gnulib/ "Gnulib"
34[modules]: http://www.gnu.org/software/gnulib/MODULES.html "Gnulib Modules"
35
36<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Guidelines
2parent: FAQ
3---
4
5# How should a plugin be written?
6
7The [Nagios Plugin Development Guidelines][guidelines] provide the
8specifications for writing a plugin.
9
10[guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines"
11
12<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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
4 4
5# FAQ 5# FAQ
6 6
7The list of Frequently Asked Questions (FAQ) will come back soon. 7This is a list of Frequently Asked Questions (FAQ) regarding the Nagios
8Plugins.
9
10## General
11
12* [Who controls the Nagios Plugins project?][control]
13* [What license is the code distributed under?][license]
14* [Can I submit a patch?][contribute]
15* [Do you accept donations?][donations]
16
17## Compiling
18
19* [How do I compile the plugins?][compilation]
20* [The configure script appears to hang][configure-hangs]
21* [Why doesn't the --ssl option work?][ssl]
22* [How do I build the Nagios::Plugin module?][build-perl-module]
23* [Building check\_mysql fails on Solaris][mixing-compilers]
24* [Why use pst3 for check\_procs on Solaris?][ps-on-solaris]
25
26## Installing
27
28* [How do I install the plugins?][installation]
29* [Why aren't the root plugins installed?][root-plugins]
30* [Which user owns the installed plugins?][ownership]
31
32## Development
33
34* [How do I use Git?][git]
35* [How should a plugin be written?][guidelines]
36* [Private C APIs][c-apis]
37* [How do I prove the C routines work?][libtap]
38* [Can I add extra tests to the C routines?][extra-tests]
39* [How do the NPTest parameters work?][nptest]
40* [How do I use and update Gnulib?][gnulib]
41* [How do I use the Nagios::Plugin module?][use-perl-module]
42* [How do I modify NagiosMIB?][nagiosmib]
43* [Can I use Nagios Plugins in my project?][reuse]
44
45[control]: doc/faq/control.html
46[license]: doc/faq/license.html
47[contribute]: doc/faq/contribute.html
48[donations]: doc/faq/donations.html
49[compilation]: doc/faq/compilation.html
50[configure-hangs]: doc/faq/configure-hangs.html
51[ssl]: doc/faq/ssl.html
52[build-perl-module]: doc/faq/build-perl-module.html
53[mixing-compilers]: doc/faq/mixing-compilers.html
54[ps-on-solaris]: doc/faq/ps-on-solaris.html
55[installation]: doc/faq/installation.html
56[root-plugins]: doc/faq/root-plugins.html
57[ownership]: doc/faq/ownership.html
58[git]: doc/faq/git.html
59[guidelines]: doc/faq/guidelines.html
60[c-apis]: doc/faq/private-c-api.html
61[libtap]: doc/faq/libtap.html
62[extra-tests]: doc/faq/extra-tests.html
63[nptest]: doc/faq/nptest.html
64[gnulib]: doc/faq/gnulib.html
65[use-perl-module]: doc/faq/use-perl-module.html
66[nagiosmib]: doc/faq/nagiosmib.html
67[reuse]: doc/faq/reuse.html
8 68
9<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %--> 69<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Installing Nagios Plugins
2parent: FAQ
3---
4
5# How do I install the plugins?
6
7After [compiling][compilation] the plugins, you can run the following command
8to install them:
9
10 make install
11
12[compilation]: doc/faq/compilation.html "Compilation"
13
14<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: libtap
2parent: FAQ
3---
4
5# How do I prove the C routines work?
6
7We use [libtap][libtap] to test C routines that are in `lib/utils_*.c`. The
8tests are in `lib/tests/test_*.c`.
9
10The latest libtap version is currently 1.01. However, there is a bug with the
11thread implementation. To workaround, run:
12
13 CPPFLAGS="-UHAVE_LIBPTHREAD" ./configure
14 make
15 make check
16 make install
17
18Now when you run the Nagios Plugins `./configure` script, it should find the
19libtap library and compile the tests and run them when you run `make` `test`.
20
21*Update:* These days, the Nagios Plugins tarball includes a copy of libtap
22which is used if you run `./configure` `--enable-libtap`.
23
24[libtap]: http://jc.ngo.org.uk/trac-bin/trac.cgi/wiki/LibTap "libtap"
25
26<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: What license is used?
2parent: FAQ
3---
4
5# What license is the code distributed under?
6
7The Nagios Plugins code is currently distributed using the [GNU General Public
8License, Version 3][gpl] (GPLv3).
9
10This is because some C code that we depend upon, from the [Gnulib][gnulib]
11project, is distributed under the GPLv3; and therefore, some of our plugins
12also need to be GPLv3 licensed. The team has decided, rather than having a
13mixed license, we'll distribute all of the core Nagios Plugins code under the
14GPLv3.
15
16[gpl]: http://www.gnu.org/licenses/gpl.html "GPLv3"
17[gnulib]: http://www.gnu.org/software/gnulib/ "Gnulib"
18
19<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Mixing compilers
2parent: FAQ
3---
4
5# Building check\_mysql fails on Solaris
6
7If you are using GCC and your MySQL version was compiled using Sun's C
8compiler (or the other way round), then it is likely that the configure
9options will fail, as the configure script will run `mysql_config` to get the
10appropriate `CFLAGS`.
11
12There are various options:
13
14* Disable `check_mysql` by running `./configure` `--without-mysql`.
15* Allow `./configure` to finish, but manually amend `plugins/Makefile` and
16 remove any non-GCC flags in `MYSQLCFLAGS`.
17* Use Sun's C compiler to compile the plugins.
18* Use a GCC-compiled version of MySQL.
19
20<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Modifying NagiosMIB
2parent: FAQ
3---
4
5# How do I modify NagiosMIB?
6
7Nagiosmib is a set of MIBs for Nagios to allow traps sent from Nagios to be
8recognized by other NMSes.
9
10To develop, the requirements are:
11
12* make
13* smistrip and smilint, part of the [libsmi project][libsmi]
14
15On Debian, you'd run:
16
17 apt-get install smistrip smitools
18
19If you get errors like:
20
21 ./MIB/NAGIOS-ROOT-MIB:4: failed to locate MIB module `SNMPv2-SMI'
22 ./MIB/NAGIOS-ROOT-MIB:6: failed to locate MIB module `SNMPv2-TC'
23
24then you are missing some prerequisite MIBs. These need to be installed from
25the libsmi project.
26
27Currently there are some warnings such as:
28
29 ./MIB/NAGIOS-ROOT-MIB:35: warning: current type `NotifyType' is not referenced in this module
30 ./MIB/NAGIOS-NOTIFY-MIB:153: warning: use Integer32 instead of INTEGER in SMIv2
31
32These are probably okay.
33
34To change the MIB information, update the `src-mib` directory and run `make`
35to generate the MIBs. Run `make` `test` to check.
36
37Update the `CHANGES` file and commit.
38
39To release, change the version number in the `Makefile` and run `make`
40`tarball`. Publish the tarball and md5sum. Create a news story on this site.
41Link back to here from the tarball release.
42
43[libsmi]: http://www.ibr.cs.tu-bs.de/projects/libsmi/ "libsmi"
44
45<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: NPTest
2parent: FAQ
3---
4
5# How do the NPTest parameters work?
6
7NPTest.pm is a perl module, originally written by Peter Bray, and provides
8some basic functions for testing the plugins. It has two main helpers:
9`getTestParameter` and `testCmd`.
10
11## getTestParameter
12
13Used to get parameters given in previous test runs. Use the 3 parameter
14version (the 4 parameter version is deprecated).
15
16Saved parameters are put in `/var/tmp/NPTest.cache`. Unfortunately, there is
17no easy way of altering this - you will have to manually change this file to
18edit existing parameters.
19
20If you are adding new parameters, there are three values for the parameters
21that you need to be aware of:
22
23* default value
24* the value that you check against in the test script
25* an empty string, which is returned by getTestParameter when the test is run
26 via automated testing (technically, when no terminal is associated to the
27 test run)
28
29You should try and ensure current tests are not affected when a new parameter
30is added. So it may be better to say `NP_INTERNET_ACCESS`, with information
31like *default "yes", disable with "no"* and check for
32`NP_INTERNET_ACCESS == "no"` to skip the tests.
33
34## testCmd
35
36This runs a command and returns an NPTest object back. You can combine
37Test::More routines with the object to get the return code, output or perf
38data to test against expected values.
39
40See `plugins/t/check_disk.t` as an example test script.
41
42<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Ownership
2parent: FAQ
3---
4
5# Which user owns the installed plugins?
6
7If you run `./configure` `--with-user=nagios`, then at `make` `install` time,
8the installation will set the ownership of the plugins to the nagios user
9(similarly for `--with-group`). If these options are not set, the plugins
10will be installed with the install user's owner and group permissions - it is
11your responsibility to set other permissions, if required.
12
13The only exception are root plugins. These are under `plugins-root/` and are
14also installed with the install user's owner and group permissions.
15
16If you run:
17
18 make install-root
19
20This will set permissions to root, assuming you are either root or using
21fakeroot. If not, the setuid bit is still set, but the plugin may not work
22correctly. This is the behaviour used by coreutils for the `su` binary and is
23duplicated in this project.
24
25<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Private C APIs
2parent: FAQ
3---
4
5# Private C APIs
6
7This page describes the Nagios Plugins routines that can be accessed from the
8internal library.
9
10This page is in development, so these are not guaranteed to be available. As
11the API matures and is available in libraries, this information will be
12migrated to the [Development Guidelines][guidelines].
13
14## Basic Functions
15
16### np\_init(char \*plugin\_name, int argc, char \*\*argv)
17
18Initialize the Nagios Plugins routines. Pass the plugin name and `argc` and
19`argv` from `main()`.
20
21A variable `nagios_plugin` will be created for internal use.
22
23### np\_set\_args(int argc, char \*\*argv)
24
25Sets the internally held `argc` and `argv` values.
26
27Shouldn't really need this, but due to `np_extra_opts()`, this is set after
28that call.
29
30### np\_cleanup(void)
31
32Used to clean up allocated memory by the `nagios_plugin` variable. This is
33called by the `die()` routine before exiting.
34
35## State Information
36
37Saving and restoring state allows a plugin to know the last results and thus
38work out differences. This is especially useful when a plugin is capturing
39counter information, which increases with every request.
40
41This currently works by saving state information to a file, though the API
42doesn't care what the backend implementation is.
43
44*Note:* Binary data is not currently supported.
45
46Some things to be aware of, if you use state information:
47
48* There will be problems if a remote host is checked from two different Nagios
49 instances, as the state file on the remote host will be updated twice as
50 often.
51* Binary data may not restore on a program compiled with different options
52 from the program that saved it (e.g., 32 or 64 bit).
53* Binary data may include a structure containing a pointer. Pointer values
54 may not be used in the reading program - i.e., you need to overwrite the
55 value with something `malloc(3)`ed in the current run of the program.
56* State files could be left lying around. We recommend you run a regular job
57 to remove unmodified state files older than 1 week.
58
59### np\_enable\_state(char \*keyname, int data\_version)
60
61Enables the plugin state retention routines. Will set the filename for the
62state file to be `.../{keyname}`.
63
64The `keyname` will have any non alphanumerics replaced with "`_`".
65
66If `keyname` is `NULL`, will generate an SHA1 `keyname` based on the `argv` of
67the plugin (using the [extra-opts][extra-opts] parsed version, if applicable).
68
69*Note:* The `keyname` should be uniquely defined for a particular service, to
70avoid a second invocation of the plugin to use the state information from a
71different invocation. If in doubt, set `keyname=NULL` and allow the routine
72to calculate the `keyname`.
73
74### np\_state\_read(void)
75
76Reads the state file and returns a `state_data` variable.
77
78This routine will call `die()` with `UNKNOWN` if:
79
80* There was a problem reading the state file.
81
82Returns `NULL` if:
83
84* No state file exists - this is possible on the first run.
85* The state file format (internally held by the plugin) does not match.
86* The state data format (passed in `np_enable_state()`) does not match.
87
88Your plugin should always check for `NULL`. It is recommended that your
89plugin returns `OK` on `NULL` as this is similar to a "first run".
90
91If valid data was read, a pointer will be returned which points to a struct
92of:
93
94 typedef struct state_data_struct {
95 time_t time;
96 void *data;
97 int length; /* Of binary data. */
98 } state_data;
99
100### np\_state\_write\_string(time\_t data\_time, char \*string)
101
102If `data_time==0`, use current time. Creates state file, with state format
103version. Writes data version, time, and data. Creates a temporary file and
104then renames into place. There is a possible loss of data if two things
105writing to same key at same time, but there will not be a corrupted state
106file.
107
108### np\_state\_write\_binary(time\_t data\_time, char \*start, int length)
109
110Same as `np_state_write_string()`, but writes binary data. *Currently
111unimplemented.*
112
113[guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines"
114[extra-opts]: doc/extra-opts.html "Extra-Opts"
115
116<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Process listings on Solaris
2parent: FAQ
3---
4
5# Why use pst3 for check\_procs on Solaris?
6
7Solaris systems restrict the information that is available when you run `ps`.
8On other Unix systems, running `ps` will list you the entire arguments, but
9Solaris restricts the arguments to the first 64 characters at the kernel.
10
11This is a problem if you need to access the arguments to find out a specific
12process (common for listing Java programs).
13
14`/usr/ucb/ps` does list the full arguments, but only for your own processes.
15If you are root, then running `/usr/ucb/ps` can get the full arguments for all
16processes. However, the columns for `RSS` and `VSZ` merge together when the
17values are too large and check\_procs cannot pull the value out correctly.
18
19The chosen approach is to create our own `ps`-like command, `pst3`. This
20outputs the required information in a known format for `check_procs` to parse.
21This is the default if you run `./configure` on a Solaris system.
22
23Because `pst3` needs access to some kernel structures, it needs to be compiled
24in 32 and 64 bit modes.
25
26If you are comfortable with the limitations, it is possible to use a Solaris
27`ps` command by specifying these options to `./configure`:
28
29 --with-ps-command="/usr/bin/ps -eo 's uid pid ppid vsz rss pcpu etime comm args'" \
30 --with-ps-format="%s %d %d %d %d %d %f %s %s %n" \
31 --with-ps-cols=10 \
32 --with-ps-varlist="procstat,&procuid,&procpid,&procppid,\
33 &procvsz,&procrss,&procpcpu,procetime,procprog,&pos"
34
35The `--with-ps-varlist` should be on one line - separated here for
36readability.
37
38<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Code reuse
2parent: FAQ
3---
4
5# Can I use Nagios Plugins in my project?
6
7Firstly, there is a distinction between a Nagios plugin and plugins from the
8Nagios Plugins project.
9
10Although Nagios (the system) is licensed under the GPL, plugins are executed
11in their own environment, so they [do not fall][aggregation] under the "viral"
12aspect of the GPL. Therefore, any plugin written for use by Nagios can be
13under any license the copyright holder selects.
14
15However, the plugins contained within the Nagios Plugins project are
16distributed under the [GPL][gpl]. If you distribute an application that
17includes the Nagios Plugins (modified or not), you are required to distribute
18a copy of the source code for the plugins under the terms of the GPL,
19regardless of the licensing for the rest of the application.
20
21If you write a plugin which is a derivative work from code of the Nagios
22Plugins project, then your plugin must also be licensed under the GPL,
23although you own the copyright for your modified portions.
24
25*Derivative work* usually includes:
26
27* modified versions of the plugins
28* other software that contains code (modified or not) copied from the plugins
29* other software that `#include`s header files from the plugins
30* other software that has linked against library files from the plugins
31
32and does not usually include:
33
34* other software that parses the output of a plugin run from the command line,
35 exit status, etc.
36* software that provides a "wrapper" for command line execution of the plugin
37* software that uses status codes and other values which are in the header
38 files, but also described in the documentation (though not including or
39 linking to the source)
40
41[aggregation]: http://www.gnu.org/licenses/gpl-faq.html#MereAggregation "GPL FAQ: Mere Aggregation"
42[gpl]: http://www.gnu.org/licenses/gpl.html "GPLv3"
43
44<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Root plugins
2parent: FAQ
3---
4
5# Why aren't the root plugins installed?
6
7There are a few plugins which require root access, namely check\_dhcp and
8check\_icmp. These are compiled under the `plugins-root` subdirectory. A
9`make` `install` will install them with the install user's owner and group
10permissions. However, if you run `make` `install` without being root, this
11message will appear:
12
13 WARNING: insufficient access; not installing setuid plugins
14 NOTE: to install setuid plugins, run 'make install-root' as root
15
16To install, run as root:
17
18 make install-root
19
20Even if you are not root, the plugins will still be installed. This is for
21packagers which can then alter the permissions of the plugins before
22packaging.
23
24This behaviour is used by coreutils for the `su` binary and is duplicated for
25this project.
26
27<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: SSL libraries
2parent: FAQ
3---
4
5# Why doesn't the --ssl option work?
6
7To get the SSL features, you need to have the SSL libraries available. Either
8[OpenSSL][openssl] or [GntTLS][gnutls] is suitable.
9
10Check the `./configure` output to see if the SSL libraries have been detected.
11
12[openssl]: http://www.openssl.org/ "OpenSSL"
13[gnutls]: http://www.gnutls.org/ "GnuTLS"
14
15<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
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 @@
1title: Using Nagios::Plugin
2parent: FAQ
3---
4
5# How do I use the Nagios::Plugin module?
6
7The Nagios::Plugin Perl module can be obtained from two main locations:
8
9* from the Nagios Plugins tarball with an
10 [extra configure option][configure-module]
11* from [CPAN][cpan-module]
12
13If you install from the Nagios Plugins tarball, the Perl module will be
14installed in `$prefix/perl`.
15
16If you install from CPAN, the Perl module will be installed into your Perl's
17system directories by default.
18
19To write your plugin, you should start it with:
20
21 use FindBin;
22 use lib "$FindBin::Bin/../perl/lib";
23 use Nagios::Plugin;
24
25This bit of code tells Perl to look for the Nagios::Plugin module in a
26directory relative to where the plugin is executed - this is a hard
27dependency. If Nagios::Plugin is not found there, Perl's system directories
28will be searched.
29
30This approach allows a system administrator to decide whether they want
31Nagios::Plugin installed via system directories or within the `$prefix` area
32of the plugins.
33
34[configure-module]: doc/faq/build-perl-module.html "configure with Nagios::Plugin"
35[cpan-module]: http://search.cpan.org/dist/Nagios-Plugin/ "Nagios::Plugin on CPAN"
36
37<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->