azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

wiki: compile pfsense (full) — add unifi-wifi pfSense SSH gateway-control tooling

Browse Source
This commit is contained in:
Howard Enos
2026-06-21 11:36:30 -07:00
parent 6c0beb5a96
commit e23e3e66b4
2 changed files with 84 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
wiki/index.md
View File

@@ -1,7 +1,7 @@
# Wiki Index
g<1>2026-06-20
Compiled by: GURU-5070/claude-main
Last updated: 2026-06-21
Compiled by: HOWARD-HOME/claude-main
This wiki is LLM-maintained. Do not edit articles manually — run `/wiki-compile` to update.
Run `/wiki-lint` to check for stale entries and broken backlinks.
@@ -87,6 +87,7 @@ Run `/wiki-lint` to check for stale entries and broken backlinks.
| [Pluto (Claude-Builder)](systems/pluto.md) | 172.16.3.36 — Windows Server 2019 virsh VM on Jupiter; **fallback** Windows MSI + cargo build host for GuruRMM (Beast/GURU-BEAST-ROG is primary) | 2026-06-12 |
| [Uranus](systems/uranus.md) | 172.16.3.21 — Unraid secondary (Dell R730xd); OwnCloud archive storage only; formerly Saturn's IP (reused Apr 2026); RAM too low for VMs | 2026-05-24 |
| [IX Web Hosting Server](systems/ix-server.md) | 172.16.3.10 / 72.194.62.5 — cPanel/WHM 134 on CloudLinux 9.7 (64-core Xeon, 4.4 T /home); **72 cPanel accounts / 185 domains / 101 WordPress** + ACG sites (radio Astro, Flarum community, Matomo analytics); GuruRMM-enrolled; SSH key auth from GURU-5070; behind Cloudflare tunnel `acg-origin`; **backups look unconfigured (gap)**. Live SSH inventory 2026-06-05 — full account→domain map in the article | 2026-06-05 |
| [pfsense (ACG Gateway/Firewall)](systems/pfsense.md) | 172.16.0.1 (SSH :2248) — ACG office FreeBSD gateway/firewall + Tailscale subnet router. ALSO the home of the **fleet-wide pfSense management tooling** in the `unifi-wifi` skill: SSH backend (`pfsense-ssh.sh` + `pfsense-gwc.php`) that audits/controls ANY client pfSense — `audit`/`pf-*`/`fw-*`/`block-ips`, DRY-RUN default, cred `clients/<slug>/pfsense-firewall`. Validated on Cascades (Plus 25.07) 2026-06-21 | 2026-06-21 |
## Patterns

86
wiki/systems/pfsense.md
View File

@@ -2,18 +2,26 @@
type: system
name: pfsense
display_name: pfsense (ACG Gateway/Firewall)
last_compiled: 2026-05-25
compiled_by: DESKTOP-0O8A1RL/claude-main
last_compiled: 2026-06-21
compiled_by: HOWARD-HOME/claude-main
sources:
- session-logs/2026-05-25-session.md
- session-logs/2026-06/2026-06-21-howard-unifi-pfsense-control-verbs.md
backlinks:
- systems/gururmm-build
- systems/jupiter
- systems/uos-server
- clients/cascades-tucson
---
# pfsense (ACG Gateway/Firewall)
## Identity
> Two things live under this article: (1) the **ACG office** pfSense gateway (172.16.0.1), and
> (2) the **fleet-wide pfSense management tooling** that now ships in the `unifi-wifi` skill — an
> SSH backend that audits and controls ANY client pfSense, not just the office box. See
> [[systems/uos-server]] for the UniFi side of the same skill.
## Identity (ACG office gateway)
| Field | Value |
|-------|-------|
@@ -49,7 +57,7 @@ Persisted in `/etc/netplan/00-installer-config.yaml` on the build server. This a
---
## SSH Access
## SSH Access (office box)
```bash
ssh -p 2248 <user>@172.16.0.1
@@ -59,7 +67,75 @@ ssh -p 2248 <user>@100.119.153.74
---
## Management Tooling — `unifi-wifi` pfSense SSH backend
The `unifi-wifi` skill includes a **pfSense gateway compatibility layer**: the same gateway verbs
it exposes for UniFi gateways (`gw-audit` / `gw-control`) now route to a pfSense over SSH when a
site has no UniFi gateway. Decision (Mike, 2026-06-16): **SSH only — no RESTAPI package needed.**
The REST backend (`pfsense-backend.sh`, `clients/<slug>/pfsense-api`) is a dormant fallback.
**Scripts** (in `.claude/skills/unifi-wifi/scripts/`):
- `pfsense-ssh.sh <slug> <verb>` — entry point; talks to the box over **system OpenSSH via askpass**.
- `pfsense-gwc.php` — argv-driven config helper, shipped to the box per-call (base64 over the wire)
and run under `php`, which bootstraps `$config` + `write_config()` + `filter_configure()` via
`require_once("config.inc")`.
**Cred convention:** `clients/<slug>/pfsense-firewall` in the vault — top-level `host`,
`credentials.username`, `credentials.password`.
**Verbs:**
- Reads (no gate): `audit` (WAN/DHCP/states/DNS/NIC health), `dhcp` (pool pressure), `pf-list`
(NAT port-forwards), `fw-list` (filter rules), `showblock [--if wan]`, `run "<cmd>"`.
- Writes (DRY-RUN default; add `--apply` to commit — backs up `config.xml`, then `write_config` +
filter reload):
- `fw-disable|fw-enable <tracker|descr>` — toggle a filter rule. **Validated live.**
- `block-ips|unblock <ip[,ip,...]> [--if wan]` — via `easyrule`. **Validated live.**
- `pf-disable|pf-enable|pf-delete <tracker|descr>`, `pf-set-ports <dst> [<local>]`,
`pf-set-src <cidr|any>` — port-forwards (+ associated filter rule). **Built; live-verify
pending** (needs a box that has port-forwards).
- Filter rules are matched by `tracker` (the `id` field is empty on pf25.07) or exact `descr`.
**Dispatch:** `gw-audit.sh` / `gw-control.sh` prefer this SSH backend (keyed on the
`pfsense-firewall` cred) and run the dispatch BEFORE UOS site resolution, so a pfSense-only client
slug works without a matching UOS site name (pass `--pfsense <slug>` if the names differ).
**Caveat for THIS office box:** `pfsense-ssh.sh` currently assumes SSH **port 22**; the ACG office
pfSense listens on **2248**, so the skill needs a port option before it can manage the office
gateway. Cred for it is vaulted at `infrastructure/pfsense-firewall` (verify).
**pfSense PHP gotchas** (baked into the scripts; carry forward to any new helper):
- Bootstrap with `require_once("config.inc")` ONLY — re-requiring util/functions/filter → "cannot
redeclare" fatal. It already provides `write_config()`/`filter_configure()`.
- `display_errors` is **Off** — php fatals are silent (rc=255, no message). Run php with `2>&1` and
`ini_set("display_errors","1")`.
- pfSense already defines `backup_config()` (and many generic names) → **prefix helper functions**.
- `pfSsh.php` does NOT eval piped ad-hoc code (only its built-in `playback` scripts) — use `php <file>`.
- Ship the helper with `base64 | openssl base64 -A -d` (both present on FreeBSD).
---
## Known Issues & Quirks
- **`easyrule` leaves residue:** once used, it persists a `'Blocked via EasyRule'` WAN rule + an
`EasyRuleBlockHostsWAN` alias even after `unblock` empties the alias. Inert (empty alias blocks
nothing) but visible in `fw-list`. One such artifact was left on **Cascades** pfSense by the
2026-06-21 validation (pending operator decision to remove).
- **Office box is on SSH port 2248**, not 22 — see the tooling caveat above.
---
## Key Rules
- **Do not restart or apply firewall rules without user confirmation** — pfsense is the single point of failure for the entire ACG LAN.
- **Do not restart or apply firewall rules without user confirmation** — the office pfsense is the
single point of failure for the entire ACG LAN.
- Any changes to NAT, firewall rules, or routing should be confirmed before applying.
- The `unifi-wifi` write verbs are **DRY-RUN by default**; `--apply` is required to commit and each
write backs up `config.xml` first. pfSense also keeps its own config history.
---
## Backlinks
- [[systems/uos-server]] — the UniFi side of the `unifi-wifi` skill (controller + WiFi/switch tooling).
- [[clients/cascades-tucson]] — pfSense Plus 25.07; the box the SSH gateway-control layer was validated against.
- [[systems/jupiter]], [[systems/gururmm-build]] — depend on this gateway for routing.