Configuration Reference#
Complete reference for all opnDossier configuration options. Configuration can be set via command-line flags, environment variables, or configuration file with clear precedence order.
For how configuration precedence works and worked setup recipes, see Configuring opnDossier.
Global Options#
These options are persistent flags available on all subcommands.
Logging & Output#
| Setting | CLI Flag | Environment Variable | Config File | Type | Default | Description |
|---|---|---|---|---|---|---|
| Verbose logging | --verbose | OPNDOSSIER_VERBOSE | verbose | boolean | false | Enable debug-level logging |
| Quiet mode | --quiet | OPNDOSSIER_QUIET | quiet | boolean | false | Suppress all output except errors |
| Color output | --color | OPNDOSSIER_COLOR | - | string | "auto" | Color output: auto, always, never |
| No progress | --no-progress | OPNDOSSIER_NO_PROGRESS | no_progress | boolean | false | Disable progress indicators |
| Timestamps | --timestamps | - | - | boolean | false | Include timestamps in log output |
| Minimal mode | --minimal | OPNDOSSIER_MINIMAL | minimal | boolean | false | Minimal output (suppress progress/verbose) |
| Device type | --device-type | - | - | string | "" | Force device type (auto-detected if empty) |
| Config file | --config | - | - | string | "" | Custom config file path |
Convert Command Options#
Output Control#
| Setting | CLI Flag | Environment Variable | Config File | Type | Default | Description |
|---|---|---|---|---|---|---|
| Output file | -o, --output | OPNDOSSIER_OUTPUT_FILE | output_file | string | stdout | Output file path |
| Format | -f, --format | OPNDOSSIER_FORMAT | format | string | "markdown" | Output format (see below) |
| Force | --force | - | - | boolean | false | Overwrite existing files without prompt |
Supported formats: markdown (md), json, yaml (yml), text (txt), html (htm)
Content & Formatting#
| Setting | CLI Flag | Environment Variable | Config File | Type | Default | Description |
|---|---|---|---|---|---|---|
| Sections | --section | OPNDOSSIER_SECTIONS | sections | string[] | [] | Sections: system, network, firewall, services, security |
| Wrap width | --wrap | OPNDOSSIER_WRAP | wrap | int | -1 | Text wrap width (-1=auto, 0=off, >0=cols) |
| No wrap | --no-wrap | - | - | boolean | false | Disable text wrapping (alias for --wrap 0) |
| Comprehensive | --comprehensive | - | - | boolean | false | Generate comprehensive detailed reports |
| Include tunables | --include-tunables | - | - | boolean | false | Include all system tunables in report output (markdown, text, HTML only; JSON/YAML always include all tunables) |
| Redact | --redact | - | - | boolean | false | Redact sensitive fields (passwords, keys, etc.) |
Audit Command Options#
The audit command is the dedicated entry point for security audit and compliance checks. See the audit command documentation for complete details.
Audit-Specific Flags#
| Setting | CLI Flag | Type | Default | Description |
|---|---|---|---|---|
| Audit mode | --mode | string | "blue" | Audit mode: blue (defensive audit with compliance), red (attack surface) |
| Compliance plugins | --plugins | string[] | [] | Comma-separated list: stig, sans, firewall. Only valid with --mode blue. Empty = all plugins run. |
| Plugin directory | --plugin-dir | string | "" | Directory containing third-party dynamic .so compliance plugins. Does not affect the built-in stig/sans/firewall plugins (compiled into the binary; always available). Linux/macOS/FreeBSD only — Go's plugin package is not implemented on Windows. Third-party plugins run with full process privileges; opnDossier does not verify signatures. A preflight rejects symlinks, group/world-writable files and directories, and oversize (>64 MiB) files, and every load attempt is logged with a SHA-256 digest. See audit -- Third-Party Plugin Security for the full restriction list, threat scenarios, and operator responsibilities. Failed loads are non-fatal (warnings logged). |
| Failures only | --failures-only | boolean | false | Show only failing controls in compliance tables. Only valid with --mode blue and markdown format. |
Shared Output Flags#
The audit command shares the following output and formatting flags with convert:
--format/-f-- Output format (markdown, json, yaml, text, html)--output/-o-- Output file path (cannot be used with multiple input files)--force-- Overwrite existing files without prompt--comprehensive-- Generate detailed comprehensive reports--redact-- Redact sensitive fields (passwords, keys, etc.)--wrap-- Text wrap width--no-wrap-- Disable text wrapping--include-tunables-- Include all system tunables (markdown, text, HTML only)--section-- Filter output to specific sections
Multi-File Audit Behavior#
When auditing multiple files, the --output flag cannot be used. Each report is auto-named with an -audit suffix and format extension:
# Single file: --output allowed
opndossier audit config.xml --mode blue -o security-report.md
# Multiple files: auto-named outputs (config1-audit.md, config2-audit.md)
opndossier audit config1.xml config2.xml --mode blue
Path encoding for multi-file output:
- Bare filenames:
config.xml→config-audit.md - Paths with directories:
prod/site-a/config.xml→prod_site-a_config-audit.md
Usage Examples#
# Blue team audit with all plugins (default when no --plugins specified)
opndossier audit config.xml --mode blue
# Blue team audit with specific plugins
opndossier audit config.xml --mode blue --plugins stig,sans
# Show only failing controls in blue mode
opndossier audit config.xml --mode blue --failures-only
# Red team attack surface analysis
opndossier audit config.xml --mode red
# Custom plugins directory
opndossier audit config.xml --mode blue --plugin-dir /opt/plugins
# Multi-file audit with JSON output
opndossier audit config1.xml config2.xml --mode blue --format json
Display Command Options#
| Setting | CLI Flag | Environment Variable | Config File | Type | Default | Description |
|---|---|---|---|---|---|---|
| Theme | --theme | OPNDOSSIER_THEME | theme | string | "" | Rendering theme: auto, dark, light, none |
| Sections | --section | OPNDOSSIER_SECTIONS | sections | string[] | [] | Sections: system, network, firewall, services, security |
| Wrap width | --wrap | OPNDOSSIER_WRAP | wrap | int | -1 | Text wrap width (-1=auto, 0=off, >0=cols) |
| No wrap | --no-wrap | - | - | boolean | false | Disable text wrapping |
| Comprehensive | --comprehensive | - | - | boolean | false | Generate comprehensive reports |
| Include tunables | --include-tunables | - | - | boolean | false | Include all system tunables in report output (markdown, text, HTML only; JSON/YAML always include all tunables) |
| Redact | --redact | - | - | boolean | false | Redact sensitive fields in output |
Validate Command Options#
| Setting | CLI Flag | Environment Variable | Config File | Type | Default | Description |
|---|---|---|---|---|---|---|
| JSON output | --json-output | OPNDOSSIER_JSON_OUTPUT | json_output | boolean | false | Output validation errors in JSON format |
Configuration File Format#
YAML Configuration File#
Create ~/.opnDossier.yaml with your preferred settings:
# Logging Configuration
verbose: false
quiet: false
# Output Settings
format: markdown
wrap: 120
sections: []
# File Paths
input_file: ''
output_file: ''
# Display
theme: ''
# Advanced
no_progress: false
json_output: false
minimal: false
Environment Variables#
Every configuration key has an environment-variable equivalent. Uppercase the key, replace dots with underscores, and prefix it with OPNDOSSIER_:
- Flat keys —
verbose→OPNDOSSIER_VERBOSE,input_file→OPNDOSSIER_INPUT_FILE - Nested keys —
display.width→OPNDOSSIER_DISPLAY_WIDTH,logging.level→OPNDOSSIER_LOGGING_LEVEL
Complete variable reference#
| Configuration Key | Environment Variable | Type | Default |
|---|---|---|---|
input_file | OPNDOSSIER_INPUT_FILE | string | "" |
output_file | OPNDOSSIER_OUTPUT_FILE | string | "" |
verbose | OPNDOSSIER_VERBOSE | boolean | false |
debug | OPNDOSSIER_DEBUG | boolean | false |
quiet | OPNDOSSIER_QUIET | boolean | false |
format | OPNDOSSIER_FORMAT | string | "markdown" |
theme | OPNDOSSIER_THEME | string | "" |
sections | OPNDOSSIER_SECTIONS | []string | [] |
wrap | OPNDOSSIER_WRAP | int | -1 |
json_output | OPNDOSSIER_JSON_OUTPUT | boolean | false |
minimal | OPNDOSSIER_MINIMAL | boolean | false |
no_progress | OPNDOSSIER_NO_PROGRESS | boolean | false |
display.width | OPNDOSSIER_DISPLAY_WIDTH | int | -1 |
display.pager | OPNDOSSIER_DISPLAY_PAGER | boolean | false |
display.syntax_highlighting | OPNDOSSIER_DISPLAY_SYNTAX_HIGHLIGHTING | boolean | true |
export.format | OPNDOSSIER_EXPORT_FORMAT | string | "markdown" |
export.directory | OPNDOSSIER_EXPORT_DIRECTORY | string | "" |
export.backup | OPNDOSSIER_EXPORT_BACKUP | boolean | false |
logging.level | OPNDOSSIER_LOGGING_LEVEL | string | "info" |
logging.format | OPNDOSSIER_LOGGING_FORMAT | string | "text" |
validation.strict | OPNDOSSIER_VALIDATION_STRICT | boolean | false |
validation.schema_validation | OPNDOSSIER_VALIDATION_SCHEMA_VALIDATION | boolean | false |
Value encoding#
Booleans accept true/false in any case, plus 1/0. Lists are comma-separated.
export OPNDOSSIER_VERBOSE=1
export OPNDOSSIER_SECTIONS="system,network,firewall,services,security"
export OPNDOSSIER_INPUT_FILE="/path/to/config.xml"
Configuration Validation#
opnDossier validates configuration values on startup. Invalid values will result in clear error messages:
# Invalid format
$ opndossier convert -f invalid config.xml
Error: invalid format "invalid", must be one of: markdown, md, json, yaml, yml, text, txt, html, htm
# Mutually exclusive flags
$ opndossier --verbose --quiet convert config.xml
Error: if any flags in the group [verbose quiet] are set none of the others can be
# Invalid color mode
$ opndossier --color invalid convert config.xml
Error: invalid color "invalid", must be one of: auto, always, never
Related#
- Configuring opnDossier -- precedence, recipes, and troubleshooting
- Commands Overview -- per-command flag reference
- Audit Command -- dedicated security audit and compliance checks
- XML Field Reference -- OPNsense XML schema details