monokit

monokit is a collection of tools that were previously written in Bash in the mono.sh repository. These tools are written in Go and provide a more efficient and faster alternative to the Bash scripts. The tools are cross-platform.

---

Table of Contents

• Table of Contents
• Tools
• Usage
• Building
• License

---

Core tools

These core tools will be available in every monokit installation.

• logs

  • Log viewing tool for monokit.
  • Allows you to comprehensively filter components using log types, fields, component, date, version and more.
  • Also has wildcard support for easy searching.

• db

  • Inspect the monokit health SQLite database.
  • Subcommands:
    • path: Print the SQLite DB path
    • list [--module ]: List keys (optionally filter by module)
    • get <key> --module : Get value for a key
    • dump [--module ]: Dump entries as JSON
    • del <key> --module : Delete a key
  • Examples:

    monokit db path
    monokit db list --module osHealth
    monokit db get <key> --module pgsqlHealth
    monokit db dump --module redisHealth
    monokit db del <key> --module pgsqlHealth

  • Use --no-colors or set MONOKIT_NOCOLOR=1 to disable colored JSON output.

• plugin

  • Plugin management system for monokit.
  • Allows you to install, list, and remove plugins.
  • Plugins are installed to /var/lib/monokit/plugins.

• client

  • A client that sends information to the Monokit server.
  • Config: /etc/mono/client.yaml

• shutdownNotifier

  • Notifies of a poweroff/poweron through the Slack webhook.

• sshNotifier

  • Notifies of a successful SSH login/logout through the Slack webhook.
  • Config: /etc/mono/ssh-notifier.yaml

• osHealth

  • Checks OS health, including Disk, CPU and Memory usage.
  • Sends alarm notifications to a Slack webhook.
  • Opens issue in Redmine if disks are above the threshold.
  • Config: /etc/mono/os.yaml

• redmine

  • Allows you to create, update and close issues in Redmine.
  • Has a service system that keeps track of the issue ID.
  • Config: /etc/mono/global.yaml

• alarm

  • Sends alarm notifications to a Slack webhook.
  • Config: /etc/mono/global.yaml

• daemon

  • Daemonizes Monokit, allowing you to run it as a service.
  • Runs health checks with the specified interval.
  • Config: /etc/mono/daemon.yaml

• update

  • Updates the monokit binary to the latest version.
  • Allows you to choose the version to update with the --version flag.

• migrate

  • Migrates from a old version of Monokit to a new one in case of a breaking change.

• versionCheck

  • Checks the version of various services, including OPNsense, Zimbra and Proxmox.
  • Creates a Redmine news entry if the version has been updated.
  • Config: /etc/mono/global.yaml

Tools

• esHealth

  • Check Opensearch/Elasticsearch health.
  • Validates cluster health status through the /_cluster/health endpoint.
  • Monitors shard allocation issues using the /_cluster/allocation/explain endpoint.
  • Sends alarm notifications if shards cannot be allocated.
  • Config: /etc/mono/es.yaml

• server

  • An API server that gets information from other Monokit instances.
  • Config: /etc/mono/server.yaml
  • Only available on with_api builds.

• zimbraLdap

  • Runs ldap.sh script.

• traefikHealth

  • Check Traefik health, including service status and logs.
  • Sends alarm notifications to a Slack webhook.

• pritunlHealth

  • Check Pritunl server health.
  • Sends alarm notifications to a Slack webhook.
  • Config: /etc/mono/pritunl.yaml (optional)

• postalHealth

  • Check Postal health, including service status, containers, and queued messages.
  • Checks SMTP SSL certificate expiry (port 25, STARTTLS) and opens a Redmine issue when nearing expiration.
  • Sends alarm notifications to a Slack webhook.
  • Opens an issue in Redmine if the database is down.
  • Config: /etc/mono/mail.yaml

• zimbraHealth

  • Check Zimbra health, including service status, queued messages, SSL certificate expiry and Z-Push status.
  • Sends alarm notifications to a Slack webhook.
  • Opens an issue in Redmine if the SSL certificate is about to expire.
  • Config: /etc/mono/mail.yaml

• pmgHealth

  • Checks PMG health, including service status, queued messages and PostgreSQL status.
  • Sends alarm notifications to a Slack webhook.
  • Config: /etc/mono/mail.yaml

• k8sHealth

  • Checks Kubernetes health, including node status and certificate expiration.
  • Tracks the running Kubernetes server version against endoflife.date and alarms when the cycle is near or past End-of-Life (configurable eol.warn_days, default 180).
  • Sends alarm notifications to a Slack webhook.
  • Config: /etc/mono/k8s.yaml
  • Is a plugin, install it with monokit plugin install k8sHealth.

• mysqlHealth

  • Checks MySQL health, including read and write operations.
  • Supports Galera Cluster monitoring (Receive Queue and Flow Control).
  • Verifies scheduled events (event_scheduler) are consistent: on a Galera cluster, ENABLED on exactly one node and SLAVESIDE_DISABLED on the rest (by connecting to peer nodes discovered via wsrep_incoming_addresses); on a standalone node, all events are ENABLED.
  • Alarms when event_scheduler is not ON on a node that still has ENABLED events (they would never run).
  • Events can be excluded from this check with the mysql.disabled_events config list (bare event names or schema.event_name).
  • Sends alarm notifications to a Slack webhook.
  • Opens Redmine issues for Galera Flow Control issues, event_scheduler inconsistencies, and ENABLED events on a node with event_scheduler off.
  • Config: /etc/mono/db.yaml

• mongodbHealth

  • Checks standalone and replica set MongoDB health.
  • Monitors connections/cache/WiredTiger ticket usage, primary election, secondary quorum, replication lag and oplog window.
  • Sends alarm notifications to a Slack webhook.
  • Opens Redmine issues for connection loss, primary absence, secondary quorum loss, critical replication lag and critical oplog window.
  • Config: /etc/mono/db.yaml
  • By default connects to mongodb://127.0.0.1:27017/admin with no credentials, which works out of the box on MongoDB instances without auth enabled.
  • If the target MongoDB has auth enabled, serverStatus/replSetGetStatus require a real user - mongodbHealth detects this and raises a mongodb-metrics-permission / mongodb-replicaset-mismatch alarm instead of silently misreporting. To fix, create a minimal-privilege monitoring user and put its credentials in the uri:

    // in mongosh, connected as an admin user:
    use admin
    db.createUser({
      user: "monokit_monitor",
      pwd: "CHANGE_ME",
      roles: [ { role: "clusterMonitor", db: "admin" } ]
    })

    # /etc/mono/db.yaml
    mongodb:
      uri: "mongodb://monokit_monitor:CHANGE_ME@127.0.0.1:27017/admin?authSource=admin"

    clusterMonitor is read-only and sufficient for all checks mongodbHealth performs (no write/admin access needed).

• pgsqlHealth

  • Checks PostgreSQL health, including read and write operations.
  • Sends alarm notifications to a Slack webhook.
  • Config: /etc/mono/db.yaml

• mongodbHealth

  • Checks MongoDB health, standalone and replica set.
  • Monitors connections/cache/WiredTiger ticket usage, primary election, secondary quorum, replication lag and oplog window.
  • Sends alarm notifications to a Slack webhook.
  • Opens Redmine issues for connection loss, ticket exhaustion, primary absence, secondary quorum loss, critical replication lag and critical oplog window.
  • Config: /etc/mono/db.yaml

• redisHealth

  • Checks Redis health, including read and write operations.
  • Sends alarm notifications to a Slack webhook.
  • On sentinel masters whose connected slave count differs from slave_count, opens a Redmine issue and closes it once the count matches again.
  • Config: /etc/mono/redis.yml (optional)
  • Is a plugin, install it with monokit plugin install redisHealth.

• rmqHealth

  • Checks RabbitMQ health, including service status, Management API, port availability and cluster node status.
  • Monitors queue health: detects stopped queues, missing consumers, message backlog and mirror/quorum sync issues.
  • Sends alarm notifications to a Slack webhook.
  • Opens a single Redmine issue listing every stopped or unsynced queue, and updates that list as queues start or stop failing.
  • Config: /etc/mono/rabbitmq.yaml (optional)

    user: guest
    password: guest
    queues:
      enabled: true                # enable queue health checks (default: false)
      mirrorSyncCheck: true        # alarm if classic/quorum queues are not fully synced across all nodes
      consumerCheck: false         # alarm if a queue has no active consumers
      messageThreshold: 0          # alarm if message count exceeds this value (0 = disabled)
      expectedMirrorCount: 0       # expected number of mirrors/slaves (0 = cluster node count - 1)
      ignoreQueues: []             # queue names to skip from all checks
      redmine:
        enabled: true              # open one Redmine issue listing all stopped/unsynced queues
        excludeQueues: []          # queue names to leave out of that issue

• lbPolicy

  • Allows you to switch between the load balancing policies on Caddy, and list current policies.
  • Config: /etc/mono/glb-*.yaml

• wppconnectHealth

  • Checks WPPConnect health, phone status.
  • Sends alarm notifications to a Slack webhook.
  • Config: /etc/mono/wppconnect.yaml
  • Is a plugin, install it with monokit plugin install wppconnectHealth.

• ufw

  • Manages UFW rules by downloading and applying IP lists from URLs.
  • Supports both dynamic URL-based rules and static rules.
  • Config: /etc/mono/ufw.yaml

---

Usage

1. Configure by editing the config files in /etc/mono/. You can default values in the config folder. Please keep in mind that to use any of the tools, you need to also configure /etc/mono/global.yaml file.

2. Run the desired tool using the following command as root:

monokit NAME

Replace NAME with the name of the tool you want to run (e.g. osHealth).

A log file will be put on /var/log/monokit.log if you want to check the errors. They will also be printed to stdout.

If you use Monokit on a place where there is no proper color support, you can disable the color output by setting the MONOKIT_NOCOLOR  environment variable to true or 1.

Windows

• Copy the Windows config templates (config/win.yaml and config/global.yml) from the release archive to C:\\ProgramData\\mono\\ or next to monokit.exe inside a config folder.
• Run monokit.exe winHealth from an elevated terminal to collect and report Windows health data.
• Enable Windows service monitoring by setting services.enabled: true in win.yaml; use include, exclude, and status lists to scope which services are reported.
• License expiry alerts use the license.expiration_limit value in win.yaml (defaults to 30 days).

---

Kubernetes Deployment

Some components of monokit, like k8sHealth, can be deployed directly in Kubernetes. We've provided Kubernetes manifests and instructions to help you deploy these components in your cluster.

k8sHealth in Kubernetes

To deploy k8sHealth in a Kubernetes cluster:

1. Go to the k8sHealth/kubernetes/ directory
2. Update the configmap.yaml with your specific configurations
3. Run ./deploy.sh to deploy all resources

The deployment includes:

• RBAC resources for appropriate permissions
• ConfigMap for configuration
• Deployment or CronJob (configurable) for running k8sHealth

For more details, see the k8sHealth Kubernetes README.

Docker Images

Docker images for monokit are automatically built and published to GitHub Container Registry (ghcr.io) through GitHub Actions. These images are built for multiple architectures (amd64 and arm64), so they'll work on both Intel/AMD and ARM-based systems including Raspberry Pi.

You can use these images in your Kubernetes deployments:

image: ghcr.io/monobilisim/monokit:latest  # Latest stable release
# OR
image: ghcr.io/monobilisim/monokit:1.2.3   # Specific version

---

Building

To build monokit:

make

To build plugins:

make build-plugins

You can also build the documentation by running:

make docs

To build a binary with the API server:

make with-api

To see other options run:

make help

The resulting binaries will be in the bin folder.

---

License

monokit is licensed under GPL-3.0-only. See LICENSE file for details.