Metadata-Version: 2.4
Name: saltext.napalm
Version: 0.1.0
Summary: Salt Extension for multi-vendor network device management via NAPALM
Author-email: "Gary T. Giesen" <ggiesen@giesen.me>
License: Apache Software License
Project-URL: Homepage, https://gitlab.com/ggiesen/saltext-napalm
Project-URL: Documentation, https://ggiesen.gitlab.io/saltext-napalm/
Project-URL: Source, https://gitlab.com/ggiesen/saltext-napalm
Project-URL: Tracker, https://gitlab.com/ggiesen/saltext-napalm/-/work_items
Keywords: salt-extension
Platform: any
Classifier: Programming Language :: Python
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: salt>=3008
Requires-Dist: napalm>=5.2.0
Provides-Extra: changelog
Requires-Dist: towncrier==25.8.0; extra == "changelog"
Provides-Extra: dev
Requires-Dist: nox[uv]!=2025.05.01,>=2024.3; extra == "dev"
Requires-Dist: pre-commit>=2.21.0; extra == "dev"
Provides-Extra: dev-extra
Requires-Dist: black==26.5.1; extra == "dev-extra"
Requires-Dist: isort==8.0.1; extra == "dev-extra"
Requires-Dist: coverage==7.14.3; extra == "dev-extra"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-prompt; extra == "docs"
Requires-Dist: sphinxcontrib-spelling; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: towncrier==25.8.0; extra == "docs"
Requires-Dist: sphinxcontrib-towncrier; extra == "docs"
Requires-Dist: myst_parser; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: sphinx-inline-tabs; extra == "docs"
Provides-Extra: docsauto
Requires-Dist: sphinx-autobuild; extra == "docsauto"
Provides-Extra: lint
Requires-Dist: pylint==4.0.4; extra == "lint"
Provides-Extra: tests
Requires-Dist: pytest>=7.2.0; extra == "tests"
Requires-Dist: pytest-salt-factories>=1.0.0; extra == "tests"
Requires-Dist: pytest-instafail; extra == "tests"
Dynamic: license-file

# Salt Extension for Napalm

Salt Extension for multi-vendor network device management via NAPALM

## Security

If you discover a security vulnerability, please refer
to [Salt's security guide][security].

## User Documentation

For setup and usage instructions, please refer to the
[User Documentation][docs].

## Deployment models

This extension requires **Salt 3008 or newer** for every deployment model. The
built-in NAPALM support was removed from Salt core in 3008; this extension
restores it (and adds the Resources model). On Salt 3006/3007 the NAPALM modules
are still part of core, so the extension is neither needed nor installable there
(`pip` enforces `salt>=3008`).

saltext-napalm can manage devices three ways:

| Model | How devices are managed |
| --- | --- |
| Proxy minion | One `salt-proxy` process per device (`proxytype: napalm`). |
| Deltaproxy | Many devices as sub-proxies under a single control proxy minion (control `proxytype: deltaproxy`, each sub-proxy `proxytype: napalm`). |
| Resources | Devices managed from a regular minion as first-class Salt resources, addressed with `salt -C 'T@napalm:<id>'`. |

All three models expose the NAPALM surface: the `net.*` execution module, the
`napalm_*` modules, and the `netconfig`, `netntp`, `netsnmp`, `netusers` and
`netacl` states. Proxy minion and deltaproxy run identical proxy code (deltaproxy
just runs many instances in one process). The Resources model reaches the same
`net.*`/`napalm_*` execution surface through the resource's shared, cached device
connection, so `salt -C 'T@napalm:<id>' net.cli ...`, `net.arp`, `napalm.call`
and the rest work as they do on a proxy.

Limitations:

- **Scope is NAPALM only** (multi-vendor via NAPALM drivers: junos, eos, ios,
  iosxr, nxos, and so on). Vendor-specific standalone modules such as `junos` or
  `nxos_api` are out of scope and not shipped here.
- **Deltaproxy** needs `metaproxy: deltaproxy` set on the control proxy. Its
  per-sub-proxy schedule/beacon isolation also depends on a Salt-core fix
  ([Salt issue #65088][salt-65088]); sub-proxies still connect and run without
  it, but keepalives can collide.
- **All three models load NAPALM through Salt's module loader** and are therefore
  subject to the ncclient requirement below.

## Salt loader compatibility (ncclient)

NAPALM depends on `junos-eznc`, which pins `ncclient==0.7.0`. Under Salt's module
loader that build of `ncclient` triggers a `sys.path` shadow ([Salt issue
#69139][salt-69139]): NAPALM's import fails, so the `napalm.*` functions never
load and a proxy reports `Proxymodule napalm is missing an init()`.

The root-cause fix is Salt-side ([Salt PR #69787][salt-69787]). Until it ships in
a Salt release, install a newer `ncclient` after the extension:

```bash
pip install saltext-napalm
pip install "ncclient>=0.7.1"          # onedir: salt-pip install "ncclient>=0.7.1"
```

`pip` warns that this conflicts with `junos-eznc`'s pin; the warning is expected,
and `junos-eznc` works correctly with `ncclient` 0.7.1. See the
[installation guide][install-docs] for details.

## Contributing

The saltext-napalm project welcomes contributions from anyone!

The [Salt Extensions guide][salt-extensions-guide] provides comprehensive instructions on all aspects
of Salt extension development, including [writing tests][writing-tests], [running tests][running-tests],
[writing documentation][writing-docs] and [rendering the docs][rendering-docs].

### Quickstart

To get started contributing, first clone this repository (or your fork):

```bash
# Clone the repo
git clone --origin upstream https://gitlab.com/ggiesen/saltext-napalm.git

# Change to the repo dir
cd saltext-napalm
```

#### Automatic
If you have installed [direnv][direnv], copying the included `.envrc.example` to `.envrc` and
allowing it to run ensures a proper development environment is present and the virtual environment is active.

Without `direnv`, you can still run the automation explicitly:

```bash
make dev  # or python3 tools/initialize.py
source .venv/bin/activate
```

#### Manual
Please follow the [first steps][first-steps], skipping the repository initialization and first commit.

### Ways to contribute

Contributions come in many forms, and they’re all valuable! Here are some ways you can help
without writing code:

* **Documentation**: Especially examples showing how to use this project
  to solve specific problems.
* **Triaging issues**: Help manage [issues][issues].

You can also contribute by:

* Writing blog posts
* Sharing your experiences using Salt + Napalm
  on social media
* Giving talks at conferences
* Publishing videos
* Engaging in IRC, Discord or email groups

Any of these things are super valuable to our community, and we sincerely
appreciate every contribution!

[security]: https://github.com/saltstack/salt/blob/master/SECURITY.md
[salt-extensions-guide]: https://salt-extensions.github.io/salt-extension-copier/
[writing-tests]: https://salt-extensions.github.io/salt-extension-copier/topics/testing/writing.html
[running-tests]: https://salt-extensions.github.io/salt-extension-copier/topics/testing/running.html
[writing-docs]: https://salt-extensions.github.io/salt-extension-copier/topics/documenting/writing.html
[rendering-docs]: https://salt-extensions.github.io/salt-extension-copier/topics/documenting/building.html
[first-steps]: https://salt-extensions.github.io/salt-extension-copier/topics/creation.html#initialize-the-python-virtual-environment
[submitting-pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork
[direnv]: https://direnv.net
[issues]: https://gitlab.com/ggiesen/saltext-napalm/-/work_items
[comments]: https://conventionalcomments.org/
[docs]: https://ggiesen.gitlab.io/saltext-napalm/
[install-docs]: https://ggiesen.gitlab.io/saltext-napalm/topics/installation.html
[salt-69139]: https://github.com/saltstack/salt/issues/69139
[salt-69787]: https://github.com/saltstack/salt/pull/69787
[salt-65088]: https://github.com/saltstack/salt/issues/65088
