This article explains how to manually run Checkmk agent plugins for debugging when they cannot be executed directly from the command line.

LAST TESTED ON CHECKMK 2.4.0P22

Table of Contents

Overview

This article explains how to manually execute Checkmk agent plugins for troubleshooting and debugging purposes.

Some agent plugins cannot be run directly from the command line because they rely on environment variables that are automatically set by the Checkmk Agent during normal operation. If these variables are not defined, the plugin may fail or return incomplete results.

The Oracle plugin is used as an example in this article. The same procedure applies to any agent plugin that depends on agent provided environment variables.

Problem

When running an agent plugin manually from the command line, you may observe:

Errors related to missing files or configuration
Unexpected or incomplete output
Plugin termination without meaningful error messages

This behavior is expected.

During normal monitoring, the Checkmk Agent prepares the required runtime environment before executing plugins. If a plugin is started manually, these environment variables are not defined.

Solution

To manually execute such plugins, you must define the required environment variables before running the plugin.

Commonly required variables:

MK_LIBDIR
Path to the agent library directory
MK_CONFDIR
Path to the agent configuration directory
MK_VARDIR
Path to the agent runtime or variable data directory
Required by some plugins, for example mk_oracle

The exact paths depend on how the agent was installed.

You can verify which variables are currently defined in your shell:

env | grep MK_

Linux

Legacy installation

This applies to classic Linux agent installations using system packages.

Example:

MK_LIBDIR=/usr/lib/check_mk_agent \
MK_CONFDIR=/etc/check_mk \
MK_VARDIR=/var/lib/check_mk_agent \
/usr/lib/check_mk_agent/plugins/60/mk_oracle --no-spool

Alternatively, you can export the variables first:

export MK_LIBDIR=/usr/lib/check_mk_agent
export MK_CONFDIR=/etc/check_mk
export MK_VARDIR=/var/lib/check_mk_agent

/usr/lib/check_mk_agent/plugins/60/mk_oracle --no-spool

Adjust paths if your system uses different directories.

Packaged agent installation

This applies to installations where the agent was deployed using the Checkmk agent package.

Example:

MK_LIBDIR=/opt/checkmk/agent/default \
MK_CONFDIR=/opt/checkmk/agent/default/config \
MK_VARDIR=/opt/checkmk/agent/default/var \
/opt/checkmk/agent/default/plugins/oracle_unified_sync

Adjust the path according to your installation directory.

Windows

On Windows systems, agent plugins are typically PowerShell scripts located under:

%PROGRAMDATA%\checkmk\agent\plugins

Command prompt example

Open a Command Prompt and define the required variables:

set MK_LIBDIR=%PROGRAMDATA%\checkmk\agent
set MK_CONFDIR=%PROGRAMDATA%\checkmk\agent\config
set MK_VARDIR=%PROGRAMDATA%\checkmk\agent\var

Then execute the plugin using PowerShell:

powershell .\oracle_unified_sync.ps1

Make sure you are in the directory where the plugin script is located or use the full absolute path.

Notes for Windows

You may need to run the shell as Administrator.
PowerShell execution policy may block unsigned scripts.
Ensure the script has sufficient permissions.
Some plugins may require additional runtime components depending on their implementation, for example Oracle client libraries.

Important notes

This procedure is only required for manual debugging

The steps in this article are intended for troubleshooting purposes only. Under normal operation, you do not need to manually execute agent plugins.

Manual execution is typically used to:

Reproduce errors
Verify plugin output
Perform advanced debugging

If monitoring works as expected, no manual action is required.

The Checkmk Agent sets required environment variables automatically

When the Checkmk Agent runs a plugin, it prepares the required runtime environment. This includes setting variables such as:

MK_LIBDIR
MK_CONFDIR
MK_VARDIR

These variables allow the plugin to locate configuration files, libraries, and runtime data.

If you execute a plugin directly without defining them, it may fail or return incomplete output. This behavior is expected.

Execute the plugin from the correct location

Always run the plugin using its full absolute path or from its installation directory. Running it from another location may lead to misleading results.

Plugin cache

Some Checkmk plugins use caching. On Windows, this cache is cleared by restarting the Checkmk service, while on Linux, it can be reset by manually deleting the cached files located in /var/lib/check_mk_agent/cache/.

root@mylinuxhost:/var/lib/check_mk_agent/cache$ ls -ltr
total 8
-rw-r--r-- 1 root root  409 Mar  5 17:17 plugins_cmk-update-agent.cache
-rw-r--r-- 1 root root 3949 Mar 19 08:58 omd_status.cache

Ensure proper execution permissions

On Linux, verify that the plugin has executable permissions.
On Windows, ensure that PowerShell execution policy and permissions allow the script to run.

Do not permanently modify environment variables

Only define required variables temporarily within your current shell session. Do not add them to system wide configuration files.

After debugging, close the shell or unset the variables to restore the normal environment.

How-to manually start agent plugins for debugging