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
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.
151 lines
5.4 KiB
Markdown
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/
|
|
```
|