Appearance
Zielgruppe & Rolle
Rolle: IT-Administrator | Voraussetzung: Administrator-Rechte auf dem Windows Server & microtech BpConfig
Automatische NetBird-Anbindung für microtech ERP
Mit der automatischen NetBird-Enrollment-Funktion können Sie Ihren On-Premises microtech büro+ Server ohne manuelle Zertifikatserstellung, feste externe IP-Adressen oder Firewall-Portweiterleitungen sicher und verschlüsselt an ConnectCLOUD anbinden.
Übersicht & Funktionsweise
Die Anbindung erfolgt über ein sicheres VPN-Overlay-Netzwerk (NetBird) und selbstsignierte TLS-Zertifikate mit Ende-zu-Ende-Verschlüsselung:
- Enrollment starten: Im ConnectCLOUD-Portal (
/customer-adminunter microtech) wird für den Server ein einmaliger, zeitlich begrenzter Enrollment-Code (Gültigkeit: 60 Minuten) erzeugt. - Bootstrap-Skript ausführen: Auf dem Windows-Server wird als Administrator ein vorgefertigter, geheimnisfreier PowerShell-Befehl ausgeführt. Das Skript installiert NetBird, verbindet den Peer, erstellt ein ECDSA-TLS-Zertifikat und lädt den öffentlichen Schlüssel zu ConnectCLOUD hoch.
- Zertifikat in microtech zuweisen: In
BpConfig.exewird das neue Zertifikat anhand des Thumbprints für die HTTP/2-Schnittstelle ausgewählt. - Aktivierung bestätigen: Im Kundenportal wird die Aktivierung per Klick auf „In microtech aktiviert“ abgeschlossen.
Fester DNS- und Peer-Name
Jeder Server erhält bei der ersten Einrichtung einen eindeutigen und stabilen NetBird-Peer-Namen nach dem Schema:
text
microtech-<umgebung>-<kundennummer>-<zufallssuffix>- Beispiel:
microtech-prod-10639-81962348 - Vollständiger Domänenname (FQDN):
microtech-prod-10639-81962348.netbird.cloud - Automatische Basis-URL: ConnectCLOUD hinterlegt automatisch die Basis-URL
https://microtech-prod-10639-81962348.netbird.cloud:8443/microtech/erp.
Dieser Name und die URL bleiben auch bei wiederholter Ausführung des Skripts oder regulärer Zertifikatsrotation unverändert erhalten.
Voraussetzungen
- Betriebssystem: Windows Server 2016+ oder Windows 10/11 (64-Bit), auf dem microtech ERP ausgeführt wird.
- PowerShell: Version 5.1 oder neuer (Standard auf modernen Windows-Systemen) mit Administratorrechten.
- Netzwerk: Ausgehender Internetzugang (HTTPS / Port 443 sowie UDP für NetBird WireGuard-Verbindungen). Es sind keine eingehenden Portweiterleitungen oder öffentlichen IP-Adressen erforderlich!
- microtech Vorbereitung: Die microtech-Anwendung für ConnectCLOUD mit Client-ID und Client-Secret muss angelegt sein (siehe Basis-Konfiguration).
Schritt-für-Schritt-Anleitung
Schritt 1: Enrollment in ConnectCLOUD starten
- Melden Sie sich im ConnectCLOUD-Portal an und navigieren Sie zur Kunden-Administration (
/customer-admin). - Wechseln Sie in den Reiter microtech.
- Neuer Server: Klicken Sie oben auf „Server mit NetBird anbinden“.
- Geben Sie einen sprechenden Namen ein (z. B.
ERP Hauptserver). - Hinterlegen Sie
Client-IDundClient-Secretder microtech-Anwendung. - Optional: Fügen Sie bereits Mandanten-Zuordnungen hinzu.
- Klicken Sie auf „Weiter“.
- Geben Sie einen sprechenden Namen ein (z. B.
- Bestehender Server: Falls der Server bereits in der Liste existiert, klicken Sie auf der Server-Karte im Bereich NetBird & TLS Enrollment auf „Enrollment starten“ bzw. „Neues Enrollment“.
- Beantworten Sie die Frage „Läuft auf dem Server schon ein anderes VPN?“:
- Ja: Der Befehl enthält
-InstanceMode Isolated. ConnectCLOUD wird getrennt neben dem bestehenden VPN eingerichtet (siehe Parallelbetrieb mit bestehenden VPNs). - Nein oder Weiß nicht: Der Befehl enthält keinen zusätzlichen Parameter. Das Skript erkennt bestehende VPNs selbst.
-InstanceMode Defaultwird bewusst nie automatisch gesetzt.
- Ja: Der Befehl enthält
- Auf der Server-Karte fasst ein zweiter Schritt zusammen, was passieren wird. War der Server bereits verbunden, wird er mit derselben Identität erneut verbunden. Erst mit „Befehl erzeugen“ bzw. „Server anlegen & Befehl erzeugen“ wird der Enrollment-Code (gültig für 60 Minuten) erzeugt und zusammen mit dem vollständigen PowerShell-Befehl angezeigt.
Verwaltung des Enrollments
Solange ein Enrollment aktiv ist, stehen Ihnen auf der Server-Karte zwei Optionen zur Verfügung:
- Befehl & Code neu generieren: Erzeugt bei Bedarf einen frischen Code, falls der vorherige abgelaufen ist.
- Enrollment abbrechen: Bricht den Vorgang ab und setzt den Server-Status zurück.
Schritt 2: Bootstrap-Skript auf dem microtech-Server ausführen
- Öffnen Sie auf dem Windows-Server eine PowerShell als Administrator (Rechtsklick auf Windows Start -> Windows PowerShell (Administrator)).
- Kopieren Sie den angezeigten Einzeiler aus dem Kundenportal und führen Sie ihn aus:powershell
& { iwr -useb "https://microtech.mbcom.cloud/api/microtech/v1/enrollment/bootstrap.ps1" | iex } -Code "<ENROLLMENT-CODE>" - Das Bootstrap-Skript arbeitet autonom und führt folgende Schritte aus:
- Überprüfung der Administratorrechte und PowerShell-Version.
- Herunterladen und Installation des offiziellen NetBird-Clients (sofern noch nicht installiert).
- Prüfung, ob auf dem Server bereits ein anderes NetBird-Konto, Tailscale oder ein anderes WireGuard-VPN eingerichtet ist. In diesem Fall wird automatisch eine isolierte ConnectCLOUD-Instanz verwendet (siehe Parallelbetrieb mit bestehenden VPNs).
- Einrichtung eines dedizierten NetBird-Profils (
ConnectCLOUD) anstelle des Default-Profils (nur Standardinstanz). - Dynamische Zuweisung des WireGuard-Ports (
--wireguard-port 0), um Port-Kollisionen mit Windows-Diensten (wie dem Windows DNS Server auf Port 51820) zu vermeiden. - Verbindung zum NetBird-VPN-Netzwerk als vorkonfigurierter Peer.
- Erstellung oder Wiederverwendung eines TLS-Zertifikats (ECDSA P-256) im Windows-Zertifikatsspeicher (
Cert:\LocalMachine\My) mit nicht-exportierbarem privaten Schlüssel. - Sichere Übertragung des öffentlichen Zertifikats an ConnectCLOUD.
- Nach Abschluss gibt das Skript den Zertifikats-Thumbprint (SHA-1 / SHA-256 Fingerabdruck) in der Konsole aus.
Execution Policy
Falls PowerShell die Skriptausführung mit einem Sicherheitsfehler blockiert, führen Sie den Befehl mit vorangestelltem Bypass aus:
powershell
powershell -ExecutionPolicy Bypass -Command "& { iwr -useb 'https://microtech.mbcom.cloud/api/microtech/v1/enrollment/bootstrap.ps1' | iex } -Code '<ENROLLMENT-CODE>'"Erweiterte Parameter (Profil & WireGuard-Port)
Das Skript unterstützt optionale Parameter für spezifische Netzwerk- oder Profilanforderungen:
-ProfileName <Name>: Verwendet ein alternatives NetBird-Profil (Standard:ConnectCLOUD). Gilt nur für die Standardinstanz.-UseDefaultWireGuardPort: Deaktiviert die dynamische Portwahl und lässt NetBird den Standardport (51820) nutzen.-WireGuardPort <Port>: Erzwingt einen bestimmten WireGuard UDP-Port (z. B.-WireGuardPort 51825).-InstanceMode Auto|Default|Isolated: Steuert, ob die NetBird-Standardinstanz oder eine isolierte ConnectCLOUD-Instanz verwendet wird (Standard:Auto).
Schritt 3: Zertifikat in microtech aktivieren (BpConfig)
- Öffnen Sie
BpConfig.exeauf dem microtech-Server. - Navigieren Sie zu den Einstellungen für die GraphQL / HTTP/2 API.
- Stellen Sie sicher, dass der HTTP/2 Port auf
8443(oder den von Ihnen gewünschten Port) konfiguriert ist. - Öffnen Sie die Zertifikatsauswahl.
- Wählen Sie das Zertifikat aus, dessen Thumbprint (Fingerabdruck) mit dem vom Skript ausgegebenen bzw. im ConnectCLOUD-Portal angezeigten Wert übereinstimmt.
- Speichern Sie die Konfiguration in
BpConfig.exeund starten Sie die microtech-Dienste bei Bedarf neu.
Schritt 4: Aktivierung in ConnectCLOUD bestätigen
- Kehren Sie in das ConnectCLOUD-Portal zur Kunden-Administration (Reiter microtech) zurück.
- Die Server-Karte zeigt nun den Status „Zertifikat hochgeladen – Aktivierung in microtech erforderlich“ an.
- Überprüfen Sie, ob der angezeigte Thumbprint mit dem in microtech ausgewählten Zertifikat übereinstimmt.
- Klicken Sie auf die Schaltfläche „In microtech aktiviert“.
- Der Status wechselt auf „Bereit“ (grün).
Schritt 5: Mandanten abrufen & Verbindung testen
- Klicken Sie auf der Server-Karte auf „Bearbeiten“ oder nutzen Sie den Button „Mandanten abrufen“.
- ConnectCLOUD ruft über die frisch aufgebaute NetBird-Verbindung die microtech GraphQL-API ab und zeigt alle erkannten Mandanten an.
- Weisen Sie die microtech-Mandanten Ihren ConnectCLOUD-Mandanten zu und aktivieren Sie die gewünschten Einträge.
- Klicken Sie auf „Verbindung testen“, um den Token-Abruf und eine Testabfrage abschließend zu verifizieren.
Parallelbetrieb mit bestehenden VPNs
Viele Server sind bereits über ein eigenes VPN angebunden – etwa über ein eigenes NetBird-Konto, Tailscale oder WireGuard. Das Bootstrap-Skript erkennt das und richtet ConnectCLOUD dann als isolierte NetBird-Instanz ein, ohne die bestehende Verbindung zu verändern.
Wann wird die isolierte Instanz verwendet?
Mit dem Standardwert -InstanceMode Auto verwendet das Skript die isolierte Instanz, wenn mindestens eine der folgenden Bedingungen zutrifft:
- NetBird ist mit einem Konto eingerichtet, das nicht von ConnectCLOUD stammt.
- Ein Tailscale-, WireGuard- oder ZeroTier-Dienst ist installiert.
- Der Server wurde bereits zuvor mit der isolierten Instanz angebunden.
Ist kein anderes VPN vorhanden, wird wie bisher die NetBird-Standardinstanz verwendet. Mit -InstanceMode Default bzw. -InstanceMode Isolated lässt sich die Wahl erzwingen.
Was unterscheidet die isolierte Instanz?
| Standardinstanz | Isolierte Instanz | |
|---|---|---|
| Windows-Dienst | netbird | NetBird-ConnectCLOUD |
| Programmdateien | C:\Program Files\NetBird (MSI) | %ProgramData%\ConnectCLOUD\NetBird\bin (eigene Kopie, nur für SYSTEM und Administratoren beschreibbar) |
| Daemon-Adresse | Standard | npipe://netbird-connectcloud |
| Netzwerk | Netzwerkadapter wt0, Routen und DNS-Einträge | Userspace-Modus: kein Netzwerkadapter, keine Routen- oder DNS-Änderungen am System |
| NetBird-Oberfläche (Tray) | ja | nein – Status nur per Kommandozeile |
Da die isolierte Instanz keinen Netzwerkadapter anlegt, kollidiert sie weder mit dem Adapter eines anderen NetBird-Kontos noch mit überlappenden IP-Bereichen (z. B. 100.64.0.0/10 bei Tailscale). Eingehende Verbindungen von ConnectCLOUD auf die NetBird-Adresse leitet NetBird an 127.0.0.1 weiter.
Voraussetzungen und Hinweise
- Lokale Erreichbarkeit: Der HTTP/2-Dienst von microtech muss auf dem Server auch über
127.0.0.1:8443erreichbar sein (Standard bei Bindung an alle Adressen). - Firewall-Regel: Alle NetBird-Instanzen teilen sich die Windows-Firewall-Regeln
NetbirdundNetbird-v6. Damit ein Neustart der ConnectCLOUD-Instanz die Regeln der Kundeninstanz nicht entfernt, richtet das Skript die geplante Aufgabe\ConnectCLOUD\NetBird Firewall Guardein. Sie stellt die Regeln beim Systemstart und alle 5 Minuten wieder her – für Adressen aus den NetBird-Standardbereichen (100.64.0.0/10bzw.fc00::/7). Kann die Aufgabe nicht eingerichtet werden, wird die Anbindung trotzdem abgeschlossen und eine Warnung ausgegeben. - Updates: Updates der NetBird-Installation des Kunden betreffen die isolierte Instanz nicht. Zum Aktualisieren der isolierten Instanz führen Sie das Skript erneut mit
-UpgradeNetBirdaus. - Verzeichnisrechte: Existiert
%ProgramData%\ConnectCLOUDoder%ProgramData%\ConnectCLOUD\NetBirdbereits und gehört es nicht Administratoren bzw. SYSTEM, bricht das Skript ab. Prüfen und entfernen Sie das Verzeichnis in diesem Fall.
Signaturprüfung
Das Skript installiert bzw. entpackt NetBird nur, wenn das Installationspaket (und bei der isolierten Instanz zusätzlich netbird.exe) gültig von der NetBird GmbH signiert ist. Auf Servern ohne aktuelle Stammzertifikate (z. B. dauerhaft offline) kann die Prüfung fehlschlagen; installieren Sie dann die Windows-Stammzertifikatsupdates.
Status prüfen und isolierte Instanz entfernen
powershell
# Status der ConnectCLOUD-Instanz
& "$env:ProgramData\ConnectCLOUD\NetBird\bin\netbird.exe" status --daemon-addr npipe://netbird-connectcloud
# Entfernen (z. B. nach Kündigung)
& "$env:ProgramData\ConnectCLOUD\NetBird\bin\netbird.exe" down --daemon-addr npipe://netbird-connectcloud
Stop-Service NetBird-ConnectCLOUD; sc.exe delete NetBird-ConnectCLOUD
Unregister-ScheduledTask -TaskPath "\ConnectCLOUD\" -TaskName "NetBird Firewall Guard" -Confirm:$false
Remove-Item "$env:ProgramData\ConnectCLOUD\NetBird" -Recurse -ForceZertifikatsrotation & Re-Run-Verhalten
Die NetBird-Anbindung ist auf maximale Betriebssicherheit und minimale Wartung ausgelegt:
Idempotente Mehrfachausführung (Re-Run)
Das Bootstrap-Skript ist vollständig idempotent. Wenn Sie das Skript auf einem bereits angebundenen Server erneut ausführen (z. B. nach einem Server-Neustart oder zur Überprüfung), erkennt das Skript die bestehende NetBird-Peer-Verbindung und führt keine erneute Peer-Registrierung durch.
Automatische Konfigurationsbereinigung & Mandantenwechsel (Re-Enrollment)
Bei Migrationen zwischen verschiedenen ConnectCLOUD-Mandanten oder nach einer vorherigen NetBird-Deinstallation auf dem Windows-Server verbleiben standardmäßig Konfigurationsdateien in %ProgramData%\NetBird. Das Bootstrap-Skript verhindert zuverlässig, dass solche Altdaten wiederverwendet werden:
- Automatische Sicherung bei nicht-aktiver Verbindung: Ist NetBird nicht verbunden oder frisch installiert, verschiebt das Skript alle vorhandenen Konfigurations- und Statusdateien (
config.json,default.json,state.json) automatisch in ein zeitgestempeltes Backup-Verzeichnis (%ProgramData%\NetBird\backup-YYYYMMDD-HHMMSS). Anschließend wird NetBird mit dem neuen Setup-Key sauber initialisiert. - Schutz aktiver Verbindungen: Ist NetBird auf dem Server bereits mit einem fremden NetBird-Konto eingerichtet, richtet das Skript eine isolierte ConnectCLOUD-Instanz ein und lässt die bestehende Verbindung unverändert. Ist die Standardinstanz mit einem anderen ConnectCLOUD-Peer (
microtech-…) verbunden oder wurde-InstanceMode Defaultangegeben, bricht das Skript mit einer Konfliktmeldung ab (peer_mismatch), um unbeabsichtigte Trennungen zu vermeiden. - Erzwungener Mandantenwechsel mit
-ResetNetbirdConfig: Soll der Server bewusst neu zugeordnet werden, kann der Parameter-ResetNetbirdConfigübergeben werden. Er wirkt immer nur auf die verwendete Instanz – in der isolierten Instanz bleibt eine NetBird-Installation des Kunden unberührt. Um die Standardinstanz bewusst zu übernehmen, kombinieren Sie ihn mit-InstanceMode Default:powershellDas Skript trennt die Verbindung, sichert die bisherige Konfiguration in das Backup-Verzeichnis und verbindet NetBird frisch mit dem neuen Mandanten.& { iwr -useb "https://microtech.mbcom.cloud/api/microtech/v1/enrollment/bootstrap.ps1" | iex } -Code "<ENROLLMENT-CODE>" -ResetNetbirdConfig - Strikte Domain-Validierung: Nach jedem Verbindungsaufbau verifiziert das Skript, dass die von NetBird gemeldete Domäne (FQDN) exakt der vom Enrollment-Dienst zugewiesenen Identität entspricht. Bei einer Abweichung bricht das Setup sofort ab, bevor TLS-Zertifikate erstellt oder hochgeladen werden.
Zero-Downtime Zertifikatsrotation (Dual-Trust)
TLS-Zertifikate besitzen eine begrenzte Laufzeit. Vor Ablauf des Zertifikats (< 30 Tage Restlaufzeit) kann ein neues Zertifikat erzeugt werden:
- Bei erneutem Enrollment generiert das Skript ein neues ECDSA-Zertifikat und lädt es als ausstehendes Zertifikat (pending) hoch.
- Dual-Trust-Bundle: ConnectCLOUD vertraut während des Wechsels sowohl dem bisherigen aktiven Zertifikat als auch dem neuen ausstehenden Zertifikat.
- Der laufende API-Verkehr wird zu keinem Zeitpunkt unterbrochen.
- Sie können in aller Ruhe
BpConfig.exeöffnen und das neue Zertifikat hinterlegen. - Nach dem Klick auf „In microtech aktiviert“ im Portal wird das neue Zertifikat zum aktiven Standard und das alte Zertifikat sicher abgelöst.
Fehlerbehebung & Häufige Fragen
NetBird-Dienst verbindet sich nicht
- Prüfen Sie, ob der Windows-Dienst
NetBirdausgeführt wird (Get-Service netbird). - Prüfen Sie in einer administrativen Konsole mit
netbird status, ob der Peer alsConnectedgelistet ist. - Isolierte Instanz: Dienst
NetBird-ConnectCLOUDprüfen (Get-Service NetBird-ConnectCLOUD) und den Status über& "$env:ProgramData\ConnectCLOUD\NetBird\bin\netbird.exe" status --daemon-addr npipe://netbird-connectcloudabfragen. Das Log liegt unter%ProgramData%\ConnectCLOUD\NetBird\client.log. - Stellen Sie sicher, dass ausgehende UDP-Pakete nicht durch lokale Firmenfirewalls blockiert werden.
Fehler beim Verbindungstest nach Aktivierung
- Port: Stimmt der in
BpConfig.exeeingestellte Port mit der Basis-URL überein (Standard:8443)? - Zertifikatsauswahl: Wurde in
BpConfig.exetatsächlich das Zertifikat mit dem im Portal angezeigten Fingerabdruck ausgewählt? - GraphQL-Aktivierung: Ist GraphQL in den Firmenvorgaben des betreffenden Mandanten freigeschaltet und hat der Benutzer die Berechtigung
SupervisorsowieZugriff über GraphQL erlaubt?
Konflikt: NetBird ist bereits mit einer anderen Identität verbunden (peer_mismatch)
- Tritt auf, wenn die NetBird-Standardinstanz mit einem anderen ConnectCLOUD-Peer verbunden ist oder
-InstanceMode Defaulterzwungen wurde. - Im Portal: Die Fehlermeldung auf der Server-Karte nennt den Peer, mit dem der Rechner noch verbunden ist, und bietet „Befehl mit Neukonfiguration erzeugen“ an. Der neue Befehl enthält
-ResetNetbirdConfigund übernimmt die bisherige VPN-Antwort. Nur verwenden, wenn Sie sicher am richtigen Server sind: Ein anderer Server, der diese Verbindung nutzt, verliert dadurch seinen Zugang zu ConnectCLOUD. - Parallelbetrieb: Soll die bestehende Verbindung erhalten bleiben, führen Sie den Befehl mit
-InstanceMode Isolatedaus. - Lösung: Wenn Sie den Server auf den neuen ConnectCLOUD-Mandanten umstellen möchten, führen Sie den Enrollment-Befehl mit dem Parameter
-ResetNetbirdConfigaus:powershellAlternativ können Sie die bestehende Verbindung vorab manuell über& { iwr -useb "https://microtech.mbcom.cloud/api/microtech/v1/enrollment/bootstrap.ps1" | iex } -Code "<ENROLLMENT-CODE>" -ResetNetbirdConfignetbird downtrennen.
Verwandte Dokumentation
- Kunden-Administration: Reiter microtech — Zentrale Server- und Mandantenverwaltung im Portal.
- microtech Basis-Konfiguration — Grundlegende Schnittstelleneinrichtung in microtech büro+.
- microtech Mandantenkonfiguration — Mandantenbezogene Einstellungen im Portal.
Nächster Schritt in der Basiskonfiguration
Nach erfolgreicher Server- und NetBird-Anbindung aktivieren und testen Sie die microtech-Komponente im Portal: microtech Mandantenkonfiguration im Portal
Zurück zur Übersicht: Basiskonfiguration Übersicht