After a reboot apk and opkg have no package index. get_available_updates() raised a bare RuntimeError for that, which netOrk could not tell from a read that failed. It now raises napalm-device-types' PackageIndexMissing, so netOrk loads the index instead of reporting a communication error. Needs napalm-device-types 4.39.0. Refs NetOrk/netork#2527
napalm-openwrt
NAPALM community driver for OpenWrt routers and access-points.
Communicates over SSH using Netmiko (linux device type).
Requires OpenWrt 19.07 or newer.
Tested devices
| Model | OpenWrt version | Tested |
|---|---|---|
| TP-Link TL-WR1043N/ND v5 | 23.05.3 | ✅ |
Contributions for additional devices and firmware versions are welcome.
Requirements
| Dependency | Minimum version |
|---|---|
| Python | 3.12 |
| NAPALM | 4.0 |
| Netmiko | 4.0 |
Installation
From source:
git clone https://git.netork.io/NAPALM/napalm-openwrt
cd napalm-openwrt
pip install -e .
Quick start
from napalm import get_network_driver
driver = get_network_driver("openwrt")
device = driver("192.0.2.1", "root", "")
device.open()
facts = device.get_facts()
print(facts)
interfaces = device.get_interfaces()
print(interfaces)
device.close()
Supported NAPALM getters
| Getter | Supported | Notes |
|---|---|---|
get_facts |
✅ | Uses /etc/openwrt_release, /tmp/sysinfo/model, /proc/uptime |
get_interfaces |
✅ | Uses ip link show |
get_interfaces_ip |
✅ | Uses ip addr show |
get_interfaces_counters |
✅ | Uses /proc/net/dev |
get_arp_table |
✅ | Uses ip neigh show |
get_mac_address_table |
✅ | Uses bridge fdb show |
get_config |
✅ | Uses uci export |
get_environment |
✅ | CPU from /proc/stat, memory from /proc/meminfo; raises when either cannot be read |
get_lldp_neighbors |
✅ | Requires lldpd installed and running (raises otherwise); reads only, never starts or configures it |
get_lldp_neighbors_detail |
✅ | Requires lldpd installed and running (raises otherwise); reads only, never starts or configures it |
get_listening_sockets |
✅ | busybox netstat -lntup, procd service from the process's cgroup (napalm-device-types ListeningSocketsMixin); over an SSH exec channel |
get_host_status |
✅ | napalm-device-types HostStatusMixin: whether the router needs a reboot, how full / (the overlay) is, and whether apk or opkg was left halfway (apk: a package with broken files or a broken script; opkg: one left unpacked; needs napalm-device-types 4.32); over an SSH exec channel |
get_scheduled_jobs() |
✅ | BusyBox crond's /etc/crontabs/<user>, time zone from system.@system[0].zonename, owner from opkg search (napalm-device-types PosixScheduledJobsMixin) |
manage_scheduled_job(key, action, digest=) |
✅ | enable, disable, run now (bounded by timeout where the router has it; another user's job through start-stop-daemon -c) |
put_scheduled_job(spec) / delete_scheduled_job(key, digest=) |
✅ | an application's own job: two marked lines in the user's crontab; @daily and the other aliases as five fields, @reboot refused (BusyBox crond has no special times) |
get_ntp_servers / get_ntp_peers |
✅ | system.ntp.server in UCI, every server of the list; none while system.ntp.enabled is off -- the same list as get_time_sync() |
get_time_sync() |
✅ | napalm-device-types TimeSyncMixin: the servers as above, the zone from zonename where the rule in timezone is that zone's (else the one zone with that rule, or none); synchronized is not readable (None) |
Configuration management
Configuration is managed via UCI (Unified Configuration Interface).
Merge candidate
device.load_merge_candidate(
config="""
uci set system.@system[0].hostname='my-router'
uci set network.lan.ipaddr='192.0.2.1'
"""
)
print(device.compare_config())
device.commit_config()
Replace candidate
with open("full-config.uci") as f:
device.load_replace_candidate(config=f.read())
print(device.compare_config())
device.commit_config()
Rollback
# Reverts to the config state before the last commit_config call
device.rollback()
LLDP agent
configure_lldp_agent(interfaces) (napalm-device-types LldpAgentMixin) installs
lldpd where it is missing, sets its interface list (lldpd.config.interface in UCI)
to the interfaces given, enables it at boot and restarts it. A VLAN device such as
br-ap.10 is written as the device under it (br-ap): lldpd sends on the L2 device.
Which interfaces is the caller's choice; at least one is required.
Wireless writes
push_mac_acl(ssid_name, mode, macs) (napalm-device-types MacAclMixin) rewrites the
MAC filter of every wifi-iface carrying the SSID and reloads wifi;
push_radio_channel(radio, channel) sets a radio's channel (0 is auto) and restarts
wifi in full. Each uci step runs on an SSH exec channel of its own, as root, with its
exit status checked: a refused step raises CommandErrorException naming it, what was
staged is reverted, and nothing is committed or restarted. An SSID no wifi-iface
carries raises too.
Time sync
configure_time_sync(ntp_servers=, timezone=) (napalm-device-types TimeSyncMixin)
writes both values into UCI's system config and applies them; a value the router
already has is not written again, so nothing restarts.
- The servers replace the
system.ntp.serverlist; the client is enabled andsysntpdrestarts.use_dhcpstays as the router has it: the NTP servers of a DHCP lease (option 42) count (NetOrk/netork#2380).
get_time_sync() reads the configured servers and the zone from uci -q show system,
and in the same round trip the servers a lease brought, as dhcp_ntp_servers: what
sysntpd adds to ntpd's list while use_dhcp is on -- every interface's data.ntpserver
in ubus call network.interface dump, or only the dhcp_interface list's. [] while
use_dhcp or the client is off; None where netifd gave no answer.
- The zone goes into
zonename(as LuCI keeps it, with spaces for underscores) and its POSIX rule intotimezone, the value libc reads -- an IANA name there leaves the router on UTC (NetOrk/netork#1849)./etc/init.d/system reloadapplies it, and logd restarts, as it reads the zone when it starts.
Writes run as root: OpenWrt has no sudo, so another login is refused before anything runs.
Development
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Lint
ruff check napalm_openwrt/