In vielen kleinen Unternehmen ist unklar, welche Geräte im Netz hängen: private Tablets, vergessene Switches, der Laptop eines Dienstleisters. NetAlertX durchsucht die konfigurierten Netzbereiche regelmäßig per ARP, führt eine Liste aller gesehenen Geräte und meldet jedes neue. Die Anleitung beschreibt die Einrichtung per Docker Compose samt Stolpersteinen aus dem Testlauf.

Was NetAlertX leistet und wo die Grenzen liegen

NetAlertX (früher PiAlert, GPL-3.0, github.com/netalertx/NetAlertX, aktiv gepflegt, v26.10.0 vom 30. September 2026) erfasst Geräte per ARP-Scan sowie Namensermittlung per nmap, nbtscan, Avahi und DNS. Es speichert je Gerät IP, MAC und Hersteller, protokolliert Online- und Offline-Zeiten und meldet neue Geräte per E-Mail, Push-Dienst oder weitere Kanäle.

NetAlertX ist kein Schwachstellenscanner und keine Angriffserkennung: Es zeigt, dass ein unbekanntes Gerät da ist, nicht ob es gefährlich ist. Es erkennt nur Geräte in per ARP erreichbaren Netzbereichen, andere VLANs brauchen eine eigene Anbindung oder zweite Instanz. Windows-Hosts sind mangels Host-Netzwerkmodus nicht unterstützt. Smartphones und Tablets wechseln aus Datenschutzgründen ihre MAC und erscheinen wiederholt als neue Geräte (siehe Typische Fehler).

Voraussetzungen und Ressourcen

Linux-Host mit Docker und Compose-Plugin (geprüft mit Docker 29.1.3, Compose 2.40.3, Ubuntu).
Der Host muss im selben Netzsegment hängen wie die Geräte, ARP läuft nicht über Router.
Der Container braucht den Netzwerkmodus host, im Bridge-Netzwerk funktioniert der ARP-Scan nicht.
Arbeitsspeicher: Das offizielle Beispiel begrenzt auf 2 GB (Reservierung 1 GB), im Test lag der Verbrauch deutlich darunter.
Speicher: Die Datenbank hatte nach dem ersten Scan rund 500 KB, für lange Historien einige hundert MB einplanen.
Architekturen: amd64 und arm64 (auch Raspberry Pi).

Installation mit Docker Compose

Legen Sie das Verzeichnis an:

sudo mkdir -p /opt/netalertx
cd /opt/netalertx

Erstellen Sie die compose.yaml nach dem offiziellen Beispiel, mit fester Version statt latest und nur lokal erreichbarer Weboberfläche:

services:
  netalertx:
    image: ghcr.io/netalertx/netalertx:26.10.0
    container_name: netalertx
    network_mode: host
    read_only: true
    cap_drop:
      - ALL
    cap_add:
      - NET_ADMIN
      - NET_RAW
      - NET_BIND_SERVICE
      - CHOWN
      - SETUID
      - SETGID
    sysctls:
      net.ipv4.conf.all.arp_ignore: 1
      net.ipv4.conf.all.arp_announce: 2
    volumes:
      - netalertx_data:/data
      - /etc/localtime:/etc/localtime:ro
    tmpfs:
      - "/tmp:mode=1700,uid=0,gid=0,rw,noexec,nosuid,nodev"
    environment:
      LISTEN_ADDR: "127.0.0.1"
      PORT: "20211"
      GRAPHQL_PORT: "20212"
      TZ: Europe/Berlin
    mem_limit: 2048m
    mem_reservation: 1024m
    pids_limit: 512
    restart: unless-stopped
    logging:
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  netalertx_data:

Die wichtigsten Angaben im Einzelnen:

network_mode: host ist zwingend: ARP arbeitet auf Schicht 2.
LISTEN_ADDR: "127.0.0.1" bindet die Weboberfläche lokal (Projektvorgabe: 0.0.0.0, alle Schnittstellen). Zugriff siehe Absicherung.
read_only: true schützt das Dateisystem, Veränderliches liegt in /data (Volume) und /tmp (tmpfs).
cap_drop: ALL entzieht alle Sonderrechte, cap_add gibt nur die nötigen zurück.
NET_ADMIN und NET_RAW brauchen die Rohsockets von arp-scan, nmap und nbtscan.
NET_BIND_SERVICE braucht nbtscan für privilegierte Ports.
CHOWN, SETUID und SETGID braucht der Start, um Rechte zu setzen und auf einen unprivilegierten Benutzer zu wechseln.
Die sysctls mindern ARP-Flux (mehrdeutige ARP-Antworten bei mehreren Schnittstellen im selben Netz). Verbietet die Umgebung das, entfernen Sie den Block und setzen die Werte auf dem Host: sudo sysctl -w net.ipv4.conf.all.arp_ignore=1 net.ipv4.conf.all.arp_announce=2.
Das tmpfs für /tmp nimmt Protokolle und Zwischenstände auf.

Starten Sie den Container:

sudo docker compose up -d

Funktionsprüfung

Prüfen Sie den Zustand des Containers:

sudo docker compose ps

Ergebnis aus dem Testlauf:

NAME        IMAGE                                SERVICE     STATUS
netalertx   ghcr.io/netalertx/netalertx:26.10.0   netalertx   Up 29 seconds (healthy)

Im Host-Netzwerkmodus bleibt die Port-Spalte leer (normal). Prüfen Sie die Oberfläche:

curl -s -o /dev/null -w "%{http_code} %{url_effective}\n" -L http://127.0.0.1:20211/

Verifizieren: Die Ausgabe endet mit 200 und der Adresse der Geräteübersicht (die Wurzeladresse leitet per 302 weiter). Das Startprotokoll zeigt die geladenen Erweiterungen:

sudo docker logs netalertx --tail 50

Erwartet sind unter anderem ARPSCAN, NSLOOKUP, DIGSCAN, CSVBCKP (CSV-Sicherung der Geräteliste) und NTFPRCS (Benachrichtigungen) sowie die Aktualisierung der Herstellerdatenbank.

Scan-Bereiche konfigurieren

NetAlertX trägt beim ersten Start die Netzbereiche aller Host-Schnittstellen selbst ein. Prüfen Sie den Eintrag:

sudo docker exec netalertx grep SCAN_SUBNETS /data/config/app.conf

Im Test standen dort auch zwei Docker-Bridge-Netze mit Präfixlänge 16 (je 65.534 Adressen), der ARP-Scan lief in seine Zeitbegrenzung:

[ARPSCAN] arp-scan timed out after 300s

Setzen Sie die Netzbereiche deshalb von Hand auf die zu überwachenden Netze, in der Weboberfläche unter den Einstellungen oder in der Konfigurationsdatei:

SCAN_SUBNETS=['192.168.10.0/24 --interface=eth0']

Weitere Netze ergänzen Sie als zusätzliche Listeneinträge mit passender Schnittstelle. Die Schnittstellennamen zeigt:

ip -br addr

Starten Sie den Container nach einer Änderung an der Datei neu:

sudo docker compose restart

Verifizieren: Der grep-Befehl oben zeigt nur noch Ihre Netze; im Protokoll erscheint keine Meldung arp-scan timed out mehr.

Erster Scan und Ergebnis

Der erste Scan startet nach dem Zeitplan, im Test nach rund drei Minuten:

[ARPSCAN] Found: Devices without duplicates  36
[Plugins] SUCCESS for ARPSCAN received 36 entries
[Scan Stats] Devices Detected.......: 38
[Scan Stats] New Devices............: 38
[Process Scan] Creating new devices

Die Zahlen unterscheiden sich, weil weitere Quellen einfließen. Geräteanzahl in der Datenbank:

sudo docker exec netalertx python3 -c "
import sqlite3
c = sqlite3.connect('/data/db/app.db')
print('Geraete:', list(c.execute('select count(*) from Devices'))[0][0])
"

Verifizieren: Die ausgegebene Zahl entspricht etwa der Zahl aktiver Geräte in Ihrem Netz; die Weboberfläche listet sie mit IP-Adresse, MAC-Adresse und Hersteller.

Benachrichtigungen einrichten

In der Standardkonfiguration sind alle Meldekanäle deaktiviert, hier am Beispiel ntfy:

NTFY_RUN='disabled'  # use 'on_notification' to enable
NTFY_HOST='https://ntfy.sh'
NTFY_TOPIC='replace_my_secure_topicname_91h889f28'

Setzen Sie die Werte in der Weboberfläche statt in der Datei: Sie prüft die Eingaben, und der Dienst schreibt die Datei bei eigenen Änderungen neu. Tragen Sie bei eigenem ntfy-Server dessen Adresse und ein nicht erratbares Thema ein. Markieren Sie vorher die Geräte des ersten Scans als bekannt, sonst meldet jedes vorhandene Gerät. Ereignisse bleiben standardmäßig 90 Tage:

DAYS_TO_KEEP_EVENTS=90

Verifizieren: Die Testfunktion des Kanals in den Einstellungen liefert eine Nachricht auf Ihrem Endgerät.

Absicherung und Netzwerkfreigabe

Die Weboberfläche hat keine Anmeldung und zeigt eine vollständige Netzkarte, sie gehört nie ungeschützt ins Internet. Im Host-Netzwerkmodus gibt es kein ports:, deshalb setzt die compose.yaml die Bindeadresse per Variable:

    environment:
      LISTEN_ADDR: "127.0.0.1"
      PORT: "20211"

Greifen Sie per SSH-Tunnel (ssh -L 20211:127.0.0.1:20211 benutzer@host) oder über einen Reverse Proxy auf demselben Host zu, zum Beispiel Caddy mit Anmeldung:

netz.example.de {
    basic_auth {
        admin $2a$14$HierDenErzeugtenHashEinsetzen
    }
    reverse_proxy 127.0.0.1:20211
}

Den Hash erzeugt Caddy selbst:

caddy hash-password --plaintext 'IhrPasswort'

Zusätzlich lässt sich die Passwortfunktion von NetAlertX aktivieren, die Doku beschreibt auch Authelia. Host-Firewall-Regeln greifen im Host-Netzwerkmodus normal, sperren Sie beide Ports zusätzlich:

sudo ufw deny 20211/tcp
sudo ufw deny 20212/tcp

Verifizieren: sudo ss -ltnp | grep 20211 zeigt 127.0.0.1:20211; von einem anderen Rechner im Netz ist http://<Host-IP>:20211 nicht erreichbar.

Persistente Daten und Rechte

Alle dauerhaften Daten liegen im Volume unter /data:

sudo docker exec netalertx ls -la /data/db /data/config

Ergebnis aus dem Testlauf, gekürzt:

/data/config:
-rw-r--r-- 1 netalertx netalertx 4457 app.conf
-rw------- 1 netalertx netalertx 4450 app.conf_old_setting_names_20260913052659.bak

/data/db:
-rw-r--r-- 1 netalertx netalertx  532480 app.db
-rw-r--r-- 1 netalertx netalertx   32768 app.db-shm
-rw-r--r-- 1 netalertx netalertx 4124152 app.db-wal

Die .bak-Datei entsteht beim Übersetzen alter Einstellungsnamen. -shm und -wal gehören zur Datenbank und müssen mitgesichert werden. Der Dienst läuft als UID 20211, bei einem Hostverzeichnis statt Volume setzen Sie die Rechte:

sudo mkdir -p /opt/netalertx/data
sudo chown -R 20211:20211 /opt/netalertx/data

Backup und Wiederherstellung

Wichtig sind laut Doku /data/db/app.db, /data/config/app.conf, devices.csv und workflows.json. Sichern Sie das Volume bei gestopptem Container, sonst landet die laufende Datenbank unfertig im Archiv (im Test rund 202 KB):

cd /opt/netalertx
sudo docker compose stop
sudo docker run --rm \
  -v netalertx_netalertx_data:/data \
  -v /var/backups:/backup \
  alpine tar czf /backup/netalertx-$(date +%F).tgz -C /data .
sudo docker compose start

Verifizieren: tar tzf /var/backups/netalertx-$(date +%F).tgz | grep app.db listet die Datenbank. Die Wiederherstellung läuft in umgekehrter Reihenfolge mit derselben Image-Version:

cd /opt/netalertx
sudo docker compose down
sudo docker volume rm netalertx_netalertx_data
sudo docker volume create netalertx_netalertx_data
sudo docker run --rm \
  -v netalertx_netalertx_data:/data \
  -v /var/backups:/backup \
  alpine tar xzf /backup/netalertx-2026-09-13.tgz -C /data
sudo docker compose up -d

Prüfen Sie danach die Geräteanzahl. Eine alte Sicherung in einer deutlich neueren Version kann an geänderten Datenbankdefinitionen scheitern. Die CSV-Sicherung unter /data/config ist ohne NetAlertX lesbar, enthält aber keine Historie.

Updates und Rollback

So aktualisieren Sie:

cd /opt/netalertx
sudo docker compose stop
# Sicherung wie oben anlegen
# image-Zeile in compose.yaml auf die neue Version aendern
sudo docker compose pull
sudo docker compose up -d
sudo docker logs -f netalertx --tail 50

Verifizieren: sudo docker compose ps zeigt die neue Version als healthy. Ein Rollback gelingt zuverlässig nur mit dem alten Image zusammen mit der vor dem Update erstellten Sicherung, weil die neue Version die Datenbank umstellen kann. Über mehrere Hauptversionen gehen Sie laut Projektdokumentation schrittweise entlang der Migrationsanleitung vor.

Von 26.9.0 auf 26.10.0 ändert sich für diese compose.yaml nur der Image-Tag. Die einzige Breaking Change betrifft externe Programme mit alten API-Endpunkten, die auf die neue API umgestellt werden müssen. Neu sind unter anderem System Info → Performance (CPU-, Speicher- und Scan-Dauer-Verlauf) und Seitenumbruch in Geräte- und Ereignislisten. Eigene Plugins per Volume von einer Version vor 26.9.0 brauchen den Pfad /server/plugins statt /front/plugins.

Typische Fehler und Lösungen

Der Start scheitert mit „Abbildkennung nicht auffindbar“. Ursache im Test: GitHub-Releases heißen v26.10.0, die Image-Tags 26.10.0 ohne „v“.

Der Start scheitert mit „sysctl … not allowed in host network namespace“: Die Umgebung (etwa LXC oder Incus als Docker-Host) verbietet das Setzen der ARP-Werte. Entfernen Sie den sysctls-Block und setzen Sie die Werte falls nötig auf dem Host (siehe Installation).

Es werden keine Geräte gefunden. Prüfen Sie den Host-Netzwerkmodus, die Capabilities NET_ADMIN und NET_RAW sowie Netz und Schnittstelle in SCAN_SUBNETS.

Nach dem Start passiert minutenlang nichts. Normal: Der erste Scan folgt dem eingestellten Intervall (im Testlauf etwa drei Minuten).

Der Scan läuft in eine Zeitbegrenzung. Meldung arp-scan timed out after 300s: Grenzen Sie SCAN_SUBNETS auf die benötigten Netze ein (typisch: Docker-Bridge-Netz /16 automatisch erkannt).

Erweiterungen zur Namensauflösung melden Zeitüberschreitungen (im Test Avahi, nbtscan, nslookup, dig). Geräte werden erfasst, nur Namen fehlen. Erhöhen Sie den Zeitwert der Erweiterung, das Scan-Intervall oder schalten Sie Erweiterungen ab, die nichts liefern.

Jedes Mobiltelefon erscheint ständig als neues Gerät. Ursache sind private (wechselnde) MAC-Adressen. Aktivieren Sie auf den Geräten für das Firmen-WLAN die feste Adresse oder nehmen Sie diese Geräte von Meldungen aus.

Der Port ist bereits belegt. Ändern Sie im Host-Netzwerkmodus die Variable PORT, nicht einen Eintrag unter ports:.

Saubere Deinstallation

Container entfernen, Daten bleiben erhalten:

cd /opt/netalertx
sudo docker compose down

Achtung: Der Befehl löscht Gerätehistorie, Einstellungen und Ereignisse unwiderruflich. Sichern Sie vorher, wenn Sie die Netzwerkdokumentation brauchen.

sudo docker compose down -v

Entfernen Sie anschließend Image und Verzeichnis:

sudo docker image rm ghcr.io/netalertx/netalertx:26.10.0
sudo rm -rf /opt/netalertx

Haben Sie die ARP-Flux-Werte auf dem Host gesetzt, nehmen Sie sie zurück, sofern kein anderer Dienst sie braucht.

Was tatsächlich geprüft wurde

Im Test (Docker 29.1.3, Compose 2.40.3, isolierte Umgebung) liefen: Start mit korrigiertem Image-Tag, healthy, Weiterleitung auf die Geräteübersicht, Startprotokoll, ein ARP-Scan (36 gefundene, 38 angelegte Geräte mit Hersteller), die Zeitüberschreitung bei zu großem Netzbereich, Konfigurationsauslese und Volume-Sicherung.

Nachtest mit 26.10.0 am 3. Oktober 2026 (Debian 12, Docker CE, Testhost als Incus-Container): Der Container startete mit dieser compose.yaml, war nach wenigen Sekunden healthy, die Oberfläche antwortete auf 127.0.0.1:20211 mit Weiterleitung auf die Geräteübersicht, das Startprotokoll lud ARPSCAN, NSLOOKUP, DIGSCAN, CSVBCKP und NTFPRCS. Der sysctls-Block musste entfallen, weil der Testhost net.ipv4.conf.all.arp_announce im Host-Netzwerkmodus verweigert (sysctl ... not allowed in host network namespace). Dafür gilt die Alternative per sysctl -w auf dem Host.

Passende Anleitungen auf S-EDV

NetBox für IP-Adressverwaltung und Netzwerkdokumentation ergänzt die automatische Erfassung um die gepflegte Solldokumentation.
ntfy selbst hosten für Push-Benachrichtigungen beschreibt den Meldekanal, den NetAlertX ansprechen kann.
Docker Compose unter Linux als Grundlage für Selfhosting erklärt die verwendeten Bausteine.

Quellen

Projekt-Repository netalertx/NetAlertX auf GitHub, Kennzahlen abgerufen am 13. September 2026
NetAlertX-Dokumentation, insbesondere die Abschnitte zu Docker Compose und Sicherungen
NetAlertX: Veröffentlichungen, Version v26.10.0 vom 30. September 2026, abgerufen am 3. Oktober 2026