OPNsense Configuration Processor#

Welcome to the OPNsense Configuration Processor documentation! This CLI tool helps you process OPNsense config.xml files and convert them to human-readable markdown format.

Features#

Parse OPNsense XML configurations - Process complex configuration files with ease
Configuration Validation - Comprehensive validation with detailed error reporting
Convert to Markdown - Generate human-readable documentation
Terminal Display - View results with syntax highlighting in your terminal
Export to Files - Save processed configurations to markdown files
Offline Operation - Works completely offline, no external dependencies
Streaming Processing - Memory-efficient handling of large configuration files

Quick Start#

# Convert a configuration file to markdown
opndossier convert config.xml -o output.md

# Display the result in terminal with syntax highlighting
opndossier display config.xml

# Get help for any command
opndossier --help

Project Philosophy#

This tool follows the operator-focused philosophy:

Built for operators, by operators - Intuitive workflows designed for network administrators
Offline-first architecture - Functions in airgapped environments
Structured data approach - Versioned, portable, and auditable outputs
Framework-first development - Leverages established Go libraries and patterns

Architecture#

The tool uses a layered CLI architecture built with modern Go libraries:

Component	Technology	Purpose
CLI Framework	Cobra	Command structure & argument parsing
Configuration	Viper	Layered configuration (files, env, flags)
CLI Enhancement	Charm Fang	Enhanced UX layer (styled help, completion)
Structured Logging	Charm Log	Structured, leveled logging
Terminal Styling	Charm Lipgloss	Styled terminal output formatting
Markdown Rendering	Charm Glamour	Markdown rendering in terminal
XML Processing	Go's built-in `encoding/xml`	Native XML parsing and validation

Data Model Architecture#

opnDossier uses a hierarchical model structure that organizes OPNsense configuration into logical domains:

System Domain: Core system settings, users, groups, system services
Network Domain: Interfaces, routing, VLANs, network addressing
Security Domain: Firewall rules, NAT, VPN, certificates
Services Domain: DNS, DHCP, monitoring, web services

This hierarchical approach provides logical organization, improved maintainability, domain-specific validation, and better extensibility.

Processor Workflow#

The processor implements a comprehensive four-phase pipeline:

Normalize: Fill defaults, canonicalize addresses, sort for determinism
Validate: Struct tag validation, custom checks, cross-field validation
Analyze: Dead rule detection, security analysis, performance checks
Transform: Multi-format output (Markdown, JSON, YAML)

Configuration Management#

opnDossier implements comprehensive configuration management with Viper:

Precedence Order (highest to lowest):

Command-line flags
Environment variables (OPNDOSSIER_*)
Configuration file (~/.opnDossier.yaml)
Default values

Configuration Options:

verbose: Enable debug logging
quiet: Suppress all output except errors
input_file: Default input file path
output_file: Default output file path

Validation & Error Handling#

opnDossier includes comprehensive validation capabilities:

Validation Features#

Structure Validation - Ensures required fields are present (hostname, domain, etc.)
Data Type Validation - Verifies IP addresses, subnet masks, and network configurations
Cross-Field Validation - Checks relationships between configuration elements
Streaming Limits - Handles large files efficiently with memory-conscious processing

Error Output Examples#

Parse Error:

parse error at line 45, column 12: XML syntax error: expected element name after <

Validation Error:

validation error at opnsense.system.hostname: hostname is required

Aggregated Report:

validation failed with 3 errors: hostname is required (and 2 more)
  - opnsense.system.hostname: hostname is required
  - opnsense.system.domain: domain is required
  - opnsense.interfaces.lan.subnet: subnet mask '35' must be valid (0-32)

Getting Started#

Check out the Getting Started tutorial, or browse the Commands Overview for the full command reference.

Documentation#

User Documentation#

Getting Started - Tutorial to process your first configuration
User Guide - Commands, configuration, and workflows
Examples - Comprehensive usage examples and common workflows
About - Project overview and features
API Reference - Command-line interface and API documentation

Developer Documentation#

Architecture - System design and component interactions
Development Standards - Go coding standards and project structure
Release Process - How to prepare and release new versions
API Reference - Full internal API documentation
Plugin Development - Plugin development guide
Contributing - How to contribute

For AI agent coding standards and workflows, see AGENTS.md in the root directory.

Compliance & Reference#

Compliance Standards - Security and compliance framework documentation
Firewall Security Controls Reference - Firewall configuration best practices reference

Technical Research#

Theme Usage - Internal guidance for local documentation theme usage and customization

Contributing#

Interested in contributing? See our Contributing Guide for information on how to get involved with the project.

This documentation is built with MkDocs Material and follows our established documentation standards.