Files
napalm-openwrt/README.md
T
Christian Manivong 7bb15f5af3
driver / standard (pull_request) Successful in 15s
driver / lint (pull_request) Successful in 14s
driver / types (pull_request) Successful in 53s
driver / test (3.12) (pull_request) Successful in 58s
driver / test (3.13) (pull_request) Successful in 56s
driver / lowest (pull_request) Successful in 27s
driver / build (pull_request) Successful in 29s
driver / security (pull_request) Successful in 58s
CI / driver (pull_request) Successful in 2m26s
driver / publish (pull_request) Skipped
feat(time-sync): NTP servers and time zone through TimeSyncMixin
netOrk aligns every device's time sources and zone through the driver
(NetOrk/netork#2360); for APs that replaces the UCI commands netOrk
built itself for the AP profile fields (NetOrk/netork#2364).

Both values live in UCI's system config:
- The servers are system.ntp.server. A write replaces the list, enables
  the client, sets use_dhcp=0 so the servers of a DHCP lease are not
  added, and restarts sysntpd: the router ends up with exactly these.
  A disabled client reads as no servers.
- The zone is zonename (the IANA name, in LuCI's spelling with spaces)
  and timezone, the POSIX rule from posix_tz that libc reads as TZ. The
  rule is what counts (NetOrk/netork#1849), so the name is read as the
  zone only where the rule in force is that zone's; a rule alone reads
  as the one zone that has it, or None where several share it. A write
  sets both, reloads /etc/init.d/system and restarts logd, which reads
  the zone at start.

netOrk aligns on every poll, so each step compares first and writes
and restarts nothing when the router already has the values. GMT0 (the
stock rule) counts as UTC's time.

get_ntp_servers now uses the same reading, so it agrees with
get_time_sync; it used to keep only the first server of a list, as uci
prints a list as 'a' 'b' on one line. synchronized is None: BusyBox
ntpd keeps no state to read.

The floor on napalm-device-types is 4.35.0, the first with
TimeSyncMixin.
2026-11-11 15:22:54 +01:00

151 lines
5.4 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.168.1.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='10.0.0.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.
## 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, the servers
of a DHCP lease are turned off (`use_dhcp=0`) so the router has exactly these, and
`sysntpd` restarts.
* 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/
```