Permalink
Browse files

Updated documentation and added make.bat to easily build documentatio…

…n without using the full tool chain
  • Loading branch information...
1 parent f542694 commit d9318f296c3626c3ee795fcdc8be7c4bfb1bbdbb @mickem committed May 21, 2013
Showing with 3,051 additions and 24 deletions.
  1. +1 −1 docs/CMakeLists.txt
  2. BIN docs/_static/nsclient.png
  3. +3 −5 docs/_templates/indexcontent.html
  4. +30 −0 docs/_templates/layout.html
  5. +2 −2 docs/contents.rst
  6. +127 −4 docs/faq/index.rst
  7. +147 −0 docs/howto/03x_migration.rst
  8. +355 −0 docs/howto/external_scripts.rst
  9. BIN docs/howto/images/external-scripts-args-1.png
  10. BIN docs/howto/images/external-scripts-args-2.png
  11. BIN docs/howto/images/external-scripts-args-3.png
  12. BIN docs/howto/images/external-scripts.png
  13. +2 −0 docs/howto/index.rst
  14. +2 −2 docs/index.rst
  15. +242 −0 docs/make.bat
  16. +58 −0 docs/manual/about.rst
  17. +306 −0 docs/manual/getting_started.rst
  18. +5 −2 docs/manual/index.rst
  19. +75 −0 docs/manual/installing.rst
  20. +12 −0 docs/manual/nscp_client.rst
  21. +5 −0 docs/manual/nscp_service.rst
  22. +5 −0 docs/manual/nscp_settings.rst
  23. +7 −0 docs/manual/nscp_test.rst
  24. +95 −0 docs/manual/nscp_usage.rst
  25. +95 −0 docs/manual/theory.rst
  26. +263 −0 docs/tutorial/nagios/check_nt.rst
  27. BIN docs/tutorial/nagios/images/nagios-active-nrpe-001.png
  28. BIN docs/tutorial/nagios/images/nagios-active-nrpe-002.png
  29. BIN docs/tutorial/nagios/images/nagios-active-nrpe-003.png
  30. BIN docs/tutorial/nagios/images/nagios-active-nrpe.png
  31. BIN docs/tutorial/nagios/images/nagios-active-nsclient-001.png
  32. BIN docs/tutorial/nagios/images/nagios-active-nsclient-002.png
  33. BIN docs/tutorial/nagios/images/nagios-active-nsclient-003.png
  34. BIN docs/tutorial/nagios/images/nagios-active-nsclient-and-nrpe.png
  35. BIN docs/tutorial/nagios/images/nagios-active-nsclient.png
  36. BIN docs/tutorial/nagios/images/nagios-active-passive-roll-your-own.png
  37. BIN docs/tutorial/nagios/images/nagios-configuration-inheritance.png
  38. BIN docs/tutorial/nagios/images/nagios-passive-nsca-001.png
  39. BIN docs/tutorial/nagios/images/nagios-passive-nsca-002.png
  40. BIN docs/tutorial/nagios/images/nagios-passive-nsca-003.png
  41. BIN docs/tutorial/nagios/images/nagios-passive-nsca.png
  42. BIN docs/tutorial/nagios/images/nagios-server-check-nt.png
  43. BIN docs/tutorial/nagios/images/nrpe-overview.png
  44. BIN docs/tutorial/nagios/images/nsca-nsclient-internals.png
  45. BIN docs/tutorial/nagios/images/nsca-overview.png
  46. BIN docs/tutorial/nagios/images/windows-computer-active.png
  47. +77 −8 docs/tutorial/nagios/index.rst
  48. +359 −0 docs/tutorial/nagios/nrpe.rst
  49. +389 −0 docs/tutorial/nagios/nsca.rst
  50. +389 −0 docs/tutorial/nagios/nsca.rst.bak
  51. BIN resources/help.png
  52. BIN resources/nsclient.png
View
@@ -27,7 +27,7 @@ SET_TARGET_PROPERTIES(copy_docs PROPERTIES FOLDER "files")
IF(SPHINX_FOUND)
ADD_CUSTOM_TARGET(build_doc_sources
- COMMAND ${CMAKE_BINARY_DIR}/nscp py --load-all --script docs --format rst --output docs/source/reference
+ COMMAND ${CMAKE_BINARY_DIR}/nscp py --settings dummy --load-all --script docs --format rst --output docs/source/reference
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
DEPENDS nscp
COMMENT "Generate RST files")
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -9,7 +9,7 @@
<span class="linkdescr">start here</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("manual/index") }}">NSClient++ Manual</a><br/>
<span class="linkdescr">using and configuring NSClient++</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">Module Reference</a><br/>
+ <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">NSClient++ Reference</a><br/>
<span class="linkdescr">command line syntax, configuration of built-in commands and queries</span></p>
</td><td width="50%">
<p class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">Extending and Scripting</a><br/>
@@ -18,16 +18,14 @@
<span class="linkdescr">API for extending NSClient++</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">FAQs</a><br/>
<span class="linkdescr">frequently asked questions (with answers!)</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">HOWTOs</a><br/>
- <span class="linkdescr">in-depth documents on specific topics</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">HOWTOs and Guides</a><br/>
+ <span class="linkdescr">in-depth documents and guides on specific topics</span></p>
</td></tr>
</table>
<p><strong>Indices and tables:</strong></p>
<table class="contentstable" align="center"><tr>
<td width="50%">
- <p class="biglink"><a class="biglink" href="{{ pathto("py-modindex") }}">Command Index</a><br/>
- <span class="linkdescr">quick access to all commands and queries</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/>
<span class="linkdescr">...</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("glossary") }}">Glossary</a><br/>
@@ -0,0 +1,30 @@
+{% extends "!layout.html" %}
+{% block rootrellink %}
+ <li><img src="{{ pathto('_static/nsclient.png', 1) }}" alt=""
+ style="vertical-align: middle; margin-top: -1px"/></li>
+ <li><a href="http://www.nsclient.org/">NSClient++</a>{{ reldelim1 }}</li>
+ <li><a href="{{ pathto('index') }}">Documentation</a>{{ reldelim1 }}</li>
+{% endblock %}
+{% block footer %}
+ <div class="footer">
+ &copy; <a href="{{ pathto('copyright') }}">Copyright</a> {{ copyright|e }}.
+ <br />
+ NSClient++ is a non-profit project.
+ <a href="https://www.nsclient.org/nscp/wiki/sponsor">Please donate.</a>
+ <br />
+ Last updated on {{ last_updated|e }}.
+ <a href="{{ pathto('bugs') }}">Found a bug</a>?
+ <br />
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version|e }}.
+ </div>
+{% endblock %}
+{% block sidebarsourcelink %}
+{%- if show_source and has_source and sourcename %}
+<h3>{{ _('This Page') }}</h3>
+<ul class="this-page-menu">
+ <li><a href="{{ pathto('bugs') }}">Report a Bug</a></li>
+ <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
+ rel="nofollow">Show Source</a></li>
+</ul>
+{%- endif %}
+{% endblock %}
View
@@ -6,12 +6,12 @@
whatsnew/index.rst
tutorial/index.rst
- using/index.rst
+ manual/index.rst
reference/index.rst
extending/index.rst
api/index.rst
- howto/index.rst
faq/index.rst
+ howto/index.rst
glossary.rst
about.rst
View
@@ -4,10 +4,133 @@
FAQ: Frequently asked questions
#################################
-TODO
+1. Problems
+========
-Contents:
+1.1 I am having problems where do I start?
+******************************************
-.. toctree::
- :maxdepth: 2
+ NSCP has a built-in "test and debug" mode that you can activate with the following command
+.. code-block:: bat
+ nscp test
+
+ What this does is two things.
+ 1. it starts the daemon as "usual" with the same configuration and such.
+ 2. it enables debug logging and logs to the console.
+ This makes it quite easy to see what is going on and why things go wrong.
+
+1.2 Failed to open performance counters
+***************************************
+ * The first thing to check is the version. If you are using an old version (pre 0.3.x) upgrade!
+ * Second thing to check is whether the servers' performance counters working?
+ Sometimes the performance counters end up broken and need to be rebuilt there is a command to validate performance counters:
+.. code-block:: bat
+
+ nscp sys --validate
+
+For details: Microsoft KB: http://support.microsoft.com/kb/300956 essentially you need to use the "lodctr /R" command.
+
+1.3 Bind failed
+****************
+ Usually this is due to running more then once instance of NSClient++ or possibly running another program that uses the same port.
+ - Make sure you don't have any other instance NSCLient++ started.
+ - Check if the port is in use (netstat -a look for LISTENING)
+
+1.4 "EventlogBuffer? is too small
+**********************************
+This is because you have one or more entries in your eventlog which are larger then the "default buffer size of 64k". The best way to fix this is to increase the buffer used.
+
+.. code-block:: ini
+
+ [/settings/eventlog]
+ buffer_size=128000
+
+1.5 How do I properly escape spaces in strings
+***********************************************
+
+When you need to put spaces in a string you do the following:
+ * nagios:
+ - As usual you can do it anyway you like but I prefer: check_nrpe ... 'this is a string'
+
+1.6 How do I properly escape $ in strings
+******************************************
+
+From:
+ * nagios:
+ - $$ (you use two $ signs)
+ * from NSClient++
+ - $ (you do not need to escape them at all)
+
+1.7 System Tray does not work
+******************************
+ **NOTICE**
+ System tray is currently disabled and will be added back at some point
+
+1.8 I get <insert random error from nagios here>
+*************************************************
+
+This information is usually useless to me since the error in nagios is not related to the problem.
+This is due to most protocols supported by nagios does not support reporting errors only status.
+To see the error do the following:
+
+.. code-block:: bat
+
+ net stop nscp
+ nscp test --log info
+ ... wait for errors to be reported ...
+ exit
+ net start nscp
+
+To get the debug log do the following:
+
+.. code-block:: bat
+
+ net stop nscp
+ nscp test --log debug
+ ... wait for errors to be reported ...
+ exit
+ net start nscp
+
+Please check and include this information before you submit questions and/or bug reports.
+
+1.9 I use version 0.3.9 or 0.2.7
+********************************
+
+please upgrade to 0.4.1 and see if the error still persist before you ask questions and/or report bugs
+
+1.10 Rejected connection from: <ip address here>
+************************************************
+This is due to invalid configuration.
+One important thing you '''NEED''' to configure is which hosts are allowed to connect. If this configuration is missing or invalid you will get the following error:
+
+.. code-block:: log
+
+ 013-04-02 16:34:07: e:D:\source\nscp\trunk\include\check_nt/server/protocol.hpp:65: Rejected connection from: ::ffff:10.83.14.251
+
+To resolve this please update your configuration:
+
+.. code-block:: ini
+
+ [/settings/default]
+
+ ; ALLOWED HOSTS - A coma separated list of hosts which are allowed to connect. You can use netmasks (/ syntax) or * to create ranges.
+ allowed hosts = <ADD YOUR NAGIOS 1 IP HERE>,<ADD YOUR NAGIOS 2 IP HERE>,10.11.12.0/24
+
+1.11 Arguments via NRPE
+***********************
+
+For details see :ref:`how_to_external_scripts`
+
+1.12 Nasty metacharacters
+*************************
+
+If you get illegal metachars or similar errors you are sending characters which are considered harmful through NRPE.
+This is a security measure inherited from the regular NRPE client.
+
+The following characters are considered harmful: |`&><'\"\\[]{}
+To enable this in the NRPE server you can add the following (please '''notice''' the same issue is also valid for CheckExternalScripts if you are using scripts see question 12 for details):
+.. code-block:: ini
+
+ [/settings/NRPE/server]
+ allow nasty characters=true
@@ -0,0 +1,147 @@
+= Migrating to 0.4.1 =
+
+Since 0.4.1 has now been released it is important to consider how this will affect existing users. In general there are three major strategies:
+
+
+#. I am happy and don't want to change anything
+#. I am willing to migrate manually
+#. I Want to migrate automatically
+
+Depending on your choice of route you will end up either with a brand new NSClient++ which is very powerful or one whilst being brand new will work very much like the old one. Thus the drawback to not migrating to the "new format" that you wont (easily) be able to use new features.
+Your migration strategy is also affected by the fact that in the next 6-to-12 months NSClient++ 0.4.2 will be released which is also a technology shift and which might very well introduce some migration work as well.
+
+Background (Whats has changed)
+==============================
+
+In 0.4.0 a new format for the configuration was introduced. In addition to this some modules were renamed, some were changed from an architectural perspective and some were deprecated. The reason for this is that the "old" NSCient++ was approaching 10 years and was simply not designed for the flexibility which it offers today.
+I will readily admit that NSClient++ is the most flexible and powerful monitoring agent available in the open source space (and this is not PR speak it is the truth).
+To accommodate this flexibility the format **had to change**, it would have been impossible to keep backwards compatibility.
+But the changes are mainly structural and designed to make things look more similar so from a human perspective the change is minor.
+For instance compare the NRPE server configuration:
+
+'''0.3.9''':
+
+.. TODO: Indent lines, set language: Example .. code-block:: python
+`modules <modules>`_
+NRPEListsner
+
+`NRPE <NRPE>`_
+port = 1234
+allow_arguments = 1
+
+
+'''0.4.1''':
+
+.. TODO: Indent lines, set language: Example .. code-block:: python
+`/modules </modules>`_
+NRPEServer = enabled
+
+`/settings/NRPE/server </settings/NRPE/server>`_
+port = 1234
+allow arguments = 1
+
+
+If we analyse this we can see four structural changes:
+
+#. Servers are now called Servers (they used to be called Listeners)
+ Thus NRPEListener is now NRPEServer
+
+#. Syntax is now KEY=VALUE, before it was sometimes just KEY, and sometimes KEY=VALUE
+ Thus where before it was module-name it is now module-name= enabled
+
+#. Paths are now hierarchical and there are two reasons for this. The first one is that you can now load a module multiple times which requires you to configure it more than once which is impossible in a flat structure. The second reason is that where before it was 10-15 section there is now probably closer to hundreds.
+ `NRPE <NRPE>`_ is now `/settings/NRPE/server </settings/NRPE/server>`_
+
+#. Keys are now using space not dash, underscore nor space etc. This is the only change I really regret doing but the idea was to make it simpler since before there was no rule.
+ Thus allowed-hosts is now "allowed hosts"
+
+This is pretty much it in terms of structural changes. Some modules were changed, for instance NSCAAgent was split up into NSCAClient and Scheduler to allow for other passive protocols.
+
+== Future (What's to come) ==
+
+So what will happen in the future?
+Well, two tings.
+
+#. Next version will support Lua configuration (i.e. scripts) which will handle all migration so hopefully this is the last change.
+#. Next version will feature a new command check subsystem
+The first change is just good, the latter change might have impacts on how you use NSClient++ (it might be good to look into this if you're planning to migrate). Just a quick recap (see milestone `milestone:0.4.2 <milestone:0.4.2>`_ for more details): checks will no longer support variable lists, instead more common argument parsing system is used throughout. I think this is a simplification which helps since it is pretty confusing the way arguments are parsed today. For instance:
+
+.. TODO: Indent lines, set language: Example .. code-block:: python
+1 = CheckCounter MaxWarn=10 Counter=\a\a MaxWarn=20
+2 = CheckCounter MaxWarn=10 Counter=\b\b MaxWarn=20 Counter=\c\c
+
+
+Compare the following two aliases, what would you expect for bounds?
+
+#. \a\a = 10 or 20? (Answer is: 20)
+#. \b\b = 10 or 20? (Answer is: 10)
+#. \c\c = 10 or 20? (Answer is: 20)
+
+Pretty confusing right? In the future options will override each other so the answer in 0.4.2 will become:
+
+#. \a\a = 10 or 20? (Answer is: 20)
+#. \b\b = 10 or 20? (Answer is: 20)
+#. \c\c = 10 or 20? (Answer is: 20)
+Essentially rendering the Multiple MaxWarn statements meaningless.
+
+But this also means that you can only have one bound for each check (something you can easily get around by using CheckMulti so I don't think it's a big deal). But if you are using a lot of Multiple MaxWarn/Crit statements you might take this time to either wait before you upgrade or start looking at ways to change your checks (like check multi).
+
+.. TODO: Indent lines, set language: Example .. code-block:: python
+old = CheckCounter MaxWarn=10 Counter=\b\b MaxWarn=20 Counter=\c\c
+new = CheckMulti command="CheckCounter Counter=\b\b MaxWarn=10" command="MaxWarn=20 Counter=\c\c"
+
+
+I also don't "officially" support 0.3.x any more. This does not mean I wont help you but it does mean I reserve the right to say "sorry, you have to upgrade for that". or "can you reproduce on 0.4.1?". I always try to help people but without a support team I only have so much time to dedicate to support.
+
+== Hands-on ==
+
+=== I don't want to upgrade ===
+
+This is fine and you can keep using the old format even with the new version without any problems.
+It is important to understand the limitations by doing this:
+
+
+* No new things: None of the new keys will be available to you unless you "include" a new syntax file.
+* No automatic process: You cannot use the "nscp settings" command line for managing your configuration.
+* No remote configuration (in 0.4.2): since the remote configuration tools will work using nscp settings they will not work either.
+* No registry support: Old settings file ONLY work with the old ini file not the old registry concept.
+
+It is simple to keep the old format. When you upgrade you select "Old configuration" in the installer UI. And afterwards you can at any time run the following command to change the configuration file:
+
+.. TODO: Indent lines, set language: Example .. code-block:: python
+nscp settings --switch old
+
+To change to the old file. This assumes you have the file since it is not shipped with NSClient++ any more. If you want you can always get the old ini file from github here: `https://github.com/mickem/nscp/blob/0.3.9/NSC.dist <https://github.com/mickem/nscp/blob/0.3.9/NSC.dist>`_
+
+I want to migrate
+-----------------
+
+Migrating automatically should work for most people and can be done from the installer or manually at a later time. It is very possible to install with "Old configuration" and then migrate at a later time.
+To migrate the configuration you run the following command:
+
+.. TODO: Indent lines, set language: Example .. code-block:: python
+nscp settings --migrate-to ini
+
+
+I want to change by hand
+------------------------
+
+migrating by hand is perhaps also a valid option if you don't have too much configuration. In this case there is (in builds post 0.4.1.89) a sample (full) config file from which you can copy/paste the settings.
+Another option is to use the settings command line tool to generate, add and remove default values.
+
+See the guide on using settings command line interface (TODO).
+In the mean time the following commands might be a pointer:
+
+.. TODO: Indent lines, set language: Example .. code-block:: python
+nscp settings --help
+nscp settings --validate
+nscp settings --generate ini --add-defaults
+nscp settings --generate ini --remove-defaults
+nscp settings --path /settings/NRPE/server --key "allowed hosts" --set 127.0.0.1
+
+
+
+Troubleshooting
+---------------
+
+TODO: Add this section!
Oops, something went wrong.

0 comments on commit d9318f2

Please sign in to comment.