Files
napalm-openwrt/README.md
T
Christian Manivong 530f04055c feat(firmware): offer the newest release of the line and install it with owut (NetOrk/netork#2615)
get_firmware_offer() looks the device's release line up in the attended
sysupgrade server's overview.json, fetched at most once a day per server.
start_firmware_upgrade() runs owut upgrade detached from the session, and
get_update_progress() follows its log until owut hands the image to sysupgrade.
2026-11-17 11:06:32 +01:00

201 lines
8.5 KiB
Markdown

# 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/<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](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 <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
```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/
```