Skip to content

DD-WRT Binding ​

This binding monitors and manages DD-WRT, OpenWrt, Tomato, and other Linux-based routers and access points via SSH. It auto-detects the wireless chipset driver (Broadcom wl, Atheros wl_atheros, iwinfo, iw) and adapts its commands accordingly.

Features include:

  • Device telemetry — CPU load, CPU temperature, uptime, WAN IP, interface traffic counters
  • Wireless radio monitoring — SSID, channel, mode, associated client list
  • Client tracking — wireless, wired, and VPN client presence, signal strength, roaming between APs, MAC randomization support
  • Syslog monitoring — real-time DHCP, wireless association, warning, and error events via logread -f or tail -F
  • Firewall rule control — enable/disable DD-WRT GUI-configured filter rules via nvram
  • Device reboot — remote reboot via SSH

Supported Things ​

ThingTypeUIDLabelDescription
networkDD-WRT NetworkBridge representing the network of managed devices
deviceDD-WRT DeviceA DD-WRT, OpenWrt, Tomato, or compatible Linux device managed via SSH
radioWireless RadioA wireless radio interface on a device (e.g. wl0, wlan0)
clientClientA client endpoint on the network (wireless, wired, or VPN)
firewall-ruleFirewall RuleA GUI-configured firewall filter rule from DD-WRT nvram

The binding auto-detects the chipset and firmware variant during the first SSH connection. Tested firmware includes DD-WRT, OpenWrt, FreshTomato, and generic Linux with iw/iwconfig.

Discovery ​

After adding and configuring the network bridge, the binding automatically discovers:

  • Devices — from the hostnames list configured on the bridge
  • Radios — by probing wireless interfaces on each device
  • Clients — from radio association lists, DHCP lease tables, and ARP/neighbor caches on each device
  • Firewall rules — from DD-WRT nvram filter_rule entries (DD-WRT gateway devices only)

For clients without an administrator-assigned hostname, discovery reuses a friendly name published by another openHAB Thing or inbox result when it has the same MAC address. Explicit mappings, /etc/hosts entries, and static DHCP hostnames take precedence; a matching friendly name may replace a dynamic DHCP or reverse-DNS name. If none of these sources has a name, discovery uses the existing OUI-based name or a stable client-<MAC> fallback.

Discovery results appear in the openHAB inbox after each device refresh cycle.

Quick Start ​

  1. Enable SSH on your router (see Firmware SSH Setup below)
  2. Set up SSH key authentication (see SSH Key Setup below)
  3. Test from the openHAB host: ssh root@router should log in without a password prompt
  4. Add the bridge in openHAB with your device hostnames:
dsl
Bridge ddwrt:network:home "Home Network" [ hostnames="router,office-ap,garage-ap" ]
  1. Wait for discovery — devices, radios, clients, and DD-WRT firewall rules appear in the inbox

The hostnames parameter is a comma-separated list of hostnames or IP addresses. Each hostname is connected via SSH and auto-detected during the first refresh cycle. Devices that fail to connect are retried every refresh interval until they come online. You do not need to manually add device things — they are discovered automatically from this list.

SSH Authentication ​

The binding connects to devices using Apache MINA SSHD. Authentication is attempted in this order:

  1. SSH keys from $OPENHAB_USERDATA/ddwrt/keys/ (any files in this directory)
  2. SSH keys from $HOME/.ssh/ (standard OpenSSH key files like id_ed25519, id_rsa)
  3. Password from thing configuration (least secure, not recommended)

On openhabian, $HOME for the openHAB service is /var/lib/openhab, so keys should be placed in /var/lib/openhab/.ssh/.

The binding also respects $HOME/.ssh/config for per-host settings including HostName, User, Port, ProxyJump, and IdentityFile. This means you can use jump hosts (ProxyJump) to reach devices behind NAT.

If no user is configured on the thing, the binding defers to $HOME/.ssh/config or the system username. If no port is configured (port = 0), the binding defers to $HOME/.ssh/config or port 22.

SSH Key Setup ​

SSH key authentication is strongly recommended over password authentication.

1. Generate an SSH key pair (if you don't have one) ​

bash
ssh-keygen -t ed25519 -C "openhab"

This creates $HOME/.ssh/id_ed25519 (private key) and $HOME/.ssh/id_ed25519.pub (public key). The binding automatically loads keys from $HOME/.ssh/.

2. Copy the public key to each device ​

bash
ssh-copy-id root@router
ssh-copy-id root@office-ap

Or manually append the public key to the device's authorized keys file (see firmware-specific instructions below).

3. Verify passwordless login ​

bash
ssh root@router

You should be logged in without a password prompt.

Key directories ​

The binding loads private keys from two directories:

DirectoryDescription
$HOME/.ssh/Standard OpenSSH key directory (recommended)
$OPENHAB_USERDATA/ddwrt/keys/Binding-specific key directory for dedicated keys

Files named id_ed25519, id_rsa, id_ecdsa, or any file not ending in .pub are loaded as private keys. Files named known_hosts, config, authorized_keys, and backup files (~) are skipped.

If openHAB runs as a different user (e.g. openhab), place keys in that user's $HOME/.ssh/ directory or in the $OPENHAB_USERDATA/ddwrt/keys/ directory.

Note: SSH keys are loaded once when the binding starts. If you add or change key files, restart openHAB for the binding to pick them up.

SSH config (optional) ​

You can use $HOME/.ssh/config to set per-host defaults:

text
Host router
    HostName 192.168.1.1
    User root

Host office-ap
    HostName 192.168.1.10
    User root
    Port 2222

Host remote-ap
    HostName 10.0.0.1
    User root
    ProxyJump router

This lets you use short hostnames in the binding configuration and reach devices behind NAT via ProxyJump.

Host Key Verification ​

The binding uses Trust On First Use (TOFU) host key verification with $HOME/.ssh/known_hosts:

  • First connection — the host key is automatically accepted and saved to $HOME/.ssh/known_hosts
  • Subsequent connections — the saved key is verified; if it matches, the connection proceeds
  • Changed key — the connection is rejected and a warning is logged with instructions to fix it

If a device's host key changes (e.g. after a firmware reflash), you will see:

text
WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!
The host key for 192.168.1.1:22 has changed.
Add correct host key in /home/openhab/.ssh/known_hosts to get rid of this message.
Offending key in /home/openhab/.ssh/known_hosts:1

To fix this, remove the old key and restart openHAB so the binding re-reads known_hosts and re-learns the new key on the next connection:

bash
ssh-keygen -R 192.168.1.1

Note: The known_hosts file is read once when the binding starts and cached in memory. Changes to this file (including new keys accepted via TOFU) are written back automatically, but manual edits require an openHAB restart to take effect.

Firmware SSH Setup ​

Each firmware has its own way to enable SSH and install public keys:

  • DD-WRT — Services → Secure Shell → Enable SSHd, paste public key into "Authorized Keys". See DD-WRT SSH documentation.
  • OpenWrt — System → Administration → SSH Access is enabled by default on port 22. Paste public key into System → Administration → SSH-Keys. See OpenWrt Dropbear key-based authentication.
  • FreshTomato — Administration → Admin Access → Enable SSH Daemon, paste public key into "Authorized Keys". See FreshTomato documentation.
  • Standard OpenSSH — For generic Linux devices, use ssh-copy-id or append the public key to $HOME/.ssh/authorized_keys. See OpenSSH manual.

Linux Host SSH Setup ​

Use a dedicated, key-only account instead of root or a shared password when monitoring a general-purpose Linux host. The following example creates an ohmon account with a locked password:

bash
sudo useradd --create-home --shell /bin/bash ohmon
sudo usermod --append --groups adm ohmon
sudo passwd --lock ohmon

On Debian-family systems, the adm group commonly grants access to system logs and the journal. Other distributions may use a different group, such as systemd-journal; grant only the access required by the commands the binding uses.

Install the public key used by the openHAB service:

bash
sudo install -d -m 700 -o ohmon -g ohmon /home/ohmon/.ssh
sudo install -m 600 -o ohmon -g ohmon /path/to/openhab-key.pub /home/ohmon/.ssh/authorized_keys

authorized_keys contains the text from the public .pub key, not the .pub file as an attachment. The corresponding private key stays on the openHAB host in $OPENHAB_USERDATA/ddwrt/keys/ or the openHAB service user's $HOME/.ssh/ directory. Do not copy the private key to the monitored host.

Specify a username for each entry in the network bridge's hostnames list when the devices use different accounts:

text
root@192.168.1.1, ohmon@192.168.1.20, ohmon@192.168.1.21

DD-WRT and OpenWrt appliances commonly continue to use root, while general-purpose Linux hosts should use the dedicated account. Saving the bridge configuration after changing a per-host username also retries any suspended authentication attempts.

The read-only monitoring features do not require general sudo access. If the reboot channel is enabled, the device handler invokes sudo reboot for a non-root session. Permit only the exact reboot executable by creating /etc/sudoers.d/ohmon-ddwrt, for example:

sudoers
ohmon ALL=(root) NOPASSWD: /usr/sbin/reboot

Check the executable path on the monitored host with command -v reboot; it must match the sudoers rule exactly. Set the required permissions and validate the file before relying on it:

bash
sudo chmod 440 /etc/sudoers.d/ohmon-ddwrt
sudo visudo -cf /etc/sudoers.d/ohmon-ddwrt

Verify the account and permissions without rebooting the host:

bash
ssh -o BatchMode=yes ohmon@HOST id
ssh ohmon@HOST journalctl -n 1 --no-pager
ssh ohmon@HOST sudo -n -l /usr/sbin/reboot

Do not grant ohmon unrestricted sudo, and keep password authentication disabled. Radio enable and disable operations on generic Linux may require additional privileges; do not grant them broadly by default.

Thing Configuration ​

network Bridge Configuration ​

NameTypeDescriptionDefaultRequiredAdvanced
hostnamestextComma-separated list of hostnames or IP addresses for device discoveryN/Anono
usertextDefault SSH username for all devices (if omitted, uses SSH config)N/Anono
passwordtextDefault SSH password for all devices (if omitted, uses key auth)N/Anono
portintegerDefault SSH port for all devices (0 = use SSH config or 22)0noyes
refreshIntervalintegerPolling interval in seconds3noyes

device Thing Configuration ​

NameTypeDescriptionDefaultRequiredAdvanced
hostnametextHostname or IP address of the deviceN/Ayesno
usertextSSH username (overrides bridge default; if omitted, uses SSH config)N/Anono
passwordtextSSH password (overrides bridge default)N/Anono
portintegerSSH port (0 = use SSH config or 22)0noyes
refreshIntervalintegerPolling interval in seconds (overrides bridge default)3noyes
syslogPrioritytextMinimum syslog level to capture (debug/info/notice/warning/error/critical)warningnoyes

radio Thing Configuration ​

NameTypeDescriptionDefaultRequiredAdvanced
interfaceIdtextWireless interface identifier (e.g. wl0, wlan0)N/Ayesno
parentDeviceMactextMAC address of the parent deviceN/Anoyes

client Thing Configuration ​

NameTypeDescriptionDefaultRequiredAdvanced
hostnametextHostname of the client (stable identifier with MAC randomization)N/Ayesno
mactextMAC address of the client (may change due to MAC randomization)N/Anoyes

The thing ID is derived from the client's sanitized hostname (e.g. Joes-Phone → joesphone). If the client uses MAC randomization, the binding tracks it by hostname rather than MAC address. When a new randomized MAC appears with the same unique DHCP hostname, the binding merges it with the existing client. If multiple active DHCP leases use the same dynamic hostname, the binding instead uses exact-MAC discovery metadata or an OUI/MAC-based name so that the clients remain distinct.

firewall-rule Thing Configuration ​

NameTypeDescriptionDefaultRequiredAdvanced
ruleIdtextThe nvram filter_rule key (e.g. filter_rule3)N/Ayesno

Channels ​

Network Bridge Channels ​

ChannelTypeRead/WriteDescription
total-clientsNumberROTotal clients connected across all devices
wireless-clientsNumberROWireless clients connected across all devices
wired-clientsNumberROWired clients connected across all devices
wan-ipStringROExternal WAN IP address (gateway devices only)
wan-inNumber:DataAmountROTotal bytes received on WAN (gateway devices only)
wan-outNumber:DataAmountROTotal bytes sent on WAN (gateway devices only)
dhcp-leasesNumberRONumber of active DHCP leases (gateway devices only)
dhcp-remainingNumberROAvailable IP addresses in the DHCP pool (gateway devices only)
last-dhcp-eventStringROLast DHCP lease/renewal/release event

Device Channels ​

ChannelTypeRead/WriteDescription
onlineSwitchROWhether the device is reachable via SSH
uptimeDateTimeROSystem boot time (updates only on reboot)
cpu-loadNumberRO1-minute load average
cpu-tempNumber:TemperatureROCPU temperature
if-inNumber:DataAmountROTotal bytes received on the LAN or primary network interface
if-outNumber:DataAmountROTotal bytes sent on the LAN or primary network interface
rebootSwitchRWTurn ON to reboot the device; automatically resets to OFF
device-wireless-clientsNumberROWireless clients associated with radios on this device
syslog-connectedSwitchROWhether the syslog follower has an active SSH channel
last-warning-eventStringROLast warning-level syslog line
last-error-eventStringROLast error-level syslog line
warning-eventsNumberROWarning event count since startup
error-eventsNumberROError event count since startup
last-wireless-eventStringROLast wireless association/deassociation event

Network Bridge Trigger Channels ​

ChannelKindDescription
dhcp-eventTriggerFires when a DHCP lease/renewal/release is detected

Device Trigger Channels ​

ChannelKindDescription
warning-eventTriggerFires when a warning-level syslog event arrives
error-eventTriggerFires when an error-level syslog event arrives
wireless-eventTriggerFires when a wireless assoc/deassoc is detected

Radio Channels ​

ChannelTypeRead/WriteDescription
enabledSwitchRWWhether the radio is enabled
ssidStringROWireless network name
channelNumberROWireless channel number
modeStringROWireless mode (e.g. Master, Client, Ad-Hoc)
client-countNumberRONumber of clients associated with this radio
assoclistStringROComma-separated MACs of associated clients

Client Channels ​

ChannelTypeRead/WriteDescription
onlineSwitchROWhether the client is currently connected
mac-addressStringROCurrent MAC address of the client
hostnameStringROHostname from DHCP lease
ip-addressStringROIP address from DHCP lease
connection-typeStringROHow the client is connected: wireless, wired, or vpn
apStringROName of the radio the client is associated with
ap-macStringROMAC address of the access point
ssidStringROSSID the client is connected to
channelNumberROWireless channel number
signalNumber:PowerROSignal strength in dBm
snrNumberROSignal-to-noise ratio in dB
rx-rateNumber:DataTransferRateROReceive rate
tx-rateNumber:DataTransferRateROTransmit rate
last-seenDateTimeROTimestamp when the client was last seen online

Firewall Rule Channels ​

ChannelTypeRead/WriteDescription
enabledSwitchRWWhether the firewall rule is on
descriptionStringRODescription of the firewall rule

Properties ​

Device Properties ​

PropertyDescription
macMAC address of the device's primary interface
modelHardware model (from MOTD, DMI, or device-tree)
firmwareFirmware version (DD-WRT build, OpenWrt release, etc.)
chipsetWireless chipset type (broadcom, atheros, marvell, etc.)

Full Example ​

Example Thing Configuration ​

dsl
Bridge ddwrt:network:home "Home Network"  [ hostnames="router,office-ap,garage-ap", user="root", refreshInterval=3 ] {
    Thing device router    "Main Router"  [ hostname="router" ]
    Thing device officeap  "Office AP"    [ hostname="office-ap" ]
    Thing device garageap  "Garage AP"    [ hostname="garage-ap" ]

    Thing radio router_wl0    "Router 2.4GHz"   [ interfaceId="wl0" ]
    Thing radio router_wl1    "Router 5GHz"     [ interfaceId="wl1" ]
    Thing radio officeap_wlan0 "Office 2.4GHz"  [ interfaceId="wlan0" ]
    Thing radio officeap_wlan1 "Office 5GHz"    [ interfaceId="wlan1" ]

    Thing client joesphone     "Joe's Phone"      [ hostname="Joes-Phone", mac="c2:af:b0:aa:9c:ef" ]
    Thing client livingroomtv  "Living Room TV"   [ hostname="LivingRoomTV", mac="b0:8b:a8:7f:99:2c" ]

    Thing firewall-rule bedtime10 "Bedtime 10-12" [ ruleId="filter_rule3" ]
    Thing firewall-rule bedtime12 "Bedtime 12-6"  [ ruleId="filter_rule4" ]
}

Example Item Configuration ​

dsl
// Network bridge
String             WanIp          "WAN IP [%s]"                   { channel="ddwrt:network:home:wan-ip" }
String             LastDhcp       "Last DHCP [%s]"                { channel="ddwrt:network:home:last-dhcp-event" }

// Device telemetry
Switch             RouterOnline   "Router Online [%s]"            { channel="ddwrt:device:home:router:online" }
DateTime           RouterUptime   "Router Uptime [%1$tF %1$tR]"   { channel="ddwrt:device:home:router:uptime" }
Number             RouterCpuLoad  "Router CPU [%.2f]"             { channel="ddwrt:device:home:router:cpu-load" }
Number:Temperature RouterCpuTemp  "Router Temp [%.1f %unit%]"     { channel="ddwrt:device:home:router:cpu-temp" }
Switch             RouterReboot   "Reboot Router"                 { channel="ddwrt:device:home:router:reboot" }

// Syslog events
String             RouterLastWifi "Last Wireless [%s]"            { channel="ddwrt:device:home:router:last-wireless-event" }

// Radio
String             Router24Ssid    "2.4GHz SSID [%s]"             { channel="ddwrt:radio:home:router_wl0:ssid" }
Number             Router24Channel "2.4GHz Channel [%d]"          { channel="ddwrt:radio:home:router_wl0:channel" }
Number             Router24Clients "2.4GHz Clients [%d]"          { channel="ddwrt:radio:home:router_wl0:client-count" }

// Client
Switch             PhoneOnline    "Phone Online [%s]"             { channel="ddwrt:client:home:joesphone:online" }
String             PhoneConnType  "Phone Connection [%s]"         { channel="ddwrt:client:home:joesphone:connection-type" }
String             PhoneAp        "Phone AP [%s]"                 { channel="ddwrt:client:home:joesphone:ap" }
String             PhoneSsid      "Phone SSID [%s]"               { channel="ddwrt:client:home:joesphone:ssid" }
Number             PhoneSnr       "Phone SNR [%d dB]"             { channel="ddwrt:client:home:joesphone:snr" }
DateTime           PhoneLastSeen  "Phone Last Seen [%1$tF %1$tR]" { channel="ddwrt:client:home:joesphone:last-seen" }

// Firewall
Switch             Bedtime10      "Bedtime 10-12 [%s]"            { channel="ddwrt:firewall-rule:home:bedtime10:enabled" }
Switch             Bedtime12      "Bedtime 12-6 [%s]"             { channel="ddwrt:firewall-rule:home:bedtime12:enabled" }

Example Sitemap Configuration ​

dsl
sitemap home label="Home Network" {
    Frame label="Network" {
        Text   item=WanIp
        Text   item=LastDhcp
    }
    Frame label="Router" {
        Switch item=RouterOnline
        Text   item=RouterUptime
        Text   item=RouterCpuLoad
        Text   item=RouterCpuTemp
        Switch item=RouterReboot
    }
    Frame label="Radios" {
        Text item=Router24Ssid
        Text item=Router24Channel
        Text item=Router24Clients
    }
    Frame label="Clients" {
        Switch item=PhoneOnline
        Text   item=PhoneConnType
        Text   item=PhoneAp
        Text   item=PhoneSsid
        Text   item=PhoneSnr
        Text   item=PhoneLastSeen
    }
    Frame label="Parental Controls" {
        Switch item=Bedtime10
        Switch item=Bedtime12
    }
}

Syslog Monitoring ​

The binding follows the device syslog in real time via SSH to detect events without polling. The syslog command is auto-detected:

  • DD-WRT / OpenWrt — logread -f (if BusyBox logread supports -f)
  • Tomato — tail -F /var/log/messages
  • Generic Linux — journalctl -f --no-pager -p <priority>

DHCP and wireless events are parsed inline from the syslog stream and immediately update the cache, so client association and presence changes are reflected within seconds.

The syslogPriority device configuration parameter controls the minimum severity for warning/error event channels. DHCP and wireless events are always captured regardless of this setting.

Presence and ARP/Neighbor Resolution ​

Current client presence uses the following precedence:

  • Wireless clients are considered present while they are associated with an AP, even if they are not currently generating IP traffic. Their connection-type channel reads wireless.
  • Wired clients are inferred from the DHCP lease table and ARP/neighbor cache when they are not present in any wireless radio association list. Their connection-type channel reads wired.
  • Gateway ARP/neighbor data is preferred when a managed gateway is present. The local openHAB host ARP cache is only used as a fallback when no gateway is available.
  • Static hostname mapping files and inline hostnameMappings are treated as static hints only; dynamic neighbor data is authoritative for current IP presence.

Dynamic neighbor entries are classified as active for 60 seconds, stale after 60 seconds, and expired after 120 seconds. Static entries remain static until updated. Dump APs are not queried for ARP because they are Layer-2 bridges and do not have authoritative client IP visibility.

MAC Randomization ​

Modern mobile devices randomize their MAC address per network. The binding handles this by tracking clients primarily by their DHCP hostname. When a device reconnects with a new randomized MAC but the same unique hostname, the binding automatically merges the new MAC with the existing client record. Concurrent leases that share a dynamic hostname remain separate clients and use exact-MAC metadata or OUI/MAC-based discovery names.

If a client has no DHCP hostname (some IoT devices), the binding generates a synthetic hostname from the MAC address OUI vendor prefix (e.g. Espressif-a1b2c3).

Multi-AP Roaming ​

The binding aggregates wireless clients across all managed access points. When a client roams from one AP to another, the syslog follower detects the association/deassociation events and updates the client's ap, ap-mac, and ssid channels in real time.