checkmk-minecraft/README.md

# Checkmk Minecraft Monitoring Plugin

This repository provides a **Checkmk MKP package** to monitor Minecraft servers.

It includes both an **agent plugin** (running on the Minecraft host) and a **check plugin** (running in Checkmk).



## Features

* **Server statistics** via the built-in Minecraft **Query interface**

  * Player count (online/max)
  * Player list
  * MOTD
  * Server version
  * Ping
* **Per-world performance metrics** (via **RCON**, optional)

  * TPS (ticks per second)
  * Tick time (ms)
* Automatic service discovery for each server and its worlds
* Metrics for graphs and performance analysis in Checkmk
* Error handling with fail counter to suppress short outages



## Requirements

* A running [Checkmk](https://checkmk.com/) installation (v2.x or newer recommended)
* Minecraft server with **Query interface enabled** (default on most servers)
* Optional: **RCON enabled** if you want per-world TPS and tick-time monitoring

Currently, **only NeoForge has been tested for RCON TPS support**.
If you need other implementations or encounter problems, please [open an issue](https://git.project-name-here.de/Project-Name-Here/checkmk-minecraft/issues).


## Installation

### Development setup

If you want to work on or test the plugin directly inside a Checkmk site, you have two options:

**a) Release an installed MKP**
If you already installed the package via `mkp install`, you can release it:

```bash
omd su <yoursite>
mkp release minecraft
```

This removes the MKP registration but leaves all contained files unpacked in the correct places under `~/local/...`, so you can edit them directly:

* **Check plugin (agent-based):** `~/local/lib/python3/cmk_addons/plugins/minecraft/agent_based/`
* **Graph definitions:** `~/local/lib/python3/cmk_addons/plugins/minecraft/graphing/`
* **Agent plugin:** `~/local/share/check_mk/agents/plugins/minecraft.py` (Just for download purposes)

**b) Clone the repository into your development site**
Alternatively, you can clone this repository directly into the site’s local directory:

```bash
omd su <yoursite>
cd ~/local/lib/python3/cmk_addons/plugins
git clone https://git.project-name-here.de/Project-Name-Here/checkmk-minecraft.git minecraft

# reload monitoring core
cmk -R
```

This way you can pull updates from git and test changes directly.

### Installation from MKP (recommended)

For production use install the packaged MKP:

* Download the `.mkp` file from the [Releases](https://git.project-name-here.de/Project-Name-Here/checkmk-minecraft/releases) or Checkmk Exchange.
* Install it via GUI (**Extension Packages**) or via CLI:

```bash
omd su <yoursite>
mkp install minecraft-<version>.mkp
cmk -R
```

After installation, the **agent plugin** is available for download in the Checkmk GUI under *Agents → Plugins*. Install it on your Minecraft server as described in the next section.

## Agent Plugin Setup

On the monitored Minecraft server host, place the agent plugin in `/usr/lib/check_mk_agent/plugins/` and make it executable. It will then be executed automatically by the Checkmk agent. You can also run it manually for testing:

```bash
/usr/lib/check_mk_agent/plugins/minecraft.py
```

This will generate or update the `minecraft.cfg` file in the same directory.

### Dependencies

Install the required Python dependencies on the monitored Minecraft server:

```bash
pip3 install mcstatus mcrcon --break-system-packages
apt install python3-typeguard
```


## Usage

1. Run the agent plugin once on your Minecraft server. This will automatically generate a configuration file (`minecraft_servers.json`) in the same directory, which you can edit to define server addresses and optional RCON credentials.
2. Run a service discovery in Checkmk for the host.
3. You should now see:

   * One service for the **server itself** (players, MOTD, version, ping).
   * Additional services for each **world** (TPS and tick times, if RCON is enabled).
4. Graphs will be available for player counts, ping, TPS, and tick times.

### Example Configuration

A simple automatically generated config (`minecraft_servers.json`):

```json
[
  {
    "name": "default",
    "host": "127.0.0.1",
    "port": 25565,
    "rcon": false,
    "rcon_type": "neoforge",
    "rcon_port": 25575,
    "rcon_password": ""
  }
]
```

A valid configuration with multiple servers:

```json
[
  {
    "name": "server1",
    "host": "127.0.0.1",
    "port": 25565,
    "rcon": true,
    "rcon_type": "neoforge",
    "rcon_port": 25575,
    "rcon_password": "xxxxxxxxxxx"
  },
  {
    "name": "server2",
    "host": "127.0.0.1",
    "port": 25566,
    "rcon": false,
    "rcon_type": "neoforge",
    "rcon_port": 25575,
    "rcon_password": ""
  },
  {
    "name": "server3",
    "host": "127.0.0.1",
    "port": 25567,
    "rcon": false,
    "rcon_type": "neoforge",
    "rcon_port": 25575,
    "rcon_password": ""
  },
  {
    "name": "server4",
    "host": "127.0.0.1",
    "port": 25568,
    "rcon": false,
    "rcon_type": "neoforge",
    "rcon_port": 25575,
    "rcon_password": ""
  }
]
```

## Error Handling

* Both Query and RCON errors are checked.
* A **fail counter** prevents false alarms by tolerating short outages.
* After 5 consecutive failures, the check switches to **CRIT**.


## Development & Contributions

* Currently tested only with **NeoForge** for RCON TPS values.
* Support for additional server implementations may be added later.
* If you need support for another implementation or encounter issues, please [open an issue](https://git.project-name-here.de/Project-Name-Here/checkmk-minecraft/issues).

Contributions via pull requests are welcome!


## License

This project is licensed under the **GNU General Public License v3.0** (GPL-3.0).
See the [LICENSE](LICENSE) file for details.