Advanced Configuration Examples#

This guide covers advanced configuration options and customization techniques for opnDossier.

Theme Customization#

Built-in Themes#

opnDossier supports four display themes for terminal rendering. For detailed information on themes, see the display command reference.

# Auto-detect theme based on terminal
opndossier display config.xml --theme auto

# Use light theme
opndossier display config.xml --theme light

# Use dark theme
opndossier display config.xml --theme dark

# No theme (plain text output)
opndossier display config.xml --theme none

Available themes: auto (default), dark, light, none.

Section Filtering#

Basic Section Filtering#

For more details on section filtering, see the display command reference and convert command reference.

# Display only system information
opndossier display config.xml --section system

# Display network and firewall sections
opndossier display config.xml --section network,firewall

# Display multiple sections
opndossier display config.xml --section system,network,firewall

# Convert only specific sections
opndossier convert config.xml --section system,network -o partial-report.md

Output Formatting#

Text Wrapping#

# Set text wrap width (allowed: 40-200, recommended: 80-120)
opndossier display config.xml --wrap 80

# Wide format for large screens
opndossier display config.xml --wrap 160

# Disable text wrapping entirely
opndossier display config.xml --no-wrap

# Auto-detect terminal width (default behavior)
opndossier display config.xml --wrap -1

The --wrap and --no-wrap flags are mutually exclusive.

Comprehensive Reports#

For detailed information on comprehensive mode and system tunables, see the convert command reference.

# Generate detailed comprehensive report
opndossier convert config.xml --comprehensive -o detailed-report.md

# Include all system tunables in the report (markdown/text/HTML only)
opndossier convert config.xml --include-tunables -o tunables-report.md

# Combine comprehensive with tunables
opndossier convert config.xml --comprehensive --include-tunables -o full-report.md

# Display all tunables directly in the terminal
opndossier display config.xml --include-tunables

Note: The --include-tunables flag affects only markdown, text, and HTML output formats. By default, these formats show only security-related tunables. When the flag is enabled, all system tunables are included. JSON and YAML exports always include all tunables regardless of this flag setting.

Custom Output Formats#

JSON with Custom Processing#

# Convert to JSON and extract specific data with jq
opndossier convert config.xml -f json | jq '{
  hostname: .system.hostname,
  domain: .system.domain,
  interfaces: .interfaces
}'

YAML with Filtering#

# Convert to YAML and extract sections with yq
opndossier convert config.xml -f yaml | yq '.system'

Configuration File#

Basic Configuration#

For complete details on configuration options and precedence, see the Configuration Guide and Configuration Reference.

Create ~/.opnDossier.yaml for persistent settings:

# Logging configuration
verbose: false
quiet: false

# Output settings
format: markdown
wrap: 120

# Content options
sections: []

Using a Custom Config File#

# Use a project-specific config
opndossier --config ./project-config.yaml convert config.xml

# Override specific settings from the config file
opndossier --config ./project-config.yaml --verbose convert config.xml

Configuration Precedence#

Settings are applied in this order (highest to lowest priority):

Command-line flags - Direct CLI arguments
Environment variables - OPNDOSSIER_* prefixed variables
Configuration file - ~/.opnDossier.yaml
Default values - Built-in defaults

For more information on configuration precedence and best practices, see the Configuration Guide.

Advanced Workflows#

Multi-Format Generation#

#!/bin/bash
# multi-format-generator.sh

CONFIG_FILE="$1"
OUTPUT_DIR="$2"

# Create output directory
mkdir -p "$OUTPUT_DIR"

# Generate multiple formats
opndossier convert "$CONFIG_FILE" -o "$OUTPUT_DIR/network-config.md"
opndossier convert "$CONFIG_FILE" -f json -o "$OUTPUT_DIR/network-config.json"
opndossier convert "$CONFIG_FILE" -f yaml -o "$OUTPUT_DIR/network-config.yaml"
opndossier convert "$CONFIG_FILE" -f html -o "$OUTPUT_DIR/network-config.html"

echo "Multi-format generation completed in $OUTPUT_DIR"

Conditional Processing#

For detailed information on validation, see the validate command reference.

#!/bin/bash
# conditional-processing.sh

CONFIG_FILE="$1"

# Validate before any processing
if ! opndossier validate "$CONFIG_FILE"; then
    echo "Configuration validation failed"
    exit 1
fi

# Generate configuration report
opndossier convert "$CONFIG_FILE" \
    --comprehensive \
    -o config-report.md

# Generate JSON export for programmatic processing
opndossier convert "$CONFIG_FILE" \
    -f json \
    -o config-data.json

echo "Processing complete"

Parallel Processing#

# Process multiple files in parallel
find configs/ -name "*.xml" | xargs -P 4 -I {} \
    opndossier convert {} -o docs/{}.md

# Batch processing with parallel execution
for config in configs/*.xml; do
    opndossier convert "$config" -o "docs/$(basename "$config" .xml).md" &
done
wait

Environment Variables#

All configuration options can be set via environment variables:

# Logging preferences
export OPNDOSSIER_VERBOSE=true
export OPNDOSSIER_QUIET=false

# Output settings
export OPNDOSSIER_FORMAT=json
export OPNDOSSIER_WRAP=100

# Use in scripts
opndossier convert config.xml -o output.json

Best Practices#

For a comprehensive guide to configuration best practices, see the Configuration Guide.

1. Use Configuration Files for Persistent Settings#

# Store frequently used settings in ~/.opnDossier.yaml
cat > ~/.opnDossier.yaml << 'EOF'
verbose: false
format: markdown
wrap: 120
EOF

2. Use Environment Variables for CI/CD#

#!/bin/bash
# ci-pipeline.sh

export OPNDOSSIER_QUIET=true
export OPNDOSSIER_FORMAT=json

opndossier convert config.xml -o report.json

3. Use CLI Flags for One-off Overrides#

# Debug a specific run
opndossier --verbose convert problematic-config.xml

# Generate output in a different format temporarily
opndossier convert config.xml -f yaml -o temp-output.yaml

Next Steps:

For basic documentation, see Basic Documentation
For automation, see Automation and Scripting
For troubleshooting, see Troubleshooting
For command reference, see Commands Overview