convert#

The convert command is the primary way to extract useful documentation from an OPNsense configuration backup. It parses the raw XML and produces structured output in your choice of format -- Markdown for human-readable reports, JSON or YAML for programmatic consumption, or HTML for self-contained sharing.

When to use it:

• Generating network documentation from a firewall config backup
• Exporting structured data for integration with other tools or dashboards
• Creating redacted reports safe for sharing with vendors or consultants
• Batch-processing multiple configs for fleet-wide documentation

Usage#

opndossier convert [flags] <config.xml> [config2.xml ...]

Flags#

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

Device Types#

By default, opnDossier auto-detects the device type from the XML root element of the configuration file. The built-in device types are OPNsense (<opnsense>) and pfSense (<pfsense>).

The --device-type flag overrides auto-detection, which is useful if a config file has an unexpected root element or if you want to explicitly specify the parser.

opndossier convert config.xml --device-type opnsense

opnDossier includes built-in parsers for OPNsense and pfSense. The device type system is extensible -- additional device types (e.g., Fortinet) can be added via parser plugins. Use opndossier convert --device-type <TAB> to see all available device types via shell completion. See the Plugin Development Guide for details on creating device parsers.

Sections#

By default, all sections are included in the output. Use --section to limit output to specific areas of the configuration. This is useful when you only need to document or audit a particular domain -- for example, generating a firewall-only report for a security review.

opndossier convert config.xml --section firewall,network -o network-security.md

System Tunables#

OPNsense allows administrators to set kernel-level parameters (sysctl values) that control low-level system behavior -- things like TCP buffer sizes, IP forwarding, and connection tracking limits. These are configured under System > Settings > Tunables in the OPNsense web interface.

By default, only security-related tunables (IP forwarding, TCP/UDP blackhole) are included in output. The --include-tunables flag adds all tunables -- including performance tuning, buffer sizes, and other kernel parameters:

opndossier convert config.xml --include-tunables -o full-report.md

When included, tunables appear as a table with three columns: the sysctl parameter name, its value, and its description.

Comprehensive Mode#

By default, convert produces a baseline report covering the core sections: system settings, interfaces, firewall rules, NAT, and services. The --comprehensive flag generates a more detailed report that adds:

• VLAN configuration
• Static routes
• IPsec VPN configuration
• OpenVPN configuration
• High Availability / CARP
• All system tunables (comprehensive mode implies --include-tunables)

Use comprehensive mode when you need a complete picture of the device -- for example, when onboarding a new firewall, performing a full audit, or creating handover documentation.

opndossier convert config.xml --comprehensive -o full-documentation.md

Redacting Sensitive Data#

The --redact flag replaces sensitive field values with [REDACTED] in the output. This lets you generate reports that are safe to share without exposing credentials or secrets.

Fields that are redacted:

• Passwords (HA sync password, user passwords)
• Private keys (certificates, certificate authorities)
• API key secrets
• SNMP community strings
• WireGuard pre-shared keys
• DHCPv6 key info secrets

# Generate a redacted report for sharing with a vendor
opndossier convert config.xml --redact -o report-for-vendor.md

# Combine with comprehensive for a full but safe report
opndossier convert config.xml --comprehensive --redact -o full-redacted.md

For full XML-level sanitization (replacing IPs, hostnames, and all identifying data), see the sanitize command instead.

Output Formats#

Security Audits#

Security auditing and compliance checks are handled by the dedicated audit command, not convert.

Supported audit modes:

Available compliance plugins in blue mode: stig, sans, firewall.

Multiple Files#

When processing multiple files, the --output flag is ignored. Each output file is named based on its input file with the appropriate extension.

Examples#

# Convert to markdown and save to file
opndossier convert config.xml -o documentation.md

# Convert to JSON with forced overwrite
opndossier convert config.xml -f json -o output.json --force

# Convert multiple files to JSON (auto-named outputs)
opndossier convert -f json config1.xml config2.xml

Related#

• CLI Reference — convert -- auto-generated exhaustive flag list
• audit -- run security audits with compliance checks
• display -- render in terminal instead of writing to file
• validate -- check config correctness before converting
• Configuration Reference -- global flags and settings