opnDossier diff#
Compare two OPNsense configuration files.
Synopsis#
The 'diff' command compares two OPNsense config.xml files and shows meaningful
configuration changes in a content-aware, security-focused way.
Unlike a raw XML text diff, this command understands OPNsense semantics:
- Firewall rules are matched by UUID and compared structurally
- Interfaces are compared by name with field-level change tracking
- Static DHCP reservations are tracked by MAC address
- Changes are scored by a pattern-based engine (high/medium/low)
OUTPUT FORMATS (--format/-f):
terminal - Color-coded terminal output with +/-/~ markers (default)
markdown - Markdown formatted output for documentation
json - JSON structured output for automation
html - Self-contained HTML report
DISPLAY MODES (--mode/-m):
unified - Standard diff view (default)
side-by-side - Two-column comparison (terminal format only)
SECTION FILTERING (--section/-s):
Implemented: system, firewall, nat, interfaces, vlans, dhcp, users, routing
Placeholders (reject with a helpful error): dns, vpn, certificates
ANALYSIS OPTIONS:
--security Show only security-relevant changes
--normalize Normalize displayed values (whitespace, IPs, ports)
--detect-order Detect rule reordering without content changes
SECURITY IMPACT SCORING:
HIGH - Permissive rules (any-any), risky configurations
MEDIUM - User changes, NAT modifications, protocol downgrades
LOW - Minor modifications with limited security relevance
RELATED:
audit - Compliance check on a single config (no comparison)
convert - Render a single config to markdown/JSON/YAML
opnDossier diff <old-config.xml> <new-config.xml> [flags]
Examples#
# Compare two configs with terminal output (default)
opnDossier diff old-config.xml new-config.xml
# Generate a markdown report
opnDossier diff old-config.xml new-config.xml -f markdown -o changes.md
# Compare only firewall rules
opnDossier diff old-config.xml new-config.xml --section firewall
# Show only security-relevant changes
opnDossier diff old-config.xml new-config.xml --security
# Generate JSON for automation
opnDossier diff old-config.xml new-config.xml -f json | jq '.changes[]'
# Generate a self-contained HTML report
opnDossier diff old-config.xml new-config.xml -f html -o report.html
# Side-by-side terminal comparison
opnDossier diff old-config.xml new-config.xml -m side-by-side
# Normalize values and detect reordering
opnDossier diff old-config.xml new-config.xml --normalize --detect-order
Options#
-o, --output string Output file path (default: print to console)
-f, --format string Output format (terminal, markdown, json, html) (default "terminal")
-m, --mode string Display mode (unified, side-by-side) (default "unified")
-s, --section strings Sections to compare (default: all)
--security Show only security-relevant changes
--normalize Normalize displayed values (whitespace, IPs, ports)
--detect-order Detect rule reordering without content changes
-h, --help help for diff
Options inherited from parent commands#
--color string Color output mode (auto, always, never) (default "auto")
--config string Configuration file path (default: $HOME/.opnDossier.yaml)
--debug Enable debug-level logging (all messages, for troubleshooting)
--device-type string Force device type (supported: opnsense, pfsense). Bypasses auto-detection.
--minimal Minimal output mode (suppresses progress and verbose messages)
--no-progress Disable progress indicators
-q, --quiet Suppress all output except errors and critical messages
--timestamps Include timestamps in log output
-v, --verbose Enable info-level logging (warnings, errors, and informational messages)
SEE ALSO#
- opnDossier - opnDossier: A CLI tool for processing OPNsense and pfSense configuration files.
