93e534cef5
Replaces the raw sqlite3 query in get_netalertx_devices() with DeviceInstance().getAll() as suggested in code review, applying the archived/offline/new filters in Python. Removes the sqlite3 and fullDbPath imports. Updates tests to mock DeviceInstance.getAll(). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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:
- Reads all (or only known) devices from the NetAlertX database.
- Fetches the current list of persistent clients from AdGuard Home via its REST API.
- Adds clients that are in NetAlertX but not yet in AdGuard Home.
- Updates clients whose name, identifiers, or device-type tag have changed.
- Optionally deletes clients that have been removed from NetAlertX (see
DELETEsetting).
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
- Copy the
adguard_export/folder into/app/front/plugins/inside your NetAlertX container (or mount it as a volume). - Restart NetAlertX so the plugin is discovered.
- 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:
/app/db/state.ADGUARDEXP.json
Logs
Plugin logs are written to:
/tmp/log/plugins/script.ADGUARDEXP.log
Result rows (used by the NetAlertX UI) are written to:
/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
- Release Date: 10-May-2026