Skip to content

Troubleshooting and Debugging Examples

This guide covers common issues, error handling, and debugging techniques for opnDossier.

Common Error Scenarios

XML Parsing Errors

Invalid XML Structure

# Error: Invalid XML syntax
opnDossier convert invalid-config.xml
# Output: failed to parse XML from invalid-config.xml: XML syntax error on line 42

# Debug XML issues
opnDossier --verbose convert invalid-config.xml

# Validate XML syntax first
xmllint --noout invalid-config.xml

Malformed OPNsense Configuration

# Error: Missing required elements
opnDossier convert malformed-config.xml
# Output: validation error at opnsense.system.hostname: hostname is required

# Debug with verbose output
opnDossier --verbose convert malformed-config.xml

# Check specific validation errors
opnDossier validate malformed-config.xml

File Permission Issues

# Error: Permission denied
opnDossier convert /root/config.xml
# Output: failed to open file /root/config.xml: permission denied

# Solutions:
# 1. Copy file to accessible location
sudo cp /root/config.xml ./config.xml
opnDossier convert config.xml

# 2. Change file permissions (if appropriate)
sudo chmod 644 /root/config.xml

# 3. Run with appropriate permissions
sudo opnDossier convert /root/config.xml

Configuration Validation Errors

# Error: Conflicting flags
opnDossier --verbose --quiet convert config.xml
# Output: verbose and quiet options are mutually exclusive

# Error: Invalid output format
opnDossier convert config.xml -f txt
# Output: unsupported format: txt

Debug Techniques

Verbose Debugging

# Enable verbose output for detailed debugging
opnDossier --verbose convert config.xml

# Combine verbose with other flags
opnDossier --verbose convert config.xml --format json

Step-by-Step Debugging

# 1. Validate configuration first
opnDossier validate config.xml

# 2. Test basic conversion
opnDossier convert config.xml

# 3. Test with specific format
opnDossier convert config.xml -f json

# 4. Test with specific sections
opnDossier convert config.xml --section system

Common Issues and Solutions

Issue 1: Large File Processing

Symptoms:

  • Slow processing
  • High memory usage
  • Timeout errors

Solutions:

# Use built-in optimization
opnDossier convert large-config.xml

# Monitor memory usage
/usr/bin/time -v opnDossier convert large-config.xml

# Process in sections
opnDossier convert large-config.xml --section system,interfaces
opnDossier convert large-config.xml --section firewall,nat

Issue 2: Output File Issues

Symptoms:

  • File not created
  • Permission errors
  • Overwrite prompts

Solutions:

# Check output directory permissions
ls -la /path/to/output/directory

# Force overwrite
opnDossier convert config.xml -o output.md --force

# Use different output location
opnDossier convert config.xml -o /tmp/output.md

# Check disk space
df -h /path/to/output/directory

Advanced Debugging

Memory Profiling

# Run with memory profiling
go tool pprof -http=:8080 $(which opnDossier) mem.prof

# Generate memory profile
opnDossier convert config.xml -o output.md
# (Memory profile is automatically generated for large files)

Performance Analysis

# Measure execution time
time opnDossier convert config.xml

# Profile CPU usage
go tool pprof -http=:8080 $(which opnDossier) cpu.prof

# Analyze specific operations
opnDossier --verbose convert config.xml 2>&1 | grep "duration"

Network Debugging (if applicable)

# Check for network calls (should be none in offline mode)
strace -e trace=network opnDossier convert config.xml

# Monitor file system access
strace -e trace=file opnDossier convert config.xml

# Check for external dependencies
ldd $(which opnDossier)

Error Recovery

Recovering from Validation Errors

# 1. Identify specific validation errors
opnDossier validate config.xml

# 2. Fix common issues
# Missing hostname
sed -i 's/<hostname><\/hostname>/<hostname>firewall<\/hostname>/' config.xml

# Invalid IP address
sed -i 's/<ipaddr>256.256.256.256<\/ipaddr>/<ipaddr>192.168.1.1<\/ipaddr>/' config.xml

# 3. Re-validate
opnDossier validate config.xml

# 4. Convert if valid
opnDossier convert config.xml

Diagnostic Scripts

Configuration Health Check

#!/bin/bash
# config-health-check.sh

CONFIG_FILE="$1"
LOG_FILE="health-check.log"

echo "Configuration Health Check for $CONFIG_FILE" > "$LOG_FILE"
echo "Started at $(date)" >> "$LOG_FILE"

# Check file existence
if [ ! -f "$CONFIG_FILE" ]; then
    echo "ERROR: File not found: $CONFIG_FILE" >> "$LOG_FILE"
    exit 1
fi

# Check file size
FILE_SIZE=$(stat -c%s "$CONFIG_FILE")
echo "File size: $FILE_SIZE bytes" >> "$LOG_FILE"

# Check file permissions
FILE_PERMS=$(stat -c%a "$CONFIG_FILE")
echo "File permissions: $FILE_PERMS" >> "$LOG_FILE"

# Validate XML syntax
if xmllint --noout "$CONFIG_FILE" 2>/dev/null; then
    echo "XML syntax: VALID" >> "$LOG_FILE"
else
    echo "XML syntax: INVALID" >> "$LOG_FILE"
    exit 1
fi

# Run opnDossier validation
if opnDossier validate "$CONFIG_FILE" >> "$LOG_FILE" 2>&1; then
    echo "opnDossier validation: PASSED" >> "$LOG_FILE"
else
    echo "opnDossier validation: FAILED" >> "$LOG_FILE"
    exit 1
fi

# Test conversion
if opnDossier convert "$CONFIG_FILE" -o /tmp/test.md >> "$LOG_FILE" 2>&1; then
    echo "Conversion test: PASSED" >> "$LOG_FILE"
    rm -f /tmp/test.md
else
    echo "Conversion test: FAILED" >> "$LOG_FILE"
    exit 1
fi

echo "Health check completed successfully at $(date)" >> "$LOG_FILE"

Performance Diagnostic

#!/bin/bash
# performance-diagnostic.sh

CONFIG_FILE="$1"
RESULTS_FILE="performance-results.log"

echo "Performance Diagnostic for $CONFIG_FILE" > "$RESULTS_FILE"
echo "Started at $(date)" >> "$RESULTS_FILE"

# Measure validation time
echo "Measuring validation time..." >> "$RESULTS_FILE"
VALIDATION_TIME=$(/usr/bin/time -f "%e" opnDossier validate "$CONFIG_FILE" 2>&1)
echo "Validation time: ${VALIDATION_TIME}s" >> "$RESULTS_FILE"

# Measure conversion time
echo "Measuring conversion time..." >> "$RESULTS_FILE"
CONVERSION_TIME=$(/usr/bin/time -f "%e" opnDossier convert "$CONFIG_FILE" -o /tmp/test.md 2>&1)
echo "Conversion time: ${CONVERSION_TIME}s" >> "$RESULTS_FILE"

# Measure memory usage
echo "Measuring memory usage..." >> "$RESULTS_FILE"
MEMORY_USAGE=$(/usr/bin/time -f "%M" opnDossier convert "$CONFIG_FILE" -o /tmp/test.md 2>&1)
echo "Memory usage: ${MEMORY_USAGE}KB" >> "$RESULTS_FILE"

# Clean up
rm -f /tmp/test.md

echo "Performance diagnostic completed at $(date)" >> "$RESULTS_FILE"

Error Pattern Analysis

#!/bin/bash
# error-pattern-analysis.sh

LOG_FILE="$1"
ANALYSIS_FILE="error-analysis.log"

echo "Error Pattern Analysis for $LOG_FILE" > "$ANALYSIS_FILE"

# Extract error messages
echo "=== ERROR MESSAGES ===" >> "$ANALYSIS_FILE"
grep -i "error\|failed\|invalid" "$LOG_FILE" >> "$ANALYSIS_FILE"

# Count error types
echo "=== ERROR COUNTS ===" >> "$ANALYSIS_FILE"
grep -i "error\|failed\|invalid" "$LOG_FILE" | sort | uniq -c | sort -nr >> "$ANALYSIS_FILE"

# Extract timing information
echo "=== TIMING INFORMATION ===" >> "$ANALYSIS_FILE"
grep -i "duration\|time\|elapsed" "$LOG_FILE" >> "$ANALYSIS_FILE"

# Extract validation errors
echo "=== VALIDATION ERRORS ===" >> "$ANALYSIS_FILE"
grep -i "validation" "$LOG_FILE" >> "$ANALYSIS_FILE"

echo "Error pattern analysis completed" >> "$ANALYSIS_FILE"

Best Practices for Troubleshooting

1. Systematic Approach

# Always start with validation
opnDossier validate config.xml

# Test basic functionality
opnDossier convert config.xml

# Add complexity gradually
opnDossier convert config.xml -f json
opnDossier convert config.xml --comprehensive
opnDossier convert config.xml --section system,interfaces

2. Error Handling in Scripts

#!/bin/bash
# robust-script.sh

set -e  # Exit on any error

# Function to handle errors
handle_error() {
    local exit_code=$?
    echo "Error occurred in line $1, exit code: $exit_code"

    # Log error details
    echo "$(date): Error in $0 at line $1, exit code: $exit_code" >> error.log

    # Send notification if needed
    # curl -X POST -H 'Content-type: application/json' \
    #     --data "{\"text\":\"Error in opnDossier script\"}" \
    #     "$WEBHOOK_URL"

    exit $exit_code
}

# Set error handler
trap 'handle_error $LINENO' ERR

# Your script logic here
opnDossier validate config.xml
opnDossier convert config.xml -o output.md

3. Environment Isolation

# Test in clean environment
env -i PATH=/usr/bin:/bin opnDossier convert config.xml

# Test with minimal configuration
opnDossier --config /dev/null convert config.xml

# Test with specific environment variables
OPNDOSSIER_OUTPUT_FILE=./docs/network.md opnDossier convert config.xml

Next Steps: