diff#

The diff command compares two OPNsense configurations and shows what changed between them. Unlike a raw text diff, it understands the structure of OPNsense configs -- it groups changes by section, scores their security impact, and can detect rule reordering separately from content changes.

When to use it:

• Reviewing what changed between two config backups (before/after a maintenance window)
• Change management auditing -- documenting exactly what was modified and why it matters
• Security review of configuration changes, filtering to only security-relevant differences
• Comparing configs across environments (production vs staging)

Usage#

opndossier diff [flags] <old-config.xml> <new-config.xml>

Flags#

For global flags (--verbose, --quiet, --config, etc.), see Configuration Reference.

Display Modes#

The --mode flag controls how changes are presented in terminal output.

# Side-by-side comparison
opndossier diff -m side-by-side old-config.xml new-config.xml

Security Filtering#

Every change detected by diff is scored for security impact using pattern-based rules. The --security flag filters the output to show only changes that have a security impact, hiding cosmetic or low-risk differences.

This is useful when reviewing a large set of changes and you only care about what affects the security posture -- for example, during a change management review or incident investigation.

# Show only security-relevant changes
opndossier diff --security old-config.xml new-config.xml

Security Impact Levels#

Normalization#

OPNsense configurations can contain cosmetic differences that are not meaningful -- extra whitespace, different IP address formatting, or inconsistent port notation. The --normalize flag cleans up these differences before comparing, so the diff only shows changes that actually matter.

When normalization is enabled:

• Whitespace is standardized
• IP addresses are normalized to a canonical form
• Port numbers and ranges are normalized

If two values are identical after normalization, the change is silently skipped.

# Skip cosmetic differences
opndossier diff --normalize old-config.xml new-config.xml

# Combine with security filtering for a focused review
opndossier diff --security --normalize old-config.xml new-config.xml

Rule Reordering Detection#

Firewall rule order matters in OPNsense -- rules are evaluated top to bottom, and the first match wins. The --detect-order flag identifies rules that were reordered without any content changes. These are reported separately from added/removed/modified changes so you can see at a glance whether rule precedence shifted.

By default, reordering detection is off because it requires comparing every rule against every other rule, which adds processing time for large rulesets.

# Detect reordered firewall rules
opndossier diff --detect-order old-config.xml new-config.xml

Available Sections#

system, firewall, nat, interfaces, vlans, dhcp, users, routing

Examples#

# Compare two configs in terminal
opndossier diff old-config.xml new-config.xml

# Generate markdown diff report
opndossier diff old-config.xml new-config.xml -f markdown -o changes.md

# Compare only firewall and NAT sections
opndossier diff old-config.xml new-config.xml -s firewall,nat

# Show only security-relevant changes with normalization
opndossier diff old-config.xml new-config.xml --security --normalize

Related#

• CLI Reference — diff -- auto-generated exhaustive flag list
• convert -- generate full documentation from a single config
• Configuration Reference -- global flags and settings