README

Easy-to-use, but feature-rich client for Checkmk Web API

Please note: This project is not an official product by synetics GmbH. synetics GmbH doesn't provide any commercial support.

About

Checkmk is a software application for network monitoring. The community edition ("raw") is licensed under the GPLv2.

This client communicates with Checkmk over its Web API. It provides a simple, but powerful abstraction layer for written in PHP. Feel free to use it as a library in your own projects.

Requirements

Meet these simple requirements before using the client:

One or more Checkmk sites, version 1.4 or higher (most calls work since 1.5)
PHP, version 8.0 or higher (8.1 is recommended, 7.4 should work but is deprecated)
PHP modules curl, date, json, openssl, spl and zlib

Installation

It is recommended to install this client via Composer. Change to your project's root directory and fetch the latest stable version:

composer require idoit/checkmkwebapiclient

This command installs the latest stable version. Instead of sticking to a specific/minimum version you may switch to the current development branch by using @DEV:

composer require "idoit/checkmkwebapiclient=@DEV"

Updates

Composer has the great advantage (besides many others) that you can simply update the client by running:

composer update

Usage

Composer comes with its own autoloader. Include this line into your PHP code:

require_once 'vendor/autoload.php';

This is it. All other files will be auto-loaded on-the-fly if needed.

First call

This is a simple "Hello, world!" example. It fetches all configured hosts from Checkmk:

use Idoit\CheckmkWebAPIClient\API;
use Idoit\CheckmkWebAPIClient\Config;
use Idoit\CheckmkWebAPIClient\Host;

$config = new Config();
$config
    ->setURL('https://monitoring.example.org/mysite/check_mk/')
    ->setUsername('automation')
    ->setSecret('abc123');

$api = new API($config);

$request = new Host($api);
$hosts = $request->getAll();

var_dump($hosts);

Configuration

The API class requires configuration settings passed to its constructor:

use Idoit\CheckmkWebAPIClient\API;
use Idoit\CheckmkWebAPIClient\Config;

$config = new Config();
$config
    ->setURL('https://monitoring.example.org/mysite/check_mk/')
    ->setPort(443)
    ->setUsername('automation')
    ->setSecret('abc123')
    ->enableProxy()
    //->disableProxy()
        ->useHTTPProxy()
        //->useSOCKS5Proxy()
        ->setProxyHost('proxy.example.net')
        ->setProxyPort(8080)
        ->setProxyUsername('proxyuser')
        ->setProxyPassword('verysecure');

$api = new API($config);

The Config class has public methods which must be called to configure the API:

Optional proxy settings:

Hosts

Class Host with public methods:

Sites

Class Site with public methods:

Folders

Class Folder with public methods:

Groups

Classes HostGroup, ServiceGroup and ContactGroup with public methods:

Host Tags

Class HostTag with public methods:

Users

Class Users with public methods:

Rulesets

Class Ruleset with public methods:

Agents

Class Agent with public methods:

Activate Changes

Class Change with public methods:

Metrics

Class Graph with public method:

Inventory

Checkmk can collect various information about your hardware/software inventory.

Class Inventory with public methods:

Contribute

Please, report any issues to our issue tracker. Pull requests are very welcomed. If you like to get involved see file CONTRIBUTING.md for details.

Copyright & License

Licensed under the GNU Affero GPL version 3 or later (AGPLv3+). This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

idoit / checkmkwebapiclient

Maintainers

Details