christianmanivong 5c91af6033
driver / types (push) Successful in 1m3s
driver / standard (push) Successful in 18s
driver / lint (push) Successful in 15s
driver / test (3.12) (push) Successful in 1m5s
driver / test (3.13) (push) Successful in 55s
driver / lowest (push) Successful in 31s
driver / build (push) Successful in 34s
driver / security (push) Successful in 1m3s
driver / publish (push) Successful in 30s
CI / driver (push) Successful in 3m9s
Merge pull request 'feat(firmware): offer the newest release of the line and install it with owut (NetOrk/netork#2615)' (#49) from feature/openwrt-sysupgrade-2615 into main
2026-11-17 12:56:16 +00:00
2026-05-29 09:10:40 +02:00
2026-11-17 12:36:06 +01:00
2026-11-17 12:36:06 +01:00
2026-05-29 09:10:40 +02:00

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)
get_firmware_offer() ✅ napalm-device-types FirmwareOfferMixin: the newest release of the device's own line on the attended sysupgrade server (see Firmware upgrade)

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.

Zabbix agent

configure_zabbix_agent(settings) (napalm-device-types ZabbixAgentMixin) runs the feed's C agent, zabbix-agentd: it loads the package index (it lives in RAM), installs the package where it is missing, writes Server, ServerActive, ListenPort and Hostname into /etc/zabbix_agentd.conf (the old file stays as .bak), enables the agent in UCI (zabbix_agentd.general.enabled, without which the init script does not start it), opens tcp/listen_port for the allowed sources in the zone that owns the management address where a firewall runs, then enables and restarts it. Zabbix publishes no repository for OpenWrt; the feed is the only source.

Firmware upgrade

A package upgrade writes the new package to the overlay while the old one stays in the read-only image, so the overlay only fills. A sysupgrade to the next release of the device's own line brings those packages, and every package installed since, in the new image.

  • get_firmware_offer() reads /etc/openwrt_release and the sysupgrade server the device is set to (attendedsysupgrade.@server[0].url, else https://sysupgrade.openwrt.org), and looks the release line up in the server's /json/v1/overview.json. That file is fetched by the caller, at most once a day per server and process. latest_version is the newest release of the device's line (release candidates only where the line has no release), latest_major_version the newest later line, installable whether owut is installed (left out before 24.10, where owut does not exist). A snapshot, or a target the line does not build, has no offer.
  • start_firmware_upgrade(version) runs owut upgrade --version-to <version> as root, detached from the session, with its output in /tmp/owut-upgrade.log. It refuses while another upgrade runs or owut is missing.
  • get_update_progress() reads that log: running, then done once owut hands the image to sysupgrade (which keeps the configuration and restarts the device), or failed when owut stopped before that.

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.server list; the client is enabled and sysntpd restarts. use_dhcp stays 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 into timezone, the value libc reads -- an IANA name there leaves the router on UTC (NetOrk/netork#1849). /etc/init.d/system reload applies 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/
S
Description
No description provided
Readme
743 KiB
0 Stars 1 Watchers 0 Forks
2026-11-17 13:00:59 +00:00
Languages
Python 100%