236 lines
6.8 KiB
Markdown
236 lines
6.8 KiB
Markdown
# NetBox Client Agent für Windows
|
|
|
|
Der Agent inventarisiert einen Windows-PC automatisch in NetBox und im Plugin [ArnesSI/netbox-inventory](https://github.com/ArnesSI/netbox-inventory). Das Ergebnis ist eine einzelne, selbstenthaltende `agent.exe`; auf dem Client muss kein .NET installiert sein.
|
|
|
|
## Ergebnis in NetBox
|
|
|
|
Nach dem ersten Lauf entstehen beziehungsweise aktualisieren sich:
|
|
|
|
- ein `DCIM > Device` für den Windows-PC,
|
|
- ein damit verknüpftes Inventory-Asset,
|
|
- Interfaces für erkannte Netzwerkadapter,
|
|
- je Interface eine zugewiesene primäre MAC-Adresse,
|
|
- Module und Module Bays für CPU, RAM-Riegel und Datenträger,
|
|
- ein Hardware- und Softwarebericht in den Kommentaren von Device und Asset.
|
|
|
|
Der Agent erkennt den PC anhand seiner BIOS-Seriennummer wieder. Wiederholte Ausführungen aktualisieren deshalb die vorhandenen Objekte. Es werden keine NetBox-Objekte gelöscht.
|
|
|
|
> NetBox 4.2 oder neuer wird empfohlen, da MAC-Adressen seit 4.2 eigenständige Objekte sind. Module sind in NetBox eigentlich für austauschbare Hardwarekomponenten vorgesehen; für PC-Inventarisierung werden CPU, RAM und Datenträger bewusst auf dieses Modell abgebildet.
|
|
|
|
## 1. NetBox vorbereiten
|
|
|
|
Erforderlich:
|
|
|
|
1. `netbox-inventory` ist installiert.
|
|
2. Eine Device Role mit dem Slug `windows-client` existiert.
|
|
3. Die in der Konfiguration genannten Site und Location existieren, sofern sie verwendet werden.
|
|
4. Der API-Token besitzt Lese-, Erstell- und Änderungsrechte für:
|
|
- DCIM Devices, Manufacturers und Device Types
|
|
- DCIM Interfaces und MAC Addresses
|
|
- DCIM Module Types, Module Bays und Modules
|
|
- Inventory Assets des Plugins
|
|
|
|
Site, Location und Device Role legt der Agent absichtlich nicht automatisch an. Hersteller, Device Types und erkannte Hardwaretypen dagegen schon.
|
|
|
|
## 2. Repository herunterladen und EXE bauen
|
|
|
|
PowerShell öffnen und ausführen:
|
|
|
|
```powershell
|
|
git clone https://git.mrblake.cc/MrBlake/Netbox-Client-Agent-for-Windows.git
|
|
Set-Location .\Netbox-Client-Agent-for-Windows
|
|
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass `
|
|
-File .\scripts\build.ps1 `
|
|
-Runtime win-x64
|
|
```
|
|
|
|
Zum Bauen wird das [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) oder neuer benötigt. Die fertige Datei liegt anschließend hier:
|
|
|
|
```text
|
|
dist\win-x64\agent.exe
|
|
```
|
|
|
|
## 3. Konfiguration erstellen
|
|
|
|
```powershell
|
|
Copy-Item .\config.example.json .\dist\win-x64\config.json
|
|
notepad .\dist\win-x64\config.json
|
|
```
|
|
|
|
Minimalbeispiel zum Kopieren:
|
|
|
|
```json
|
|
{
|
|
"netbox_url": "https://netbox.example.local",
|
|
"api_token": "HIER_DEN_NETBOX_TOKEN_EINTRAGEN",
|
|
"region": "emea",
|
|
"site": "berlin",
|
|
"location": "office-1",
|
|
"device_role": "windows-client",
|
|
"verify_tls": true,
|
|
"allow_insecure_tls": false,
|
|
"timeout_seconds": 30,
|
|
"collect_software": true,
|
|
"max_software_entries": 250,
|
|
"create_hardware_modules": true,
|
|
"create_interfaces": true,
|
|
"custom_fields": {}
|
|
}
|
|
```
|
|
|
|
`site` und `location` dürfen vollständig entfernt oder auf `null` gesetzt werden. `region` grenzt die Suche nach der Site ein.
|
|
|
|
### Selbstsigniertes Zertifikat
|
|
|
|
Wenn NetBox ein selbstsigniertes Zertifikat verwendet und Windows der ausstellenden CA nicht vertraut:
|
|
|
|
```json
|
|
"allow_insecure_tls": true
|
|
```
|
|
|
|
Dies ignoriert Zertifikatsketten- und Namensfehler. In produktiven Umgebungen ist es sicherer, die interne CA auf dem Client zu installieren und `allow_insecure_tls` auf `false` zu lassen.
|
|
|
|
### Optionale Funktionen abschalten
|
|
|
|
```json
|
|
"collect_software": false,
|
|
"create_hardware_modules": false,
|
|
"create_interfaces": false
|
|
```
|
|
|
|
`max_software_entries` darf zwischen 0 und 1000 liegen. Erfasst wird maschinenweit installierte klassische Windows-Software aus der 32- und 64-Bit-Registry. Benutzerspezifische Store-/AppX-Pakete sind beim Lauf als SYSTEM nicht zuverlässig verfügbar.
|
|
|
|
Custom Fields werden standardmäßig nicht benötigt. Sollen sie verwendet werden, müssen sie vorher für `DCIM > Device` in NetBox existieren. Unterstützte Zuordnungen sind:
|
|
|
|
```json
|
|
"custom_fields": {
|
|
"agent_version": "netbox_agent_version",
|
|
"windows_version": "windows_version",
|
|
"device_uuid": "device_uuid",
|
|
"last_sync": "agent_last_sync"
|
|
}
|
|
```
|
|
|
|
## 4. Verbindung testen
|
|
|
|
Der Dry-Run liest Hardware und NetBox, schreibt aber absichtlich nichts:
|
|
|
|
```powershell
|
|
.\dist\win-x64\agent.exe `
|
|
--config .\dist\win-x64\config.json `
|
|
--dry-run
|
|
```
|
|
|
|
Erwartete Ausgabe:
|
|
|
|
```text
|
|
Erfasst: CLIENT01, LENOVO 21MW, S/N ABC123
|
|
Dry-Run erfolgreich; keine Änderungen geschrieben.
|
|
```
|
|
|
|
## 5. Erste echte Synchronisation
|
|
|
|
```powershell
|
|
.\dist\win-x64\agent.exe `
|
|
--config .\dist\win-x64\config.json
|
|
```
|
|
|
|
Erwartete Ausgabe:
|
|
|
|
```text
|
|
Synchronisiert: Device #123, Asset #456
|
|
```
|
|
|
|
## 6. Dauerhaft installieren
|
|
|
|
PowerShell **als Administrator** öffnen:
|
|
|
|
```powershell
|
|
Set-Location C:\Pfad\zum\Netbox-Client-Agent-for-Windows
|
|
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass `
|
|
-File .\scripts\install.ps1 `
|
|
-SourceDirectory .\dist\win-x64
|
|
```
|
|
|
|
Das Skript:
|
|
|
|
- kopiert EXE und Konfiguration nach `C:\Program Files\NetBox Windows Agent`,
|
|
- erlaubt nur SYSTEM und lokalen Administratoren den Zugriff auf den API-Token,
|
|
- erstellt die tägliche geplante Aufgabe `NetBox Windows Agent`,
|
|
- startet sofort die erste Synchronisation.
|
|
|
|
Deinstallation, ebenfalls als Administrator:
|
|
|
|
```powershell
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass `
|
|
-File .\scripts\uninstall.ps1
|
|
```
|
|
|
|
## Intune-Verteilung
|
|
|
|
Diese vier Dateien gemeinsam als Win32-App (`.intunewin`) paketieren:
|
|
|
|
```text
|
|
agent.exe
|
|
config.json
|
|
install.ps1
|
|
uninstall.ps1
|
|
```
|
|
|
|
Copy-&-Paste-Werte für Intune:
|
|
|
|
```text
|
|
Installationsbefehl:
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -SourceDirectory .
|
|
|
|
Deinstallationsbefehl:
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\uninstall.ps1
|
|
|
|
Installationsverhalten:
|
|
System
|
|
|
|
Erkennungsregel:
|
|
Datei C:\Program Files\NetBox Windows Agent\agent.exe vorhanden
|
|
```
|
|
|
|
## Fehlerbehebung
|
|
|
|
### `agent.exe fehlt im Quellverzeichnis`
|
|
|
|
Als `SourceDirectory` muss der Ordner angegeben werden, in dem sowohl `agent.exe` als auch `config.json` liegen:
|
|
|
|
```powershell
|
|
-SourceDirectory .\dist\win-x64
|
|
```
|
|
|
|
### `RemoteCertificateNameMismatch` oder `RemoteCertificateChainErrors`
|
|
|
|
Zum Testen `allow_insecure_tls` auf `true` setzen. Dauerhaft besser die korrekte interne CA installieren und einen zur URL passenden Zertifikatsnamen verwenden.
|
|
|
|
### Custom Field ist nicht vorhanden
|
|
|
|
Wenn keine eigenen NetBox Custom Fields angelegt wurden:
|
|
|
|
```json
|
|
"custom_fields": {}
|
|
```
|
|
|
|
### `403 Forbidden`
|
|
|
|
Dem Benutzer des API-Tokens fehlen Rechte für den im Fehler genannten Objekttyp.
|
|
|
|
### `400 Bad Request`
|
|
|
|
Die vollständige Antwort hinter `FEHLER:` enthält das von NetBox beanstandete Feld. Häufig fehlen die konfigurierte Device Role, Site oder Location.
|
|
|
|
## Entwicklung
|
|
|
|
```powershell
|
|
dotnet build
|
|
.\scripts\build.ps1 -Runtime win-x64
|
|
```
|
|
|
|
GitHub Actions baut automatisch x64- und ARM64-Artefakte. `config.json`, `dist`, `bin`, `obj` und lokale Build-Werkzeuge werden nicht committed.
|