# Modernize4Linux v4.7.7

**Zero-Downtime Linux Migration & Modernization Tool**

Modernize4Linux automates the migration of Linux systems from legacy distributions to modern ones (e.g., CentOS 7 → Rocky Linux 9, Ubuntu 18.04 → Ubuntu 22.04) with minimal downtime and maximum data preservation.

## 🆕 What's New in 4.7.0

**Intelligent Repository Auto-Enablement**
- 🎯 Automatically detects when packages need EPEL or PowerTools/CRB repositories
- 💬 Interactive prompts let you approve repos with full context
- 🔒 Safe defaults for enterprise/compliance environments
- 📊 Solves the `libssh2`, `htop`, and development package availability issues
- 📖 See `REPOSITORY_AUTO_ENABLEMENT.md` for complete documentation

---

## 🚀 Quick Installation (Recommended)

Install Modernize4Linux with a single command:

```bash
curl -fsSL https://www.cyberautomation.com.au/Modernize/Linux/4.7.7install.sh | sudo bash
```

This installer will:
- ✓ Auto-detect your system architecture (amd64/arm64)
- ✓ Download the latest version
- ✓ Verify GPG signatures and SHA256 checksums
- ✓ Install to `/usr/local/bin/Modernize4Linux`

---

## 📦 Manual Installation

If you prefer manual installation or want to verify downloads yourself:

### Step 1: Download Binary

```bash
# For x86_64/AMD64 systems (most common)
wget https://www.cyberautomation.com.au/Modernize/Linux/4.7.7/Modernize4Linux-amd64

# For ARM64 systems
wget https://www.cyberautomation.com.au/Modernize/Linux/4.7.7/Modernize4Linux-arm64
```

### Step 2: Verify Binary (CRITICAL)

**⚠️ SECURITY WARNING:** Always verify binaries before running them!

#### Option A: Automatic Verification (Recommended)

```bash
wget https://www.cyberautomation.com.au/Modernize/Linux/4.7.7/verify.sh
bash verify.sh
```

#### Option B: Manual Verification

```bash
# Download checksums and signatures
wget https://www.cyberautomation.com.au/Modernize/Linux/4.7.7/SHA256SUMS
wget https://www.cyberautomation.com.au/Modernize/Linux/4.7.7/SHA256SUMS.asc
wget https://www.cyberautomation.com.au/Modernize/Linux/4.7.7/GPG-PUBLIC-KEY.asc

# Import GPG key
gpg --import GPG-PUBLIC-KEY.asc

# Verify checksum signature
gpg --verify SHA256SUMS.asc SHA256SUMS

# Verify binary checksum
sha256sum -c SHA256SUMS --ignore-missing
```

Expected output: `Modernize4Linux-amd64: OK`

**❌ DO NOT PROCEED** if verification fails.

### Step 3: Install Binary

```bash
# Make executable
chmod +x Modernize4Linux-amd64

# Move to system path
sudo mv Modernize4Linux-amd64 /usr/local/bin/Modernize4Linux
```

---

## 🎯 Getting Started

### First Run - Configuration Wizard

Simply run the command. Modernize4Linux will launch an interactive configuration wizard:

```bash
Modernize4Linux
```

### Configuration Modes

Choose from three configuration modes:

#### 1. **Quick Start** (Recommended - 2 minutes)
- Minimal questions with smart defaults
- Auto-detects MySQL, PostgreSQL, services
- Best for most migrations

#### 2. **Standard Configuration** (5 minutes)
- Common customization options
- More control over migration settings
- Transfer method selection
- Network migration options

#### 3. **Advanced Configuration** (10 minutes)
- Full control over all options
- For complex migration scenarios
- Detailed service management
- Custom directory selection

### Interactive Questions

The wizard will ask you:

1. **License Key** (required)
   - Your Modernize4Linux license key
   - Validates immediately

2. **Destination IP/Hostname** (required)
   - IP address or hostname of destination system
   - Tests SSH connectivity automatically

3. **Database Passwords** (if detected)
   - MySQL password (if MySQL is running)
   - PostgreSQL password (if PostgreSQL is running)
   - **Security Note:** Can use environment variables instead:
     ```bash
     export MYSQL_PASSWORD="your-password"
     export PGPASSWORD="your-postgres-password"
     ```

4. **Configuration Review**
   - Summary of all settings
   - Confirm or edit before proceeding

### Configuration File

The wizard creates `Modernize4Linux.conf` with this format:

```ini
LICENSE_KEY=your-license-key-here
DESTINATION_IP=192.168.1.101
TRANSFER_METHOD=RSYNC
MODERNIZE_RSYNC_PASSES=2
MODERNIZE_IMAGE_DIR=/root/Image
MODERNIZE_LOGFILE=/var/log/live_migrate.log
MODERNIZE_JSON_LOGFILE=/var/log/live_migrate.json
MODERNIZE_DRY_RUN=false
MODERNIZE_MYSQL_PASSWORD=your-mysql-password
MODERNIZE_POSTGRESQL_PASSWORD=your-postgres-password
MODERNIZE_CRITICAL_SERVICES=mysql httpd nginx postgresql
MODERNIZE_COPY_USERS_GROUPS=true
MODERNIZE_MIGRATE_NETWORK=false
SOURCE_ARCHITECTURE=amd64
MIGRATION_DASHBOARD_ENABLED=Y
MIGRATION_DASHBOARD_SERVER=https://modernize4linuxdashboard.cyberautomation.com.au
```

**Security:** The config file is automatically set to `chmod 600` (owner read/write only).

---

## 🔄 Running Migrations

### Full Migration (Recommended)

Run the complete migration process:

```bash
Modernize4Linux
```

This performs:
1. **Cleanup Phase** - Removes old backup files (automatic)
2. **Backup Phase** - Backs up source system
3. **Transfer Phase** - Copies data to destination
4. **Restore Phase** - Restores on destination

**Note:** Modernize4Linux automatically cleans up old backup files from previous runs before starting. This prevents duplicate file transfers and saves disk space.

### Phase-Specific Operations

For testing or troubleshooting, run individual phases:

```bash
# Backup only (on source system)
Modernize4Linux --backup

# Restore only (on destination system)
Modernize4Linux --restore

# Clean up old backup files
Modernize4Linux --clean

# Preview what would be cleaned (safe, no changes)
Modernize4Linux --clean-report
```

---

## 📊 Migration Dashboard

If enabled, view real-time migration progress at:

**https://modernize4linuxdashboard.cyberautomation.com.au**

The dashboard shows:
- Migration progress and status
- Source and destination system info
- Architecture compatibility
- Pre-flight and post-flight check results
- Real-time event logging
- Error and warning notifications

---

## 🔧 What Gets Migrated

### Automatically Migrated

- ✅ **Packages** - All installed packages (with architecture translation)
- ✅ **Package Repositories** - Yum/DNF/APT repositories
- ✅ **Configuration Files** - `/etc` directory contents
- ✅ **Data** - `/home`, `/var/www`, `/opt`, custom directories
- ✅ **System Services** - Service definitions and states
- ✅ **Users & Groups** - User accounts and group memberships (optional)
- ✅ **MySQL Databases** - Complete database backup/restore
- ✅ **PostgreSQL Databases** - Complete database backup/restore
- ✅ **Network Configuration** - Network settings (optional)

### Smart Features

- **Architecture Detection** - Auto-detects and handles amd64/arm64 differences
- **Package Translation** - Maps packages between distributions (e.g., `httpd` → `apache2`)
- **Service Preservation** - Maintains service enabled/disabled states
- **Minimal Downtime** - Services quiesced only during final sync
- **Incremental Transfers** - Multiple rsync passes for large datasets

---

## 📋 Prerequisites

### On Both Systems

- **Operating System**: Linux (RHEL, CentOS, Debian, Ubuntu, Rocky, Alma, Fedora)
- **Access**: Root privileges required
- **Network**: SSH connectivity between systems
- **Disk Space**: Minimum 5GB free for staging directory

### On Source System

- Valid Modernize4Linux license key
- SSH client installed
- Sufficient disk space for backups (typically 20-50% of used space)

### On Destination System

- SSH server running (`sshd`)
- Root SSH access enabled (temporarily for migration)
- Same or greater disk capacity as source

---

## 🔐 Security Features

### Binary Security
- ✅ GPG-signed binaries
- ✅ SHA256 checksums
- ✅ HTTPS-only downloads

### Data Security
- ✅ SSH-encrypted transfers
- ✅ License key validation (HMAC-SHA256)
- ✅ Secure config file permissions (600)
- ✅ Environment variable support for passwords

### Dashboard Security
- ✅ HTTPS-only communication
- ✅ License-based authentication
- ✅ Optional self-signed certificate support

---

## 📝 Pre-Flight Checks

Before migration, Modernize4Linux automatically verifies:

- ✅ License validity
- ✅ SSH connectivity to destination
- ✅ Disk space availability
- ✅ Required commands present
- ✅ MySQL/PostgreSQL access (if configured)
- ✅ Source system compatibility
- ✅ Network connectivity

If any check fails, you'll see detailed error messages before migration starts.

---

## 🔍 Post-Flight Validation

After migration, automatic verification includes:

- ✅ Package count comparison
- ✅ Service status verification
- ✅ User account verification
- ✅ Database accessibility
- ✅ Critical file presence
- ✅ Overall migration status report

---

## 📖 Common Workflows

### Example 1: CentOS 7 → Rocky Linux 9

```bash
# On CentOS 7 source system
curl -fsSL https://www.cyberautomation.com.au/Modernize/Linux/4.7.7install.sh | sudo bash
Modernize4Linux

# Follow wizard:
# - Enter license key
# - Enter Rocky Linux 9 destination IP
# - Confirm auto-detected services
# - Provide MySQL password if prompted
# - Review and confirm

# Migration runs automatically
# Logs saved to /var/log/live_migrate.log
```

### Example 2: Ubuntu 18.04 → Ubuntu 22.04

```bash
# On Ubuntu 18.04 source
curl -fsSL https://www.cyberautomation.com.au/Modernize/Linux/4.7.7install.sh | sudo bash
Modernize4Linux

# Select Quick Start mode
# Enter destination Ubuntu 22.04 IP
# Migration proceeds automatically
```

### Example 3: Testing with Backup Only

```bash
# Run backup phase only for testing
Modernize4Linux --backup

# Review backup in /root/Image/
# When ready, run full migration:
Modernize4Linux
```

---

## 🐛 Troubleshooting

### SSH Connection Fails

**Problem:** Cannot connect to destination

**Solutions:**
```bash
# Check SSH is running on destination
systemctl status sshd

# Test manual connection
ssh root@destination-ip

# Ensure PermitRootLogin is enabled (temporarily)
# Edit /etc/ssh/sshd_config on destination:
PermitRootLogin yes
systemctl restart sshd
```

### Database Password Issues

**Problem:** MySQL/PostgreSQL password incorrect

**Solutions:**
```bash
# Test MySQL password
mysql -u root -p

# Use environment variables instead
export MYSQL_PASSWORD="correct-password"
export PGPASSWORD="correct-postgres-password"
Modernize4Linux
```

### Disk Space Errors

**Problem:** Insufficient disk space

**Solutions:**
```bash
# Check available space
df -h

# Clean up old backup files
Modernize4Linux --clean

# Check what would be cleaned first (dry run)
Modernize4Linux --clean-report

# Use custom image directory with more space
# Edit Modernize4Linux.conf:
MODERNIZE_IMAGE_DIR=/mnt/large-disk/Image

# Clean up old logs/files
rm -rf /var/log/*.old
```

### Duplicate Files Being Transferred

**Problem:** Seeing duplicate backup files during transfer

**Example:**
```
custom_services_backup.tar.gz (14MB)
custom_services_backup_1770197446.tar.gz (14MB)  ← Duplicate
custom_services_backup_1770198717.tar.gz (14MB)  ← Duplicate
```

**Solutions:**
```bash
# Option 1: Let automatic cleanup handle it (recommended)
Modernize4Linux
# Cleanup runs automatically

# Option 2: Manual cleanup before migration
Modernize4Linux --clean-report  # Preview
Modernize4Linux --clean         # Clean
Modernize4Linux                 # Migrate
```

**Note:** Duplicate files are typically leftovers from previous test migrations. Automatic cleanup (added in v4.2.0) prevents this issue.

**For Support/Advanced Users:**
```bash
# Investigate source of duplicate files
./investigate_duplicates.sh
# Provides detailed analysis and recommendations
```

### License Validation Fails

**Problem:** Invalid license key

**Solutions:**
- Verify license key is correct (no extra spaces)
- Contact support for license renewal
- Check system date/time is correct

---

## 📚 Additional Resources

- **Installation Guide**: `/usr/local/share/doc/modernize4linux/INSTALL.md`
- **Quick Reference**: `/usr/local/share/doc/modernize4linux/QUICK_REFERENCE.md`
- **Cleanup Guide**: `/usr/local/share/doc/modernize4linux/CLEANUP_GUIDE.md`
- **Dashboard**: https://modernize4linuxdashboard.cyberautomation.com.au
- **All Commands**: Run `Modernize4Linux --help`

---

## 💬 Support

- **Email**: support@cyberautomation.com.au
- **Security Issues**: security@cyberautomation.com.au
- **Website**: https://www.cyberautomation.com.au
- **Documentation**: https://www.cyberautomation.com.au/Modernize/Linux/4.7.7/

---

## 📄 License

This software is proprietary and requires a valid license key.

**Copyright © 2025-2026 Cyber Automation Pty Ltd. All rights reserved.**

---

## 🧹 Backup Cleanup (New in v4.2.0)

### Automatic Cleanup

Modernize4Linux now **automatically cleans up** old backup files before each migration to prevent duplicate file transfers and save disk space.

**What gets cleaned automatically:**
- Timestamped backup files from previous runs (e.g., `custom_services_backup_1234567890.tar.gz`)
- Temporary and partial files (`.tmp`, `.partial`)
- Rsync working directories
- Orphaned checksum files

**What is preserved:**
- Current backup files needed for migration
- All database backups
- Configuration files
- User data

### Manual Cleanup

View or clean backup directory manually:

```bash
# Preview what would be cleaned (safe, no changes)
Modernize4Linux --clean-report

# Clean up old files (interactive confirmation)
Modernize4Linux --clean
```

**Example output:**
```
Cleaning up old backup files...
  ✓ Removed: custom_services_backup_1770197446.tar.gz (14.2 MB)
  ✓ Removed: custom_services_backup_1770198717.tar.gz (14.2 MB)
  ✓ Removed orphaned checksum: *.md5

Cleanup Summary:
  Files removed: 3
  Space freed: 42.6 MB
```

### When to Use Manual Cleanup

- Before running a migration on a system with previous test runs
- When you see duplicate files in transfer logs
- To reclaim disk space between migrations
- For troubleshooting disk space issues

---

## 🌐 Multi-Distribution Support & Intelligent Package Resolution

### Overview

Modernize4Linux now supports migrations across **8 major Linux distributions** with intelligent package mapping and fuzzy resolution capabilities:

**Supported Distributions:**
- ✅ Red Hat Enterprise Linux (RHEL) 7/8/9
- ✅ CentOS 7/8
- ✅ Ubuntu 18.04/20.04/22.04
- ✅ Debian 10/11/12
- ✅ Fedora 36/37/38/39
- ✅ SUSE SLES 12/15, openSUSE Leap 15.x
- ✅ VMware Photon OS 3.0/4.0/5.0
- ⚠️ Mandrake 10.x / Mandriva 2010 (legacy support)

**Total Package Mappings:** 3,170+
**Migration Confidence:** 85-95% for modern distributions, 80% for legacy

### Supported Migration Paths

All of these migrations are production-ready:

| From → To | Confidence | Use Case |
|-----------|-----------|----------|
| RHEL 7/8/9 → Ubuntu/Debian | 90% | Cloud migrations, standardization |
| CentOS 7/8 → RHEL 8/9 | 95% | End-of-life migrations |
| Ubuntu → RHEL | 90% | Enterprise compliance |
| Fedora → RHEL | 85% | Development to production |
| SUSE SLES → RHEL | 80% | Vendor consolidation |
| Photon OS → RHEL | 85% | VMware/vSphere workloads |
| Mandrake/Mandriva → RHEL | 80% | Legacy system modernization |

**Bi-directional Support:** Most migrations work in both directions (e.g., RHEL ↔ Ubuntu).

### How Package Mapping Works

#### The Two-Phase Approach

Modernize4Linux uses a sophisticated two-phase strategy that balances thoroughness with speed:

**Phase 1: Backup (Rich Context Gathering)**

During backup on your **source system**, Modernize4Linux performs comprehensive analysis:

1. **Package Discovery** - Identifies all installed packages
2. **Context Collection** - For each package, gathers:
   - Installed files and locations
   - Package descriptions and metadata
   - Provided capabilities (e.g., "webserver")
   - Configuration files
   - Dependencies and relationships
   - Critical system packages identification

3. **Intelligent Pre-Resolution** - Uses live package manager to:
   - Query detailed package information
   - Search for file owners and providers
   - Map packages to target distribution
   - Resolve complex dependencies

4. **Manifest Creation** - Saves everything to a portable migration manifest

**Why This Matters:** The source system is still running, so we have full access to package managers and file systems for rich context gathering.

**Phase 2: Restore (Fast Installation)**

During restore on your **target system**, Modernize4Linux:

1. **Uses Pre-Resolved Mappings** - Installs packages using mappings from backup phase
2. **Quick Fuzzy Fallback** - If pre-resolved mapping fails, uses fast fuzzy resolution
3. **Graceful Failure** - Logs any unresolved packages for post-restore review (doesn't block migration)

**Why This Matters:** Restore is fast because most work was done during backup. Only edge cases need real-time resolution.

### 5-Layer Fuzzy Package Resolution

When exact mappings aren't available, Modernize4Linux uses a 5-layer intelligent resolution system:

#### Layer 1: Exact Mapping (95% Confidence)
Direct lookup in comprehensive mapping database.

**Example:**
```
Source: httpd (RHEL)
Target: apache2 (Ubuntu)
Status: ✅ Exact match
```

#### Layer 2: Fuzzy Name Matching (60-80% Confidence)
Intelligent name variant generation using pattern recognition.

**Common Patterns:**
- Version suffixes: `libssl1.1` → `libssl`, `libssl1.0`, `libssl3`
- Dev packages: `libfoo-dev` ↔ `libfoo-devel`
- Python variants: `python3-foo` → `python-foo`, `python39-foo`
- Service names: `apache2` ↔ `httpd`, `mysql-server` ↔ `mariadb-server`

**Example:**
```
Source: libssl1.1 (Ubuntu 18.04)
Generated: libssl, libssl1.0, libssl3, openssl-libs
Found: openssl-libs (RHEL 8)
Status: ✅ 75% confidence
```

#### Layer 3: Package Manager Intelligence (70% Confidence)
Leverages native package manager search capabilities.

**Package Manager Queries:**
- **DNF/YUM** (RHEL/Fedora): `dnf whatprovides */filename`, `dnf search`
- **APT** (Ubuntu/Debian): `apt-file search`, `apt-cache search`
- **Zypper** (SUSE): `zypper search --provides`, `zypper what-provides`
- **TDNF** (Photon): `tdnf search`, `tdnf provides`

**Example:**
```
Source: apache2 (Ubuntu)
Query: dnf whatprovides */apache2
Response: "httpd provides /usr/sbin/httpd"
Status: ✅ 70% confidence
```

#### Layer 4: Content-Based Search (55-90% Confidence)
Matches packages based on what they contain or provide.

**Search Methods:**
1. File path matching (e.g., owns `/usr/sbin/postfix`)
2. Capability matching (e.g., provides "webserver")
3. Description semantic matching
4. Dependency pattern matching

**Example:**
```
Source: postfix (mail-transport-agent)
Context: Provides mail-transport-agent, owns /usr/sbin/postfix
Search: Packages providing mail-transport-agent
Found: postfix (target distro)
Status: ✅ 90% confidence
```

#### Layer 5: Manual Intervention
For packages that can't be automatically resolved:
- Detailed logging for review
- Recommendations based on partial matches
- Alternative package suggestions
- Custom mapping support

**Example Output:**
```
⚠️ Resolution Needed:
  Package: custom-legacy-tool
  Alternatives:
    - modern-replacement-tool (80% overlap)
    - manual-migration-required
  Recommendation: Review requirements
```

### Self-Learning System

Modernize4Linux improves with every migration:

1. **Learning Process:**
   - Successful fuzzy resolutions → Added to learned mappings
   - Future migrations use learned mappings as exact matches
   - Community contributions can be shared
   - Manual corrections automatically incorporated

2. **Example Learning Cycle:**
   ```
   First Migration:
     Source: custom-apache-mod
     Resolution: Fuzzy → mod_custom (70% confidence)
     Result: ✅ Success → Logged as learned mapping

   Second Migration:
     Source: custom-apache-mod
     Resolution: ✅ Exact match (learned mapping)
     Speed: 10x faster
   ```

### Confidence Thresholds

Modernize4Linux uses confidence scores to determine installation behavior:

| Confidence | Action | Method |
|------------|--------|--------|
| ≥ 95% | ✅ Auto-install | Exact mapping |
| 80-94% | ✅ Auto-install | Fuzzy name match |
| 60-79% | ✅ Auto-install + log | Package manager query |
| 55-59% | ⚠️ Prompt user | Content-based search |
| < 55% | ❌ Skip + log | Manual intervention |

**Safety Features:**
- All auto-installs logged for audit
- Dry-run mode available for testing
- Rollback capability
- Post-restore verification reports

### Distribution-Specific Intelligence

#### Fedora → RHEL
- Handles Fedora's rapid release cycle (F36→F39)
- Maps newer packages to stable RHEL equivalents
- Development-to-production transitions

#### SUSE/openSUSE → RHEL
- Maps YaST tools to RHEL equivalents
- Converts SUSE patterns to package groups
- Enterprise package handling

#### Photon OS → RHEL
- Preserves VMware tools/integrations
- Container workload optimizations
- Minimal-to-full system expansion

#### Mandrake/Mandriva → RHEL (Legacy)
- 500+ comprehensive mappings
- Drak* tools suite (20+ tools)
- Hardware detection tools
- Major version upgrade support (PHP 4→8, MySQL 4→8, kernel 2.6→5.x)
- **⚠️ Requires extensive testing:** Staging environment mandatory

### Migration Workflow Example

#### Step 1: Pre-Migration Analysis
```bash
Modernize4Linux --analyze
```

**Output:**
```
✅ 847 packages detected
✅ 98.2% have exact mappings (Ubuntu → RHEL)
⚠️ 15 packages need fuzzy resolution
ℹ️ Estimated confidence: 92%
```

#### Step 2: Backup with Pre-Resolution
```bash
Modernize4Linux --backup
```

**Output:**
```
✅ Package inventory: 847 packages
✅ Context gathering: 847/847 analyzed
✅ Pre-resolution: 832/847 exact matches
⚠️ Fuzzy resolution: 15/847 logged
✅ Manifest created: migration-manifest.json
⏱️ Time: 3m 42s
```

#### Step 3: Review Manifest
```bash
Modernize4Linux --review migration-manifest.json
```

Shows all package mappings, confidence levels, and packages needing attention.

#### Step 4: Restore on Target
```bash
Modernize4Linux --restore
```

**Output:**
```
✅ Installing: 832/847 using exact mappings
⚡ Fuzzy resolution: 12/15 resolved
⚠️ Manual review: 3 packages
✅ Configuration: 156 files migrated
✅ Services: 23 services migrated
⏱️ Time: 8m 15s
```

#### Step 5: Post-Restore Verification
```bash
Modernize4Linux --verify
```

**Output:**
```
✅ Package installation: 844/847 (99.6%)
✅ Services running: 23/23
⚠️ Review required:
  - legacy-tool-1: No equivalent
  - custom-mod-2: Manual install needed
  - obsolete-pkg-3: No longer needed
```

### Best Practices for Multi-Distribution Migrations

1. **Always Test in Staging First**
   - Clone production to staging
   - Run full migration in staging
   - Verify all critical services
   - Then migrate production

2. **Review Pre-Resolution Results**
   ```bash
   Modernize4Linux --review --show-fuzzy
   ```

3. **Add Custom Mappings**
   For proprietary/custom packages:
   ```bash
   Modernize4Linux --add-mapping \
     --source custom-app \
     --target custom-app-rhel \
     --confidence 100
   ```

4. **Incremental Migrations**
   For large systems, migrate in stages:
   ```bash
   # Stage 1: Core packages
   Modernize4Linux --backup --include-group base

   # Stage 2: Applications
   Modernize4Linux --backup --include-group apps

   # Stage 3: Development tools
   Modernize4Linux --backup --include-group devel
   ```

5. **Export Learned Mappings**
   Share knowledge across migrations:
   ```bash
   Modernize4Linux --export-learned \
     --output custom-mappings.json
   ```

### Troubleshooting Multi-Distribution Issues

#### Package Not Found After Migration

**Problem:** Package exists on source but not found on target.

**Solutions:**
1. Search for renamed package:
   ```bash
   Modernize4Linux --search --package apache2 --target rhel:8
   ```

2. Enable additional repositories:

   **NEW in 4.7.0:** Modernize4Linux can automatically detect and enable repositories (EPEL, PowerTools/CRB) when packages are not found. Simply approve when prompted during migration. See `REPOSITORY_AUTO_ENABLEMENT.md` for details.

   **Manual approach (if auto-enablement is disabled):**
   ```bash
   # RHEL: Enable EPEL, PowerTools
   dnf install epel-release
   dnf config-manager --set-enabled powertools

   # Ubuntu: Enable universe, multiverse
   add-apt-repository universe
   add-apt-repository multiverse
   ```

3. Add custom mapping:
   ```bash
   Modernize4Linux --add-mapping \
     --source oldpkg --target newpkg
   ```

#### Low Confidence Resolution

**Problem:** Fuzzy resolution returns <60% confidence.

**Solutions:**
1. Review package context in manifest
2. Search manually:
   ```bash
   # RHEL/Fedora
   dnf search <keywords>

   # Ubuntu/Debian
   apt-cache search <keywords>
   ```
3. Check if functionality is built-in to target OS
4. Consider alternative packages

#### Service Fails After Migration

**Problem:** Migrated service won't start.

**Solutions:**
1. Check configuration compatibility:
   ```bash
   Modernize4Linux --verify-config --service httpd
   ```

2. Review service dependencies:
   ```bash
   systemctl status httpd
   journalctl -u httpd
   ```

3. Update paths/syntax:
   - Ubuntu: `/etc/apache2/` → RHEL: `/etc/httpd/`
   - Check module availability
   - Verify configuration syntax

### Migration Readiness Matrix

Quick reference for supported migrations:

| From ↓ / To → | RHEL | CentOS | Ubuntu | Debian | Fedora | SUSE | Photon | Mandrake |
|---------------|------|--------|--------|--------|--------|------|--------|----------|
| **RHEL**      | ✅   | ✅     | ✅     | ✅     | ✅     | ✅   | ✅     | ❌       |
| **CentOS**    | ✅   | ✅     | ✅     | ✅     | ✅     | ✅   | ✅     | ❌       |
| **Ubuntu**    | ✅   | ✅     | ✅     | ✅     | ✅     | ✅   | ✅     | ❌       |
| **Debian**    | ✅   | ✅     | ✅     | ✅     | ✅     | ✅   | ✅     | ❌       |
| **Fedora**    | ✅   | ✅     | ✅     | ✅     | ✅     | ✅   | ✅     | ❌       |
| **SUSE**      | ✅   | ✅     | ✅     | ✅     | ✅     | ✅   | ✅     | ❌       |
| **Photon**    | ✅   | ✅     | ✅     | ✅     | ✅     | ✅   | ✅     | ❌       |
| **Mandrake**  | ⚠️   | ⚠️     | ⚠️     | ⚠️     | ⚠️     | ⚠️   | ⚠️     | ✅       |

**Legend:**
- ✅ Production ready (85-95% confidence)
- ⚠️ Legacy support (80% confidence, testing required)
- ❌ Not supported

### Technical Documentation

For detailed technical information, see:
- **MULTI_DISTRO_SUPPORT_PLAN.md** - Implementation details
- **MIGRATION_READINESS_MATRIX.md** - Detailed migration paths
- **FUZZY_PACKAGE_RESOLUTION.md** - Algorithm details
- **FUZZY_RESOLUTION_PHASES.md** - Backup vs restore strategies

---

## 🔄 Version History

**v4.2.9** (Current)
- ✨ **NEW:** Multi-distribution support (8 distributions, 3,170+ mappings)
- ✨ **NEW:** Intelligent fuzzy package resolution (5-layer system)
- ✨ **NEW:** Two-phase migration approach (backup + restore)
- ✨ **NEW:** Self-learning package mapping system
- ✨ **NEW:** Version-aware package intelligence
- ✨ **NEW:** Distribution-specific optimizations
- ✨ **NEW:** Legacy system support (Mandrake/Mandriva)
- 🔧 **ENHANCED:** 150% increase in package mappings (1,270 → 3,170)
- 🔧 **ENHANCED:** Migration confidence: 85-95%

**v4.2.0**
- ✨ **NEW:** Automatic cleanup of old backup files
- ✨ **NEW:** Manual cleanup commands (`--clean`, `--clean-report`)
- 🔧 **FIXED:** Duplicate file transfers from previous runs
- 📊 **IMPROVED:** Disk space management
- Interactive configuration wizard with 3 modes
- Auto-detection of MySQL, PostgreSQL, services
- One-liner installer
- Enhanced dashboard integration
- Improved security with GPG signing
- Architecture-aware package migration

**v4.1.7 and earlier**
- Previous versions without automatic cleanup

For older versions, visit: https://www.cyberautomation.com.au/Modernize/Linux/4.7.7