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
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.
167 lines
6.3 KiB
Markdown
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/
|
|
```
|