VM Tracker Client - FAQ & Troubleshooting¶

Inhaltsverzeichnis¶

Installation & Deployment
Netzwerk-Probleme
Interface-Erkennung
API-Server Verbindung
Fehler beim Start
Laufzeitprobleme
Performance & Ressourcen
Container & Orchestrierung
Konfiguration
Logging & Debugging

Installation Deployment¶

F: Der Client startet nicht - "command not found"¶

Problem: Beim Ausführen erscheint bash: vm-tracker-client: command not found

Ursache: - Binary ist nicht im PATH - Keine Ausführungsrechte

Lösung:

# Ausführungsrechte setzen
chmod +x vm-tracker-client

# Mit vollem Pfad ausführen
./vm-tracker-client

# Oder in /usr/local/bin verschieben
sudo mv vm-tracker-client /usr/local/bin/
vm-tracker-client

F: Build schlägt fehl - "go: cannot find main module"¶

Problem: go build funktioniert nicht

Ursache: - Nicht im richtigen Verzeichnis - go.mod fehlt

Lösung:

# Ins richtige Verzeichnis wechseln
cd vm-tracker-client/

# go.mod erstellen falls nicht vorhanden
go mod init vm-tracker-client

# Build ausführen
go build -o vm-tracker-client main.go

Code-Referenz: go.mod:1-3

F: Cross-Compilation für andere Plattformen?¶

Problem: Muss Binary für Linux erstellen, arbeite aber auf macOS

Lösung:

# Für Linux 64-bit
GOOS=linux GOARCH=amd64 go build -o vm-tracker-client-linux main.go

# Für Windows
GOOS=windows GOARCH=amd64 go build -o vm-tracker-client.exe main.go

# Für ARM (z.B. Raspberry Pi)
GOOS=linux GOARCH=arm64 go build -o vm-tracker-client-arm64 main.go

# Für ARM 32-bit
GOOS=linux GOARCH=arm GOARM=7 go build -o vm-tracker-client-arm main.go

Netzwerk-Probleme¶

F: "interface eth0 not found"¶

Problem:

Warning: interface eth0 not found: route ip+net: no such network interface, retrying in 5 seconds...

Ursache: - Interface-Name ist falsch (main.go:102) - Interface existiert nicht auf dem System - Interface-Namen unterscheiden sich je nach OS

Diagnose:

# Alle Interfaces anzeigen
ip addr show           # Linux
ifconfig              # macOS/BSD
ip link show          # Alternative Linux

# Oder mit dem Client selbst
go run main.go -interface "FALSCHER_NAME" 2>&1 | grep "interface"

Lösung:

# Korrekten Interface-Namen verwenden
./vm-tracker-client -interface "eth0"     # Typisch für Linux
./vm-tracker-client -interface "enp0s1"   # Moderne Linux-Systeme
./vm-tracker-client -interface "en0"      # macOS
./vm-tracker-client -interface "ens33"    # VMware VMs

Gängige Interface-Namen:

System	Typische Namen
Ubuntu/Debian (alt)	eth0, eth1, wlan0
Ubuntu/Debian (neu)	enp0s1, enp0s3, ens33
CentOS/RHEL	eno1, ens192, enp0s3
macOS	en0, en1
Docker	eth0, docker0
Kubernetes	eth0, cali*

Code-Referenz: main.go:33-37

F: "no IPv4 address found on interface"¶

Problem:

Warning: no IPv4 address found on interface docker0, retrying in 5 seconds...

Ursache: - Interface hat keine IPv4-Adresse (main.go:46-55) - Interface ist down - Nur IPv6 konfiguriert - DHCP hat noch keine IP vergeben

Diagnose:

# Interface-Status prüfen
ip addr show eth0
ifconfig eth0

# Prüfen ob Interface UP ist
ip link show eth0 | grep "state UP"

Lösung:

# Interface aktivieren
sudo ip link set eth0 up

# DHCP IP anfordern
sudo dhclient eth0

# Statische IP setzen (falls nötig)
sudo ip addr add 192.168.1.100/24 dev eth0

# Anderes Interface wählen
./vm-tracker-client -interface "eth1"

Workaround für IPv6-only Systeme: Der Client unterstützt aktuell nur IPv4. Sie müssen ein Interface mit IPv4 wählen.

Code-Referenz: main.go:46-55

F: Client findet IP-Adresse nicht bei dynamischem DHCP¶

Problem: Bei DHCP-Lease-Verlängerung verliert der Client kurzzeitig die IP

Ursache: - Interface wird kurzzeitig neu konfiguriert - IP-Adresse ändert sich - Race Condition während DHCP-Renewal

Lösung:

# Kürzeres Update-Intervall verwenden
./vm-tracker-client -interval 10

# Längeren Retry-Delay für mehr Stabilität
./vm-tracker-client -retry 10

# Statische IP verwenden (empfohlen für Server)
sudo ip addr add 192.168.1.100/24 dev eth0

Best Practice: Für produktive VMs empfiehlt sich die Verwendung statischer IP-Adressen oder DHCP-Reservierungen.

API-Server Verbindung¶

F: "Failed to register: connection refused"¶

Problem:

Failed to register: error sending request: Post "http://10.0.2.196:8080/api/register": dial tcp 10.0.2.196:8080: connect: connection refused

Ursache: - API-Server läuft nicht (main.go:80-82) - Falsche URL konfiguriert - Firewall blockiert Port 8080 - Netzwerk-Routing-Problem

Diagnose:

# Server-Erreichbarkeit testen
ping 10.0.2.196

# Port-Erreichbarkeit prüfen
nc -zv 10.0.2.196 8080
telnet 10.0.2.196 8080

# Mit curl testen
curl -v http://10.0.2.196:8080/api/register

Lösung:

# Korrekte API-URL verwenden
./vm-tracker-client -api "http://KORREKTE_IP:8080"

# Prüfen ob API-Server läuft
systemctl status vm-tracker-api
docker ps | grep vm-tracker-api

# Firewall-Regel hinzufügen (Server-Seite)
sudo ufw allow 8080/tcp
sudo firewall-cmd --add-port=8080/tcp --permanent

Code-Referenz: main.go:100, main.go:80-82

F: "server returned status 404"¶

Problem:

Failed to register: server returned status 404

Ursache: - API-Endpoint existiert nicht (main.go:91-93) - Falsche API-Version - Server ist falsch konfiguriert

Diagnose:

# API-Endpoints testen
curl -v http://api-server:8080/api/register

# Prüfen welche Endpoints verfügbar sind
curl http://api-server:8080/
curl http://api-server:8080/health

Lösung:

# API-Server Logs prüfen
journalctl -u vm-tracker-api -n 50

# API-Server neu starten
systemctl restart vm-tracker-api

# Korrekte URL sicherstellen (ohne trailing slash)
./vm-tracker-client -api "http://api-server:8080"

Hinweis: Der Client erwartet den Endpoint /api/register (main.go:80)

Code-Referenz: main.go:80, main.go:91-93

F: "server returned status 500"¶

Problem:

Failed to register: server returned status 500

Ursache: - Interner Fehler im API-Server - Datenbank-Verbindung fehlgeschlagen - Ungültige Daten im Request

Diagnose:

# API-Server Logs prüfen
journalctl -u vm-tracker-api -f
docker logs vm-tracker-api --tail 100

# Request manuell testen
curl -X POST http://api-server:8080/api/register \
  -H "Content-Type: application/json" \
  -d '{"hostname":"test","ip_address":"192.168.1.1","interface":"eth0"}'

Lösung: - Server-seitige Logs analysieren - API-Server neu starten - Datenbank-Verbindung prüfen

Code-Referenz: main.go:91-93

F: Timeouts bei langsamen Netzwerken¶

Problem: Client hängt bei langsamen Netzwerkverbindungen

Ursache: - Keine Timeouts konfiguriert (main.go:67) - Default HTTP-Client hat sehr lange Timeouts

Lösung: Aktuell verwendet der Client http.Post() ohne Custom-Timeouts. Für Produktionsumgebungen empfiehlt sich eine Anpassung:

// Empfohlene Erweiterung (nicht im Code)
client := &http.Client{
    Timeout: 10 * time.Second,
}

Workaround:

# Kürzeres Intervall verwenden
./vm-tracker-client -interval 10 -retry 3

Verbesserungsvorschlag: HTTP-Client mit konfigurierbarem Timeout erweitern

Interface-Erkennung¶

F: Mehrere IP-Adressen auf einem Interface¶

Problem: Interface hat mehrere IPs, Client nimmt die falsche

Ursache: - Code nimmt die erste gefundene IPv4-Adresse (main.go:47-52) - Keine Priorisierung nach IP-Typ

Diagnose:

# Alle IPs auf Interface anzeigen
ip addr show eth0

# Beispiel-Output:
# inet 192.168.1.100/24 ...
# inet 10.0.0.5/8 ...

Aktuelles Verhalten: Der Client gibt die erste nicht-Loopback IPv4-Adresse zurück.

Lösung: Wenn eine spezifische IP benötigt wird, muss aktuell ein Interface gewählt werden, das nur diese IP hat, oder der Code muss angepasst werden.

Code-Referenz: main.go:47-52

F: VPN-Interfaces werden erkannt statt physische¶

Problem: Client registriert VPN-IP statt Server-IP

Ursache: - VPN-Interface heißt z.B. auch "eth0" - Keine Unterscheidung zwischen Interface-Typen

Diagnose:

# Interface-Typen anzeigen
ip -d link show

# Alle Interfaces mit IPs
ip addr show

Lösung:

# Spezifisches physisches Interface angeben
./vm-tracker-client -interface "enp0s1"  # Physisches Interface
# NICHT: -interface "tun0"                # VPN Interface

Gängige VPN-Interface-Namen (vermeiden): - tun0, tun1 (OpenVPN) - wg0 (WireGuard) - ppp0 (PPTP)

F: Loopback-Interface wird nicht erkannt (erwartetes Verhalten)¶

Problem: ./vm-tracker-client -interface "lo" findet keine IP

Ursache: Loopback-Adressen werden absichtlich gefiltert (main.go:48)

if ipnet, ok := addr.(*net.IPNet); ok && !ipnet.IP.IsLoopback() {

Lösung: Das ist beabsichtigtes Verhalten. Verwenden Sie ein echtes Netzwerk-Interface.

Code-Referenz: main.go:48

Fehler beim Start¶

F: "Failed to register after 3 attempts, exiting"¶

Problem:

Failed to register: error sending request: ..., retrying in 5 seconds...
Failed to register: error sending request: ..., retrying in 5 seconds...
Failed to register: error sending request: ..., retrying in 5 seconds...
Failed to register after 3 attempts, exiting

Ursache: - Alle 3 Retry-Versuche fehlgeschlagen (main.go:160-162) - API-Server nicht erreichbar - Netzwerk-Problem persistent

Diagnose:

# Verbose-Modus aktivieren für mehr Details
./vm-tracker-client -verbose

# Netzwerk-Konnektivität prüfen
ping API_SERVER_IP
curl http://API_SERVER_IP:8080/api/register

Lösung:

# API-Server starten/prüfen
systemctl status vm-tracker-api

# Längeren Retry-Delay (mehr Zeit für Server-Start)
./vm-tracker-client -retry 10

# Netzwerk-Probleme beheben
# (Firewall, Routing, etc.)

Hinweis: - Max. 3 Retries sind hardcoded (main.go:126) - Retry-Delay ist konfigurierbar via -retry Flag

Code-Referenz: main.go:124-162

F: Client startet zu früh (vor Netzwerk-Initialisierung)¶

Problem: Client startet beim Boot, aber Netzwerk ist noch nicht bereit

Ursache: - Systemd/Init startet Service zu früh - Netzwerk-Interface noch nicht konfiguriert

Lösung für Systemd:

[Unit]
Description=VM Tracker Client
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
# Zusätzliche Verzögerung
ExecStartPre=/bin/sleep 5
ExecStart=/usr/local/bin/vm-tracker-client -api "http://api:8080" -interface "eth0"
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Alternative: Längeren Retry-Delay verwenden

./vm-tracker-client -retry 10

Laufzeitprobleme¶

F: Client stoppt nach einiger Zeit mit Updates¶

Problem: Initial Registration erfolgreich, aber dann keine Updates mehr

Ursache: - Netzwerk-Unterbrechung - API-Server neu gestartet - Fehler werden nur geloggt, Client läuft weiter (main.go:186-187)

Diagnose:

# Logs prüfen
journalctl -u vm-tracker-client -f

# Mit verbose Mode starten
./vm-tracker-client -verbose

Verhalten: Im Hauptloop werden Fehler nur geloggt, der Client terminiert nicht (main.go:186-187):

if err := sendRegistration(*apiURL, info); err != nil {
    log.Printf("Failed to send update: %v", err)
    // Client läuft weiter!
}

Lösung: Das ist erwartetes Verhalten - der Client versucht beim nächsten Intervall wieder zu senden.

Code-Referenz: main.go:186-187

F: IP-Adresse ändert sich, aber alte IP wird weiter gesendet¶

Problem: DHCP erneuert IP, aber Client sendet alte IP

Ursache: Dies sollte nicht passieren, da die IP jedes Mal neu abgerufen wird (main.go:169):

ipAddress, err := getIPAddress(*interfaceName)

Diagnose:

# Mit Verbose-Logging prüfen
./vm-tracker-client -verbose

# Output sollte zeigen:
# Sending update: {Hostname:... IPAddress:NEUE_IP Interface:eth0}

Falls Problem weiter besteht:

# Client neu starten
systemctl restart vm-tracker-client

# Kürzeres Update-Intervall
./vm-tracker-client -interval 10

Code-Referenz: main.go:169

F: Hostname ändert sich zu "unknown"¶

Problem: Hostname wird plötzlich als "unknown" registriert

Ursache: - os.Hostname() schlägt fehl (main.go:25-28) - Hostname wurde auf dem System geändert - Permissions-Problem

Diagnose:

# Hostname prüfen
hostname
cat /etc/hostname

# Manuell testen
go run -exec "hostname" main.go

Lösung:

# Hostname setzen
sudo hostnamectl set-hostname mein-server

# /etc/hostname prüfen
echo "mein-server" | sudo tee /etc/hostname

# Client neu starten
systemctl restart vm-tracker-client

Code-Referenz: main.go:24-30

F: Client verbraucht zu viele Ressourcen¶

Problem: Hohe CPU- oder RAM-Nutzung

Ursache: - Update-Intervall zu kurz - Memory-Leak (unwahrscheinlich bei diesem Code) - Zu viele Log-Einträge

Diagnose:

# Ressourcen-Verbrauch prüfen
top -p $(pgrep vm-tracker-client)
ps aux | grep vm-tracker-client

# Memory-Profiling
go tool pprof http://localhost:6060/debug/pprof/heap

Lösung:

# Längeres Intervall
./vm-tracker-client -interval 300  # 5 Minuten

# Verbose-Logging deaktivieren
./vm-tracker-client -verbose=false

# Logs limitieren (systemd)
journalctl --vacuum-time=7d

Erwarteter Verbrauch: - CPU: < 1% idle - RAM: 5-10 MB

Performance Ressourcen¶

F: Zu viele Log-Einträge bei Problemen¶

Problem: Log-Files werden sehr groß

Ursache: - Fehler werden bei jedem Intervall geloggt - Verbose-Modus aktiviert - Keine Log-Rotation

Lösung:

1. Log-Rotation einrichten (logrotate):

# /etc/logrotate.d/vm-tracker-client
/var/log/vm-tracker-client.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    create 0644 root root
}

2. Systemd Journal limitieren:

# /etc/systemd/journald.conf
SystemMaxUse=100M
MaxRetentionSec=7day

3. Verbose-Modus nur bei Bedarf:

./vm-tracker-client  # Ohne -verbose

F: Intervall vs. Netzwerk-Last¶

Problem: Wie balanciere ich Update-Frequenz und Netzwerk-Last?

Empfehlungen:

Szenario	Empfohlenes Intervall	Begründung
Entwicklung/Testing	10-30s	Schnelles Feedback
Produktions-VMs (stabil)	60-300s	Gute Balance
Niedrige Priorität	300-600s	Minimale Last
Dynamische IPs (DHCP)	30-60s	Zeitnahe Updates
Statische IPs	300s+	Selten Änderungen

Berechnung Netzwerk-Last:

Last = (Anzahl VMs × Request-Größe) / Intervall
     = (1000 VMs × 2 KB) / 60s
     = ~33 KB/s

Code-Referenz: main.go:104

Container Orchestrierung¶

F: Docker-Container kann Host-Interface nicht finden¶

Problem:

interface eth0 not found

Ursache: - Container hat eigenes Netzwerk-Namespace - Host-Interfaces sind nicht sichtbar - Verwendet falsches Interface im Container

Lösung:

Option 1: Host-Netzwerk verwenden

docker run --network host \
  vm-tracker-client:latest \
  -api "http://api:8080" \
  -interface "eth0"

Option 2: Container-Interface verwenden

# Im Container ist das Interface normalerweise "eth0"
docker run \
  vm-tracker-client:latest \
  -api "http://api:8080" \
  -interface "eth0"

Option 3: Custom Network

docker network create --driver bridge my-network
docker run --network my-network \
  vm-tracker-client:latest \
  -api "http://api:8080" \
  -interface "eth0"

F: Kubernetes Pod kann keine VM-Informationen senden¶

Problem: Pod registriert Container-IP statt Node-IP

Ursache: - Pod hat eigenes Netzwerk - hostNetwork nicht aktiviert

Lösung:

DaemonSet mit hostNetwork:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: vm-tracker-client
spec:
  selector:
    matchLabels:
      app: vm-tracker-client
  template:
    metadata:
      labels:
        app: vm-tracker-client
    spec:
      hostNetwork: true
      containers:
      - name: client
        image: vm-tracker-client:latest
        args:
        - "-api"
        - "http://vm-tracker-api:8080"
        - "-interface"
        - "eth0"  # Host Interface!

Wichtig: hostNetwork: true ist erforderlich für Zugriff auf Host-Interfaces

F: Graceful Shutdown funktioniert nicht in Container¶

Problem: Container stoppt hart, keine saubere Beendigung

Ursache: - Signal wird nicht weitergeleitet - Container läuft nicht als PID 1 - Stop-Timeout zu kurz

Lösung:

Dockerfile:

FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o vm-tracker-client main.go

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/vm-tracker-client .

# Binary als PID 1 ausführen
ENTRYPOINT ["./vm-tracker-client"]
CMD ["-api", "http://api:8080", "-interface", "eth0"]

Docker-Compose:

services:
  client:
    image: vm-tracker-client:latest
    stop_grace_period: 30s  # Genug Zeit für Shutdown
    command: ["-api", "http://api:8080", "-interface", "eth0"]

Code-Referenz: main.go:117-119, main.go:192-194

Konfiguration¶

F: Standard-API-URL im Code hardcoded¶

Problem: Default ist http://10.0.2.196:8080 (main.go:100)

Ursache: Entwickler-spezifische IP ist hardcoded

Lösung:

Option 1: Immer -api Flag verwenden

./vm-tracker-client -api "http://MY_API_SERVER:8080"

Option 2: Environment Variable (nicht unterstützt) Aktuell unterstützt der Client keine ENV-Variablen.

Option 3: Wrapper-Script erstellen

#!/bin/bash
# /usr/local/bin/vm-tracker-start.sh
API_URL="${API_URL:-http://production-api:8080}"
INTERFACE="${INTERFACE:-eth0}"

exec /usr/local/bin/vm-tracker-client \
  -api "$API_URL" \
  -interface "$INTERFACE" \
  "$@"

Code-Referenz: main.go:100

F: Wie kann ich Konfiguration persistieren?¶

Problem: Möchte nicht bei jedem Start alle Flags angeben

Lösung:

Option 1: Systemd-Service

[Service]
ExecStart=/usr/local/bin/vm-tracker-client \
  -api "http://api:8080" \
  -interface "eth0" \
  -interval 60 \
  -verbose

Option 2: Wrapper-Script (siehe oben)

Option 3: Config-File (nicht unterstützt) Der Client unterstützt aktuell keine Config-Files. Erweiterung möglich mit: - YAML/JSON Config - Viper Library - Environment Variables

F: Kann ich mehrere Interfaces überwachen?¶

Problem: VM hat mehrere Netzwerk-Interfaces

Antwort: Nein, der Client unterstützt aktuell nur ein Interface (main.go:102).

Workaround: Mehrere Client-Instanzen starten:

# Instance 1
./vm-tracker-client -api "http://api:8080" -interface "eth0" &

# Instance 2
./vm-tracker-client -api "http://api:8080" -interface "eth1" &

Hinweis: Dies sendet separate Registrationen. Der API-Server muss mehrere IPs pro Hostname verwalten können.

Logging Debugging¶

F: Wie aktiviere ich Debug-Logging?¶

Lösung:

# Verbose-Modus
./vm-tracker-client -verbose

# Output umleiten
./vm-tracker-client -verbose > /var/log/vm-tracker.log 2>&1

# Mit systemd
journalctl -u vm-tracker-client -f

Verbose-Output zeigt: - Jeden Registration-Request - Gesendete VMInfo-Daten - Erfolgs-Bestätigungen

Code-Referenz: main.go:145-146, main.go:182-183, main.go:188-189

F: Keine Logs sichtbar¶

Problem: Client läuft, aber keine Log-Ausgabe

Ursache: - Logs gehen nach stdout/stderr - systemd journal fängt Logs ab - Keine Fehler = wenig Output ohne -verbose

Lösung:

# Systemd Logs
journalctl -u vm-tracker-client -f

# Docker Logs
docker logs -f container_name

# Kubernetes Logs
kubectl logs -f pod_name

# File-basiertes Logging
./vm-tracker-client -verbose 2>&1 | tee /var/log/vm-tracker.log

F: Wie kann ich HTTP-Requests debuggen?¶

Problem: Möchte sehen was genau gesendet wird

Lösung:

Option 1: Verbose + tcpdump

# Terminal 1: Client mit Verbose
./vm-tracker-client -verbose -api "http://api:8080"

# Terminal 2: Traffic mitschneiden
sudo tcpdump -i eth0 -A 'tcp port 8080'

Option 2: Proxy verwenden

# HTTP-Debugging-Proxy (mitmproxy)
mitmproxy -p 8888

# Client über Proxy
HTTP_PROXY=http://localhost:8888 ./vm-tracker-client

Option 3: Code-Modifikation Request-Body loggen vor dem Senden (main.go:75-78):

jsonData, err := json.Marshal(info)
log.Printf("DEBUG: Sending JSON: %s", string(jsonData))  // Hinzufügen

F: Wie teste ich ohne echten API-Server?¶

Problem: Möchte Client testen, aber kein API-Server verfügbar

Lösung:

Option 1: Mock-Server mit netcat

# Terminal 1: Mock-Server
while true; do
  echo -e "HTTP/1.1 200 OK\r\n\r\nOK" | nc -l 8080
done

# Terminal 2: Client
./vm-tracker-client -api "http://localhost:8080"

Option 2: httpbin.org (für Internet-Tests)

./vm-tracker-client -api "https://httpbin.org/post"

Option 3: Unit-Tests verwenden

go test -v -run TestSendRegistration

Code-Referenz: main_test.go:168-235

Erweiterte Problembehandlung¶

F: Client sendet falsche Daten¶

Problem: API-Server empfängt ungültige oder falsche Daten

Diagnose:

# 1. Verbose-Modus aktivieren
./vm-tracker-client -verbose

# 2. Daten im Log prüfen
# Output sollte sein:
# Sending registration: {Hostname:xyz IPAddress:192.168.1.100 Interface:eth0}

# 3. Hostname manuell prüfen
hostname

# 4. IP manuell prüfen
ip addr show eth0 | grep "inet "

Mögliche Ursachen: - Hostname ist "unknown" → os.Hostname() schlägt fehl - IP ist falsch → Falsches Interface - Interface-Name falsch → Typo in Parameter

Code-Referenz: main.go:139-143

F: Memory-Leak bei Langzeit-Betrieb?¶

Problem: Speicherverbrauch steigt kontinuierlich

Diagnose:

# Memory-Profiling aktivieren
# (Erfordert Code-Änderung für pprof-Server)

# Ressourcen überwachen
watch -n 5 'ps aux | grep vm-tracker-client'

# Go Memory Stats
GODEBUG=gctrace=1 ./vm-tracker-client

Erwartetes Verhalten: - Konstanter Memory-Verbrauch (~5-10 MB) - Kein Anstieg über Zeit - Go Garbage Collector sollte regelmäßig laufen

Mögliche Ursachen: - HTTP-Response Bodies nicht geschlossen → Bereits behoben (main.go:85-89) - Ticker nicht gestoppt → Wird korrekt behandelt (main.go:122)

Code-Referenz: main.go:85-89, main.go:122

F: Race Conditions beim Shutdown?¶

Problem: Fehler beim Beenden des Clients

Diagnose:

# Race-Detector aktivieren
go run -race main.go -api "http://api:8080"

# Oder beim Build
go build -race -o vm-tracker-client main.go
./vm-tracker-client

Shutdown-Sequenz: 1. SIGTERM/SIGINT empfangen (main.go:192) 2. Log-Nachricht ausgeben (main.go:193) 3. return aus main() (main.go:194) 4. defer ticker.Stop() wird ausgeführt (main.go:122)

Code ist race-free da: - Nur ein Goroutine (main) - Channels werden korrekt verwendet - Ticker wird ordnungsgemäß gestoppt

Code-Referenz: main.go:117-122, main.go:192-194

Performance-Optimierung¶

F: Wie optimiere ich für hohe VM-Anzahl?¶

Szenario: 10,000 VMs, jede sendet Updates

Problem: API-Server wird überlastet

Lösungen:

1. Intervall erhöhen:

# Statt 30s → 300s (5 Minuten)
./vm-tracker-client -interval 300

Last-Berechnung: - 10,000 VMs × 2KB / 30s = ~667 KB/s - 10,000 VMs × 2KB / 300s = ~67 KB/s (10× weniger!)

2. Jitter hinzufügen (erfordert Code-Änderung):

// Statt fixem Intervall:
interval + random(0, 30s)
// Vermeidet "thundering herd" Problem

3. Load Balancing: - Mehrere API-Server - Client verteilt auf verschiedene Server

F: Kann ich Updates batchen?¶

Problem: Möchte mehrere Updates in einem Request senden

Antwort: Aktuell nicht unterstützt. Jedes Update ist ein separater POST-Request (main.go:80).

Mögliche Erweiterung: - Updates in Queue sammeln - Alle X Sekunden oder bei Y Updates senden - Erfordert API-Server-Änderung

Sicherheit¶

F: HTTPS-Verbindung schlägt fehl¶

Problem:

error sending request: x509: certificate signed by unknown authority

Ursache: - Self-signed Certificate - CA nicht vertraut

Lösung:

Option 1: CA-Certificate installieren

# Certificate kopieren
sudo cp ca-cert.pem /usr/local/share/ca-certificates/

# Update CA-Trust
sudo update-ca-certificates

Option 2: Certificate Verification überspringen (NICHT für Produktion!) Erfordert Code-Änderung (main.go:66-68)

Best Practice: Verwenden Sie gültige TLS-Certificates (Let's Encrypt)

F: API-Authentication fehlt¶

Problem: Jeder kann Daten an API senden

Aktueller Stand: Keine Authentication implementiert (main.go:80)

Mögliche Erweiterungen: - API-Key in Header: Authorization: Bearer <token> - mTLS (Mutual TLS) - OAuth2

Workaround: - Firewall-Regeln (nur bekannte IPs) - VPN/Private Network - API-Gateway mit Authentication

Bekannte Limitierungen¶

L1: Nur IPv4-Unterstützung¶

Problem: Keine IPv6-Adressen werden erkannt

Code: main.go:49

if ipnet.IP.To4() != nil {  // Nur IPv4!

Workaround: Verwenden Sie Interface mit IPv4-Adresse oder erweitern Sie den Code für IPv6.

L2: Kein Reconnect bei API-Server-Neustart¶

Problem: Initial Registration schlägt fehl wenn API-Server nicht läuft → Client beendet sich

Code: main.go:160-162

if retryCount >= maxRetries {
    log.Fatalf("Failed to register after %d attempts, exiting", maxRetries)
}

Workaround: - Systemd mit Restart=always - Längeren Retry-Delay - API-Server vor Client starten

L3: Keine Configuration-File Unterstützung¶

Problem: Alle Parameter via CLI-Flags

Workaround: - Systemd-Unit-Files - Wrapper-Scripts - Environment-Variables (erfordert Code-Änderung)

L4: Hardcoded max. 3 Retries¶

Problem: maxRetries := 3 ist hardcoded (main.go:126)

Workaround: Aktuell keine. Erweiterung auf CLI-Flag möglich.

L5: Keine HTTP-Timeouts¶

Problem: Kann ewig auf HTTP-Response warten

Code: main.go:67 verwendet http.Post() ohne Timeout

Workaround: Aktuell keine. Empfohlene Erweiterung: Custom HTTP-Client mit Timeout.

Hilfreiche Befehle (Cheat Sheet)¶

Diagnose-Befehle¶

# Netzwerk-Interfaces anzeigen
ip addr show              # Linux
ifconfig                  # macOS/BSD
netstat -i                # Alle Systeme

# API-Erreichbarkeit testen
curl -v http://api:8080/api/register
nc -zv api 8080

# Logs ansehen
journalctl -u vm-tracker-client -f                    # Systemd
docker logs -f vm-tracker-client                      # Docker
kubectl logs -f pod/vm-tracker-client                 # Kubernetes

# Prozess-Status
ps aux | grep vm-tracker-client
pgrep -f vm-tracker-client
systemctl status vm-tracker-client

# Ressourcen-Verbrauch
top -p $(pgrep vm-tracker-client)
docker stats vm-tracker-client

Test-Befehle¶

# Unit-Tests
go test -v
go test -v -cover
go test -bench=. -benchmem

# Manual Testing
./vm-tracker-client -verbose -api "http://localhost:8080"

# Race Detection
go run -race main.go

# Network Capture
sudo tcpdump -i eth0 -A 'tcp port 8080'

Weitere Hilfe¶

Wo finde ich weitere Dokumentation?¶

API-Referenz: api/reference
Test-Dokumentation: api/reference.md
Source Code: main.go, main_test.go

Problem nicht gelöst?¶

Verbose-Logging aktivieren: -verbose
Logs prüfen: journalctl -u vm-tracker-client -n 100
Tests ausführen: go test -v
Issue erstellen: Im Repository

Beitragen¶

Haben Sie weitere FAQ-Einträge? PRs sind willkommen!

Version: 1.0 Letzte Aktualisierung: 2025-11-04 Maintainer: VM Tracker Team