Docs: Monitoring with your custom plugin

Change-Id: I0e2abf94cafa90d4c546f0a2c5cb83774804a785

doc/source/tutorials/index.rst

@@ -7,3 +7,4 @@ Tutorials
    getting_started
    developing_the_api
    running_the_tests
+   monitoring_with_your_custom_plugin

doc/source/tutorials/monitoring_with_your_custom_plugin.rst

@@ -0,0 +1,83 @@
+.. role:: bash(code)
+   :language: bash
+
+Monitoring with your custom plugin
+##################################
+
+Surveil is compatible with Nagios plugins. It is trivial to write a custom plugin to monitor your applcation. In this guide, we will create a new plugin and configure a new Host that uses it in Surveil.
+
+1. Test the check_example plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The first step to create a plugin is to successfully test the check_example plugin. This plugin
+will serve as a base file to create your own plugin.
+
+Create virtual environment and install requirements: ::
+
+    virtualenv env
+    source env/bin/activate
+    cd tools/docker/alignak_container/plugins/check-example
+    pip install -r requirements.txt
+
+Install the check_example plugin: ::
+
+    python setup.py develop
+
+Run the plugin: ::
+
+    check_example
+
+The output should look like this: ::
+
+    DISK OK - free space: / 3326 MB (56%); | /=2643MB;5948;5958;0;5968
+
+2. Modify the plugin
+~~~~~~~~~~~~~~~~~~~~
+
+The next step is to modify the plugin to meet your needs. In order to do this,
+please refer to the `Nagios plugin API documentation <http://nagios.sourceforge.net/docs/3_0/pluginapi.html>`_.
+
+
+3. Create a host using this plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that you are done developing your plugin, it is time to use it in Surveil.
+
+Creating a command
+------------------
+
+Before you can use your plugin in a host/service configuration, you need to create an Alignak command: ::
+
+    surveil config-command-create --command_name check_example --command_line "check_example"
+
+Creating a host
+---------------
+
+Create a host with the following command: ::
+
+   surveil config-host-create --host_name check_example_host --address savoirfairelinux.com
+
+Creating a Service
+------------------
+
+Create a service with the following command: ::
+
+    surveil config-service-create --host_name check_example_host --service_description check_example_service --check_command "check_example" --max_check_attempts 4 --check_interval 5 --retry_interval 3 --check_period "24x7" --notification_interval 30 --notification_period "24x7" --contacts admin --contact_groups admins
+
+Reload the config
+-----------------
+
+Reload the config this will tell Alignak to reload the new config with the new host ::
+
+    surveil config-reload
+
+Show the new service
+--------------------
+
+Show the service list with this command: ::
+
+    surveil status-service-list
+
+
+You should see the service you just add in the list with the correct status (this could take a minute a two for the
+result to show)

tools/docker/alignak_container/Dockerfile

@@ -108,10 +108,18 @@ RUN sh  -c 'gpg --recv-keys --keyserver keyserver.ubuntu.com 2320E8F8 && gpg --e
     apt-get update && \
     apt-get install -y --force-yes monitoring-packs-sfl-generic-host monitoring-packs-sfl-linux-system-nrpe
 
+## Add check example plugin
+ADD plugins/check-example /plugins/check_example
+RUN virtualenv /plugins/check_example/env
+ENV PATH=$PATH:/plugins/check_example/env/bin
+RUN /plugins/check_example/env/bin/pip install -r /plugins/check_example/requirements.txt
+RUN cd /plugins/check_example && sudo /opt/surveilplugins/env/bin/python setup.py install && ln -s /opt/surveilplugins/env/bin/check_example /usr/lib/alignak/plugins/
+
 ## configuration
 ADD setup.sh /setup.sh
 RUN rm -rf /etc/alignak
 ADD etc/alignak /etc/alignak
+
 RUN chown -R root:alignak /etc/alignak
 
 ### Supervisor

tools/docker/alignak_container/plugins/check-example/check_example/check_example.py

@@ -0,0 +1,30 @@
+# Copyright 2014 - Savoir-Faire Linux inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+import sys
+
+
+class Plugin(object):
+
+    def run(self):
+        print("DISK OK - free space: / 3326 MB (56%); | /=2643MB;5948;5958;0;"
+              "5968")
+        sys.exit(0)
+
+
+def main():
+    Plugin().run()
+
+if __name__ == "__main__":
+    main()

tools/docker/alignak_container/plugins/check-example/requirements.txt

@@ -0,0 +1 @@
+requests

tools/docker/alignak_container/plugins/check-example/setup.py

@@ -0,0 +1,38 @@
+# Copyright 2014 - Savoir-Faire Linux inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from __future__ import with_statement
+
+import setuptools
+
+
+description = 'An Alignak plugin'
+long_description = (''' .. ''')
+
+
+setuptools.setup(
+    name='check_example',
+    version="1.0",
+    packages=setuptools.find_packages(),
+    author="Vincent Fournier",
+    author_email="vincent.fournier@savoirfairelinux.com",
+    long_description=long_description,
+    description=description,
+    platforms=['any'],
+    install_requires=[],
+    entry_points="""
+    [console_scripts]
+    check_example = check_example.check_example:main
+    """,
+)