Skip to content

it00x32/lancom-onsite

Repository files navigation

OnSite

Lokales SNMP-Dashboard für Netzwerkgeräte. Kein Cloud-Zugang erforderlich – alle Abfragen laufen direkt per SNMP gegen die Geräte im lokalen Netz.

Optional: Geräte-Import aus der LANCOM Management Cloud (LMC).

Deployment, getrennte Daten, Updates: docs/PRODUKT-DEPLOY-CHECKLISTE.md — optional Umgebungsvariable ONSITE_DATA_DIR (absolute Pfadangabe), damit die App aktualisiert werden kann, ohne ./data im Installationsordner zu überschreiben. Aktualisieren aus GitHub: siehe Update über GitHub unten.

GitHub: https://github.com/it00x32/lancom-onsite. Umbenennung & Remote-Umstellung: docs/GITHUB-REPO-UMBENENNUNG.md.


Voraussetzungen

Tool Zweck Paket / Hinweis
Node.js ≥ 18 (inkl. npm) Laufzeit und Abhängigkeiten (express, net-snmp, ws, jspdf, html2canvas, …) NodeSource (siehe unten)
snmpget / snmpwalk / snmpbulkwalk SNMP-Abfragen (werden per Unterprozess genutzt) snmp (apt)
curl NodeSource-Setup-Skript herunterladen curl (apt)
git Quellcode holen / aktualisieren git (apt)

Optional (je nach genutzten Funktionen):

Paket Nutzung in OnSite
sshpass, expect SSH-Rollout, Konfigurations-Backup auf Geräten
arp-scan Scanner-Subnetz (falls eingesetzt)

Installation (Ubuntu / Debian)

1. System aktualisieren

sudo apt update && sudo apt upgrade -y

2. Hilfspakete installieren

curl wird für das NodeSource-Installationsskript benötigt, git für den Zugriff auf das Repository.

sudo apt install -y curl git

3. Node.js installieren

Node.js ist in den Standard-Ubuntu-Paketquellen oft veraltet. Über NodeSource wird die aktuelle LTS-Version installiert:

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo bash -
sudo apt install -y nodejs

# Version prüfen (muss >= 18 sein)
node -v

4. SNMP-Tools installieren

Das Paket snmp enthält snmpget, snmpwalk und snmpbulkwalk, die der Server intern für alle Abfragen nutzt. snmp-mibs-downloader lädt die Standard-MIB-Dateien nach (empfohlen, aber optional).

sudo apt install -y snmp snmp-mibs-downloader

Nach der Installation die MIB-Nutzung in der SNMP-Konfiguration aktivieren:

# Zeile "mibs :" auskommentieren, damit alle MIBs geladen werden
sudo sed -i 's/^mibs :$/# mibs :/' /etc/snmp/snmp.conf

5. Quellcode holen und Abhängigkeiten installieren (git + npm)

Empfohlener Ordnername (einheitlich mit systemd-Vorlage): onsite.

git clone https://github.com/it00x32/lancom-onsite.git onsite
cd onsite
npm install --omit=dev

Einstellungen (SNMP, …): data/settings.json liegt nicht im Repository (lokal / geheim). Beim ersten Setup aus der Vorlage anlegen — vorhandene Datei wird nicht überschrieben (cp -n):

cp -n data/settings.example.json data/settings.json

Fehlt die Datei, nutzt der Server die Standardwerte aus dem Code (src/data.js); die UI speichert beim ersten Speichern eine echte data/settings.json.

Das Repository enthält ein vorgebündeltes app.js (esbuild aus ui/). Für einen reinen Betrieb reicht npm install --omit=dev meist aus.

Nach einem git pull, der ui/ oder die Bundling-Konfiguration ändert, das Frontend neu bauen und den Server neu starten:

npm install          # einmal mit devDependencies (esbuild), falls noch nicht vorhanden
npm run build        # erzeugt app.js aus ui/main.js

(Projekt-Repository auch unter älterem Namen onsite nutzbar — Remote anpassen: docs/GITHUB-REPO-UMBENENNUNG.md.)

6. Starten

node server.js          # Port 3004 (Standard), oder per Umgebung: PORT=8080 node server.js
node server.js 8080     # Alternativer Port als Argument

Die Web-Oberfläche ist dann unter http://<server-ip>:<port> erreichbar.

7. Firewall-Freigabe (falls ufw aktiv)

Mindestens den HTTP-Port (Standard 3004/tcp) freigeben. Zusätzlich je nach Nutzung:

Richtung Port Protokoll Funktion
eingehend 3004 (oder PORT) TCP Web-UI, API, WebSocket
eingehend 1620 UDP SNMP-Trap-Empfang
eingehend 1514 UDP Syslog-Empfang
eingehend 1812/1813 (o. ä.) UDP Nur wenn NAC / eingebetteter RADIUS genutzt wird

SNMP zu den Geräten läuft vom Server aus (üblicherweise UDP/161 zum Zielgerät) — dafür müssen Firewall/Routing zum LAN passen, nicht zwingend ein eingehender Port auf dem OnSite-Host.

sudo ufw status
sudo ufw allow 3004/tcp
# Optional:
sudo ufw allow 1620/udp
sudo ufw allow 1514/udp
sudo ufw reload

Update über GitHub

Voraussetzung: OnSite wurde wie unter Installation (Ubuntu / Debian) eingerichtet; der Quellcode liegt in einem lokalen Klon (z. B. git clone https://github.com/it00x32/lancom-onsite.git …). Remote-Repository: https://github.com/it00x32/lancom-onsite.

Daten beim Update schützen: Laufzeitdaten liegen standardmäßig unter ./data im Installationsordner — bei git pull werden sie normalerweise nicht überschrieben, solange sie nicht ins Repo committed sind. Für klare Trennung von Programm und Daten empfiehlt sich ONSITE_DATA_DIR (siehe docs/PRODUKT-DEPLOY-CHECKLISTE.md).

Schrittfolge (üblich mit systemd-Dienst onsite)

  1. Dienst anhalten (damit keine Dateien während des Updates gesperrt sind und ein sauberer Neustart folgt):

    sudo systemctl stop onsite
  2. Ins Installationsverzeichnis wechseln (Repo-Root: dort liegen server.js, package.json):

    cd /pfad/zum/onsite
  3. Neuesten Stand von GitHub holen — zuerst sicherstellen, dass ihr auf dem gewünschten Branch seid (im Repo typisch master; andere Branches z. B. beta, stable nur nach Absprache):

    git fetch origin
    git status
    git pull origin master

    (Wenn euer lokaler Branch bereits origin/master trackt, reicht oft git pull.)

    Hinweis: Lokale Änderungen an getrackten Dateien können zu Merge-Konflikten führen — vorher mit git status prüfen; eigene Anpassungen ggf. committen, stashen oder sichern.

    data/settings.json: Ab Versionen, die diese Datei aus dem Repository entfernen, kann git pull die getrackte Kopie im Arbeitsverzeichnis löschen. Vor dem Update sichern (cp data/settings.json ~/backup-onsite-settings.json), nach dem Pull bei Bedarf zurückspielen — die Datei ist gitignore und wird nicht überschrieben, solange ihr sie nach dem Pull wieder anlegt bzw. aus dem Backup kopiert.

  4. Abhängigkeiten und Frontend-Build: npm install zieht auch esbuild (devDependency), das für den Build nötig ist. npm run build erzeugt das gebündelte app.js aus ui/. Nach jedem Update zur Sicherheit ausführen (auch wenn sich nur das Backend geändert hat — schadet nicht):

    npm install
    npm run build
  5. Rechte (nur falls der Dienst nicht als euer Benutzer läuft, z. B. www-data):

    sudo chown -R www-data:www-data /pfad/zum/onsite

    (Pfad anpassen; bei --omit=dev nur nötig, wenn neue Dateien als root angelegt wurden.)

  6. Dienst wieder starten:

    sudo systemctl start onsite

    Prüfen: sudo systemctl status onsite — danach die Web-UI im Browser neu laden.

Ohne systemd (manueller node server.js)

Schritte 2–4 gleich; statt stop/start: Serverprozess beenden (Ctrl+C oder kill), nach dem Build node server.js … bzw. euer Startskript unter scripte/ wieder starten.

Siehe auch


Autostart mit systemd (empfohlen)

systemd: Das Install-Skript setzt WorkingDirectory und ExecStart auf das Projektverzeichnis (Repo-Root), aus dem es aufgerufen wird — also genau den Ordner, in dem ihr entwickelt und server.js liegt (kein fester Pfad im Code — Vorlage nutzt Platzhalter __ONSITE_INSTALL_ROOT__).

cd /pfad/zum/projektverzeichnis   # Repo-Root: dieselbe Stelle, in der auch server.js liegt
sudo bash deploy/systemd/install-onsite-service.sh
sudo systemctl restart onsite

systemd-Unit aus dem Projektverzeichnis neu setzen

Der Arbeitsordner soll kanonisch onsite heißen (Ordnername). Unit und Pfade neu schreiben:

sudo systemctl stop onsite
cd /pfad/zum/projektverzeichnis   # Repo-Root mit server.js und index.html
sudo bash deploy/rename-to-onsite.sh

Vorlage deploy/systemd/onsite.service.example (User www-data, Platzhalter __ONSITE_INSTALL_ROOT__) — Installation aus dem Projektverzeichnis:

# 1. App nach /opt/onsite (o. ä.) legen
sudo cp -r onsite /opt/onsite
cd /opt/onsite && npm install --omit=dev   # nach UI-Updates: npm install && npm run build
sudo chown -R www-data:www-data /opt/onsite

# 2. Unit erzeugen (Pfade + node automatisch) und Dienst starten
sudo bash deploy/systemd/install-onsite-service.sh --unit-product

Logs & Fehlersuche

Dienst startet nicht: Zuerst aus dem Projektroot bash deploy/verify-onsite-install.sh — prüft index.html, node_modules, Node-Pfad. Dann sudo journalctl -u onsite -n 100 --no-pager (Fehlermeldung meist ENOENT bei fehlender index.html, EADDRINUSE bei belegtem Port, oder falscher ExecStart/WorkingDirectory in der Unit).

Zweck Befehl
Live-Log (systemd) sudo journalctl -u onsite -f
Letzte Zeilen sudo journalctl -u onsite -n 150 --no-pager
Nur eine Instanz? ss -tlnp | grep 3004 — zweiter Prozess → oft EADDRINUSE, Dienst beendet sich
OOM (Speicher) journalctl -k -b | grep -i oom oder dmesg | tail

Stacktrace / Log nennt …/onsite-dev/index.html und …/onsite-dev/server.js: Der laufende Prozess kommt noch von der alten Installation. Häufig: ein Drop-In unter /etc/systemd/system/onsite.service.d/*.conf überschreibt WorkingDirectory oder ExecStart weiter mit onsite-devinstall-onsite-service.sh allein ändert nur die Hauptdatei onsite.service, die Drop-Ins bleiben und mergen sich danach wieder „falsch“ ein. Der aktuelle Code im Repo hat sendStatic nicht in Zeile 43 — ein Stack mit Zeile 43 ist veraltete server.js plus falscher Pfad.

Behebung (empfohlen): Im Repo-Root, in dem ihr entwickelt (z. B. cd /var/www/html/claude/onsite), sudo bash deploy/force-onsite-path.sh ausführen — ersetzt onsite-dev in Unit und Drop-Ins, sichert vorher, schreibt die Unit neu, daemon-reload + restart. Alternativ manuell: Drop-Ins prüfen (ls /etc/systemd/system/onsite.service.d/), alle Zeilen mit onsite-dev auf …/onsite korrigieren, dann sudo bash deploy/systemd/install-onsite-service.sh und sudo systemctl daemon-reload && sudo systemctl restart onsite. Prüfen: systemctl cat onsite — nirgends onsite-dev. pgrep -af 'node.*onsite' — kein Prozess mit onsite-dev im Pfad. Optional: bash deploy/verify-onsite-install.sh.

ENOENTindex.html: WorkingDirectory/ExecStart in der Unit müssen auf dieselbe Installation zeigen wie die Dateien (index.html im selben Ordner wie server.js). Aus dem Projektroot: sudo bash deploy/systemd/install-onsite-service.sh und sudo systemctl daemon-reload && sudo systemctl restart onsite. Beispiel: WorkingDirectory=/opt/onsite, ExecStart=/usr/bin/node /opt/onsite/server.js (Node-Pfad ggf. anpassen). Prüfen: systemctl cat onsite, grep -rE '/onsite/|__ONSITE_INSTALL_ROOT__' /etc/systemd/system/ 2>/dev/null.

Stacktrace zeigt noch eine alte server.js: Zwei Kopien der App oder ein unvollständiges Projektverzeichnis — Diagnose: bash deploy/diagnose-onsite.sh. Lösung: eine gültige Installation (index.html + server.js im selben Ordner), Unit neu installieren, Dienst neu starten.

sendStatic-Fehler mit falschem Pfad zu index.html: Oft veraltete server.js oder fehlende index.html im Ordner von server.js. Vorgehen: ls index.html im Installationsverzeichnis — fehlt die Datei → git checkout -- index.html app.js styles.css bzw. git pull. Danach sudo systemctl restart onsite. Nur einen aktiven Installationsordner nutzen (Unit-ExecStart = dieser Ordner).

  • Vorlage /opt/onsite: deploy/systemd/onsite.service.example
  • Vorlage beliebiges Repo-Root (Platzhalter in der Datei): deploy/systemd/onsite.service.var-www-html-claude.example

Hinweis: WorkingDirectory und ExecStart in der Unit-Datei müssen zum absoluten Installationspfad passen (/opt/onsite ist nur ein Beispiel).

scripte/ und das Datenverzeichnis müssen für den Dienstbenutzer beschreibbar sein: Standard ./data im Projektordner — bei ONSITE_DATA_DIR stattdessen diesen Pfad anlegen und chown setzen, z. B. sudo chown -R www-data:www-data scripte/ data/ bzw. … /var/lib/onsite/data.

Manuell mit Logdatei (ohne systemd)

chmod +x scripte/start-onsite.sh
./scripte/start-onsite.sh
# Ausgabe in log/onsite.log

Features

Tabs

Tab Beschreibung
Geräte Zentrale Geräteliste mit Online/Offline-Status, Standort, LLDP-Nachbarn, WDS- und L2TPv3-Verbindungsanzahl, MAC-Adressen. Filter nach Status und Standort.
WiFi Mesh Alle WDS-Links über alle LX Access Points – RSSI-Farbkodierung, Standort-Spalte, Filter nach Status und Standort.
L2TPv3 Alle L2TP-Endpunkte über alle LX Access Points – UP/DOWN-Status, Standort-Spalte, Filter nach Status und Standort.
Netzwerkplan Topologie-Graph aus LLDP-, WDS- und L2TPv3-Daten. BFS-Layout, Zoom/Pan/Drag, Standort-Filter. Optionen: APs ausblenden, Nicht verwaltete Geräte ausblenden (LLDP-„Geist“-Knoten und L2TP-Ziele ohne Eintrag im Gerätebestand). PDF-Export der aktuellen Ansicht inkl. LLDP-Tabelle. Bei aktivem Traffic-Modus: LLDP-Kantenfarbe nach Portgeschwindigkeit (Stufen). Legende an Hell-/Dunkeltheme angepasst. MAC-/IP-Suche: FDB-Treffer auf Switches werden nicht gezeichnet, wenn der Port laut LLDP mit einem anderen Switch verbunden ist (kein Client-Overlay auf Switch-zu-Switch-Uplinks).
Scanner Subnetz oder IP-Bereich scannen und direkt importieren. Standort kann beim Import zugewiesen werden (vorhandener Standort wählen oder neuen eingeben).
LMC Import Geräteliste aus der LANCOM Management Cloud importieren – liest automatisch den Standort (siteName) aus.
Einstellungen SNMP (v2c/v3), Communities/Passwörter mit Anzeigen/Verbergen, RSSI-Schwellwerte – serverseitig persistent.
Gerät (Detail) System-Info, Interfaces, MAC/ARP-Tabelle, WLAN-Clients, LLDP-Nachbarn.

Sync-Aktionen (Tab „Geräte")

Button Funktion
Alle Daten abrufen Führt Status → WDS → L2TPv3 → LLDP → MAC nacheinander aus und aktualisiert den Netzwerkplan.
Status Online/Offline-Prüfung per SNMP-Ping.
LLDP LLDP-Nachbartabelle abfragen.
WDS WDS-Verbindungen der LX Access Points abfragen.
L2TPv3 L2TPv3-Endpunkte der LX Access Points abfragen.
MAC Interface-MAC-Adressen abfragen.

Standort-Filter: Wenn unter „Geräte" ein Standort ausgewählt ist, werden alle Sync-Aktionen nur auf Geräte dieses Standorts angewendet.

Standort-Verwaltung

  • LMC Import: Standort (siteName) wird automatisch aus der LMC API übernommen.
  • Scanner: Standort kann beim Scan frei eingegeben oder aus vorhandenen Standorten gewählt werden.
  • Filter: Jeder Tab (Geräte, WiFi Mesh, L2TPv3, Netzwerkplan) hat einen Standort-Dropdown.
  • Netzwerkplan: Standort wird auf jedem Node-Karte angezeigt (📍). Filter blendet alle Geräte anderer Standorte aus.

Design & Bedienung

  • Tag/Nacht-Modus: Umschalter (☀️ / 🌙) in der Kopfzeile – Einstellung wird lokal gespeichert.

Versionshinweise (Auszug)

Version Kurzüberblick
v0.11.9 Netzwerkplan: Option Nicht verwaltete Geräte ausblenden (wie „APs ausblenden“); blendet Geist-Knoten und L2TP-Ziele ohne Gerät aus, inkl. Kanten.
v0.11.8 Netzwerkplan: MAC-/IP-Suche — FDB-Client nicht auf Switch-Ports, die per LLDP mit einem anderen Switch verbunden sind (frühere Uplink-Dedupe-Heuristik entfernt).
v0.11.7 Netzwerkplan: fehlende topoFdbPortMatchesLldp wiederhergestellt (MAC-Uplink-Dedupe war zur Laufzeit kaputt). Port-Matching ohne riskantes Substring. Dedupe-Priorität: Plan-Filter wie buildTopoGraph, dann Knoten im Graphen.
v0.11.6 Netzwerkplan: MAC-/FDB-Dedupe entfernt immer den Treffer, der nicht im aktuellen Topologie-Graphen liegt (sonst verschwand das Overlay komplett). LLDP-Kandidaten ohne remPortId/remPortDesc der Gegenstelle (falsche lokale Treffer).
v0.11.5 Netzwerkplan: MAC-/FDB-Uplink-Dedupe prüft pro Switch mehrere Port-Labels (LLDP zum Nachbarn, Kanten-Ports, FDB-Ports an denen Nachbar-MACs gelernt sind).
v0.11.4 Netzwerkplan: MAC-/FDB-Uplink-Deduplizierung — LLDP-Gegenport oft als MAC; Kantenenden per Nachbar-LLDP auf ifName, etwas toleranteres Port-Matching.
v0.11.3 Netzwerkplan: MAC-/FDB-Deduplizierung ohne „eine LLDP-Kante genügt“-Fallback (der echte Access-Port-Treffer neben dem Uplink verschwand). Weiterhin nur bei Port-Match zur Kante; fehlendes dstPort im Kantenobjekt wird aus LLDP des Nachbarn ergänzt.
v0.11.2 Netzwerkplan: zu aggressive MAC-/FDB-Deduplizierung (Zwischenstand, durch v0.11.3 ersetzt).
v0.11.1 Netzwerkplan: MAC-/IP-Suche blendet doppelte FDB-Treffer aus, wenn dieselbe MAC auf beiden Seiten einer LLDP-Verbindung zwischen zwei bekannten Geräten (passende Ports) erscheint.
v0.11.0 Netzwerkplan: PDF-Export (Karte + LLDP-Tabelle), Kantenfarbe nach Portgeschwindigkeit bei Traffic, Legende theme-konform; Blueprint-Ansicht entfernt. SNMP-Einstellungen: Passwörter/Communities einblenden. Frontend-Bundle inkl. jspdf / html2canvas.

Unterstützte Geräte

Gerät OS SNMP-Features
LANCOM Router LCOS System, Interfaces, MAC/ARP, LLDP
LANCOM Switches (GS-2xxx) LCOS SX System, Interfaces, MAC/ARP, LLDP
LANCOM Access Points LCOS LX System, Interfaces, MAC/ARP, LLDP, WLAN-Clients, WiFi Mesh (WDS), L2TPv3
LANCOM Access Points LCOS System, Interfaces, MAC/ARP, LLDP
LANCOM Firewalls LCOS FX System, Interfaces, MAC/ARP, LLDP
Andere SNMP-Geräte MIB-II System, Interfaces, MAC/ARP, LLDP

SNMP am Gerät aktivieren

Betriebssystem Pfad
LCOS Gerätekonfiguration → Management → SNMP → SNMPv2 aktivieren, Read-Community eintragen
LCOS LX Gerätekonfiguration → Management → SNMP → SNMPv2 aktivieren, Read-Community eintragen
LCOS SX Gerätekonfiguration → Management → SNMP → SNMPv2 aktivieren, Read-Community eintragen
LCOS FX Gerätekonfiguration → Verwaltung → SNMP aktivieren

Technische Details

LLDP

LANCOM-Geräte verwenden den IEEE-802.1AB-Pfad (1.0.8802.1.1.2) für LLDP, nicht den IANA-Pfad (1.3.6.1.2.1.111). Der Server fragt beide OIDs parallel ab und wählt automatisch den richtigen.

Netzwerk-Scanner

Der Scanner nutzt Server-Sent Events (SSE) für Echtzeit-Rückmeldung. Es werden bis zu 20 Hosts gleichzeitig per SNMP geprüft (2 Sekunden Timeout pro Host). Nur unterstützte Geräte (anhand sysDescr / sysObjectID) erscheinen in der Ergebnisliste.

Datenpersistenz

Standard: alle Laufzeitdaten unter data/ im Projektverzeichnis (lokal, nicht verpflichtend mit Git mitgeführt). Über ONSITE_DATA_DIR kann ein absoluter Pfad gesetzt werden (z. B. /var/lib/onsite/data), damit Updates das Programmverzeichnis ersetzen können, ohne die Daten zu überschreiben — siehe docs/PRODUKT-DEPLOY-CHECKLISTE.md.

Datei / Bereich Inhalt (Auszug)
data/settings.example.json Vorlage für SNMP/UI-Einstellungen (ohne Geheimnisse) → lokal nach data/settings.json kopieren
data/settings.json Lokal, nicht im Git — SNMP-Communities, v3-Passwörter, Gerätepasswort, …
data/devices.json Geräteliste, LLDP/WDS/L2TP, Standorte
weitere JSON-Dateien Traps, Monitoring, NAC, Roaming, … je nach Nutzung

Architektur

  • server.js – Einstieg; statische Auslieferung von index.html, app.js, styles.css; lädt Module unter src/ (Express-API, SNMP-Helfer, WebSockets, Traps, Scheduler, …).
  • ui/ – Quellcode der SPA (ES-Module); npm run build (esbuild) erzeugt das gebündelte app.js.
  • index.html, styles.css – Shell und Styles; kein React/Vue — Vanilla-JS-Frontend.
  • Abhängigkeiten: siehe package.json (express, net-snmp, ws, …).

Lizenz

MIT – siehe LICENSE

Die Software wird ohne jegliche Gewährleistung bereitgestellt. Der Autor übernimmt keine Haftung für Schäden, die durch die Nutzung entstehen. Produktnamen wie LCOS, LCOS LX, LCOS SX, LCOS FX sind Eigentum der jeweiligen Hersteller. Der Autor steht in keiner Verbindung zu LANCOM Systems GmbH.

About

LANCOM OnSite - Local SNMP-based device dashboard

Resources

License

Stars

0 stars

Watchers

0 watching

Forks

Packages

 
 
 

Contributors