Skip to content

Latest commit

 

History

History
251 lines (174 loc) · 13 KB

README.md

File metadata and controls

251 lines (174 loc) · 13 KB
Raw

Checkmk Web API Client

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

Latest Stable Version Minimum PHP Version Build status

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:

Setting Parameter Required Description
setURL() string yes URL to Checkmk without entry point, for example https://monitoring.example.com/mysite/check_mk/
setPort() integer no Port on which the Web server listens; if not set port 80 will be used for HTTP and 443 for HTTPS
setUsername() string yes User for authentication, probably automation
setSecret() string yes Secret specified for user
enableProxy() – no Use a proxy between client and server; see below for details

Optional proxy settings:

Setting Parameter Required Description
disableProxy() boolean no Disable proxy settings; this is the default
useHTTPProxy() – yes Use a HTTP(S) proxy
useSOCKS5Proxy() – yes Use a SOCKS5 proxy
setProxyHost() string yes FQDN or IP address to proxy
setProxyPort() integer yes port on which the proxy server listens
setProxyUsername() string no Authenticate against proxy
setProxyPassword() string no Specified password for authentication

Hosts

Class Host with public methods:

API Call Class Method Description
get_host get() Read information about a host by its hostname
get_all_hosts getAll() Read information about all hosts
add_host add() Create new host with some attributes and tags
edit_host edit() Edit host, adds new attributes, changes attributes, or unsets attributes
delete_host delete() Delete a host by its hostname
discover_services discoverServices() Discover services of a host

Sites

Class Site with public methods:

API Call Class Method Description
get_site get() Read information about a site by its identifier
– getAll() Read information about all sites

Folders

Class Folder with public methods:

API Call Class Method Description
get_folder get() Read information about a folder by its path
get_all_folders getAll() Read information about all folders
add_folder add() Create new folder with some attributes
edit_folder edit() Edit a folder's attributes
delete_folder delete() Delete a folder by its path

Groups

Classes HostGroup, ServiceGroup and ContactGroup with public methods:

API Call Class Method Description
get_all_*groups getAll() Read information about all groups
– get() Read information about a group by its name
add_*group add() Create new group with name and alias
edit_*group edit() Change the alias of a group
delete_*group delete() Delete contact group by its name

Host Tags

Class HostTag with public methods:

API Call Class Method Description
get_hosttags getAll() Read information about all host tag groups and auxiliary tags
set_hosttags set() Overwrite all host tag groups and auxiliary tags

Users

Class Users with public methods:

API Call Class Method Description
– get() Read information about an user by its identifier
get_all_users getAll() Read information about all users
– add() Create new user with some attributes
add_users batchAdd() Create new users with some attributes
– delete() Delete a user by its identifier
delete_users batchDelete() Delete users by their identifiers

Rulesets

Class Ruleset with public methods:

API Call Class Method Description
get_ruleset get() Read information about a ruleset by its name
get_rulesets_info getAll() Read information about all rulesets

Agents

Class Agent with public methods:

API Call Class Method Description
bake_agents bake() Bake agents but not sign them

Activate Changes

Class Change with public methods:

API Call Class Method Description
activate_changes activate() Activate changes on specific sites
– activateEverywhere Activate changes on all sites

Metrics

Class Graph with public method:

API Call Class Method Description
get_graph get() Get metrics as a graph

Inventory

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

Class Inventory with public methods:

API Call Class Method Description
- getHost() Read hardware/software inventory data for a specific host
- getHosts() Read hardware/software inventory data for one or more hosts

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

Copyright (C) 2022 synetics GmbH

Copyright (C) 2018-22 Benjamin Heisig

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.