Skip to content

Getting Started with opnDossier

By the end of this tutorial, you will have installed opnDossier and generated your first configuration report.

Prerequisites

  • An OPNsense config.xml file (exported from your firewall via System > Configuration > Backups)

1. Install opnDossier

Pick the method that fits your platform:

macOS (Homebrew):

brew install EvilBit-Labs/tap/opndossier

Go (any platform with Go 1.26+):

go install github.com/EvilBit-Labs/opnDossier@latest

Linux packages, Docker, and pre-built binaries are also available -- see the Installation Guide for all options.

Expected result: the opndossier command is now available in your shell.

2. Verify the Installation

opndossier version

Expected result: a version string such as opnDossier v0.9.0.

If you see command not found, ensure the Go bin directory (typically $HOME/go/bin) is in your PATH.

3. Convert a Config to Markdown

Generate a Markdown report from your OPNsense configuration:

opndossier convert config.xml

Expected result: Markdown output printed to your terminal, including sections for interfaces, firewall rules, VPN tunnels, and other configured services.

4. Save the Report to a File

Write the report directly to a file instead of stdout:

opndossier convert config.xml -o report.md

Expected result: opnDossier writes the report without any terminal output. Open report.md in any Markdown viewer to browse the full report.

5. View in the Terminal

Display the configuration with terminal styling and syntax highlighting:

opndossier display config.xml

Expected result: a styled, color-highlighted overview of your configuration rendered directly in the terminal.

6. Validate a Config

Check your configuration for structural issues:

opndossier validate config.xml

Expected result: a validation summary. If the configuration is well-formed, you will see a message confirming validation passed.

Next Steps

You now have the basics down. Explore further: