Firewall Guidance

Practical operational guidance for the firewall layer: clearing enforcement sets, swapping rulesets, recovering from lockouts, knowing when to use the GUI versus the shell, and what to do when a misconfiguration takes DHCP off the air.

This chapter is the “how do I…” companion to Firewall Manager (chapter 20) and Flow Visualizer (chapter 21). It assumes you understand the mark structure, the seven enforcement sets, and the per-msg-type chain layout introduced in Key Concepts (chapter 03).

Most routine tuning belongs in the GUI. The shell is for emergency work, sanity checks, and the rare case where the GUI itself cannot recover.

Decision Guide

When to reach for which tool.

Situation	Use this
Adjust a set timeout or size cap	Firewall Manager (chapter 20)
Swap throttling profiles (permissive / medium / strict)	Firewall Manager — Paste, Save, Apply
See where a packet is being dropped	Flow Visualizer (chapter 21)
Manually block / unblock a single device	Actions (chapter 15) or device’s Device Details (chapter 14) page
Clear every entry from one enforcement set	Shell: `sudo nft flush set ...`
Bulk un-block everything that’s currently throttled	Shell or `mac_actions` cleanup in Database Actions Sync
Restart enforcement from a known-good baseline	`sudo /opt/dhcp-dpi/nft-v2.sh`
Recover from a misconfigured apply that lost DHCP	This chapter’s Emergency Recovery section
Investigate a hung or crashed processor	Troubleshooting (chapter 41)

Clearing Sets

Flushing a set removes its entries but leaves the set definition and all rules intact.

This is the safest firewall operation. Use it when you want to drop active enforcement on a particular category of devices without changing the structure of the ruleset.

From the Shell

To clear all entries from one set on the appliance:

sudo nft flush set inet dhcp_inspection <set-name>

Common targets:

Set	Effect of flush
`blocked_macs`	Releases the per-client kernel rate-limit blocks — these will re-populate as devices misbehave again.
`llm_blocked_marks`	Unblocks every device the LLM or an operator manually blocked.
`llm_denied_marks`	Removes every deny entry. Userspace event emission resumes for those devices.
`llm_throttled_marks`	Removes every throttle entry. Throttled devices return to normal rate handling.
`llm_allowed_marks`	Removes every trusted exception. The cleared devices return to the full enforcement ladder.
`llm_monitored_marks`	Removes monitored-only flags.
`tracked_marks`	Drops per-mark rate-tracking state. Counters reset; no enforcement impact.

A flush is instantaneous. The next packet from any device whose mark used to be in the set is processed without that set’s verdict.

From the GUI

There is no per-set “flush” button in the GUI. To achieve the same effect for the LLM-managed sets, the better path is:

Open the affected device(s) in Actions (chapter 15).
Use the Cleanup action — it removes the device from every enforcement set and marks the underlying mac_actions row inactive in one step.

This keeps the database and the kernel synchronised, which a raw nft flush does not.

What Flushing Does Not Do

It does not modify the database record of the action. The mac_actions row stays “active” until you also clean it up. This is intentional: the database is the source of truth used to restore enforcement on restart — when the processor (or the host) comes back up, every still-active row is re-pushed into the kernel sets so blocks, throttles, and allows survive a reboot. A raw nft flush clears the kernel but leaves that database state behind, so the next restart will re-apply the same entries. Use the Cleanup Expired card in Database Actions Sync (described in Firewall Manager, chapter 20) to reconcile, or the device’s Cleanup action to do both sides at once.
It does not stop an LLM analysis or automation rule from re-adding the same mark a few minutes later. If you want to stop the source as well, disable the relevant automation rule or pause the LLM in LLM Setup (chapter 23).

Clearing Rules

Flushing rules is more disruptive than flushing sets. The rule structure goes away, not just the dynamic entries.

Flushing One Chain

sudo nft flush chain inet dhcp_inspection <chain-name>

Removes every rule in that chain but keeps the chain definition. Packets continuing to traverse the hook will hit the chain and find nothing.

Use case: temporarily disable a per-msg-type chain to isolate whether it is the source of a problem. Reverse by re-applying the baseline configuration.

Flushing One Table

sudo nft flush table inet dhcp_inspection

Removes every chain, set, map, and rule inside the dhcp_inspection table. The table itself remains, but enforcement is gone.

This is equivalent to the table-mode apply in Firewall Manager (chapter 20), without the immediate reload.

Flushing the Entire Ruleset

sudo nft flush ruleset

Wipes every nftables table on the appliance — DHCP DPI and anything else. The kernel is left with no rules at all.

This is the most destructive operation in this chapter. Use it only when:

You are about to re-apply nft-v2.sh or a known-good snapshot immediately after.
Some other tool is in a state that you need to clear (and you accept that DHCP enforcement disappears with it).

Equivalent in the GUI: the all-mode apply in Firewall Manager (chapter 20).

Restoring Defaults

Re-apply the baseline ruleset shipped with the appliance.

The installer drops the canonical baseline at /opt/dhcp-dpi/nft-v2.sh. To restore it:

sudo /opt/dhcp-dpi/nft-v2.sh

The script begins with nft flush ruleset and then loads its full configuration. After it completes:

Verify the ruleset is loaded:
```
sudo nft list table inet dhcp_inspection
```
You should see the seven enforcement sets and the per-msg-type chains.
Re-populate the LLM enforcement sets from the database, otherwise every blocked / throttled / allowed device is silently released.
- In the GUI: open Firewall Manager (chapter 20), expand Database Actions Sync, click Reapply Actions.
Confirm enforcement returned by visiting Firewall Decisions (chapter 10) or by browsing the relevant sets in Flow Visualizer (chapter 21).

Tip: the baseline script also resets all counters to zero. Statistics views recover on the next snapshot cycle.

GUI vs Shell

Most of the time, prefer the GUI. The shell is for emergencies and for things the GUI cannot express.

Prefer the GUI when

The change is something the Firewall Manager (chapter 20) exposes: editing a snapshot, swapping a profile, raising a set’s timeout.
You want an audit trail. Every apply in the GUI is logged with the operator’s username, the apply mode, and the snapshot ID.
You want safety nets: validation before apply, two-click confirmation for destructive modes, rollback to any older snapshot.
The change affects database-tracked actions (mac_actions). The GUI keeps the database and the kernel synchronised; raw nft commands do not.

Use the shell when

The GUI cannot reach the appliance (network outage, API down, support backchannel down).
You need to flush a single set or chain without touching the rest.
You need to inspect runtime state that the GUI doesn’t surface — counter histograms, raw mark values, kernel error messages from dmesg.
The appliance is in an unbootable or partially-broken state and you need to drop to a minimal baseline before the GUI can recover.

The shell commands in this chapter are intentionally small and safe. Avoid hand-writing large ruleset changes — paste them into Firewall Manager (chapter 20) and let validation catch the syntax errors.

Sanity Checks

Quick commands to verify enforcement is healthy.

Is the DHCP DPI table loaded?

sudo nft list table inet dhcp_inspection

Empty output means the table is missing — restore the baseline.

How many entries are in the enforcement sets?

sudo nft list set inet dhcp_inspection llm_blocked_marks
sudo nft list set inet dhcp_inspection llm_throttled_marks
sudo nft list set inet dhcp_inspection llm_allowed_marks
sudo nft list set inet dhcp_inspection blocked_macs

If blocked_macs is growing fast and llm_blocked_marks is empty, the kernel rate limiter is the one taking action — there is real misbehaving traffic. If llm_blocked_marks has thousands of entries, the LLM or an automation rule is producing a lot of blocks; cross-check in Actions (chapter 15) and the Devices History view (Devices History, chapter 13).

Are counters incrementing?

Open Flow Visualizer (chapter 21), enable Counters, and watch. Zero counters on a chain you expect traffic in indicate the wrong hook, wrong priority, or no traffic reaching the appliance.

Is the appliance receiving DHCP at all?

Open DHCP Stream (chapter 09). If events are flowing, the processor is receiving and parsing packets — the firewall is downstream of that.

Emergency Recovery

Steps for the worst case: a misconfigured firewall apply that drops DHCP service.

Symptom: DHCP clients stop getting leases after a firewall change

What just happened is almost always one of:

An all-mode apply that loaded a snapshot without the queue rule, so packets never reach the userspace inspector.
A new rule with drop in the wrong chain.
A missing set, so a rule that depends on it fails silently and drops packets.

Recovery

Drop to the shell on the appliance. Use SSH if available; if remote access is also broken, get console.
Apply the shipped baseline. This is your panic button:
```
sudo /opt/dhcp-dpi/nft-v2.sh
```
Within seconds the baseline ruleset is loaded and DHCP packets are again being inspected and forwarded. Clients should start getting leases on their next retry.
Verify packets are flowing.
```
sudo nft list table inet dhcp_inspection | head -20
```
You should see the table, the queue chain, and the per-msg-type chains.
Re-populate enforcement sets from the database so previously-blocked devices are blocked again:
- In the GUI: Firewall Manager (chapter 20) → Database Actions Sync → Reapply Actions.
Investigate the bad snapshot. Open the GUI, find the snapshot you applied just before the outage, and:
- Re-validate it — the error message will usually point at the offending rule.
- Either fix the rule, or mark the snapshot’s Boot Config off so it cannot reload on next restart.
File the lesson learned. Save the baseline as a snapshot named recovery-2026-05-19 (or whatever the date is) so you have a known-good fallback inside the GUI from now on.

Symptom: the GUI is unreachable after a firewall change

The API binds to specific addresses. If a snapshot accidentally blocks loopback or the management interface, the API stops answering. The GUI then cannot recover the firewall.

Recovery:

SSH to the appliance.
Run sudo /opt/dhcp-dpi/nft-v2.sh to restore the baseline.
The API server’s listener should resume responding within a few seconds.
Re-open the GUI in the browser.

If SSH itself is broken by the same firewall change, you will need physical console or a hypervisor recovery shell. The baseline nft-v2.sh does not block ingress to common management ports — running it on the console clears the bad snapshot’s restrictions.

Symptom: every device is suddenly blocked

This usually means an automation rule’s filter is too wide, or an LLM analysis classified normal traffic as malicious.

Recovery:

Open Actions (chapter 15) to see the recent action log. The executor column (automation, llm, or a username) tells you who is responsible.
If an automation rule is the source, open Automation (chapter 16), disable the rule, and review its thresholds.
To release the blocked devices in one operation, you have two choices:
- From the shell: sudo nft flush set inet dhcp_inspection llm_blocked_marks — fast, immediate.
- From the GUI: the Cleanup bulk action on the affected MAC list — slower but keeps the database in sync.

After releasing, fix the source first (disable the rule or pause the LLM), then re-enable enforcement once you’ve adjusted thresholds.

Common Pitfalls

Flushing a set without cleaning up the database. The kernel forgets the block, but the GUI still shows the device as blocked. Always pair nft flush set with Cleanup Expired in the Database Actions Sync panel (Firewall Manager, chapter 20), or just use the Cleanup action on the device.

Apply: flush ruleset on a busy day. For the second or two between flush and apply the appliance has zero rules. Most DHCP clients tolerate this fine, but a high-traffic relay will see a burst of packets reach the inspector unfiltered. Schedule flush-mode applies for a maintenance window.

Editing nft-v2.sh by hand on the appliance. This file is shipped with the installer and will be overwritten on the next package upgrade. Make your changes in Firewall Manager (chapter 20) snapshots instead, and mark the one you want as the boot config.

Forgetting Reapply Actions after a flush. The kernel sets are empty but the database believes devices are still blocked. Devices behave as if unblocked. Visiting Database Actions Sync as the very next step after a flush-mode apply removes this footgun.

Hand-running nft flush ruleset when you only meant to clear the DHCP DPI table. If other software (e.g. a firewall manager, Docker, fail2ban) also installs nftables rules on the box, you will erase those too. Prefer nft flush table inet dhcp_inspection unless you specifically want the full reset.

What Lives Where

A quick map for finding files on the appliance.

What	Where
Shipped baseline ruleset	`/opt/dhcp-dpi/nft-v2.sh` (plus `nft-v2.json` for the JSON source)
Shipped throttling profiles	`/opt/dhcp-dpi/share/nft-config/` (low / medium / strict JSON files)
Core configuration	`/opt/dhcp-dpi/etc/config.yaml` — see Configuration Reference (chapter 42)
`dpictl` admin CLI	`/opt/dhcp-dpi/bin/dpictl`
Service unit	`dhcp-processor.service` under systemd
Logs	`journalctl -u dhcp-processor`

For the rest of the troubleshooting toolbox — process state, service restarts, log inspection, common errors — see Troubleshooting (chapter 41).