mirror of
https://github.com/jokob-sk/NetAlertX.git
synced 2026-06-21 14:49:59 -04:00
ca7a699ce3
- config.json: add show:true to all visible column definitions so they render in the plugin output table - script.py: fix managed_names adoption bug — update/skip branches no longer add unowned clients to managed state; rename tracking now scoped to plugin-created clients only - README.md: fix ADGUARDEXP_URL default (localhost:3000, not local IP), add language tags to fenced code blocks, normalise metadata block to Other info / Maintainer / DD-Mon-YYYY format - test_adguard_export.py: add regression test for manual client matched by ID not being adopted into managed state Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
141 lines
4.7 KiB
Markdown
141 lines
4.7 KiB
Markdown
# adguard_export — NetAlertX Plugin
|
|
|
|
> **Direction:** NetAlertX → AdGuard Home
|
|
> Syncs known devices from the NetAlertX database to AdGuard Home as **persistent clients**, keeping device names, MAC addresses, and IP identifiers in sync.
|
|
|
|
---
|
|
|
|
## What it does
|
|
|
|
On every run the plugin:
|
|
|
|
1. Reads all (or only *known*) devices from the NetAlertX database.
|
|
2. Fetches the current list of persistent clients from AdGuard Home via its REST API.
|
|
3. **Adds** clients that are in NetAlertX but not yet in AdGuard Home.
|
|
4. **Updates** clients whose name, identifiers, or device-type tag have changed.
|
|
5. Optionally **deletes** clients that have been removed from NetAlertX (see `DELETE` setting).
|
|
|
|
Device types set in NetAlertX (e.g. `Smartphone`, `Laptop`, `NAS`) are automatically mapped to the corresponding AdGuard Home `device_*` tags (e.g. `device_phone`, `device_laptop`, `device_nas`).
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
| Requirement | Notes |
|
|
|---|---|
|
|
| AdGuard Home | v0.107+ (REST API must be enabled) |
|
|
| Python packages | `requests`, `pytz` — already present in the NetAlertX container |
|
|
| AdGuard credentials | A user account with permission to manage clients |
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
1. Copy the `adguard_export/` folder into `/app/front/plugins/` inside your NetAlertX container (or mount it as a volume).
|
|
2. Restart NetAlertX so the plugin is discovered.
|
|
3. Open **Settings → Plugins → AdGuard (Device Export)** and configure the settings below.
|
|
|
|
---
|
|
|
|
## Settings
|
|
|
|
| Setting key | Default | Description |
|
|
|---|---|---|
|
|
| `ADGUARDEXP_RUN` | `disabled` | When to run: `disabled`, `once`, or `schedule` |
|
|
| `ADGUARDEXP_RUN_SCHD` | `0 * * * *` | Cron schedule (default: hourly) |
|
|
| `ADGUARDEXP_URL` | `http://localhost:3000` | Base URL of AdGuard Home web UI |
|
|
| `ADGUARDEXP_USER` | `admin` | AdGuard Home username |
|
|
| `ADGUARDEXP_PASSWORD` | *(empty)* | AdGuard Home password |
|
|
| `ADGUARDEXP_VERIFYSSL` | `true` | Verify TLS cert; set `false` for self-signed certs |
|
|
| `ADGUARDEXP_INCLUDE_OFFLINE` | `true` | When `true`, devices not seen in the last scan are still exported |
|
|
| `ADGUARDEXP_INCLUDE_NEW` | `false` | When `false`, devices flagged as new/unknown are excluded until identified |
|
|
| `ADGUARDEXP_USEMAC` | `true` | Use MAC address as primary client identifier; falls back to IP |
|
|
| `ADGUARDEXP_DELETE` | `false` | ⚠ Delete AdGuard clients no longer present in NetAlertX |
|
|
|
|
---
|
|
|
|
## AdGuard Home client identifiers
|
|
|
|
AdGuard Home identifies a client by one or more **ids**, which can be:
|
|
|
|
- A MAC address (e.g. `aa:bb:cc:dd:ee:ff`)
|
|
- An IP address (e.g. `192.168.1.42`)
|
|
- A CIDR range
|
|
- A ClientID string
|
|
|
|
When `ADGUARDEXP_USEMAC=true`, the plugin prefers the device's MAC address and includes the last known IP as a secondary identifier. When `ADGUARDEXP_USEMAC=false`, only the IP address is used.
|
|
|
|
---
|
|
|
|
## Device type tags
|
|
|
|
The plugin maps NetAlertX device types to valid AdGuard Home `device_*` tags automatically:
|
|
|
|
| NetAlertX type | AdGuard tag |
|
|
|---|---|
|
|
| Smartphone, Phone, Mobile | `device_phone` |
|
|
| Laptop, Notebook | `device_laptop` |
|
|
| Desktop, Server, Hypervisor | `device_pc` |
|
|
| Tablet | `device_tablet` |
|
|
| Smart TV, SmartTV, TV | `device_tv` |
|
|
| NAS | `device_nas` |
|
|
| Printer | `device_printer` |
|
|
| IP Camera, Camera | `device_camera` |
|
|
| Game Console | `device_gameconsole` |
|
|
| Speaker, Assistant, Virtual Assistance | `device_audio` |
|
|
| AP, Gateway, Router, House Appliance | `device_other` |
|
|
|
|
Devices with an unrecognised or empty type are exported without a tag.
|
|
|
|
---
|
|
|
|
## Safe deletion
|
|
|
|
When `ADGUARDEXP_DELETE=true`, the plugin only removes clients it previously created — it will never delete clients you added manually in AdGuard Home. Ownership is tracked in a local state file at:
|
|
|
|
```text
|
|
/app/db/state.ADGUARDEXP.json
|
|
```
|
|
|
|
---
|
|
|
|
## Logs
|
|
|
|
Plugin logs are written to:
|
|
|
|
```text
|
|
/tmp/log/plugins/script.ADGUARDEXP.log
|
|
```
|
|
|
|
Result rows (used by the NetAlertX UI) are written to:
|
|
|
|
```text
|
|
/tmp/log/plugins/last_result.ADGUARDEXP.log
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Likely cause |
|
|
|---|---|
|
|
| `Connection failed` in logs | Wrong `ADGUARDEXP_URL` or AdGuard Home is unreachable from the NetAlertX container |
|
|
| `HTTP error: 401` | Wrong username / password |
|
|
| `HTTP error: 400` | Client already exists with conflicting ids — check AdGuard Home for duplicate entries |
|
|
| Devices not appearing | `ADGUARDEXP_INCLUDE_NEW=false` and devices are flagged as new/unknown; identify them in NetAlertX first |
|
|
| SSL errors | Set `ADGUARDEXP_VERIFYSSL=false` for self-signed certificates |
|
|
|
|
---
|
|
|
|
## Related plugins
|
|
|
|
- **adguard_import** — the reverse direction: imports devices *from* AdGuard Home *into* NetAlertX.
|
|
|
|
---
|
|
|
|
### Other info
|
|
|
|
- Version: 1.0.0
|
|
- Maintainer: [natecj](https://github.com/natecj)
|
|
- Release Date: 10-May-2026
|