# napalm-openwrt NAPALM community driver for **OpenWrt** routers and access-points. Communicates over SSH using [Netmiko](https://pypi.org/project/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: ```bash git clone https://git.netork.io/NAPALM/napalm-openwrt cd napalm-openwrt pip install -e . ``` ## Quick start ```python 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/`, 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](https://openwrt.org/docs/guide-user/base-system/uci) (Unified Configuration Interface). ### Merge candidate ```python 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 ```python with open("full-config.uci") as f: device.load_replace_candidate(config=f.read()) print(device.compare_config()) device.commit_config() ``` ### Rollback ```python # 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 ` 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 ```bash # 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/ ```