ufm-config-diff 1.0.3

Production-ready UFM configuration comparison tool with automated email reports, interactive HTML tables, and CI/CD support via --yes flag

UFM Configuration Differentiator Tool

A powerful, production-ready tool to compare UFM (Unified Fabric Manager) configurations between two NVIDIA Docker images with advanced interactive HTML reports, table sorting/filtering, and email notifications.

⚡ Quick Start

# Install the tool
pip install ufm-config-diff --break-system-packages
# or
pipx install ufm-config-diff

# Run complete comparison with email and automation
ufm-config-diff ufm_6.20.0-1.ubuntu22.x86_64-docker.img.gz \
                ufm_6.21.0-8.ubuntu22.x86_64-docker.img.gz \
                nvidia-ufm-enterprise-evaluation.lic \
                --email [e-mail] \
                --yes

🚀 Features

Core Functionality

• Docker Image Comparison: Compare UFM configurations between two Docker images
• Automatic Version Detection: Extract and compare UFM, SHARP, MFT, and OpenSM versions
• Configuration Analysis: Identify differences in 5+ configuration files (gv.cfg, opensm.conf, sharp_am.cfg, mft.conf, etc.)
• Smart Version Ordering: Automatically displays higher version on the right for easier comparison

Interactive HTML Reports

• 📊 Advanced Table Sorting: Click column headers to sort ascending/descending
• 🔍 Real-time Filtering: Search across all table content with instant results
• 🏷️ Status-based Filters: Filter by Modified/New Parameter/Deleted Parameter
• 🎨 Color-coded Status: Visual indicators for different change types
• 📱 Responsive Design: Works perfectly on desktop and mobile devices
• 🖨️ Print-friendly: Clean printing with hidden controls

Professional Features

• 📧 Email Reports: Send HTML reports with version comparison tables
• ⚡ Auto-yes Mode: Non-interactive mode for automation and CI/CD
• 🔧 Network Interface Support: Configure fabric and management interfaces
• 📁 Results Persistence: Save configuration files for future reference
• 🎯 Zero External Dependencies: Self-contained JavaScript functionality

📦 Installation

Install from PyPI

Method 1: Using pipx (Recommended for CLI tools)

# Install pipx if not available
sudo apt install pipx  # On Ubuntu/Debian
# or
brew install pipx      # On macOS

# Install ufm-config-diff
pipx install ufm-config-diff

Method 2: Using virtual environment (Recommended for development)

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install ufm-config-diff

Method 3: System-wide installation (Advanced users)

# For systems with externally-managed-environment restrictions
pip install ufm-config-diff --break-system-packages

# Standard installation (older Python versions)
pip install ufm-config-diff

Install from Source

git clone https://github.com/Mellanox/ufm-config-diff.git
cd ufm-config-diff

# Using virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
pip install .

# Or system-wide (if needed)
pip install . --break-system-packages

Development Installation

git clone https://github.com/Mellanox/ufm-config-diff.git
cd ufm-config-diff

# Using virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
pip install -e .

# Or system-wide (if needed)
pip install -e . --break-system-packages

🔧 Package Management

Upgrade to Latest Version

pip install --upgrade ufm-config-diff

Check Current Version

pip show ufm-config-diff

Uninstall

pip uninstall ufm-config-diff

📋 Prerequisites

• Python: 3.6 or higher
• Docker: Installed and running
• System Access: Root/sudo privileges for Docker operations
• Network Ports: Free ports required by UFM (80, 443, 8000, 6306, 8005, 8888, 2022)
• InfiniBand Interface: Configured with IP address and in "up" state (if comparing IB configurations)

🎯 Usage Examples

Main Example (Recommended)

# Complete UFM configuration comparison with email notification and automation
ufm-config-diff ufm_6.20.0-1.ubuntu22.x86_64-docker.img.gz \
                ufm_6.21.0-8.ubuntu22.x86_64-docker.img.gz \
                nvidia-ufm-enterprise-evaluation.lic \
                --email [e-mail] \
                --yes

Basic Usage

# Simple comparison between two UFM Docker images
ufm-config-diff old_image.tar.gz new_image.tar.gz license_file.lic

# Interactive mode (will prompt for confirmations)
ufm-config-diff ufm_6.20.0-1.ubuntu22.x86_64-docker.img.gz \
                ufm_6.21.0-8.ubuntu22.x86_64-docker.img.gz \
                nvidia-ufm-enterprise-evaluation.lic

Advanced Usage

# With network interface configuration
ufm-config-diff old_image.tar.gz new_image.tar.gz license_file.lic \
                --fabric-interface ib0 \
                --mgmt-interface eth0 \
                --email [e-mail] \
                --yes

# With custom output file and timestamp
ufm-config-diff old_image.tar.gz new_image.tar.gz license_file.lic \
                ufm_comparison_report_$(date +%Y%m%d_%H%M%S).html \
                --yes

# Automation-ready with all options
ufm-config-diff old_image.gz new_image.gz license.lic \
                --fabric-interface ib0 \
                --mgmt-interface eth0 \
                --email [e-mail] \
                --yes

Using the Standalone Report Generator

# Generate report from existing configuration files
python -m ufm_config_diff.create_simple_table_report

📊 Interactive HTML Report Features

The generated HTML reports include:

🔍 Filtering & Search

• Text Search: Type in the search box to filter across all content
• Status Filters: Click buttons to show only Modified/New/Deleted parameters
• Clear Filters: Reset all filters with one click

📈 Sorting

• Column Headers: Click any column header to sort
• Visual Indicators: ↑ (ascending) / ↓ (descending) arrows
• Smart Status Sorting: Modified → New → Deleted order

🎨 Visual Design

• Color-coded Rows:
  • 🟡 Yellow: Modified parameters
  • 🟢 Green: New parameters added
  • 🔴 Red: Parameters deleted
• Professional Styling: NVIDIA-branded design
• Responsive Layout: Adapts to screen size

📧 Email Integration

• HTML Email Body: Includes version comparison table
• Professional Formatting: Clean, corporate-style emails
• Attachment Support: Full HTML report attached

🔧 Configuration Files Analyzed

File	Description	Version Extraction
gv.cfg	UFM Global View configuration	✅
opensm.conf	OpenSM subnet manager configuration	✅
sharp_am.cfg	SHARP aggregation manager configuration	✅
mft.conf	Mellanox Firmware Tools configuration	✅
ufm_version	UFM version information	✅

📁 Output Structure

results/
├── old_configs/           # Server 1 configuration files
│   ├── gv.cfg
│   ├── opensm.conf
│   ├── sharp_am.cfg
│   ├── mft.conf
│   └── ufm_version
├── new_configs/           # Server 2 configuration files
│   └── [same files]
├── version_comparison.md  # Human-readable version report
├── version_comparison.json # Machine-readable version data
└── ufm_comparison_report_YYYYMMDD_HHMMSS.html # Interactive report

🚨 Troubleshooting

Common Issues

Externally-Managed-Environment Error

# Error: externally-managed-environment
# Solution 1: Use pipx (recommended)
sudo apt install pipx
pipx install ufm-config-diff

# Solution 2: Use virtual environment
python3 -m venv venv
source venv/bin/activate
pip install ufm-config-diff

# Solution 3: Override system protection (advanced users only)
pip install ufm-config-diff --break-system-packages

Docker Permission Denied

sudo usermod -aG docker $USER
# Log out and log back in

Port Already in Use

# Check what's using UFM ports
sudo netstat -tulpn | grep -E ':(80|443|8000|6306|8005|8888|2022)\s'

UFM Already Installed

# The tool will automatically detect and offer to uninstall
# Or use --yes flag for automatic handling
ufm-config-diff old.gz new.gz license.lic --yes

Email Not Sending

# Set SMTP server environment variable
export SMTP_SERVER=your-smtp-server.com
ufm-config-diff old.gz new.gz license.lic --email [e-mail]

Command Not Found After Installation

# If installed with pipx, ensure pipx bin directory is in PATH
pipx ensurepath

# If installed in virtual environment, make sure it's activated
source venv/bin/activate

# If installed system-wide, try:
which ufm-config-diff

🔄 Version History

v1.0.0 (Latest)

• ✅ Interactive table sorting and filtering
• ✅ Black status column text for better readability
• ✅ Enhanced email reports with version comparison
• ✅ Improved MFT version extraction
• ✅ Font consistency across all tables
• ✅ Professional timestamped report filenames
• ✅ Zero external dependencies

v0.2.0

• Basic UFM configuration comparison
• HTML report generation
• Docker image support

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Email: [e-mail]

🏢 About NVIDIA

This tool is developed and maintained by NVIDIA for the InfiniBand and Ethernet networking community.

---

Made with ❤️ by NVIDIA