diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 283 |
1 files changed, 63 insertions, 220 deletions
@@ -1,268 +1,111 @@ -# check_mk +Leap Platform +============================= -Puppet module for: +[](https://jenkins.leap.se/job/platform_develop/) -* Installing and configuring the Open Monitoring Distribution (OMD) which - includes Nagios, check_mk and lots of other tools +The LEAP Platform is set of complementary packages and server recipes to automate the maintenance of LEAP services in a hardened Debian environment. Its goal is to make it as painless as possible for sysadmins to deploy and maintain a service provider's infrastructure for secure communication. These recipes define an abstract service provider. It is a set of Puppet modules designed to work together to provide to sysadmins everything they need to manage a service provider infrastructure that provides secure communication services. -* Installing and configuring check_mk agents +Getting started +============================= -Agent hostnames are automatically added to the server all_hosts configuration -using stored configs. +It is highly recommended that you start by reading the overview of the [LEAP Platform](https://leap.se/docs/platform) and then begin with the [Quick Start tutorial](https://leap.se/en/docs/platform/tutorials/quick-start) to walk through a test environment setup to get familiar with how things work before deploying to live servers. -Currently only tested on Redhat-like systems and on Debian. +An offline copy of this documentation is contained in the `doc` subdirectory. For more current updates to the documentation, visit the website. -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 +Requirements +------------------ -## Server +For testing a virtual deployment simulated on your computer, you will need a fairly recent computer x86_64 with hardware virtualization features (AMD-V or VT-x) and plenty of RAM. If you follow the "Quick Start" documentation we will walk you through using Vagrant to setup a test deployment. -* Installs omd package either using the system repository (eg. yum, apt) or - from a package file retrieved from the Puppet file store +For a live deployment of the platform, the number of servers that is required depends on your needs and which services you want to deploy. At the moment, the LEAP Platform supports servers with a base Debian Wheezy installation. -* 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 - +Troubleshooting +============================= - class { 'apt': - custom_key_dir => 'puppet:///modules/site-apt/keys' - } +If you have a problem, we are interested in fixing it! -* Populates the all_hosts array in /etc/check_mk/main.mk with hostnames - exported by check::agent classes on agent hosts +If you have a problem, be sure to have a look at the [Known Issues](https://leap.se/docs/platform/known-issues) to see if your issue is detailed there. -### Example 1 +If not, the best way for us to solve your problem is if you provide to us the complete log of what you did, and the output that was produced. Please don't cut out what appears to be useless information and only include the error that you received, instead copy and paste the complete log so that we can better determine the overall situation. If you can run the same command that produced the error with a raised verbosity level (such as -v2), that provides us with more useful debugging information. - include check_mk +To capture the log, you can copy from the console, or run `leap --log FILE` or edit Leapfile to include `@log = '/tmp/leap.log'`. -Installs the 'monitoring' package from the system repository. The default 'monitoring' site is used. +Visit https://leap.se/en/docs/get-involved/communication for details on how to contact the developers. -### Example 2 +Known issues +============ - class { 'check_mk': - filestore => 'puppet:///files/check_mk', - package => 'omd-0.56-rh60-29.x86_64.rpm' - } +The following issues are known to exist in 0.5.2 and later: -Installs the specified omd package after retrieving it from the Puppet file store. +CouchDB Sync +------------ +You can't deploy new couchdb nodes after one or more have been deployed. Make *sure* that you configure and deploy all your couchdb nodes when first creating your provider. The problem is that we dont not have a clean way of adding couch nodes after initial creation of the databases, so any nodes added after result in improperly synchronized data. See Bug [#5601](https://leap.se/code/issues/5601) for more information. -### Example 3 +User setup and ssh +------------------ - class { 'check_mk': - site => 'acme', - } +. if you aren't using a single ssh key, but have different ones, you will need to define the following at the top of your ~/.ssh/config: + HostName <ip address> + IdentityFile <path to identity file> -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. + (see: https://leap.se/code/issues/2946 and https://leap.se/code/issues/3002) -### check_mk parameters +. If the ssh host key changes, you need to run node init again (see: https://leap.se/en/docs/platform/guide#Working.with.SSH) -*package*: The omd package (rpm or deb) to install. Optional. +. At the moment, only ECDSA ssh host keys are supported. If you get the following error: `= FAILED ssh-keyscan: no hostkey alg (must be missing an ecdsa public host key)` then you should confirm that you have the following line defined in your server's **/etc/ssh/sshd_config**: `HostKey /etc/ssh/ssh_host_ecdsa_key`. If that file doesn't exist, run `ssh-keygen -t ecdsa -f /etc/ssh/ssh_host_ecdsa_key -N ""` in order to create it. If you made a change to your sshd_config, then you need to run `/etc/init.d/ssh restart` (see: https://leap.se/code/issues/2373) -*filestore*: The Puppet file store location where the package can be found (eg. 'puppet:///files/check_mk'). Optional. +. To remove an admin's access to your servers, please remove the directory for that user under the `users/` subdirectory in your provider directory and then remove that user's ssh keys from files/ssh/authorized_keys. When finished you *must* run a `leap deploy` to update that information on the servers. -*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. +. At the moment, it is only possible to add an admin who will have access to all LEAP servers (see: https://leap.se/code/issues/2280) -*site*: The name of the omd site (and the user/group it runs as). Default: 'monitoring' +. leap add-user --self allows only one key - if you run that command twice with different keys, you will just replace the key with the second key. To add a second key, add it manually to files/ssh/authorized_keys (see: https://leap.se/code/issues/866) -*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) +Deploying +--------- -*use_ssh*: Configures ssh to agents that use the same parameter. - Default: false. +. If you have any errors during a run, please try to deploy again as this often solves non-deterministic issues that were not uncovered in our testing. Please re-deploy with `leap -v2 deploy` to get more verbose logs and capture the complete output to provide to us for debugging. -*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. +. If when deploying your debian mirror fails for some reason, network anomoly or the mirror itself is out of date, then platform deployment will not succeed properly. Check the mirror is up and try to deploy again when it is resolved (see: https://leap.se/code/issues/1091) -### Notes +. Deployment gives 'error: in `%`: too few arguments (ArgumentError)' - this is because you attempted to do a deploy before initializing a node, please initialize the node first and then do a deploy afterwards (see: https://leap.se/code/issues/2550) -* A user and group with the same value as the site parameter is created. By default this is 'monitoring'. +. This release has no ability to custom configure apt sources or proxies (see: https://leap.se/code/issues/1971) -* The URL is http://yourhostname/sitename/check_mk/ - for example http://monhost.domain/monitoring/check_mk/ +. When running a deploy at a verbosity level of 2 and above, you will notice puppet deprecation warnings, these are known and we are working on fixing them -* 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: +Special Environments +-------------------- - monitoring$ htpasswd -b ~/etc/htpasswd guest guest +. When deploying to OpenStack release "nova" or newer, you will need to do an initial deploy, then when it has finished run `leap facts update` and then deploy again (see: https://leap.se/code/issues/3020) -* A user called 'guest' is configured as a guest user but is not enabled unless a password is set (as above). +leap-mx +------- -* RedHat-like RPM downloads from http://files.omdistro.org/releases/centos_rhel/ +. see https://github.com/leapcode/leap_mx#070 for issues regarding leap_mx -## Agent -* Installs the check_mk-agent and check_mk-agent-logwatch packages +Contributing +============ -* Configures the /etc/xinetd.d/check_mk configuration file +In order to validate the syntax and style guide compliance +before you commit, see https://github.com/pixelated-project/puppet-git-hooks#installation -### Example 1 - include check_mk::agent +Changes +========= -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. +Read CHANGES.md or run `git log`. -### Example 2 +Authors and Credits +=================== - class { 'check_mk::agent': - version => '1.2.0p3-1', - ip_whitelist => [ '10.7.96.21', '10.7.96.22' ], - } +See contributors: -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. + git shortlog -es --all -### check_mk::agent parameters -*filestore*: The Puppet file store location where the packages can be found (eg. 'puppet:///files/check_mk'). Optional. +Copyright/License +================= -*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 +Read LICENSE |