summaryrefslogtreecommitdiff
path: root/puppet/modules/check_mk/README.md
diff options
context:
space:
mode:
authorMicah <micah@leap.se>2016-07-12 16:46:32 -0400
committerMicah <micah@leap.se>2016-07-12 16:46:32 -0400
commit56a771a3008d10720dd05fd815aeafbacdd1e08e (patch)
tree4b96fc087072834759eafd6949391de73ac43737 /puppet/modules/check_mk/README.md
parenta75fea409bf8e62e55ba341672c202aab5fa480e (diff)
git subrepo clone https://leap.se/git/puppet_check_mk puppet/modules/check_mk
subrepo: subdir: "puppet/modules/check_mk" merged: "aa02571" upstream: origin: "https://leap.se/git/puppet_check_mk" branch: "master" commit: "aa02571" git-subrepo: version: "0.3.0" origin: "https://github.com/ingydotnet/git-subrepo" commit: "1e79595" Change-Id: I6cb060eb80966dd6ae346f7a8105289caa9ccbaf
Diffstat (limited to 'puppet/modules/check_mk/README.md')
-rw-r--r--puppet/modules/check_mk/README.md268
1 files changed, 268 insertions, 0 deletions
diff --git a/puppet/modules/check_mk/README.md b/puppet/modules/check_mk/README.md
new file mode 100644
index 00000000..81e1bc87
--- /dev/null
+++ b/puppet/modules/check_mk/README.md
@@ -0,0 +1,268 @@
+# check_mk
+
+Puppet module for:
+
+* Installing and configuring the Open Monitoring Distribution (OMD) which
+ includes Nagios, check_mk and lots of other tools
+
+* Installing and configuring check_mk agents
+
+Agent hostnames are automatically added to the server all_hosts configuration
+using stored configs.
+
+Currently only tested on Redhat-like systems and on Debian.
+
+For examples how to use this class on a debian wheezy system, check out following
+snippets: https://git.codecoop.org/snippets/1, https://git.codecoop.org/snippets/2
+
+## Server
+
+* Installs omd package either using the system repository (eg. yum, apt) or
+ from a package file retrieved from the Puppet file store
+
+* Use check_mk::omd_repo to enable a debian repository for omd
+ (requires apt module from i.e. https://labs.riseup.net/code/projects/shared-apt).
+ For now, you need to fetch the omd apt-key manually from
+ http://labs.consol.de/nagios/omd-repository/, put it into your site_apt/files/keys
+ directory and pass the custom_key_dir parameter to the apt class, like
+
+
+ class { 'apt':
+ custom_key_dir => 'puppet:///modules/site-apt/keys'
+ }
+
+* Populates the all_hosts array in /etc/check_mk/main.mk with hostnames
+ exported by check::agent classes on agent hosts
+
+### Example 1
+
+ include check_mk
+
+Installs the 'monitoring' package from the system repository. The default 'monitoring' site is used.
+
+### Example 2
+
+ class { 'check_mk':
+ filestore => 'puppet:///files/check_mk',
+ package => 'omd-0.56-rh60-29.x86_64.rpm'
+ }
+
+Installs the specified omd package after retrieving it from the Puppet file store.
+
+### Example 3
+
+ class { 'check_mk':
+ site => 'acme',
+ }
+
+Installs the omd package from the system repository. A site called 'acme' is
+created making the URL http://hostname/acme/check_mk/ running as the 'acme' user.
+
+### check_mk parameters
+
+*package*: The omd package (rpm or deb) to install. Optional.
+
+*filestore*: The Puppet file store location where the package can be found (eg. 'puppet:///files/check_mk'). Optional.
+
+*host_groups*: A hash with the host group names as the keys with a list of host tags to match as values. (See 'Host groups and tags' below). Optional.
+
+*site*: The name of the omd site (and the user/group it runs as). Default: 'monitoring'
+
+*workspace*: The directory to use to store files used during installation. Default: '/root/check_mk'
+
+*omdadmin_htpasswd*: changes the htpasswd of the amdadmin user (requires apache module from i.e.
+ https://labs.riseup.net/code/projects/shared-apache)
+
+*use_ssh*: Configures ssh to agents that use the same parameter.
+ Default: false.
+
+*inventory_only_on_changes*: By default (parameter set to `true`) these two execs are called
+ only when config files changes:
+ - Exec['check_mk-refresh'] (which runs a check inventory by calling `check_mk -II`)
+ - Exec['check_mk-reload'] (which generates the nagios config and reloads nagios by calling `check_mk -O`)
+ By setting this parameter to `false` these execs will be called on each puppetrun.
+
+### Notes
+
+* A user and group with the same value as the site parameter is created. By default this is 'monitoring'.
+
+* The URL is http://yourhostname/sitename/check_mk/ - for example http://monhost.domain/monitoring/check_mk/
+
+* The default username/password is omdadmin/omd. To change this or add additional users log in as the site user and run htpasswd - for example:
+
+ monitoring$ htpasswd -b ~/etc/htpasswd guest guest
+
+* A user called 'guest' is configured as a guest user but is not enabled unless a password is set (as above).
+
+* RedHat-like RPM downloads from http://files.omdistro.org/releases/centos_rhel/
+
+## Agent
+
+* Installs the check_mk-agent and check_mk-agent-logwatch packages
+
+* Configures the /etc/xinetd.d/check_mk configuration file
+
+### Example 1
+
+ include check_mk::agent
+
+Installs the check_mk and check_mk_logwatch packages from the system repository
+and configures /etc/xinetd.d/check_mk with no IP whitelist restrictions.
+
+### Example 2
+
+ class { 'check_mk::agent':
+ version => '1.2.0p3-1',
+ ip_whitelist => [ '10.7.96.21', '10.7.96.22' ],
+ }
+
+Installs the specified versions of the check_mk and check_mk_logwatch packages
+after retrieving them from the Puppet file store. Configures
+/etc/xinetd.d/check_mk so that only the specified IPs (and localhost/127.0.0.1)
+are allowed to connect.
+
+### check_mk::agent parameters
+
+*filestore*: The Puppet file store location where the packages can be found (eg. 'puppet:///files/check_mk'). Optional.
+
+*ip_whitelist*: The list of IP addresses that are allowed to retrieve check_mk
+data. (Note that localhost is always allowed to connect.) By default any IP can
+connect.
+
+*port*: The port the check_mk agent listens on. Default: '6556'
+
+*server_dir*: The directory in which the check_mk_agent executable is located.
+Default: '/usr/bin'
+
+*use_cache*: Whether or not to cache the results - useful with redundant
+monitoring server setups. Default: 'false'
+
+*user*: The user that the agent runs as. Default: 'root'
+
+*version*: The version in the check_mk packages - for example if the RPM is
+'check_mk-agent-1.2.0p3-1.noarch.rpm' then the version is '1.2.0p3-1'.
+Only required if a filestore is used.
+
+*workspace*: The directory to use to store files used during installation.
+Default: '/root/check_mk'
+
+*method*: "xinetd" (default) or "ssh"
+ "ssh": Use ssh instead of the tcp wrapper in order to allows the server to
+ execute the agent on the client.
+
+*generate_sshkey*: true or false (default)
+
+ * Deploys ssh keypair on server (in /opt/omd/sites/monitoring/.ssh)
+ * Saves keypair on puppetmaster (/etc/puppet/modules/keys/files/check_mk_keys by default)
+ * Deploys public key on client in /root/.ssh/authorized_keys (restricting allows command to "/usr/bin/check_mk_agent")
+
+## Host groups and tags
+
+By default check_mk puts all hosts into a group called 'check_mk' but where you
+have more than a few you will often want your own groups. We can do this by
+setting host tags on the agents and then configuring host groups on the server
+side to match hosts with these tags.
+
+For example in the hiera config for your agent hosts you could have:
+
+ check_mk::agent::host_tags:
+ - '%{osfamily}'
+
+and on the monitoring host you could have:
+
+ check_mk::host_groups:
+ RedHat:
+ description: 'RedHat or_CentOS hosts'
+ host_tags:
+ - RedHat
+ Debian:
+ description: 'Debian or Ubuntu_hosts'
+ host_tags:
+ - Debian
+ SuSE:
+ description: 'SuSE hosts'
+ host_tags:
+ - Suse
+
+You can of course have as many host tags as you like. I have custom facts for
+the server role and the environment type (dev, qa, stage, prod) and define
+groups based on the role and envtype host tags.
+
+Remember to run the Puppet agent on your agent hosts to export any host tags
+and run the Puppet agent on the monitoring host to pick up any changes to the
+host groups.
+
+## Static host config
+
+Hosts that do not run Puppet with the check_mk module are not automatically
+added to the all_hosts list in main.mk. To manually include these hosts you can
+add them to '/omd/sites/monitoring/etc/check_mk/all_hosts_static' (replacing
+'monitoring' with your site name). Use the quoted fully qualified domain name
+with a two-space prefix and a comma suffix - for example:
+
+ 'host1.domain',
+ 'host2.domain',
+
+You can also include host tags - for example:
+
+ 'host1.domain|windows|dev',
+ 'host2.domain|windows|prod',
+
+Remember to run the Puppet agent on your monitoring host to pick up any changes.
+
+## Migrating from nagios-statd
+
+nagios-statd provides several features that can be replaced with check_mk
+plugins.
+
+*nagios-stat-proc*: checks processes on the agent system
+If you previously used the nagios puppet module to do something like:
+
+ check_command => 'nagios-stat-proc!/usr/sbin/foo!1!1!proc'
+
+you can now use the check_mk ps check:
+
+ check_mk::agent::ps {
+ 'foo':
+ procname => '/usr/local/weirdpath/foo',
+ levels => '1, 2, 2, 3',
+ owner => 'alice'
+ }
+
+defaults:
+ procname: "/usr/sbin/${name}"
+ levels: '1, 1, 1, 1'
+ owner: not required
+
+Run check_mk with '-M ps' for the manpage explaining the parameters.
+
+*swap*: check_mk has a 'mem.used' check which is enabled by default. But
+ as it's manpage explains if you want to measure swappiness you are
+ better off using the 'kernel' check and measuring 'Major Page Faults'
+ (pgmajfault).
+
+*disk*: check_mk has a 'df' check which is enabled by default.
+
+## Migrating from nrpe to mrpe
+
+If you were using nrpe to run a nagios plugin locally, first check if a
+native check_mk check exists with the same functionality, if not consider
+writing one. But if continuing to use the nagios plugin makes sense you
+can switch to mrpe.
+
+* Continue to deliver the plugin to the agent system
+* include check_mk::agent::mrpe
+* add a line to the mrpe.cfg file using augeas
+
+ augeas {
+ "Foo":
+ incl => '/etc/check_mk/mrpe.cfg',
+ lens => 'Spacevars.lns',
+ changes => 'set FOO /usr/local/lib/nagios/plugins/check_foo',
+ require => [ File['/usr/local/lib/nagios/plugins' ], Package['check-mk-agent'] ];
+ }
+
+
+This is the riseup clone, available at:
+
+git://labs.riseup.net/module_check_mk