# Runbook: controlled network change

## Purpose

Apply a controlled network configuration change (DNS records, firewall, LAN
gateway, VLAN) with impact assessment, approval, and a rollback path.

## Scope

- Applicable: PowerDNS zone records, `us4` firewalld allowlist, LAN gateway/VLAN/DNS changes, WireGuard.
- Not applicable: SSH access-policy changes (see `AGENTS.md` §SSH access safety — mandatory lockout-risk procedure).

## Ownership

- Owner: personal ops (Windy)
- Last reviewed: 2026-08-17
- Related systems: PowerDNS / us4 firewalld / LAN gateway / WireGuard

## Preconditions

- A change record (Linear `vps` issue) describes the change, its reason, and rollback.
- Read-only impact assessment done (current config captured, blast radius known).

## Safety

- Never change DNS or network config without a change record and approval.
- Capture the current config first; never delete existing config as the first action.
- For DNS: record the current record values and TTL before editing.
- For firewall: retain an independent SSH rollback session before applying (see `ansible-operations.md` §us4).

## Procedure

### Step 1 — Assess and capture

**Action** — capture the current state (e.g. `dig` for DNS, `--check --diff` for firewall, `show` for gateway).

**Expected** — a baseline of current config and an identified blast radius.

**Decision** — change fully specified with rollback → Step 2; missing → `STOP`.

### Step 2 — Approve

**Action** — confirm approval is recorded in the issue/change record.

**Decision** — approved → Step 3; not approved → `STOP`.

### Step 3 — Change

**Action** — apply the single change (edit the record, run the gated playbook, or change gateway config) and only that change.

**Expected** — the new value/state is in effect.

**Verification** — re-query/verify the new state and confirm dependent services still pass health.

**Rollback** — restore the captured prior config and re-verify.

## Troubleshooting

### Troubleshooting A — Change broke dependent service

- Evidence: health report / endpoint failure.
- Allowed: roll back to the captured prior config.
- Next: verify; if still broken, escalate.

## Final Verification

- New state verified; dependent services healthy.
- Change and outcome recorded in the issue.

## References

- [`ansible-operations.md`](ansible-operations.md)
- [`rollback.md`](rollback.md)
- [`network-recovery.md`](network-recovery.md)