saltext-opnsense 0.1.1.dev0__tar.gz

saltext_opnsense-0.1.1.dev0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint & Format Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install ruff
+      - run: ruff check src tests tools
+      - run: ruff format --check src tests tools
+
+  unit:
+    name: Unit Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e .[dev] || (pip install -e . && pip install pytest requests salt)
+      - run: PYTHONPATH=src pytest tests/unit -v
+
+  spec-drift:
+    name: Spec Integrity Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install requests
+      - name: Verify Spec Consistency
+        run: |
+          CORE_REF=$(python3 -c "import json,pathlib; print(json.loads(pathlib.Path('src/saltext/opnsense/utils/controllers.json').read_text()).get('meta',{}).get('core_ref','25.7'))")
+          echo "Verifying spec against upstream tag: ${CORE_REF}"
+          python tools/generate_spec.py --core-ref "${CORE_REF}" --plugins-ref "${CORE_REF}" --output /tmp/controllers.json
+          diff -u tools/controllers.json /tmp/controllers.json || (echo "controllers.json drift detected — run make bump CORE=${CORE_REF}" && exit 1)

saltext_opnsense-0.1.1.dev0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      # Required for Trusted Publishing (OIDC) to PyPI
+      id-token: write
+      contents: read
+    
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required for setuptools_scm to determine version from git tags
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check build artifacts
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # If you are using an API token instead of OIDC, uncomment the following:
+        # with:
+        #   password: ${{ secrets.PYPI_API_TOKEN }}

saltext_opnsense-0.1.1.dev0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+dist/
+build/
+.eggs/
+.pytest_cache/
+.nox/
+venv/
+.venv/
+controllers.json.bak
+/tmp/
+tools/tmp/
+# generated ergonomic wrappers - dynamic injection covers all, keep repo minimal
+src/saltext/opnsense/modules/opnsense_*.py
+src/saltext/opnsense/states/opnsense_*.py
+# but keep generic opnsense.py (excluded above would ignore generic too? pattern is opnsense_*.py, not opnsense.py, so generic safe)
+

saltext_opnsense-0.1.1.dev0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.8
+    hooks:
+      - id: ruff
+        args: [--fix]
+        types: [python]
+      - id: ruff-format
+        types: [python]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      - id: check-merge-conflict
+
+# Setup:
+#   pip install pre-commit
+#   pre-commit install
+#   pre-commit run --all-files

saltext_opnsense-0.1.1.dev0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+This changelog is managed via towncrier.
+
+Fragments in `changelog/` (feature, bugfix, doc, removal, misc) are concatenated into this file via `towncrier build`.
+
+## 0.1.0 (unreleased)
+
+- Initial scaffold: generic templated `opnsense` execution + state modules, proxy minion, utils client, codegen tool for all API endpoints, unit tests Salt way, examples replacing `query.sh` / `sync-bind-zone.sh`

saltext_opnsense-0.1.1.dev0/CONTRIBUTING.md

@@ -0,0 +1,128 @@
+# Contributing — saltext-opnsense
+
+## Quick start
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"  # dev: pytest, ruff, towncrier, nox
+# or:
+pip install -e . && pip install pytest ruff towncrier requests "salt>=3008"
+
+# generate everything (spec + wrappers + verify + sync)
+make gen-all
+# or manually:
+make gen-spec
+make gen-wrappers
+make verify
+```
+
+## Running tests
+
+```bash
+# unit (no live OPNsense, mocked)
+PYTHONPATH=src pytest tests/unit -v
+
+# import proof: 76 exec + 76 state + 1816 dynamic wrappers
+PYTHONPATH=src python3 tools/verify_import.py
+PYTHONPATH=src python3 tools/verify_import.py
+
+# lint
+ruff check src tests tools
+ruff format src tests tools --check
+
+# full nox matrix (needs salt installed)
+nox -e tests
+nox -e lint
+
+# live smoke (read-only, no Salt) against opnsense-router
+OPNSENSE_HOST=opnsense.example.com OPNSENSE_API_KEY=... OPNSENSE_API_SECRET=... python tools/test_live.py
+# or:
+python tools/test_live.py --host opnsense.example.com --key $KEY --secret $SECRET
+
+# integration (gated, live)
+OPNSENSE_LIVE_TEST=1 PYTHONPATH=src pytest tests/integration -v -k live
+```
+
+## Adding a new test
+
+Tests live in `tests/unit/`:
+- `utils/test_client.py` — mock `requests.Session.request`, test `OPNsenseClient.search/get/add`
+- `modules/test_modules_opnsense.py` — mock `_get_client`, test execution module proxy/direct branching
+- `states/test_opnsense.py` — mock `__salt__` (search/add/set/del), test `item_present/absent` idempotency
+- `test_free_modules_import.py` — proves all 76 generated wrappers import
+
+Example:
+
+```python
+from unittest.mock import MagicMock, patch
+from saltext.opnsense.utils.opnsense import OPNsenseClient, OPNsenseClientConfig
+
+@patch("saltext.opnsense.utils.opnsense.requests.Session.request")
+def test_my_feature(mock_req):
+    mock_resp = MagicMock()
+    mock_resp.status_code = 200
+    mock_resp.json.return_value = {"rows": [], "total": 0}
+    mock_resp.text = '{"rows":[]}'
+    mock_req.return_value = mock_resp
+    cfg = OPNsenseClientConfig(host="opnsense-router", api_key="a", api_secret="b")
+    client = OPNsenseClient(cfg)
+    res = client.search("unbound", "settings", "host_alias", search_phrase="www")
+    assert "rows" in res
+```
+
+Run `pytest tests/unit -v --collect-only` to verify discovery.
+
+## Regenerating code
+
+- Spec: `tools/generate_spec.py --core-ref 25.7 --plugins-ref 25.7 --output src/saltext/opnsense/utils/controllers.json`
+- Wrappers: `tools/generate_wrappers.py` (emits 76 exec + 76 state modules)
+- Verify: `tools/verify_import.py`
+`make gen-all` does all three in order.
+
+## Changelog — towncrier
+
+We use towncrier. Fragments live in `changelog/`:
+
+```
+changelog.feature.  — new features
+changelog.bugfix.   — bug fixes
+changelog.doc.      — docs
+changelog.removal.  — deprecation/removal
+changelog.misc.     — trivial (no changelog entry)
+```
+
+Create fragment:
+
+```bash
+towncrier create 123.feature --edit
+# writes changelog/123.feature.md with your text
+# commit it with your PR
+```
+
+Build on release:
+
+```bash
+towncrier build --version 0.2.0
+# appends to CHANGELOG.md, deletes fragments
+```
+
+A changelog fragment is optional for small PRs but encouraged.
+
+## Submitting PR
+
+1. Branch from `main`: `git checkout -b fix/unbound-search`
+2. Make change + regenerate if needed: `make gen-all`
+3. Run `PYTHONPATH=src pytest tests/unit -v` and `tools/verify_import.py`
+4. Run `ruff check src tests tools`
+5. Add towncrier fragment: `towncrier create <pr>.feature --edit`
+6. Push, open PR to `main` at `https://github.com/primechuck/saltext-opnsense`. Mention Renovate / OPNsense version if relevant.
+
+See `docs/MAINTENANCE.md` for OPNsense release sprint workflow.
+
+## Code style
+
+- `ruff` with `line-length=100`, `target-version=py310`
+- Builtins allowed: `__opts__`, `__salt__`, `__proxy__`, `__context__`, `__grains__`, `__utils__` (declared in `pyproject.toml`)
+- No comments unless comstream — rely on docstrings in generated wrappers
+- Prefer `file-based` vs `pip install` note in docs when adding new modules

saltext_opnsense-0.1.1.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 saltext-opnsense Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

saltext_opnsense-0.1.1.dev0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md LICENSE CHANGELOG.md
+include src/saltext/opnsense/utils/controllers.json
+include src/saltext/opnsense/utils/models.json
+recursive-include src/saltext/opnsense/utils *.json
+recursive-include tools *.json
+include pyproject.toml
+global-exclude __pycache__
+global-exclude *.py[cod]
+prune .pytest_cache
+prune .nox

saltext_opnsense-0.1.1.dev0/Makefile

@@ -0,0 +1,92 @@
+# Makefile for saltext-opnsense — maintainable codegen pipeline
+# Single entrypoint: make gen-all (wraps tools/generate_all.py)
+# See docs/MAINTENANCE.md for full sprint checklist
+
+PYTHON ?= python3
+CORE_REF ?= 25.7
+PLUGINS_REF ?= 25.7
+CORE ?= $(CORE_REF)
+ARGS ?=
+DRY ?=
+
+TOOLS_DIR := tools
+SRC_UTILS := src/saltext/opnsense/utils
+SRC_JSON := $(SRC_UTILS)/controllers.json
+SRC_MODELS_JSON := $(SRC_UTILS)/models.json
+
+.PHONY: help gen-spec gen-models gen-wrappers bump sync verify test lint gen-all clean
+
+help:
+	@echo "saltext-opnsense maintenance"
+	@echo ""
+	@echo "Targets:"
+	@echo "  gen-spec      - Clone core/plugins @ REF and parse controllers.php -> src/.../utils/controllers.json"
+	@echo "  gen-models    - Parse Model XML -> src/.../utils/models.json"
+	@echo "  gen-wrappers  - Spec -> 76 exec + 76 state wrappers (auto-generated)"
+	@echo "  bump          - Upstream version sprint: make bump CORE=25.7"
+	@echo "  sync          - Copy src -> extmods directories for gitfs file-based install"
+	@echo "  verify        - Prove all 76 modules import (exec+state+dynamic)"
+	@echo "  test          - pytest tests/unit -q"
+	@echo "  lint          - ruff check src tests tools"
+	@echo "  gen-all       - Full pipeline: spec -> wrappers -> sync -> verify -> test (via generate_all.py)"
+	@echo "  clean         - Remove caches, /tmp/opnsense-spec, pycache"
+	@echo ""
+	@echo "Variables:"
+	@echo "  CORE_REF, PLUGINS_REF (default 25.7) e.g. make gen-all CORE_REF=25.7 PLUGINS_REF=25.7"
+	@echo "  CORE (alias for CORE_REF/PLUGINS_REF) e.g. make bump CORE=25.7"
+	@echo ""
+	@echo "Examples:"
+	@echo "  make bump CORE=25.7"
+	@echo "  make gen-all CORE_REF=25.7 PLUGINS_REF=25.7"
+	@echo "  make gen-wrappers && make verify"
+
+gen-spec:
+	@mkdir -p $(SRC_UTILS)
+	$(PYTHON) $(TOOLS_DIR)/generate_spec.py --core-ref $(CORE_REF) --plugins-ref $(PLUGINS_REF) --output $(SRC_JSON)
+	@jq .meta $(SRC_JSON) 2>/dev/null || python3 -c "import json,pathlib; print(json.loads(pathlib.Path('$(SRC_JSON)').read_text()).get('meta'))"
+
+gen-models:
+	@mkdir -p $(SRC_UTILS)
+	@if [ -d /tmp/opnsense-spec/core ] && [ -d /tmp/opnsense-spec/plugins ]; then \
+		echo "Using cached clones /tmp/opnsense-spec/core and /tmp/opnsense-spec/plugins"; \
+		$(PYTHON) $(TOOLS_DIR)/generate_models.py --core /tmp/opnsense-spec/core --plugins /tmp/opnsense-spec/plugins --output $(SRC_MODELS_JSON); \
+	else \
+		$(PYTHON) $(TOOLS_DIR)/generate_models.py --core-ref $(CORE_REF) --plugins-ref $(PLUGINS_REF) --output $(SRC_MODELS_JSON); \
+	fi
+	@echo "Wrote $(SRC_MODELS_JSON)"
+
+gen-wrappers:
+	$(PYTHON) $(TOOLS_DIR)/generate_wrappers.py
+
+bump:
+	$(PYTHON) $(TOOLS_DIR)/generate_spec.py --core-ref $(CORE) --plugins-ref $(CORE) --output $(SRC_JSON)
+	cp $(SRC_JSON) $(TOOLS_DIR)/controllers.json
+	$(PYTHON) $(TOOLS_DIR)/generate_wrappers.py
+	PYTHONPATH=src $(PYTHON) $(TOOLS_DIR)/verify_import.py
+
+sync:
+	$(PYTHON) $(TOOLS_DIR)/sync_extmods.py --copy
+
+verify:
+	PYTHONPATH=src $(PYTHON) $(TOOLS_DIR)/verify_import.py
+
+test:
+	PYTHONPATH=src $(PYTHON) -m pytest tests/unit -q
+
+lint:
+	$(PYTHON) -m ruff check src tests tools || ruff check src tests tools
+
+gen-all:
+ifeq ($(DRY),1)
+	$(PYTHON) $(TOOLS_DIR)/generate_all.py --core-ref $(CORE_REF) --plugins-ref $(PLUGINS_REF) --dry-run $(ARGS)
+else
+	$(PYTHON) $(TOOLS_DIR)/generate_all.py --core-ref $(CORE_REF) --plugins-ref $(PLUGINS_REF) $(ARGS)
+endif
+
+clean:
+	rm -rf /tmp/opnsense-spec tools/tmp __pycache__ src/__pycache__ .pytest_cache .nox build dist *.egg-info src/*.egg-info
+	rm -rf src/saltext/opnsense/__pycache__ src/saltext/opnsense/modules/__pycache__ src/saltext/opnsense/states/__pycache__ src/saltext/opnsense/utils/__pycache__
+	rm -rf src/saltext/opnsense/proxy/__pycache__ src/saltext/opnsense/grains/__pycache__ tests/__pycache__ tests/unit/__pycache__
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true
+	@echo "Cleaned caches. Generated wrappers/json kept."

saltext_opnsense-0.1.1.dev0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: saltext-opnsense
+Version: 0.1.1.dev0
+Summary: Salt extension for managing OPNsense via its API - templated, 3008+ ready, with dynamic wrappers, file-based install, and Vault support
+Author-email: David Bierce <david@bierce.org>
+Maintainer-email: David Bierce <david@bierce.org>
+License: MIT
+Project-URL: Homepage, https://github.com/primechuck/saltext-opnsense
+Project-URL: Repository, https://github.com/primechuck/saltext-opnsense
+Project-URL: Issues, https://github.com/primechuck/saltext-opnsense/issues
+Project-URL: Documentation, https://primechuck.github.io/saltext-opnsense/
+Keywords: salt,salt-extension,saltext,opnsense,firewall,api,unbound,bind,kea,acme
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: System :: Networking :: Firewalls
+Classifier: Topic :: System :: Systems Administration
+Classifier: Operating System :: POSIX :: Linux
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: salt>=3008
+Requires-Dist: requests>=2.28
+Requires-Dist: urllib3>=1.26
+Dynamic: license-file
+
+# saltext-opnsense
+
+SaltStack extension for managing OPNsense firewalls via the REST API.
+
+Manage OPNsense services (Unbound DNS, Kea DHCP, BIND, ACME certs, firewall aliases, interfaces) declaratively with Salt states or programmatically via execution modules. API bindings are generated directly from upstream OPNsense schemas.
+
+> **Target Release**: Built for **OPNsense 25.7** (76 modules, ~1,816 API endpoints).
+> **Core Design Goal**: Maintainer laziness. Never hand-code API wrappers. When OPNsense ships a new release, all 76 modules and 1,800+ endpoints are regenerated directly from upstream schemas via `make bump CORE=25.7`.
+
+
+## Features
+
+- **Execution Modules**: Direct API calls to OPNsense controllers and actions.
+- **State Modules**: Declarative states for OPNsense resources (`item_present`, `item_absent`, DNS aliases, DHCP leases, ACME certs).
+- **Proxy Minion Support**: Agentless management of OPNsense hardware and VMs.
+- **Auto-Generated Spec**: Keeps up with upstream OPNsense releases without manual code edits.
+- **Diagnostics (`opnsense.doctor`)**: Quick CLI check for credentials, API connectivity, and firmware status.
+
+## Quick Start
+
+### 1. Installation
+
+Install on the Salt Master and Proxy Minion:
+
+```bash
+salt-pip install saltext-opnsense
+salt '*' saltutil.sync_all
+```
+
+Or copy directly into Salt's `file_roots` (for environments without `salt-pip`):
+
+```bash
+python3 tools/sync_extmods.py --copy
+salt '*' saltutil.sync_all
+```
+
+### 2. Configuration
+
+Define your OPNsense target in Pillar (e.g. `/srv/pillar/opnsense.sls`). See [pillar.example](file:///Users/dbierce/GitHub/configurations/projects/saltext-opnsense-review/pillar.example) for details.
+
+```yaml
+proxy:
+  proxytype: opnsense
+  host: opnsense.example.com
+  proto: https
+  api_key: "your_api_key"
+  api_secret: "your_api_secret"
+  # verify_ssl: false  # Optional; defaults to true
+```
+
+### 3. Diagnostics
+
+Verify connectivity and credential resolution:
+
+```bash
+salt opnsense-router opnsense.doctor
+```
+
+## Usage
+
+### Execution Module
+
+```bash
+# Search Unbound DNS host aliases
+salt opnsense-router opnsense.search unbound settings host_alias
+
+# Call endpoint directly
+salt opnsense-router opnsense_unbound.search_host_alias
+```
+
+### State Module
+
+```yaml
+# Ensure an Unbound Host Alias exists
+www_alias:
+  opnsense_unbound.host_alias_present:
+    - data:
+        enabled: "1"
+        hostname: www
+        domain: example.com
+    - reconfigure: unbound/service/reconfigure
+```
+
+## Maintenance & Upgrades
+
+API spec bindings are generated from upstream `opnsense/core` and `opnsense/plugins`.
+
+When OPNsense ships a new release (e.g. `26.1`), regenerate bindings with:
+
+```bash
+make bump CORE=26.1
+```
+
+For developer documentation and full maintenance details, see [docs/MAINTENANCE.md](file:///Users/dbierce/GitHub/configurations/projects/saltext-opnsense-review/docs/MAINTENANCE.md).
+
+## Testing
+
+```bash
+# Run unit tests
+PYTHONPATH=src pytest tests/unit -v
+
+# Verify module imports
+PYTHONPATH=src python3 tools/verify_import.py
+```

saltext_opnsense-0.1.1.dev0/README.md

@@ -0,0 +1,104 @@
+# saltext-opnsense
+
+SaltStack extension for managing OPNsense firewalls via the REST API.
+
+Manage OPNsense services (Unbound DNS, Kea DHCP, BIND, ACME certs, firewall aliases, interfaces) declaratively with Salt states or programmatically via execution modules. API bindings are generated directly from upstream OPNsense schemas.
+
+> **Target Release**: Built for **OPNsense 25.7** (76 modules, ~1,816 API endpoints).
+> **Core Design Goal**: Maintainer laziness. Never hand-code API wrappers. When OPNsense ships a new release, all 76 modules and 1,800+ endpoints are regenerated directly from upstream schemas via `make bump CORE=25.7`.
+
+
+## Features
+
+- **Execution Modules**: Direct API calls to OPNsense controllers and actions.
+- **State Modules**: Declarative states for OPNsense resources (`item_present`, `item_absent`, DNS aliases, DHCP leases, ACME certs).
+- **Proxy Minion Support**: Agentless management of OPNsense hardware and VMs.
+- **Auto-Generated Spec**: Keeps up with upstream OPNsense releases without manual code edits.
+- **Diagnostics (`opnsense.doctor`)**: Quick CLI check for credentials, API connectivity, and firmware status.
+
+## Quick Start
+
+### 1. Installation
+
+Install on the Salt Master and Proxy Minion:
+
+```bash
+salt-pip install saltext-opnsense
+salt '*' saltutil.sync_all
+```
+
+Or copy directly into Salt's `file_roots` (for environments without `salt-pip`):
+
+```bash
+python3 tools/sync_extmods.py --copy
+salt '*' saltutil.sync_all
+```
+
+### 2. Configuration
+
+Define your OPNsense target in Pillar (e.g. `/srv/pillar/opnsense.sls`). See [pillar.example](file:///Users/dbierce/GitHub/configurations/projects/saltext-opnsense-review/pillar.example) for details.
+
+```yaml
+proxy:
+  proxytype: opnsense
+  host: opnsense.example.com
+  proto: https
+  api_key: "your_api_key"
+  api_secret: "your_api_secret"
+  # verify_ssl: false  # Optional; defaults to true
+```
+
+### 3. Diagnostics
+
+Verify connectivity and credential resolution:
+
+```bash
+salt opnsense-router opnsense.doctor
+```
+
+## Usage
+
+### Execution Module
+
+```bash
+# Search Unbound DNS host aliases
+salt opnsense-router opnsense.search unbound settings host_alias
+
+# Call endpoint directly
+salt opnsense-router opnsense_unbound.search_host_alias
+```
+
+### State Module
+
+```yaml
+# Ensure an Unbound Host Alias exists
+www_alias:
+  opnsense_unbound.host_alias_present:
+    - data:
+        enabled: "1"
+        hostname: www
+        domain: example.com
+    - reconfigure: unbound/service/reconfigure
+```
+
+## Maintenance & Upgrades
+
+API spec bindings are generated from upstream `opnsense/core` and `opnsense/plugins`.
+
+When OPNsense ships a new release (e.g. `26.1`), regenerate bindings with:
+
+```bash
+make bump CORE=26.1
+```
+
+For developer documentation and full maintenance details, see [docs/MAINTENANCE.md](file:///Users/dbierce/GitHub/configurations/projects/saltext-opnsense-review/docs/MAINTENANCE.md).
+
+## Testing
+
+```bash
+# Run unit tests
+PYTHONPATH=src pytest tests/unit -v
+
+# Verify module imports
+PYTHONPATH=src python3 tools/verify_import.py
+```

saltext_opnsense-0.1.1.dev0/changelog/README.md

@@ -0,0 +1,10 @@
+# Changelog fragments
+
+Use towncrier:
+
+```bash
+towncrier create 123.feature --edit
+towncrier build --version 0.1.0
+```
+
+Categories: feature, bugfix, doc, removal, misc