Skip to content

Commit ae089f5

Browse files
jokob-skjokob-sk
authored
Merge pull request #1592 from sebingel/fritzbox-plugin
feat(plugins): Add Fritz!Box device scanner plugin via TR-064 protocol
2 parents ae2dc92 + 4b6203a commit ae089f5

8 files changed

Lines changed: 3701 additions & 0 deletions

File tree

‎docs/PLUGINS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ Device-detecting plugins insert values into the `CurrentScan` database table. T
5757
| `DHCPSRVS` | [dhcp_servers](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/dhcp_servers/) | ♻ | DHCP servers | | |
5858
| `DIGSCAN` | [dig_scan](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/dig_scan/) | 🆎 | Dig (DNS) Name resolution | | |
5959
| `FREEBOX` | [freebox](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/freebox/) | 🔍/♻/🆎 | Pull data and names from Freebox/Iliadbox | | |
60+
| `FRITZBOX` | [fritzbox](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/fritzbox/) | 🔍 | Fritz!Box device scanner via TR-064 | | |
6061
| `ICMP` | [icmp_scan](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/icmp_scan/) | ♻ | ICMP (ping) status checker | | |
6162
| `INTRNT` | [internet_ip](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/internet_ip/) | 🔍 | Internet IP scanner | | |
6263
| `INTRSPD` | [internet_speedtest](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/internet_speedtest/) | ♻ | Internet speed test | | |

‎front/plugins/fritzbox/README.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
## Overview
2+
3+
The Fritz!Box plugin queries connected devices from a Fritz!Box router using the **TR-064** protocol (Technical Report 064), a standardized interface for managing DSL routers and home network devices. This plugin discovers all network-connected devices and reports their MAC addresses, IP addresses, hostnames, and connection types to NetAlertX.
4+
5+
TR-064 is a UPnP-based protocol that provides programmatic access to Fritz!Box configuration and status information. Unlike web scraping, it offers a stable, documented API that works across Fritz!Box models.
6+
7+
### Features
8+
9+
- **Device Discovery**: Automatically detects all connected devices (WiFi 2.4GHz, WiFi 5GHz, Ethernet)
10+
- **Real-time Status**: Reports active connection status for each device
11+
- **Guest WiFi Monitoring**: Optional synthetic Access Point device to track guest network status
12+
- **Flexible Filtering**: Choose to report only active devices or include disconnected devices in Fritz!Box memory
13+
- **Secure Connection**: Supports both HTTP and HTTPS with configurable SSL verification
14+
15+
> [!TIP]
16+
> TR-064 is typically enabled by default on Fritz!Box routers. If you encounter connection issues, check that it hasn't been disabled in your Fritz!Box settings under **Home Network > Network > Network Settings > Allow access for applications**.
17+
18+
### Quick Setup Guide
19+
20+
To set up the plugin correctly:
21+
22+
1. **Enable TR-064 on Fritz!Box** (usually already enabled):
23+
- Log in to your Fritz!Box web interface (typically `fritz.box` or `192.168.178.1`)
24+
- Navigate to: **Home Network > Network > Network Settings**
25+
- Ensure **"Allow access for applications"** is checked
26+
- Note: Some models show this as **"Allow remote access"** - enable both HTTP and HTTPS
27+
28+
2. **Configure Plugin in NetAlertX**:
29+
- Head to **Settings** > **Fritz!Box Plugin**
30+
- Set the required settings (see below)
31+
- Choose run mode: **schedule** (recommended, runs every 5 minutes)
32+
33+
#### Required Settings
34+
35+
- **Fritz!Box Host** (`FRITZBOX_HOST`): Hostname or IP address of your Fritz!Box
36+
- Default: `fritz.box`
37+
- Alternative: `192.168.178.1` (or your Fritz!Box's IP)
38+
39+
- **TR-064 Port** (`FRITZBOX_PORT`): Port for TR-064 protocol
40+
- Default: `49443` (HTTPS). Use `49000` if HTTPS is disabled
41+
42+
- **Username** (`FRITZBOX_USER`): Fritz!Box username
43+
- Can be empty for some models when accessing from local network
44+
- For newer models, use an admin username
45+
46+
- **Password** (`FRITZBOX_PASS`): Fritz!Box password
47+
- Required: Your Fritz!Box admin password
48+
49+
#### Optional Settings
50+
51+
- **Use HTTPS** (`FRITZBOX_USE_TLS`): Enable secure HTTPS connection (default: `true`)
52+
- Recommended for security
53+
- Requires port `49443` instead of `49000`
54+
55+
- **Report Guest WiFi** (`FRITZBOX_REPORT_GUEST`): Create Access Point device for guest WiFi (default: `false`)
56+
- When enabled, adds a synthetic "Guest WiFi Network" device to your device list
57+
- Device appears only when guest WiFi is active
58+
- Useful for monitoring guest network status
59+
60+
- **Guest WiFi Service** (`FRITZBOX_GUEST_SERVICE`): Which WLANConfiguration service is the guest network (default: `3`)
61+
- Fritz!Box typically uses `1` for 2.4GHz, `2` for 5GHz, `3` for guest WiFi
62+
- Only relevant when **Report Guest WiFi** is enabled
63+
- Change this if your Fritz!Box uses a non-standard configuration
64+
65+
- **Active Devices Only** (`FRITZBOX_ACTIVE_ONLY`): Report only connected devices (default: `true`)
66+
- When enabled, only currently connected devices appear
67+
- When disabled, includes all devices stored in Fritz!Box memory (even if disconnected)
68+
69+
### Usage
70+
71+
1. Head to **Settings** > **Fritz!Box** to configure the plugin
72+
2. Set **When to run** to **schedule** (recommended) or **once** for manual testing
73+
3. The plugin will run every 5 minutes by default (configurable via **Schedule** setting)
74+
4. View discovered devices in the **Devices** page
75+
5. Check logs at `/tmp/log/plugins/script.FRITZBOX.log` for troubleshooting
76+
77+
### Device Information Reported
78+
79+
The plugin reports the following information for each device:
80+
81+
| Field | Description | Mapped To |
82+
|-------|-------------|-----------|
83+
| **MAC Address** | Device hardware address (normalized format) | `devMac` |
84+
| **IP Address** | Current IPv4 address | `devLastIP` |
85+
| **Hostname** | Device name from Fritz!Box | `devName` |
86+
| **Connection Status** | "Active" or "Inactive" | Plugin table only (not mapped to device fields) |
87+
| **Interface Type** | WiFi / LAN / Guest Network | `devType` |
88+
89+
### Guest WiFi Feature
90+
91+
When **Report Guest WiFi** is enabled and guest WiFi is active on your Fritz!Box:
92+
93+
- A synthetic device named **"Guest WiFi Network"** appears in your device list
94+
- Device Type: **Access Point**
95+
- MAC Address: Locally-administered synthetic MAC derived from Fritz!Box MAC (e.g., `02:a1:b2:c3:d4:e5`)
96+
- Status: Only appears when guest WiFi is enabled
97+
98+
This allows you to:
99+
- Monitor when guest WiFi is active
100+
- Set up notifications when guest network is enabled/disabled
101+
- Track guest network status alongside other network devices
102+
103+
> [!NOTE]
104+
> The guest WiFi device is synthetic (not a real physical device). It's created by the plugin to represent the guest network state.
105+
106+
### Troubleshooting
107+
108+
#### Connection Refused / Timeout Errors
109+
110+
**Symptoms**: Plugin logs show "Failed to connect to Fritz!Box" or timeout errors
111+
112+
**Solutions**:
113+
1. Verify Fritz!Box is reachable:
114+
```bash
115+
ping fritz.box
116+
# or
117+
ping 192.168.178.1
118+
```
119+
120+
2. Check TR-064 is enabled:
121+
- Fritz!Box web interface > **Home Network > Network > Network Settings**
122+
- Enable **"Allow access for applications"**
123+
124+
3. Verify correct port:
125+
- HTTP: Port `49000`
126+
- HTTPS: Port `49443`
127+
- Match **Use HTTPS** setting with port
128+
129+
4. Check firewall rules (if NetAlertX runs in Docker):
130+
- Ensure container can reach Fritz!Box network
131+
- Use host IP instead of `fritz.box` if DNS resolution fails
132+
133+
#### Authentication Failed
134+
135+
**Symptoms**: "Authentication error" or "Invalid credentials"
136+
137+
**Solutions**:
138+
1. Verify password is correct
139+
2. Try leaving **Username** empty (some models allow this from local network)
140+
3. Create a dedicated user in Fritz!Box:
141+
- **System > Fritz!Box Users > Add User**
142+
- Grant network access permissions
143+
4. For newer Fritz!OS versions, ensure user has **"Access from home network"** permission
144+
145+
#### No Devices Found
146+
147+
**Symptoms**: Plugin runs successfully but reports 0 devices
148+
149+
**Solutions**:
150+
1. Check **Active Devices Only** setting:
151+
- If enabled, only connected devices appear
152+
- Disable to see all devices in Fritz!Box memory
153+
2. Verify devices are actually connected to Fritz!Box
154+
3. Check Fritz!Box web interface > **Home Network > Mesh** to see devices
155+
4. Increase log level to `verbose` and check `/tmp/log/plugins/script.FRITZBOX.log`
156+
157+
#### Guest WiFi Not Detected
158+
159+
**Symptoms**: Guest WiFi enabled but no Access Point device appears
160+
161+
**Solutions**:
162+
1. Ensure **Report Guest WiFi** is enabled
163+
2. Guest WiFi must be **active** (not just configured)
164+
3. Some Fritz!Box models don't expose guest network via TR-064
165+
4. Check plugin logs for "Guest WiFi active" message
166+
167+
### Limitations
168+
169+
- **Active-only filtering**: When `FRITZBOX_ACTIVE_ONLY` is enabled, the plugin only reports currently connected devices. Disconnected devices stored in Fritz!Box memory are ignored.
170+
171+
- **Guest WiFi synthetic device**: The guest WiFi Access Point is a synthetic device created by the plugin. Its MAC address is derived from the Fritz!Box MAC and doesn't represent a physical device.
172+
173+
- **Model differences**: Some Fritz!Box models may not expose all TR-064 services (e.g., guest WiFi detection). The plugin degrades gracefully if services are unavailable.
174+
175+
- **IPv6 support**: Currently reports IPv4 addresses only. IPv6 support may be added in future versions.
176+
177+
- **Device type detection**: Interface type (WiFi/LAN) is reported, but detailed device categorization (smartphone, laptop, etc.) is handled by NetAlertX's device type detection, not this plugin.
178+
179+
### Technical Details
180+
181+
**Protocol**: TR-064 (Technical Report 064) - UPnP-based device management protocol
182+
183+
**Library**: [fritzconnection](https://github.com/kbr/fritzconnection) >= 1.15.1
184+
185+
**Services Used**:
186+
- `FritzHosts`: Device discovery and information
187+
- `WLANConfiguration`: Guest WiFi status detection
188+
- `DeviceInfo`: Fritz!Box MAC address retrieval
189+
190+
**Execution Schedule**: Default every 5 minutes (configurable via cron syntax)
191+
192+
**Timeout**: 60 seconds (configurable via `RUN_TIMEOUT`)
193+
194+
### Notes
195+
196+
- **Performance**: TR-064 queries typically complete in under 2 seconds, even with many devices
197+
- **Security**: Passwords are stored in NetAlertX's configuration database and not logged
198+
- **Compatibility**: Tested with Fritz!Box models running Fritz!OS 7.x and 8.x
199+
- **Dependencies**: Requires `fritzconnection` Python library (automatically installed via requirements.txt)
200+
201+
### Version
202+
203+
- **Version**: 1.0.0
204+
- **Author**: [@sebingel](https://github.com/sebingel)
205+
- **Release Date**: April 2026
206+
207+
### Support
208+
209+
For issues, questions, or feature requests:
210+
- NetAlertX GitHub: [https://github.com/netalertx/NetAlertX](https://github.com/netalertx/NetAlertX)
211+
- Fritz!Box TR-064 Documentation: [https://avm.de/service/schnittstellen/](https://avm.de/service/schnittstellen/)

0 commit comments

Comments
 (0)