Skip to content

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):

  1. Command-line flags - Direct CLI arguments
  2. Environment variables - OPNDOSSIER_* prefixed variables
  3. Configuration file - ~/.opnDossier.yaml
  4. 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: