Checkmk
DeutschEspañolFrançaisItaliano
master2.2.02.1.02.0.01.6.0
to checkmk.com

1. Introduction

There are many good reasons for using FreeBSD instead of Linux or other Unix-like systems: For example, the 'Jails' container feature, which has been available since 2000, its high performance even under heavy I/O loads, the robustness of the UFS2 file system, or the excellent support for the modern ZFS transactional file system. Checkmk provides an agent for FreeBSD which is based on the agent for Linux, but which has been adapted for FreeBSD entities, such as using different output formats of the command line tools and different path conventions. However, installation and functional testing must be largely manual, as there is no provision for packaging or deployment via the Agent Bakery.

Note regarding other BSD systems: This article explains the installation and setup of the agent for FreeBSD — Agents for OpenBSD and NetBSD are also available. The installation for those is similar to the that described here. If you use DragonFly BSD, we would welcome tests and any suggested patches for the FreeBSD agent.

The basic structure of the FreeBSD agent is the same as described for the Linux agent: It is a pure shell script, which can be executed via an internet superserver (inetd or xinetd) or an SSH tunnel, which makes it lightweight and secure.

In general we assume in this article that you have some experience with Linux or Solaris, so here we will mainly focus on the differences.

2. Installation

2.1. Prerequisites

In order for the Checkmk agent to be able to read all of the information useful for the monitoring, the installation of additional tools is required:

  • sysutils/ipmitool

  • devel/libstatgrab

  • shells/bash

  • lang/python3

  • ftp/wget

Python is optional at this point, but in any case is needed for many agent plug-ins. A special feature is bash, since the agent script actually uses a syntax which is not compatible with the FreeBSD Bourne Shell. The ipmitool is needed to read hardware information.

You install all of these tools with the following command:

root@bsd:/root # pkg install ipmitool libstatgrab bash python3 wget

2.2. Installation over the FreeBSD Ports

The FreeBSD Ports contain a port for the Checkmk agent maintained by Mark Peek, which may contain patches to make the agent compatible with newer FreeBSD-STABLE versions. If the version (e.g. 2.0.0) of this Checkmk agent available in the FreeBSD ports is equal to or slightly higher than your Checkmk version currently in use, you can install this agent.

root@bsd:/root # cd /usr/ports/net-mgmt/check_mk_agent
root@bsd:/usr/ports/net-mgmt/check_mk_agent # make install

2.3. Manual installation

If the version available in the FreeBSD ports is older than that on your Checkmk server, install the latest agent from the GitHub repository. Since customizations to new FreeBSD versions do not always backport to agents for older Checkmk versions, it is usually a good idea to install from the most recent development branch:

root@bsd:/root # wget -O /usr/local/bin/check_mk_agent https://checkmk.io/3EjKJlt
root@bsd:/root # chmod 0700 /usr/local/bin/check_mk_agent

If you are looking for the agents for other BSD systems or want to set the development branch to a specific Checkmk version, locate the agent folder in Github.

2.4. Test at the command line

Now call the agent on the command line and skim over the output in the pager:

root@bsd:/root # check_mk_agent | more
<<<check_mk>>>
Version: 2.1.0i1
AgentOS: freebsd
Hostname: fbsd13
AgentDirectory: /etc/check_mk
DataDirectory:
SpoolDirectory: /var/spool/check_mk_agent
PluginsDirectory: /usr/local/lib/check_mk_agent/plugins
LocalDirectory: /usr/local/lib/check_mk_agent/local

If no output at all is produced, please check the prerequisites again, in particular that Bash is installed under /usr/local/bin.

3. Setting up access via the network

3.1. FreeBSD inetd

The easiest way to access the agent is the inetd provided with FreeBSD. Alternatively, the Linux xinetd is available from the security section in the FreeBSD Ports. Its configuration is exactly the same as described in the Linux agent article. The inetd binds the output of the agent to TCP port 6556 and — if necessary — restricts access to certain Checkmk servers.

First, check if your /etc/services already contains an entry for port 6556:

root@bsd:/root # grep 6556/ /etc/services

If this is not the case, Checkmk must be identified as a service. To do this, add the following line:

/etc/services
checkmk-agent 6556/tcp #Checkmk monitoring agent

Now add the following line to the /etc/inetd.conf configuration file:

/etc/inetd.conf
checkmk-agent stream tcp nowait root /usr/local/bin/check_mk_agent check_mk_agent

The inetd must always be activated. To do this, append the following line to the /etc/rc.conf file:

/etc/rc.conf
inetd_enable="YES"

If access restriction is necessary, edit the /etc/hosts.allow file. First comment out the line that allows access from anywhere, then add a line that allows access only to the Checkmk server — here with the IP address 10.2.3.4. The first parameter is the name of the command executed by inetd:

/etc/hosts.allow
# The rules here work on a "first match wins" basis.
# ALL : ALL : allow
sshd : ALL : allow
check_mk_agent : 10.2.3.4 : allow

Once the configuration changes have been made, reboot:

root@bsd:/root # reboot

Now access to the agent from the monitoring server should work.

The easiest way to test this is with netcat or nc. Run the following command as the site user on the Checkmk server to test the network connection to the agent (in this example, to the host with the IP address 10.2.3.5). The command output is here abbreviated to show only the first lines:

OMD[mysite]:~$ nc 10.2.3.5 6556
<<<check_mk>>>
Version: 2.1.0i1
AgentOS: freebsd

3.2. Security

Since the FreeBSD agent does not currently support encryption, we recommend using an SSH tunnel in situations where it is necessary to secure the transferred data. We explain how to set this up in the Linux agent article.

4. Inclusion into the monitoring

The inclusion into the monitoring is performed by an automatic service discovery, as with all other systems. For a 'bare' FreeBSD with no server services configured yet, at least 12 services should be discovered, and ten additional ones for file system information if installed on ZFS:

List of 12 automatically discovered services.
The service discovery in Checkmk will find at least 12 services.

5. Plug-ins

Because of the completely manual configuration, the lack of automatic distribution and the different file paths compared to Linux, it is recommended to test the most important plug-in mechanisms. This is started using MRPE.

5.1. MRPE

Create a configuration file /etc/check_mk/mrpe.cfg with the following content:

/etc/check_mk/mrpe.cfg
Flux_Comp /bin/echo 'OK - Flux compensator up and running'

There should now be an MRPE section in the agent’s output:

root@bsd:/root # check_mk_agent | grep -A1 '^...mrpe'
<<<mrpe>>>
(echo) Flux_Comp 0 OK - Flux compensator up and running

In the service discovery Flux_Comp now appears as a new service:

List with the newly detected service Flux_Comp.
The MRPE plugin has been configured successfully

5.2. Agent plug-ins

The installation of the agent plug-ins is the same as described in the Linux agent article. Be sure to use the correct Shebang when installing any plug-ins. Perl and Python are installed in /usr/local/bin on FreeBSD, and many a shell script that works with /bin/sh on Linux actually requires the Bourne Again shell installed in /usr/local/bin/bash on FreeBSD.

For testing, a simple local check is suitable, with which the evaluation of whether the monitored service is OK, WARN or CRIT is done directly on the monitored host. While we’re at it, let’s use a two-liner to test the Python interpreter. Again, note the different default paths compared to Linux:

/usr/local/lib/check_mk_agent/local/hello.py
#!/usr/local/bin/python3
print("0 \"Hello Beastie\" - Just check paths and Python interpreter!")

Don’t forget to make the script executable:

root@bsd:/root # chmod 0755 /usr/local/lib/check_mk_agent/local/hello.py

Also in this case the service is found immediately:

List with the newly detected service Hello Beastie.
The new service "Hello Beastie" was found

6. Files and directories

6.1. File paths on the host being monitored

File path Description

/usr/local/bin/check_mk_agent

Installation location of the Checkmk agent on the target host.

/usr/local/lib/check_mk_agent

Base directory for agent extensions.

/usr/local/lib/check_mk_agent/plugins

Plug-ins, which extend the agent with additional monitoring data. Plug-ins can be written in any available programming language.

/usr/local/lib/check_mk_agent/local

Storage location for custom local checks.

/var/spool/check_mk_agent

Contains data that is created by cronjobs, for example, and includes its own section. These are also appended to the agent output.

/etc/check_mk

Storage location for the agent’s configuration files.

/etc/check_mk/mrpe.cfg

Configuration file for MRPE — for running classic Nagios compatible check plug-ins.

Attention: There are no default file paths defined for FreeBSD, as there are for Linux below /var/lib/check_mk_agent. Choose a suitable location and enter this in the agent’s script.

On this page