Files
napalm-openwrt/README.md
T
Christian Manivong eeeb46121f
driver / lint (pull_request) Successful in 14s
driver / standard (pull_request) Successful in 16s
driver / types (pull_request) Failing after 26s
driver / test (3.13) (pull_request) Failing after 15s
driver / test (3.12) (pull_request) Failing after 17s
driver / lowest (pull_request) Failing after 16s
driver / build (pull_request) Successful in 28s
driver / security (pull_request) Failing after 35s
CI / driver (pull_request) Failing after 1m6s
driver / publish (pull_request) Skipped
feat(scheduled-jobs): scheduled jobs through PosixScheduledJobsMixin (#32)
get_scheduled_jobs reads every crontab in /etc/crontabs in one round trip
as root, with the time zone from UCI and each crontab's package from opkg;
manage_scheduled_job enables, disables or runs one now; put_ and
delete_scheduled_job write and remove an application's own job as marked
lines in the user's crontab. BusyBox crond has no /etc/crontab, cron.d,
run-parts, anacron or systemd, so none is read.

OpenWrt's BusyBox differs from what the POSIX mixin assumes, so a few
steps are the driver's own:
- crontab -l says only "can't open" for a missing crontab, as for an
  unreadable one: the file is read directly, a missing one is empty, and
  one that cannot be read is never written.
- crontab FILE exits 0 when it could not write: every write is read back.
- cron is enabled and restarted after each write; OpenWrt does not start
  crond while /etc/crontabs is empty.
- crond has no special times: aliases are written as five fields and
  @reboot is refused.
- crond hands the whole command to sh and takes only SHELL and PATH from
  the crontab, so a run now does the same (% is no stdin).
- there is no su and no timeout before 25.x: another user's job runs
  through start-stop-daemon -c, and the run is bounded by timeout only
  where the router has it.

Every write changes only the job's own line, so the reboot failback line
in /etc/crontabs/root stays as it is.

Requires napalm-device-types 4.26.0.

Closes #32
2026-11-03 05:45:56 +01:00

132 lines
3.8 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_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) |
## 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.
## 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/
```