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

go install names the binary opnDossier

go install takes the binary name from the module path, so it installs opnDossier (capital D), not opndossier. On Linux and other case-sensitive filesystems the commands in this guide will not resolve until you rename it:

mv -i "$(go env GOPATH)/bin/opnDossier" "$(go env GOPATH)/bin/opndossier"

Homebrew and the release archives install opndossier directly and need no rename.

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 line such as opndossier version 1.7.2.

If you see command not found, check two things: that the Go bin directory (typically $HOME/go/bin) is on your PATH, and — if you installed via go install — that you renamed the binary as described above. ls "$(go env GOPATH)/bin" | grep -i opndossier shows which name you actually have.

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: