summaryrefslogtreecommitdiff
path: root/puppet/modules/nagios/README
diff options
context:
space:
mode:
Diffstat (limited to 'puppet/modules/nagios/README')
-rw-r--r--puppet/modules/nagios/README305
1 files changed, 305 insertions, 0 deletions
diff --git a/puppet/modules/nagios/README b/puppet/modules/nagios/README
new file mode 100644
index 00000000..0c42b4a7
--- /dev/null
+++ b/puppet/modules/nagios/README
@@ -0,0 +1,305 @@
+Introduction/Notes
+==================
+
+This modules was inspired and based on the work of David Schmitt
+The immerda project group adapted and improved this module.
+Mainly we made it using the new native puppet nagios commands
+as well we made it more modular to fit for multidistro usage.
+
+In it's current form, this module can be used on CentOS and Debian.
+
+
+Overview
+========
+
+To use the nagios resources in an puppetmaster setup you need to activate
+[storeconfigs](https://docs.puppetlabs.com/puppet/latest/reference/configuration.html#storeconfigs) on the puppetmaster.
+You can also use this module in a masterless setup, please set the
+`storeconfigs` parameter to `false` when declaring the nafios class.
+
+You need to be running version 0.25 or later of puppet.
+
+
+Monitor
+-------
+
+On one node the "nagios" class has to be included. By default this installs
+apache using the "apache" module. To use lighttpd instead, set the "httpd"
+parameter to the "nagios" class to "lighttpd", or, if the web server is not to
+be managed by puppet, set the "httpd" parameter to "absent".
+
+
+Hosts
+-----
+
+On a node which shall be monitored with nagios, include the "nagios::target".
+This just creates a host declaration for this host's "$::ipaddress" fact. If
+the $::ipaddress of your target is not the one you wish to modify, you can use
+"nagios::target::fqdn" instead, which will use the $::fqdn fact of the host instead.
+
+Pass the $parents variable to the target class for enabling the reachability
+features of nagios. If a node needs more customisation, use the
+native "@@nagios_host" type directly (the double-ampersand declares the object
+as an exported resource).
+
+To monitor hosts not managed by puppet, add "nagios_host" objects to the
+monitoring node. The required parameters are "alias", "address" and "use". If
+you don't specify a proper nagios template with the "use" parameter, some extra
+parameters are needed. You may look up the nagios documentation for this.
+
+
+Services
+--------
+
+Services can be monitored by using the "nagios::service" component.
+
+The simplest form is:
+
+ nagios::service { 'check_http':
+ check_command => 'http_port!80',
+ }
+
+The intention being obviously to put such declarations into a component defining
+a service, thereby being automatically applied together with all instances of
+the service.
+
+Obviously, the check command must either be defined using nagios_command objects
+(some are supplied in nagios::defaults::commands) or in the nagios configuration
+files directly.
+
+NRPE client configuration
+=========================
+
+To setup a machine as an NRPE client, the class 'nagios::nrpe' should be used:
+
+ class { 'nagios::nrpe':
+ allowed_hosts => '10.2.3.4,10.5.6.7',
+ }
+
+The class can take the following parameters to change configuration or
+configuration directory:
+
+ * $cfg_dir : Defines the path to the NRPE configuration. The default is to use
+ the path used by packages per your distro.
+
+ * $pid_file : Sets the path of the PID file. The default value is the path
+ used by init script shipped with your distro's packages.
+
+ * $plugin_dir : Defines the path in which nagios plugins that are to be
+ executed with NRPE commands are stored. The default value is the path where
+ your distro's nagios package stores plugins.
+
+ * $server_address : The IP address to which the NRPE client daemon should
+ bind. The default behaviour is to bind to all IPs.
+
+ * $allowed_hosts : A string containing a comma-separated list of host IPs that
+ are allowed to request NRPE commands to be run. The default value is to
+ allow only 127.0.0.1, so you might want to pass in a list of additional host
+ IPs.
+
+ * $dont_blame : A string that enables ('1') or disables ('0') NRPE command
+ arguments. Enabling arguments can lead to potentials of shell escapes so it
+ should be used with caution and only if absolutely needed. This is disabled
+ by default.
+
+NRPE Services
+-------------
+
+Some Nagios services need to be checked via NRPE. The following will make the
+nagios server define a service that will check the NRPE command 'check_cpu' on
+the current node:
+
+ nagios::service { 'CPU Usage':
+ use_nrpe => true,
+ check_command => "check_cpu",
+ nrpe_args => "-t 60"
+ }
+
+NRPE Commands
+-------------
+
+To be able to call NRPE commands on a host, one needs to define that command
+and what it is going to execute:
+
+ nagios::nrpe::command { 'debsums':
+ check_command => '/usr/lib/nagios/plugins/check_debsums openssh-server'
+ }
+
+
+Upgrade Notes
+=============
+
+The nagios::target bits have been reworked, the notable changes that
+may affect an upgrade are:
+
+. previous versions had nagios::target::nat which used the $::fqdn for
+the address part of nagios::target, this has been renamed to
+nagios::target::fqdn to be more clear. if you were using
+nagios::target::nat then you will need to change those references to
+::fqdn
+
+. previous versions of this module used $::fqdn for the nagios::target
+address, now it is using $::ipaddress. If you need $::fqdn, use
+nagios::target::fqdn instead of nagios::target
+
+. previous versions of nagios_host used the parameter named 'ip', that
+has been changed to 'address'
+
+
+IRC bot
+=======
+
+Notifications can easily be sent to an IRC channel by using a bot. To do so,
+simply include 'nagios::irc_bot' on the nagios server and define the right
+$nagios_nsa_* variables (see the 'Variables' section below).
+
+You can then use the notification commands 'notify-by-irc' and
+'host-notify-by-irc' with service and host definitions to make them report
+state changes over IRC.
+
+Caveats
+=======
+
+
+Consistency/Validation/Verification
+-----------------------------------
+
+After convergance of the configuration, the system is obviously consistent.
+That is, all defined services are monitored. The problem is though, that it is
+neither automatically valid - it is not guaranteed that all components declare a
+nagios::service - and even if the configuration is valid it definitly is
+unverified, since that is always a judgment call for an external observer.
+
+
+Removal of nagios objects
+-------------------------
+
+This module does not automatically purge nagios objects such as hosts and
+services that become absent from the manifests. One must set ensure => absent
+to guarantee the removal of nagios objects from the configuration as desired.
+
+
+Templates not supported using native types
+------------------------------------------
+
+Templates of hosts and services cannot yet be defined using native types. In
+this module, they are provided using a file resource by the class
+nagios::defaults::templates
+
+See : http://projects.reductivelabs.com/issues/1180
+
+
+Variables
+=========
+
+Options to change the behavior of the nagios class:
+
+- allow_external_cmd: Set to true, if you'd like to ensure that your http
+ daemon can write to the external command file. You
+ may also need to flip "check_external_commands" in
+ "nagios.cfg" to enable this functionality.
+
+For the irc_bot class:
+
+- nsa_socket: This optional variable can be used to specify the path to
+ the socket file that the IRC daemon should use.
+
+- nsa_server: When using the IRC bot, this defines the server address of
+ the IRC network on which the bot will connect.
+
+- nsa_port: Defines the port number on the IRC server on which the bot
+ should connect. When this variable is not set, the port used
+ by default is 6667.
+
+- nsa_nickname: This is the nickname that the IRC bot will take.
+
+- nsa_password: Some networks require a password to connect to them.
+ This defines such a password.
+
+- nsa_channel: The name of the channel that the IRC bot will join and
+ will post notifications to.
+
+- nsa_pidfile: This optional variable can be used to define the path to
+ the file that will contain the process ID of the IRC bot
+ daemon.
+- nsa_realname: The IRC bot user's real name that will be displayed. By
+ default, the real name is 'Nagios'.
+
+- nsa_usenotices: The IRC bot will by default "say" to the channel the
+ nagios message, but you can switch this variable to
+ 'notice' if you would prefer them to be sent as IRC
+ NOTICE messages.
+
+PNP4Nagios integration
+======================
+
+For PNP4Nagios integration information, please see README.pnp4nagios
+
+Examples
+========
+
+Usage example:
+
+~~~
+node nagios {
+
+ class { 'nagios': } -> class { 'nagios::defaults': }
+
+ # Declare another nagios command
+ nagios::command { http_port:
+ command_line => '/usr/lib/nagios/plugins/check_http -p $ARG1$ -H $HOSTADDRESS$ -I $HOSTADDRESS$'
+ }
+
+ # Declare unmanaged hosts
+ nagios_host {
+ 'router01.mydomain.com':
+ alias => 'router01',
+ notes => 'MyDomain Gateway',
+ address => '10.0.0.1',
+ use => 'generic-host';
+ 'router02.mydomain.com':
+ alias => 'router02',
+ address => '192.168.0.1',
+ parents => 'router01',
+ use => 'generic-host';
+ }
+
+}
+
+
+node target {
+
+ # Monitor this host
+ class{'nagios::target':
+ parents = 'router01'
+ }
+
+ # monitor a service
+ $apache2_port = 8080
+ include apache2
+
+ # This actually does this somewhere:
+ #nagios::service { "http_${apache2_port}":
+ # check_command => "http_port!${apache2_port}"
+ #}
+
+}
+~~~
+
+TODO
+====
+
+- Provide a default http vhost
+- Add facility to deploy nagios plugins
+- Add more useful commands and services
+- When Puppet will support them, supply nagios templates using native types
+
+
+License
+=======
+
+Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
+See the file LICENSE in the top directory for the full license.
+
+Copyright (C) 2010 Riseup Networks <micah@riseup.net>
+