Yodmon/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this project does

Yodmon is a bridge between the Yodeck digital signage API and Zabbix monitoring. It polls the Yodeck API every 10 minutes, stores player state in SQLite, exposes the data via SNMP v2c (for Zabbix to poll every minute), auto-creates/updates Zabbix hosts, and provides a web dashboard.

Running locally (dev)

pip install flask requests apscheduler
python dev_server.py          # web UI at http://localhost:8080
python snmp_test.py           # print OID tree to verify SNMP data
python snmp_test.py --filter <name_or_id>

dev_server.py sets DB_PATH to ./data/yodmon.db and skips SNMP (Linux/Docker only).

Running in Docker

docker compose up -d          # SNMP on :161/udp, web UI on :8080

Before starting, set APP_HOST in docker-compose.yml to the host IP reachable by Zabbix, and optionally fill in ZABBIX_URL / ZABBIX_PASSWORD.

Configuration

All settings come from environment variables (see app/config.py). Key ones:

Variable	Default	Purpose
YODECK_API_TOKEN	—	Token yodeck:<secret> format
APP_HOST	127.0.0.1	IP Zabbix uses to reach this app's SNMP agent
ENTERPRISE_OID	.1.3.6.1.4.1.99999	Root OID for all player data
SNMP_COMMUNITY	public	SNMPv2c community string
ZABBIX_URL	""	Leave empty to disable Zabbix auto-sync
DB_PATH	/data/yodmon.db	SQLite file path

Architecture

Yodeck API (every 10 min)
    └── app/scheduler.py  →  app/yodeck.py     fetches all screens (paginated)
                          →  app/database.py   upserts players + writes logs
                          →  app/zabbix.py     creates/updates Zabbix hosts via JSON-RPC API

Zabbix SNMP poll (every 1 min)
    └── snmpd (net-snmp)  →  snmp/pass_persist.py  reads SQLite, serves OIDs over stdin/stdout

Web UI
    └── app/web.py (Flask)  →  templates/index.html  shows player table + activity log

SNMP OID structure — ENTERPRISE_OID.1.1.<column>.<yodeck_id>:

• col 1 STRING hostname (yodeck-<id>)
• col 2 STRING display name
• col 3 INTEGER online (0/1)
• col 4 STRING last_seen (ISO-8601)
• col 5 INTEGER updating (0/1)
• col 6 INTEGER registered (0/1)

The Yodeck ID is used directly as the SNMP table index, so OIDs are stable and predictable (e.g. .1.3.6.1.4.1.99999.1.1.3.54239 = online status of player 54239).

Database — two tables in yodmon.db:

• players — one row per Yodeck player, upserted on each poll
• logs — append-only activity log; event types: yodeck_fetch, zabbix_sync, snmp_transfer, error

Docker entrypoint (entrypoint.sh) templates /etc/snmp/snmpd.conf from env vars at startup, then starts snmpd in the background before handing off to python main.py.

Zabbix integration (app/zabbix.py) targets Zabbix 6.0+ API (item type 20 = SNMP agent). Set ZABBIX_URL to enable; the sync runs after every successful Yodeck poll.