Linuxmuster OPNsense

Dieses Projekt stellt eine Sammlung von Integrationstools für die Anbindung von linuxmuster.net an OPNsense bereit. Die Hauptfunktionen umfassen:

• Synchronisation von IP-Aliasen (Rollen, Räume, Hardwaregruppen) auf der OPNsense-Firewall
• Verwaltung von Captive-Portal-Vouchers (Erstellen, Auflisten, Löschen)
• Listen und Trennen aktiver Captive-Portal-Sessions
• Automatisierte Alias-Aktualisierung nach Geräte-Importen

Installation

Erste Schritte & Konfiguration

1. Basis-Konfiguration

   • Kopieren Sie die Datei

     /etc/linuxmuster/opnsense/default-school.ini.default

     in

     /etc/linuxmuster/opnsense/MEINE_SCHULE.ini

     (MEINE_SCHULE ist ein frei wählbarer Name).

2. Parameter setzen
   Öffnen Sie die neu angelegte .ini-Datei und füllen Sie die benötigten Werte aus:

   • [opnsense]

     • api_key / api_secret: Zugangsdaten für die OPNsense-API
     • base_url: Basis-URL der OPNsense (z. B. https://firewall.example.org/api)
     • verify_ssl (True/False): SSL-Zertifikatprüfung aktivieren oder deaktivieren
     • ca_bundle: Pfad zu einer CA-Bundle-Datei (falls vorhanden)

   • [school]

     • name: Anzeigename der Schule (wird für Geräte-Filterung, Ausgaben usw. genutzt)

   • [aliases]

     • sync_roles: Legt fest, ob Rollen (z. B. Schüler, Lehrer etc.) synchronisiert werden sollen
     • roles_prefix: Prefix für Rollen-Aliasnamen (z. B. ROLE_)
     • sync_rooms: Legt fest, ob Räume synchronisiert werden sollen
     • rooms_prefix: Prefix für Raum-Aliasnamen (z. B. ROOM_)
     • sync_hwgroups: Legt fest, ob Hardware-Gruppen synchronisiert werden sollen
     • hwgroups_prefix: Prefix für Hardwaregruppen-Aliasnamen (z. B. HWGROUP_)

   • [voucher]

     • provider: Name des Voucher-Providers im OPNsense Captive Portal (Standard: Voucher)

3. Mehrere Schulen

   • Sie können mehrere .ini-Dateien anlegen (z. B. default-school.ini, schule-2.ini) und damit Skripte für verschiedene Einrichtungen ausführen.

Nutzung der Skripte

1) opn-captive-voucher

• Beschreibung: Script zur Verwaltung der Captive-Portal-Vouchers in OPNsense.
• Aufruf:

  opn-captive-voucher --school <INI-NAME> <SUBCOMMAND> [OPTIONEN]

• Subcommands:
  • list [GROUP]
    • Zeigt alle Voucher-Gruppen an (ohne GROUP).
    • Zeigt alle Vouchers in einer bestimmten Gruppe (mit GROUP).
  • create
    • Erzeugt neue Vouchers in der angegebenen Gruppe.
    • Wichtige Parameter:
      • --validity (Standard: 4h): Gültigkeitsdauer (z. B. 1d, 12h)
      • --expiry (Standard: never): Zeit bis ein Voucher verfällt
      • --count (Standard: 5): Anzahl zu erstellender Vouchers
  • delete
    • Löscht Vouchers oder ganze Gruppen.
    • Wichtige Optionen:
      • --username <USER>: Löscht einen bestimmten Voucher
      • --all-expired: Löscht alle abgelaufenen Vouchers in der Gruppe
      • --all: Löscht die gesamte Gruppe (inkl. aller Vouchers)

Beispiele:

• Alle Gruppen auflisten

  opn-captive-voucher list

• Vouchers in Gruppe test anzeigen

  opn-captive-voucher list test

• 5 neue Vouchers in Gruppe test anlegen

  opn-captive-voucher create test --count 5 --validity 4h --expiry 1d

• Einen bestimmten Voucher löschen

  opn-captive-voucher delete test --username r2x

2) opn-captive-sessions

• Beschreibung: Listet oder trennt aktive Captive-Portal-Sessions in OPNsense.
• Aufruf:

  opn-captive-sessions --school <INI-NAME> [OPTIONEN]

• Optionen:
  • --search <PHRASE>: Zeigt nur Sessions, die den Suchbegriff enthalten (z. B. Username).
  • --zone <ID1 ID2 ...>: Filtert auf bestimmte Zonen-IDs.
  • --kill-username <USER>: Trennt alle Sessions für den genannten Benutzernamen (exakter Match).
  • --kill-sessionid <SESSIONID>: Trennt eine spezifische Session.

Beispiele:

• Alle Sessions anzeigen

  opn-captive-sessions

• Alle Sessions eines bestimmten Nutzers trennen

  opn-captive-sessions --kill-username alice

• Genau eine Session trennen

  opn-captive-sessions --kill-sessionid "abc123XYZ"

3) opn-update-aliases

• Beschreibung: Aktualisiert die Alias-Listen in OPNsense basierend auf Informationen aus linuxmuster-tools. Dabei können Rollen, Räume und Hardwaregruppen berücksichtigt werden.
• Konfiguration:
  • In der jeweiligen .ini-Datei (Abschnitt [aliases]):
    • sync_roles, roles_prefix
    • sync_rooms, rooms_prefix
    • sync_hwgroups, hwgroups_prefix
• Aufruf:

  opn-update-aliases --school <INI-NAME> [--quiet]

  • --quiet: Unterdrückt normale Ausgaben, nur Fehler werden angezeigt.

Funktionsweise:

1. Liest alle Geräte aus dem Devices-Management (via linuxmusterTools.devices.devices).
2. Erzeugt oder aktualisiert die entsprechenden Alias-Einträge in OPNsense.
3. Sendet ein reconfigure, damit die Änderungen sofort aktiv werden.

4) opn-update-all-schools (Hook)

• Pfad:

  /var/lib/linuxmuster/hooks/device-import.post.d/opn-update-all-schools

• Beschreibung:
  Dieser Hook wird automatisch nach dem Import neuer Geräte (z. B. mittels linuxmuster-import-devices) ausgeführt.
  • Er sucht alle .ini-Dateien in /etc/linuxmuster/opnsense/,
  • ruft für jede davon das Skript opn-update-aliases auf,
  • und aktualisiert so alle in der Ini-Datei konfigurierten Schulen.

Hinweis: Wer diesen Automatik-Hook nicht nutzen möchte, kann ihn entfernen oder umbenennen.

5) 99_kill_wlan_sessions (Hook)

• Pfad:

  /etc/linuxmuster/tools/hooks/group-manager/99_kill_wlan_sessions

• Beschreibung:
  Dieser Hook wird automatisch aufgerufen, wenn ein Benutzer aus der Gruppe wifi entfernt wird. Er überprüft in der jeweiligen Schulkonfiguration (.ini-Datei), ob in der Sektion [wlan] die Option kill_session = True gesetzt ist.
  • Nur wenn kill_session = True eingetragen ist, werden die aktiven Captive-Portal-Sessions des betroffenen Nutzers auf OPNsense per

    opn-captive-sessions --kill-username <BENUTZERNAME>

    beendet.
  • Bei kill_session = False wird nichts unternommen.

Hinweis:

• Das Skript gibt nur Fehler aus; bei erfolgreicher Ausführung bleibt es still.
• Der Hook wird alphabetisch aufgerufen, daher stellt das Präfix 99_ sicher, dass das Skript gewöhnlich zuletzt ausgeführt wird.

Typische Anwendungsfälle

1. Geräte-Import & automatische Alias-Aktualisierung

   • Nach dem Befehl

     linuxmuster-import-devices

     wird über den Hook opn-update-all-schools die OPNsense-Aliasliste neu erstellt.

2. Voucher für Projekt-/GästewLAN

   • Mit opn-captive-voucher create <group> lassen sich kurzfristig neue Zugangscodes anlegen.
   • Abgelaufene Vouchers können über --all-expired bereinigt werden.

3. Troubleshooting bei Captive Portal

   • Aktive Sessions über opn-captive-sessions listen.
   • Notfalls einzelne Sessions trennen (z. B. bei Missbrauch).