Alles über HawkDNS.

01 Einführung #

HawkDNS ist ein Single-Process-Python-Bot, der Telegram pollt, auf Befehle mit Serverstatus antwortet und dich proaktiv warnt, wenn Domains ausfallen oder Server neu starten. Er läuft als systemd-Dienst. Außer Python 3, curl und (optional) jq hat er null externe Abhängigkeiten.

Das gesamte System besteht aus drei zusammenarbeitenden Komponenten:

• Der Bot — hawkdns-bot.py, ein dauerhaft laufender Python-Prozess, der Telegram pollt und Befehle beantwortet.
• Der Watchdog — hawkdns-watchdog.sh, ein cron-gesteuertes Shell-Skript, das deine Domains alle 2 Minuten prüft und bei Fehlern Alarm schlägt.
• Die Boot-Benachrichtigung — hawkdns-boot-notify.sh, ein One-Shot-systemd-Dienst, der nach jedem Neustart eine Telegram-Nachricht sendet.

Jede Komponente läuft unabhängig. Fällt eine aus, arbeiten die anderen weiter. Der Watchdog ist absichtlich in Bash geschrieben, damit er auch dann läuft, wenn Python oder der Bot tot sind.

02 Voraussetzungen #

Der Bot benötigt root, um System-Statistiken zu lesen und Docker-Befehle auszuführen. Es gibt keinen Nicht-root-Modus.

03 Telegram-Bot einrichten #

Vor der Installation brauchst du zwei Werte: einen Bot-Token und deine Chat-ID. Beide bekommst du direkt von Telegram.

Bot-Token besorgen

1. Öffne Telegram. Suche nach @BotFather.
2. Tippe /newbot und folge den Anweisungen.
3. Wähle einen Anzeigenamen (wird dir gezeigt) und einen Benutzernamen (muss auf bot enden).
4. BotFather antwortet mit deinem Token. Sieht aus wie 1234567:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.
5. Kopiere ihn. Behandle ihn wie ein Passwort.

Chat-ID besorgen

1. Öffne @userinfobot in Telegram.
2. Sende eine beliebige Nachricht. Du bekommst deine numerische ID zurück.
3. Kopiere sie. Sieht aus wie 1476707413.

Bot aktivieren

Suche deinen neuen Bot (z.B. @dein_bot) und sende ihm einmal /start. Damit teilst du Telegram mit, dass du Nachrichten von ihm akzeptierst. Ohne diesen Schritt kann sich der Bot zwar bei der API anmelden, aber dir nichts senden.

04 Installation #

Eine einzige curl-Zeile. Der Installer erkennt dein Betriebssystem, installiert fehlende Pakete, validiert den Token, lädt Dateien herunter, schreibt die Konfiguration, richtet systemd ein und schickt eine Bestätigungsnachricht.

Interaktiv (empfohlen für die Erstinstallation)

$ curl -fsSL https://bot.hawkdns.info/install.sh | sudo bash

Der Installer fragt nach Token, Chat-ID und Server-Name. Der Server-Name nutzt standardmäßig hostname -s.

Headless (CI, Ansible, etc.)

$ curl -fsSL https://bot.hawkdns.info/install.sh | sudo bash -s -- \
    --token="1234567:ABC-DEF…" \
    --chat="987654321" \
    --name="web-prod-1" \
    --yes

Mit Peers (Hub-Modus)

Wenn ein Server mehrere überwachen soll, gib --peers mit:

$ curl -fsSL https://bot.hawkdns.info/install.sh | sudo bash -s -- \
    --token="..." --chat="..." --name="hub" \
    --peers="db1:10.0.0.10,cache:10.0.0.11,web2:10.0.0.12" \
    --yes

Peer-Format: name:host, kommagetrennt. SSH-User ist standardmäßig root, Port 22. Siehe Föderation, wie Peers tatsächlich funktionieren.

Was installiert wird

05 Deine erste Nachricht #

Nach der Installation sendet der Installer eine Bestätigungsnachricht in deinen Chat. Öffne innerhalb von 60 Sekunden Telegram und tippe beim Bot /start.

Du solltest etwa Folgendes sehen:

Tippe einen beliebigen Button. Die Antwort erscheint in-place: dieselbe Nachricht wird mit neuem Inhalt aktualisiert.

06 Konfigurationsdateien #

Alles, was HawkDNS tut, wird durch drei Dateien unter /etc/hawkdns/ gesteuert:

Nach dem Bearbeiten von config.json oder bot.env den Bot neu starten:

$ systemctl restart hawkdns-bot

Beim Bearbeiten von watchdog.conf ist kein Neustart nötig — sie wird bei jedem Cron-Tick neu gelesen.

bot.env #

Environment-Datei im Shell-Stil. Wird von systemd über die Direktive EnvironmentFile= und vom Watchdog-Cron-Skript geladen.

# Vom Installer erzeugt. Vorsichtig bearbeiten.
TG_BOT_TOKEN=1234567:ABC-DEF…
TG_CHAT_ID=987654321
HAWKDNS_SERVER_NAME=web-prod-1

Dateimodus ist 600 (nur root). Halte den Bot-Token geheim.

config.json #

Hauptkonfiguration für den Bot-Prozess. JSON, strikte Syntax.

{
  "bot_token": "1234567:ABC-DEF…",
  "chat_whitelist": ["987654321"],
  "server_name": "web-prod-1",
  "peers": [
    { "name": "db1",    "host": "10.0.0.10", "port": 22, "user": "root" },
    { "name": "cache", "host": "10.0.0.11" }
  ]
}

watchdog.conf #

Eine Domain pro Zeile. Format: domain.com|akzeptierte,status,codes. Zeilen, die mit # beginnen, werden ignoriert.

# öffentliche Seite — muss immer 200 sein
example.com|200

# Admin — Login-Redirect ist okay
admin.example.com|200,302

# API verlangt Auth — 401 ist normal für unauthentifizierte Requests
api.example.com|200,401

# Shop hat mehrere regionale Redirects
shop.example.com|200,301,302

Der Watchdog prüft jede Domain alle 2 Minuten (Cron). Wenn 3 aufeinanderfolgende Prüfungen fehlschlagen (~6 Minuten), wird einmal Alarm geschlagen. Erholt sich die Domain wieder, kommt eine "RECOVERED"-Nachricht und der Zähler wird zurückgesetzt.

Kein Neustart nach dem Bearbeiten nötig. Warte bis zu 2 Minuten auf den nächsten Cron-Tick oder führe /opt/hawkdns/hawkdns-watchdog.sh manuell aus.

Konfiguration bearbeiten #

# Domain zum Watchdog hinzufügen
$ echo "new.example.com|200" >> /etc/hawkdns/watchdog.conf

# Chat-ID ändern (z.B. in eine Gruppe verschoben)
$ nano /etc/hawkdns/bot.env
$ nano /etc/hawkdns/config.json   # auch chat_whitelist aktualisieren!
$ systemctl restart hawkdns-bot

# Peer hinzufügen (Föderation)
$ nano /etc/hawkdns/config.json
$ systemctl restart hawkdns-bot

07 Befehle #

Tippe einen dieser Befehle in deinen Telegram-Chat mit dem Bot. Die Befehle sind nicht case-sensitiv.

08 Inline-Tastaturen #

Alle Ansichten kommen mit einer Telegram-Inline-Tastatur. Ein Klick auf einen Button aktualisiert die aktuelle Nachricht direkt — kein Chat-Spam.

Hauptmenü

Server-Detail

09 Server-Ansichten #

Status eines einzelnen Servers

Ausgelöst durch den Button 📊 server-name oder /server-name. Zeigt Load, RAM (mit Balken), Disk (mit Balken), Uptime, Container-Anzahl und ggf. neu startende/tote Container.

🟢 web-prod-1

Load  0.34 0.28 0.21
RAM   2.9G / 8.0G (frei 5.1G)
      🟩🟩🟩🟩⬜⬜⬜⬜⬜⬜  36%
Disk  54% von 197G (frei 91G)
      🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜  54%
Up    42 Tage, 19 Stunden
📦    26 laufend, 19 gestoppt

⚠️ Down/Restarting:
some-container: Restarting (1) vor 4 Minuten

Kompakte Übersicht (Alle)

Ausgelöst durch den Button 🔄 Alle oder /status. Eine Zeile pro Server mit Einzelbuchstaben-Abkürzungen.

🦅 Alle Server

🟢 web-prod-1  L 0.3 M 36% D 54% 📦26
🟢 db1         L 0.1 M 67% D 23% 📦 5
🟡 cache       L 1.4 M 88% D 41% 📦 8 ⚠️1
🟢 worker      L 0.0 M 42% D 19% 📦 3

L=Load · M=RAM% · D=Disk% · 📦=Container

Emojis: 🟢 gesund, 🟡 hohe Auslastung (RAM/Disk > 85% oder Load > 2), 🔴 hat ausgefallene Container.

Down-Filter

Zeigt nur problematische Container über alle Server. Leer, wenn alles gesund ist.

10 Container-Logs #

Tippe in jeder Server-Ansicht auf 📜 Logs Menu. Du bekommst eine Liste der laufenden Container als Buttons. Tippe auf einen — der Bot holt die letzten 20 Zeilen von docker logs und postet sie direkt im Chat.

Praktisch für "Warum startet das ständig neu?"-Debugging, ohne SSH öffnen zu müssen.

11 Föderation #

Das Problem: Telegram erlaubt nur einer Bot-Instanz, Updates zu pollen. Wenn du HawkDNS auf N Servern mit demselben Token installierst, kämpfen sie um die Nachrichten — die meisten landen auf dem falschen Server, und die Tastatur-Buttons sind kaputt.

Die Lösung: Wähle einen Server als Hub. Installiere HawkDNS nur auf dem Hub. Konfiguriere jeden Peer in der config.json als SSH-Ziel. Der Hub baut eine SSH-Verbindung zu jedem Peer auf, um Stats abzuholen — die Peers selbst führen HawkDNS gar nicht aus.

Hub-Modus #

Bearbeite auf dem Hub-Server die config.json und füge ein peers-Array hinzu. Jeder Peer wird per SSH abgefragt, sobald jemand einen /peer-name-Befehl oder die kompakte Übersicht aufruft.

{
  "bot_token": "...",
  "chat_whitelist": ["123"],
  "server_name": "hub",
  "peers": [
    { "name": "web-prod-1", "host": "10.0.0.10", "port": 22, "user": "root" },
    { "name": "db1",        "host": "10.0.0.11" },
    { "name": "cache",      "host": "10.0.0.12" }
  ]
}

SSH-Schlüssel einrichten #

Der Hub braucht passwortlosen SSH-Zugriff auf jeden Peer. Erzeuge einen Schlüssel auf dem Hub und füge den öffentlichen Teil zu ~/.ssh/authorized_keys jedes Peers hinzu:

# auf dem Hub
$ ssh-keygen -t ed25519 -N "" -f /root/.ssh/hawkdns_ed25519
$ cat /root/.ssh/hawkdns_ed25519.pub

# auf jedem Peer den öffentlichen Schlüssel anhängen
$ echo "ssh-ed25519 AAAA..." >> /root/.ssh/authorized_keys

# zurück am Hub, SSH so konfigurieren, dass dieser Key verwendet wird
$ cat >> /root/.ssh/config <<EOF
Host 10.0.0.*
  IdentityFile /root/.ssh/hawkdns_ed25519
  IdentitiesOnly yes
  StrictHostKeyChecking accept-new
EOF

# Test
$ ssh root@10.0.0.10 "hostname; uptime"

Peer später hinzufügen #

1. Vom Hub aus den SSH-Key auf den neuen Peer ausrollen (siehe oben).
2. /etc/hawkdns/config.json bearbeiten und den Peer ans Array anhängen.
3. systemctl restart hawkdns-bot.
4. Telegram öffnen, /start — der neue Peer taucht im Menü auf.

12 Watchdog #

Der Watchdog ist ein unabhängiges, cron-gesteuertes Shell-Skript, das Domains über HTTPS prüft. Es existiert, damit du auch dann Alarme bekommst, wenn der Bot-Prozess selbst abgestürzt ist.

So funktioniert es

1. Cron führt alle 2 Minuten /opt/hawkdns/hawkdns-watchdog.sh aus.
2. Für jede Domain in watchdog.conf schickt das Skript einen HTTPS-Request.
3. Passt der Response-Code zur erlaubten Liste, ist es ein Erfolg. Falls nicht, wird ein Fehler-Zähler hochgezählt.
4. Nach 3 aufeinanderfolgenden Fehlern (≈6 Min.) wird einmal eine Telegram-Nachricht 🚨 DOWN gesendet.
5. Beim ersten Erfolg nach einem DOWN folgt eine ✅ RECOVERED-Nachricht, und der Zähler wird zurückgesetzt.

Feintuning

13 Boot-Erkennung #

Ein Oneshot-systemd-Dienst läuft nach jedem Boot und sendet:

🔄 Server-Reboot erkannt
   Server: web-prod-1
   Host: web-prod-1.internal
   Kernel: 6.8.0-49-generic
   HawkDNS ist online und beobachtet.

Ausgelöst durch hawkdns-boot-notify.service am multi-user.target. Wartet 30 Sekunden nach Network-Up, damit DNS sich beruhigt.

14 Aufbau einer Benachrichtigung #

Beispiele für das, was du tatsächlich in Telegram siehst, in zeitlicher Reihenfolge:

🚨 DOWN: shop.example.com → HTTP 502 (seit 6 min)
   [web-prod-1]

— 8 Minuten später, nach Wiederherstellung —

✅ RECOVERED: shop.example.com → HTTP 200 (war ~14 min down)
   [web-prod-1]

— nach einem Reboot —

🔄 Server-Reboot erkannt
   Server: web-prod-1
   Kernel: 6.8.0-49-generic
   HawkDNS ist online und beobachtet.

Alarme werden mit [server-name] gekennzeichnet, damit Föderations-Chats eindeutig bleiben.

15 systemd #

$ systemctl status hawkdns-bot
$ systemctl restart hawkdns-bot
$ systemctl stop hawkdns-bot
$ systemctl disable hawkdns-bot   # installiert lassen, aber nicht autostarten
$ journalctl -fu hawkdns-bot       # Logs verfolgen

16 Cron #

Der Installer hängt einen Eintrag an die crontab von root an:

*/2 * * * * /opt/hawkdns/hawkdns-watchdog.sh

Um die Frequenz zu ändern, crontab -e aufrufen und den Zeitplan anpassen.

17 Logs #

18 Aktualisierung #

Den Installer einfach mit denselben Argumenten erneut ausführen. Er erkennt die bestehende Installation, lädt die Bot-Dateien neu herunter und startet die Dienste neu. Die Konfiguration bleibt erhalten.

$ curl -fsSL https://bot.hawkdns.info/install.sh | sudo bash -s -- --yes

19 Deinstallation #

$ curl -fsSL https://bot.hawkdns.info/install.sh | sudo bash -s -- --uninstall

Entfernt:

• /opt/hawkdns/
• systemd-Units (deaktiviert + entfernt)
• Watchdog-Cron-Eintrag

Bleibt erhalten:

• /etc/hawkdns/ (deine Konfiguration — bei Bedarf manuell löschen)
• /var/lib/hawkdns/ (State-Dateien — bei Bedarf manuell löschen)
• /var/log/hawkdns-watchdog.log

20 CLI-Referenz #

21 Architektur #

Ein Python-Prozess. Drei Aufgaben:

1. Polling-Loop: getUpdates als Long-Poll gegen die Telegram-API.
2. Command-Router: Parsen von /cmd und Callback-Queries; Dispatch an View-Funktionen.
3. Run-Remote: Lokal oder per SSH ausgeführte Shell-Aufrufe, um frische Stats zu holen.

Keine Datenbank. Kein Webserver. Der gesamte State ist Konfigurationsdateien + flüchtiger Prozess-Speicher + Watchdog-Zählerdateien pro Domain. Wenn der Host verschwindet, lässt sich alles aus /etc/hawkdns/ wiederherstellen.

22 Sicherheit #

Chat-Whitelist

chat_whitelist in der config.json blockt unbekannte Chats. Selbst wenn jemand den Benutzernamen deines Bots herausfindet, kann er ihm zwar schreiben, bekommt aber "Nicht autorisiert." zurück.

Umgang mit dem Token

Der Token liegt in bot.env und config.json, beide mit Modus 0600. Nicht ins Repo committen. Behandle den Token wie einen privaten SSH-Schlüssel.

SSH vom Hub

Die Föderation nutzt standardmäßiges OpenSSH. Wir empfehlen einen dedizierten Key pro Hub, über ~/.ssh/config auf die Peers beschränkt. Nicht deinen Entwickler-Key wiederverwenden.

Was HawkDNS NICHT macht

• Es öffnet keinen eingehenden Port.
• Es funkt nirgendwohin nach Hause außer zur Telegram-API.
• Es installiert keine Paket-Mirrors, Agents oder Kernelmodule.

23 Fehlerbehebung #

Bot antwortet nicht

1. systemctl status hawkdns-bot — läuft er?
2. journalctl -u hawkdns-bot -n 30 — gibt es eine Python-Exception?
3. Prüfe, ob chat_whitelist in der config.json deine Chat-ID enthält.
4. Probiere curl -s "https://api.telegram.org/bot$TOKEN/getMe" — sollte ok:true liefern.
5. Auf Token-Konflikt prüfen: läuft eine weitere Bot-Instanz (anderer Server, Dev-Laptop) auf demselben Token?

Watchdog schlägt nie Alarm

1. tail /var/log/hawkdns-watchdog.log — feuert Cron überhaupt?
2. ls /var/lib/hawkdns/watchdog/ — sind die State-Dateien da?
3. Watchdog manuell starten: /opt/hawkdns/hawkdns-watchdog.sh — gibt es Fehler?

Föderation meldet "(timeout)" für einen Peer

1. Vom Hub aus manuell per SSH auf den Peer. Klappt das ohne Passwort-Abfrage?
2. ConnectTimeout in ~/.ssh/config für diesen Host erhöhen.
3. Prüfen, ob die Firewall des Peers SSH von der Hub-IP erlaubt.

Telegram sagt "Forbidden: bot was blocked by the user"

Du hast deinen eigenen Bot blockiert. Hebe die Blockade in Telegram auf, dann läuft es wieder.

Festplatte läuft durch Logs voll

Den Watchdog-Log per logrotate rotieren (Datei: /var/log/hawkdns-watchdog.log) oder stattdessen ins journal pipen.

24 FAQ #

Geht das auch ohne Docker?

Ja. Falls Docker nicht installiert ist, zeigt der Bot einfach keine Container-Zähler an. Alles andere funktioniert.

Kann ich auch Nicht-Linux-Hosts überwachen?

Der Bot selbst braucht Linux. Aber du kannst von einem Linux-Hub per SSH auf einen BSD- oder macOS-Peer zugreifen, solange die grundlegenden Befehle (uptime, df, free) dort verfügbar sind. free gibt es auf BSD/macOS nicht — diese Peers zeigen dann "n/a" beim RAM.

Wie schneidet es gegenüber Uptime Kuma / Healthchecks.io / Grafana ab?

HawkDNS ist Single-Process, ohne DB, ohne Web-UI, ohne Dashboard. Es ist in erster Linie ein Notifier. Für Langzeit-Graphen und richtiges Monitoring kannst du es parallel zu Kuma betreiben (so macht es der Autor des Projekts).

Kann ich die Alarmtexte anpassen?

Ja — bearbeite den Text in den View-Funktionen von hawkdns-bot.py oder in hawkdns-watchdog.sh. Beim nächsten Upgrade werden deine Änderungen überschrieben. Forke das Skript lokal, wenn du sie behalten willst.

Funktioniert es hinter einem Corporate-Proxy?

Setze HTTPS_PROXY in der bot.env. Pythons urllib respektiert es, und curl übernimmt es automatisch.

Wie hoch ist der Ressourcenverbrauch?

Etwa 25 MB RAM für den Bot. Vernachlässigbare CPU-Last (die meiste Zeit idle). Der Watchdog läuft alle 2 Minuten ~1 Sekunde.

Gibt es eine MIT-Lizenz?

Ja. Das Ganze ist MIT-lizenziert. Lies das Skript — es gibt nichts zu verstecken.