Skip to content

Commit 8f1da10

Browse files
jokob-skjokob-sk
authored
Merge pull request #1649 from natecj/feat/adguard-export-plugin
feat: add adguard_export plugin
2 parents 6845104 + 727fe0e commit 8f1da10

5 files changed

Lines changed: 1555 additions & 2 deletions

File tree

‎front/plugins/adguard_export/README.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# adguard_export — NetAlertX Plugin
2+
3+
> **Direction:** NetAlertX → AdGuard Home
4+
> Syncs known devices from the NetAlertX database to AdGuard Home as **persistent clients**, keeping device names, MAC addresses, and IP identifiers in sync.
5+
6+
---
7+
8+
## What it does
9+
10+
On every run the plugin:
11+
12+
1. Reads all (or only *known*) devices from the NetAlertX database.
13+
2. Fetches the current list of persistent clients from AdGuard Home via its REST API.
14+
3. **Adds** clients that are in NetAlertX but not yet in AdGuard Home.
15+
4. **Updates** clients whose name, identifiers, or device-type tag have changed.
16+
5. Optionally **deletes** clients that have been removed from NetAlertX (see `DELETE` setting).
17+
18+
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`).
19+
20+
---
21+
22+
## Requirements
23+
24+
| Requirement | Notes |
25+
|---|---|
26+
| AdGuard Home | v0.107+ (REST API must be enabled) |
27+
| Python packages | `requests`, `pytz` — already present in the NetAlertX container |
28+
| AdGuard credentials | A user account with permission to manage clients |
29+
30+
---
31+
32+
## Installation
33+
34+
1. Copy the `adguard_export/` folder into `/app/front/plugins/` inside your NetAlertX container (or mount it as a volume).
35+
2. Restart NetAlertX so the plugin is discovered.
36+
3. Open **Settings → Plugins → AdGuard (Device Export)** and configure the settings below.
37+
38+
---
39+
40+
## Settings
41+
42+
| Setting key | Default | Description |
43+
|---|---|---|
44+
| `ADGUARDEXP_RUN` | `disabled` | When to run: `disabled`, `once`, or `schedule` |
45+
| `ADGUARDEXP_RUN_SCHD` | `0 * * * *` | Cron schedule (default: hourly) |
46+
| `ADGUARDEXP_URL` | `http://localhost:3000` | Base URL of AdGuard Home web UI |
47+
| `ADGUARDEXP_USER` | `admin` | AdGuard Home username |
48+
| `ADGUARDEXP_PASSWORD` | *(empty)* | AdGuard Home password |
49+
| `ADGUARDEXP_VERIFYSSL` | `true` | Verify TLS cert; set `false` for self-signed certs |
50+
| `ADGUARDEXP_INCLUDE_OFFLINE` | `true` | When `true`, devices not seen in the last scan are still exported |
51+
| `ADGUARDEXP_INCLUDE_NEW` | `false` | When `false`, devices flagged as new/unknown are excluded until identified |
52+
| `ADGUARDEXP_USEMAC` | `true` | Use MAC address as primary client identifier; falls back to IP |
53+
| `ADGUARDEXP_DELETE` | `false` | ⚠ Delete AdGuard clients no longer present in NetAlertX |
54+
55+
---
56+
57+
## AdGuard Home client identifiers
58+
59+
AdGuard Home identifies a client by one or more **ids**, which can be:
60+
61+
- A MAC address (e.g. `aa:bb:cc:dd:ee:ff`)
62+
- An IP address (e.g. `192.168.1.42`)
63+
- A CIDR range
64+
- A ClientID string
65+
66+
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.
67+
68+
---
69+
70+
## Device type tags
71+
72+
The plugin maps NetAlertX device types to valid AdGuard Home `device_*` tags automatically:
73+
74+
| NetAlertX type | AdGuard tag |
75+
|---|---|
76+
| Smartphone, Phone, Mobile | `device_phone` |
77+
| Laptop, Notebook | `device_laptop` |
78+
| Desktop, Server, Hypervisor | `device_pc` |
79+
| Tablet | `device_tablet` |
80+
| Smart TV, SmartTV, TV | `device_tv` |
81+
| NAS | `device_nas` |
82+
| Printer | `device_printer` |
83+
| IP Camera, Camera | `device_camera` |
84+
| Game Console | `device_gameconsole` |
85+
| Speaker, Assistant, Virtual Assistance | `device_audio` |
86+
| AP, Gateway, Router, House Appliance | `device_other` |
87+
88+
Devices with an unrecognised or empty type are exported without a tag.
89+
90+
---
91+
92+
## Safe deletion
93+
94+
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:
95+
96+
```text
97+
/app/db/state.ADGUARDEXP.json
98+
```
99+
100+
---
101+
102+
## Logs
103+
104+
Plugin logs are written to:
105+
106+
```text
107+
/tmp/log/plugins/script.ADGUARDEXP.log
108+
```
109+
110+
Result rows (used by the NetAlertX UI) are written to:
111+
112+
```text
113+
/tmp/log/plugins/last_result.ADGUARDEXP.log
114+
```
115+
116+
---
117+
118+
## Troubleshooting
119+
120+
| Symptom | Likely cause |
121+
|---|---|
122+
| `Connection failed` in logs | Wrong `ADGUARDEXP_URL` or AdGuard Home is unreachable from the NetAlertX container |
123+
| `HTTP error: 401` | Wrong username / password |
124+
| `HTTP error: 400` | Client already exists with conflicting ids — check AdGuard Home for duplicate entries |
125+
| Devices not appearing | `ADGUARDEXP_INCLUDE_NEW=false` and devices are flagged as new/unknown; identify them in NetAlertX first |
126+
| SSL errors | Set `ADGUARDEXP_VERIFYSSL=false` for self-signed certificates |
127+
128+
---
129+
130+
## Related plugins
131+
132+
- **adguard_import** — the reverse direction: imports devices *from* AdGuard Home *into* NetAlertX.
133+
134+
---
135+
136+
### Other info
137+
138+
- Version: 1.0.0
139+
- Maintainer: [natecj](https://github.com/natecj)
140+
- Release Date: 10-May-2026

0 commit comments

Comments
 (0)