Eintrag

Tailscale Healthcheck – A Dockerized Monitoring Helper Tool

Veröffentlicht Aktualisiert
Preview Image
Von Florian Lauer
6 Minuten Lesezeit
Tailscale Healthcheck – A Dockerized Monitoring Helper Tool

Überwache dein Tailscale-Netzwerk mit Leichtigkeit!

Hey, nutzt du Tailscale und möchtest sicherstellen, dass alle Geräte in deinem Netzwerk gesund und erreichbar sind? Dann ist Tailscale Healthcheck genau das Richtige für dich! Mit diesem Tool kannst du den Status deiner Geräte überwachen, gesunde und ungesunde Geräte auflisten und sogar spezifische Geräte im Auge behalten. Klingt gut, oder?

👉 Hier geht’s zum GitHub-Projekt

Warum solltest du Tailscale Healthcheck nutzen?

Ganz einfach: Es macht dein Leben leichter! Du bekommst eine einfache Möglichkeit, den Status deiner Geräte zu checken, ohne dich durch komplizierte Logs oder APIs zu wühlen. Außerdem kannst du es super easy in Docker laufen lassen und mit Monitoring-Tools wie Gatus integrieren.

Was kann das Tool?

  • Gesamtgesundheitsstatus: Kombinierter Status basierend auf:
    • Online-Status des Geräts (online_healthy)
    • Schlüsselablaufstatus (key_healthy)
    • Update-Status (update_healthy, optional)
  • Globale Gesundheitsmetriken:
    • Gesamtgesundheit aller Geräte (global_healthy)
    • Globaler Online-Status (global_online_healthy)
    • Globaler Schlüsselstatus (global_key_healthy)
    • Globaler Update-Status (global_update_healthy)
  • Update-Management:
    • Update-Verfügbarkeitsstatus
    • Client-Versionsverfolgung
    • Update-Gesundheitsfilter mit Wildcards
    • Include/Exclude Update-Filter für Identifier und Tags
  • Einstellungsanzeige:
    • Optionale Anzeige der Konfiguration im API-Output
    • Konfigurierbar über DISPLAY_SETTINGS_IN_OUTPUT
    • Sichere Maskierung sensitiver Daten
    • Umfassende Konfigurationsübersicht
  • Intelligente Filter:
    • Betriebssystem-Filter (z.B. “linux” oder “windows”)
    • Gerätebezeichner-Filter für Namen, IDs oder Hostnamen
    • Tag-basierte Filter für Gerätegruppen
    • Flexible Include/Exclude Listen mit Wildcard-Unterstützung
    • Komma-getrennte Filtermuster (z.B. “linux,freebsd”)
  • Zähler-Metriken: Detaillierte Statistiken zu:
    • Gesunde/ungesunde Geräte
    • Online/Offline Geräte
    • Gültige/abgelaufene Schlüssel
    • Tage bis zum Schlüsselablauf (key_days_to_expire)
  • Flexible Schwellenwerte: Konfigurierbare Limits für:
    • Online-Status (ONLINE_THRESHOLD_MINUTES, Standard: 5)
    • Schlüsselablauf (KEY_THRESHOLD_MINUTES, Standard: 1440)
    • Globale Gesundheit (GLOBAL_HEALTHY_THRESHOLD, Standard: 100)
    • Globaler Online-Status (GLOBAL_ONLINE_HEALTHY_THRESHOLD, Standard: 100)
    • Globaler Schlüsselstatus (GLOBAL_KEY_HEALTHY_THRESHOLD, Standard: 100)
    • Globaler Update-Status (GLOBAL_UPDATE_HEALTHY_THRESHOLD, Standard: 100)
    • Update-Health-Einschluss (UPDATE_HEALTHY_IS_INCLUDED_IN_HEALTH, Standard: NO)
  • Zeitzonen-Support: Alle Zeitstempel in Ihrer lokalen Zeitzone
  • OAuth-Unterstützung: Sichere API-Authentifizierung

So startest du

1. Voraussetzungen

  • Docker installiert
  • Ein Tailscale-API-Token oder OAuth-Client-Credentials

2. Docker-Container starten

Mit API-Token:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

docker run -d -p 5000:5000 \
    -e TAILNET_DOMAIN="example.com" \
    -e AUTH_TOKEN="your-api-key" \
    -e ONLINE_THRESHOLD_MINUTES=5 \
    -e KEY_THRESHOLD_MINUTES=1440 \
    -e GLOBAL_HEALTHY_THRESHOLD=100 \
    -e GLOBAL_ONLINE_HEALTHY_THRESHOLD=100 \
    -e GLOBAL_KEY_HEALTHY_THRESHOLD=100 \
    -e GLOBAL_UPDATE_HEALTHY_THRESHOLD=100 \
    -e UPDATE_HEALTHY_IS_INCLUDED_IN_HEALTH=NO \
    -e DISPLAY_SETTINGS_IN_OUTPUT=NO \
    -e PORT=5000 \
    -e TIMEZONE="Europe/Berlin" \
    -e INCLUDE_OS="" \
    -e EXCLUDE_OS="" \
    -e INCLUDE_IDENTIFIER="" \
    -e EXCLUDE_IDENTIFIER="" \
    -e INCLUDE_TAGS="" \
    -e EXCLUDE_TAGS="" \
    -e INCLUDE_IDENTIFIER_UPDATE_HEALTHY="" \
    -e EXCLUDE_IDENTIFIER_UPDATE_HEALTHY="" \
    -e INCLUDE_TAG_UPDATE_HEALTHY="" \
    -e EXCLUDE_TAG_UPDATE_HEALTHY="" \
    --name tailscale-healthcheck laitco/tailscale-healthcheck:latest

Mit OAuth:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

docker run -d -p 5000:5000 \
    -e TAILNET_DOMAIN="example.com" \
    -e OAUTH_CLIENT_ID="your-oauth-client-id" \
    -e OAUTH_CLIENT_SECRET="your-oauth-client-secret" \
    -e ONLINE_THRESHOLD_MINUTES=5 \
    -e KEY_THRESHOLD_MINUTES=1440 \
    -e GLOBAL_HEALTHY_THRESHOLD=100 \
    -e GLOBAL_ONLINE_HEALTHY_THRESHOLD=100 \
    -e GLOBAL_KEY_HEALTHY_THRESHOLD=100 \
    -e GLOBAL_UPDATE_HEALTHY_THRESHOLD=100 \
    -e UPDATE_HEALTHY_IS_INCLUDED_IN_HEALTH=NO \
    -e DISPLAY_SETTINGS_IN_OUTPUT=NO \
    -e PORT=5000 \
    -e TIMEZONE="Europe/Berlin" \
    -e INCLUDE_OS="" \
    -e EXCLUDE_OS="" \
    -e INCLUDE_IDENTIFIER="" \
    -e EXCLUDE_IDENTIFIER="" \
    -e INCLUDE_TAGS="" \
    -e EXCLUDE_TAGS="" \
    -e INCLUDE_IDENTIFIER_UPDATE_HEALTHY="" \
    -e EXCLUDE_IDENTIFIER_UPDATE_HEALTHY="" \
    -e INCLUDE_TAG_UPDATE_HEALTHY="" \
    -e EXCLUDE_TAG_UPDATE_HEALTHY="" \
    --name tailscale-healthcheck laitco/tailscale-healthcheck:latest

Warum OAuth nutzen?

OAuth ist sicherer als ein statisches API-Token. Mit Tailscale Healthcheck wird dein OAuth-Token automatisch alle 50 Minuten erneuert, sodass du dir keine Sorgen über abgelaufene Tokens machen musst. Außerdem wird das Token sofort aktualisiert, wenn ein 401-Fehler auftritt.

3. Endpunkte aufrufen

Alle Geräte checken:
http://IP-ADDRESS_or_HOSTNAME:5000/health

Beispielantwort:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

{
  "devices": [
    {
      "id": "1234567890",
      "device": "examplehostname.example.com",
      "machineName": "examplehostname",
      "hostname": "examplehostname",
      "os": "macOS",
      "clientVersion": "v1.36.0",
      "updateAvailable": false,
      "update_healthy": true,
      "lastSeen": "2025-04-09T22:03:57+02:00",
      "online_healthy": true,
      "keyExpiryDisabled": false,
      "keyExpiryTimestamp": "2025-05-09T22:03:57+02:00",
      "key_healthy": true,
      "key_days_to_expire": 25,
      "healthy": true,
      "tags": ["user-device", "admin-device"]
    }
  ],
  "metrics": {
    "counter_healthy_true": 1,
    "counter_healthy_false": 0,
    "counter_healthy_online_true": 1,
    "counter_healthy_online_false": 0,
    "counter_key_healthy_true": 1,
    "counter_key_healthy_false": 0,
    "counter_update_healthy_true": 1,
    "counter_update_healthy_false": 0,
    "global_key_healthy": true,
    "global_online_healthy": true,
    "global_healthy": true,
    "global_update_healthy": true
  }
}

Beispiel mit Einstellungsausgabe (DISPLAY_SETTINGS_IN_OUTPUT=YES):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

{
  "devices": [
    {
      "id": "1234567890",
      "device": "examplehostname.example.com",
      "machineName": "examplehostname",
      "hostname": "examplehostname",
      "os": "macOS",
      "clientVersion": "v1.36.0",
      "updateAvailable": false,
      "update_healthy": true,
      "lastSeen": "2025-04-09T22:03:57+02:00",
      "online_healthy": true,
      "keyExpiryDisabled": false,
      "keyExpiryTimestamp": "2025-05-09T22:03:57+02:00",
      "key_healthy": true,
      "key_days_to_expire": 25,
      "healthy": true,
      "tags": ["user-device", "admin-device"]
    }
  ],
  "metrics": {
    "counter_healthy_true": 1,
    "counter_healthy_false": 0,
    "counter_healthy_online_true": 1,
    "counter_healthy_online_false": 0,
    "counter_key_healthy_true": 1,
    "counter_key_healthy_false": 0,
    "counter_update_healthy_true": 1,
    "counter_update_healthy_false": 0,
    "global_healthy": true,
    "global_key_healthy": true,
    "global_online_healthy": true,
    "global_update_healthy": true
  },
  "settings": {
    "TAILNET_DOMAIN": "example.com",
    "OAUTH_CLIENT_ID": "123456789abcdefg",
    "OAUTH_CLIENT_SECRET": "********",
    "AUTH_TOKEN": "********",
    "ONLINE_THRESHOLD_MINUTES": 5,
    "KEY_THRESHOLD_MINUTES": 1440,
    "GLOBAL_HEALTHY_THRESHOLD": 100,
    "GLOBAL_ONLINE_HEALTHY_THRESHOLD": 100,
    "GLOBAL_KEY_HEALTHY_THRESHOLD": 100,
    "GLOBAL_UPDATE_HEALTHY_THRESHOLD": 100,
    "UPDATE_HEALTHY_IS_INCLUDED_IN_HEALTH": true,
    "DISPLAY_SETTINGS_IN_OUTPUT": true,
    "TIMEZONE": "Europe/Berlin",
    "INCLUDE_OS": "",
    "EXCLUDE_OS": "",
    "INCLUDE_IDENTIFIER": "",
    "EXCLUDE_IDENTIFIER": "",
    "INCLUDE_TAGS": "",
    "EXCLUDE_TAGS": "",
    "INCLUDE_IDENTIFIER_UPDATE_HEALTHY": "",
    "EXCLUDE_IDENTIFIER_UPDATE_HEALTHY": "",
    "INCLUDE_TAG_UPDATE_HEALTHY": "",
    "EXCLUDE_TAG_UPDATE_HEALTHY": ""
  }
}

  • Ein bestimmtes Gerät checken:
    http://IP-ADDRESS_or_HOSTNAME:5000/health/<identifier>

    Was ist ein Identifier?
    Der Identifier kann einer der folgenden Werte sein:

    • Hostname: Der Hostname des Geräts, z. B. examplehostname.
    • ID: Die eindeutige ID des Geräts, die von Tailscale vergeben wird.
    • Name: Der vollständige Name des Geräts, z. B. examplehostname.example.com.
    • Machine Name: Der Teil des Namens vor dem ersten Punkt, z. B. examplehostname aus examplehostname.example.com.

    Beispiel:
    Wenn du den Status eines Geräts mit dem Hostnamen examplehostname prüfen möchtest, rufe einfach diesen Endpunkt auf:
    http://IP-ADDRESS_or_HOSTNAME:5000/health/examplehostname

  • Gesunde Geräte anzeigen:
    http://IP-ADDRESS_or_HOSTNAME:5000/health/healthy

  • Ungesunde Geräte anzeigen:
    http://IP-ADDRESS_or_HOSTNAME:5000/health/unhealthy

Integration mit Gatus

Du willst automatische Checks und Benachrichtigungen? Kein Problem! Tailscale Healthcheck lässt sich super mit Gatus integrieren.

Beispielkonfiguration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

endpoints:
  - name: tailscale-examplehostname.example.com
    group: tailscale
    url: "http://IP-ADDRESS_or_HOSTNAME:5000/health/examplehostname"
    interval: 5m
    conditions:
      - "[STATUS] == 200"
      - "[BODY].device.healthy == true"
    alerts:
      - type: email
        failure-threshold: 2
        success-threshold: 3
        description: "Healthcheck fehlgeschlagen"
        send-on-resolved: true

Filter-Konfiguration

Das Tool bietet flexible Möglichkeiten zur Filterung deiner Geräte:

Betriebssystem-Filter

1
2
3
4
5

# Nur bestimmte Betriebssysteme einschließen
INCLUDE_OS="linux*,freebsd*"

# Bestimmte Betriebssysteme ausschließen
EXCLUDE_OS="iOS*"

Gerätebezeichner-Filter

1
2
3
4
5

# Nur bestimmte Geräte einschließen
INCLUDE_IDENTIFIER="firewall*,server*"

# Bestimmte Geräte ausschließen
EXCLUDE_IDENTIFIER="test*,dev*,temp*"

Tag-Filter

1
2
3
4
5

# Nur Geräte mit bestimmten Tags einschließen
INCLUDE_TAGS="admin*,infrastructure*"

# Geräte mit bestimmten Tags ausschließen
EXCLUDE_TAGS="test*,dev*"

Update-Filter

1
2
3
4
5
6
7
8
9
10
11

# Nur bestimmte Geräte für Update-Health einschließen (Identifier)
INCLUDE_IDENTIFIER_UPDATE_HEALTHY="firewall*,server*"

# Bestimmte Geräte für Update-Health ausschließen (Identifier)
EXCLUDE_IDENTIFIER_UPDATE_HEALTHY="test*,dev*,iphone*"

# Nur Geräte mit bestimmten Tags für Update-Health einschließen
INCLUDE_TAG_UPDATE_HEALTHY="admin*,infrastructure*"

# Geräte mit bestimmten Tags für Update-Health ausschließen
EXCLUDE_TAG_UPDATE_HEALTHY="test*,dev*"

Hinweise zur Filterung:

  • Include-Filter haben Vorrang vor Exclude-Filtern
  • Wildcard (*) ermöglicht flexible Muster
  • Leere Filter (“”) oder Leerzeichen werden ignoriert
  • Mehrere Muster können mit Komma getrennt werden
  • Groß-/Kleinschreibung wird ignoriert

Fazit

Mit dem Tailscale Healthcheck hast du ein leistungsfähiges Werkzeug zur Hand, das dir hilft, den Gesundheitszustand deiner Tailscale-Infrastruktur im Auge zu behalten. Die flexiblen Schwellenwerte und detaillierten Metriken ermöglichen eine präzise Überwachung und schnelles Reagieren auf potenzielle Probleme.

👉 Hier geht’s zum GitHub-Projekt

Docker, Self Owned Project, Apps
docker tailscale monitoring SelfOwnedProject
Dieser Eintrag ist vom Autor unter CC BY 4.0 lizensiert.