From 68e31cf23fb5134d7f99c5847f5d642a166e69be Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Mon, 27 Aug 2012 15:12:12 -0400 Subject: [PATCH] Add docs for nagios --- rst/modules.rst | 1 + rst/modules/nagios.rst | 174 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 175 insertions(+) create mode 100644 rst/modules/nagios.rst diff --git a/rst/modules.rst b/rst/modules.rst index fc403c4e62..df7c3b4650 100644 --- a/rst/modules.rst +++ b/rst/modules.rst @@ -50,6 +50,7 @@ Let's see what's available in the Ansible module library, out of the box: .. include:: modules/mount.rst .. include:: modules/mysql_db.rst .. include:: modules/mysql_user.rst +.. include:: modules/nagios.rst .. include:: modules/ohai.rst .. include:: modules/ping.rst .. include:: modules/pip.rst diff --git a/rst/modules/nagios.rst b/rst/modules/nagios.rst new file mode 100644 index 0000000000..43c044f985 --- /dev/null +++ b/rst/modules/nagios.rst @@ -0,0 +1,174 @@ +.. _nagios: + +nagios +`````` + +Perform common tasks in Nagios related to downtime and notifications. + +The Nagios module has two basic functions: scheduling downtime and +toggling alerts for services or hosts. + +The following parameters are common to all *actions* in the nagios +module: + ++---------------+----------+----------------------------------+------------------------------------------------------------------+ +| parameter | required | default | comments | ++===============+==========+==================================+==================================================================+ +| action | yes | | one of: 'downtime', 'enable_alerts'/'disable_alerts', or | +| | | | 'silence'/'unsilence' | ++---------------+----------+----------------------------------+------------------------------------------------------------------+ +| host | yes | | host to operate on in nagios | ++---------------+----------+----------------------------------+------------------------------------------------------------------+ +| cmdfile | no | /var/spool/nagios/cmd/nagios.cmd | path to the nagios *command file* (FIFO pipe) | ++---------------+----------+----------------------------------+------------------------------------------------------------------+ + +The following parameters may be used with the **downtime** action: + ++---------------+----------+----------------------------------+------------------------------------------------------------------+ +| parameter | required | default | comments | ++===============+==========+==================================+==================================================================+ +| author | no | Ansible | author to leave downtime comments as | ++---------------+----------+----------------------------------+------------------------------------------------------------------+ +| minutes | no | 30 | minutes to schedule downtime for | ++---------------+----------+----------------------------------+------------------------------------------------------------------+ +| services | no | | what to manage downtime/alerts for. separate multiple services | +| | | | with commas. use 'host' to manage the host itself. | +| | | | **service** is as an alias for **services** | ++---------------+----------+----------------------------------+------------------------------------------------------------------+ + +The following parameter must be used with the **enable_alerts** and **disable_alerts** actions: + ++---------------+----------+----------------------------------+------------------------------------------------------------------+ +| parameter | required | default | comments | ++===============+==========+==================================+==================================================================+ +| services | no | | what to manage downtime/alerts for. separate multiple services | +| | | | with commas. use 'host' to manage the host itself. | +| | | | **service** is as an alias for **services** | ++---------------+----------+----------------------------------+------------------------------------------------------------------+ + +.. note:: + The **silence** and **unsilence** actions have no additional + parameters that may be used with them. + + +All actions require the **host** parameter to be given explicitly. In +playbooks you can use the ``$inventory_hostname`` variable to refer to +the host the playbook is currently running on. + +You can specify multiple services at once by separating them with +commas, .e.g., ``services=httpd,nfs,puppet``. + +When specifying what service to handle there is a special keyword, +**host**, which will handle alerts/downtime for the **host itself**, +e.g., ``service=host``. This keyword may *not* be given with other +services at the same time. *Handling alerts/downtime for a host does +not affect alerts/downtime for any of the services running on it.* + + +Examples of Scheduling Downtime in :doc:`playbooks`:: + + --- + - hosts: webservers + user: root + tasks: + - name: set 30 minutes of apache downtime + action: nagios action=downtime minutes=15 service=httpd host=$inventory_hostname + delegate_to: nagios.com + + - name: schedule an hour of HOST downtime + action: nagios action=downtime minutes=60 service=host host=$inventory_hostname + delegate_to: nagios.com + + # Use the default of 30 minutes + # Schedule downtime for three services at once + - name: schedule downtime for a few services + action: nagios action=downtime services=frob,foobar,qeuz host=$inventory_hostname + delegate_to: nagios.com + +And from the command line: + +.. code-block:: bash + + $ ansible nagios.com -m nagios -a "action=downtime minutes=15 service=httpd host=server01.example.com" + $ ansible nagios.com -m nagios -a "action=downtime minutes=60 service=host host=server01.example.com" + $ ansible nagios.com -m nagios -a "action=downtime services=frob,foobar,qeuz host=server01.example.com" + +Examples of handling specific host/service alerts in :doc:`playbooks`:: + + --- + - hosts: webservers + user: root + tasks: + - name: enable SMART disk alerts + action: nagios action=enable_alerts service=smart host=$inventory_hostname + delegate_to: nagios.com + + # Note that you can disable multiple at once + - name: disable httpd alerts + action: nagios action=disable_alerts service=httpd,nfs host=$inventory_hostname + delegate_to: nagios.com + + # And disabling HOST alerts + - name: disable HOST alerts + action: nagios action=disable_alerts service=host host=$inventory_hostname + delegate_to: nagios.com + +And from the command line: + +.. code-block:: bash + + $ ansible nagios.com -m nagios -a "action=enable_alerts service=smart host=server01.example.com" + $ ansible nagios.com -m nagios -a "action=disable_alerts service=httpd,nfs host=server01.example.com" + $ ansible nagios.com -m nagios -a "action=disable_alerts service=host host=server01.example.com" + +Examples of Silencing all host/service alerts in :doc:`playbooks`:: + + --- + - hosts: webservers + user: root + tasks: + - name: silence ALL alerts + action: nagios action=silence host=$inventory_hostname + delegate_to: nagios.com + + - name: unsilence all alerts + action: nagios action=unsilence host=$inventory_hostname + delegate_to: nagios.com + +And from the command line: + +.. code-block:: bash + + $ ansible nagios.com -m nagios -a "action=silence host=server01.example.com" + $ ansible nagios.com -m nagios -a "action=unsilence host=server01.example.com" + + +**Optional Configuration** + +If your nagios **cmdfile** is not ``/var/spool/nagios/cmd/nagios.cmd`` +you can configure ansible (on your nagios server) to use the correct +one by making a file called ``/etc/ansible/modules/nagios.conf`` that +looks like this: + +.. code-block:: ini + + [main] + cmdfile = /path/to/your/nagios.cmd + +Or, use the **cmdfile** parameter to set it explicitly. + + +**Troubleshooting Tips** + +The nagios module may not operate for you out of the box. The most +likely problem is with your **cmdfile** permissions/paths. You will +receive this error if that is the case:: + + {"msg": "unable to write to nagios command file", "failed": true, "cmdfile": "/var/spool/nagios/cmd/nagios.cmd"} + +Steps to correct this: + +1. Ensure you are running the nagios module as a user who has + **write** permissions to the **cmdfile**. + +2. Ensure you have **cmdfile** set correctly.