Initial commit
This commit is contained in:
197
README.md
Normal file
197
README.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user