Files
napalm-openwrt/README.md
T
Christian Manivong e4ae42fea0
driver / types (pull_request) Successful in 1m0s
driver / standard (pull_request) Successful in 16s
driver / lint (pull_request) Successful in 15s
driver / test (3.12) (pull_request) Successful in 1m9s
driver / test (3.13) (pull_request) Successful in 1m3s
driver / lowest (pull_request) Successful in 32s
driver / build (pull_request) Successful in 44s
driver / security (pull_request) Successful in 1m19s
CI / driver (pull_request) Successful in 2m56s
driver / publish (pull_request) Skipped
test: documentation names and addresses in fixtures
Fixtures, docstring examples and the README use neutral host names
(ap-01, ap-02) and addresses from the documentation ranges 192.0.2.0/24,
198.51.100.0/24 and 203.0.113.0/24, mapped one to one so every test
keeps its meaning: the management network test still has its address
inside that network, a route still covers its prefix. Loopback, the
wildcard address and netmasks are unchanged.
2026-11-12 19:21:54 +01:00

167 lines
6.3 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) |
## 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.
## 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/
```