mailinabox/tools/migrate.md

Mail-in-a-Box Migration Script

Author: Ahmad Kouider
Created: April 3, 2025

Overview

The migrate-miab.sh script provides a comprehensive solution for migrating Mail-in-a-Box installations from one server to another. It handles the secure transfer of data, configuration updates, and service management to ensure a smooth migration process.

Features

• Secure Data Transfer: Uses rsync over SSH for efficient and secure file transfer
• Configuration Management: Automatically updates the Mail-in-a-Box configuration with the new IP address
• Service Control: Optional stopping and starting of Mail-in-a-Box services during migration
• Error Handling: Robust error detection and recovery with automatic service restoration
• Partial Transfer Support: Special handling for partial transfers (common with large installations)
• Dry Run Mode: Test the migration process without making any changes

Prerequisites

• SSH access to both source and target servers
• rsync installed on the source server
• Sufficient disk space on the target server
• Mail-in-a-Box installed on the source server

Usage

Basic Usage

./migrate-miab.sh --username admin --target-host 192.168.1.100 --new-ip 203.0.113.10

All Available Options

Option	Description	Default
--username USERNAME	SSH username for target server	(required)
--target-host HOST	IP address or domain of target server	(required)
--new-ip IP	Public IP address of the new target machine	(required)
--source-path PATH	Path to Mail-in-a-Box files	/home/user-data
--target-path PATH	Destination path on target server	/home/user-data
--config-path PATH	Path to mailinabox.conf file	/etc/mailinabox.conf
--exclude LIST	Comma-separated list of files/folders to exclude	(none)
--ssh-port PORT	SSH port to use	22
--stop-services	Stop Mail-in-a-Box services during transfer	(default: keep running)
--ignore-partial	Continue migration even if some files fail to transfer	(default: prompt user)
--dry-run	Simulate the transfer without making changes	(default: false)
--help	Display help message

Example Commands

Standard Migration:

./migrate-miab.sh --username admin --target-host mail2.example.com --new-ip 203.0.113.10

Migration with Service Stopping:

./migrate-miab.sh --username admin --target-host mail2.example.com --new-ip 203.0.113.10 --stop-services

Excluding Certain Directories:

./migrate-miab.sh --username admin --target-host mail2.example.com --new-ip 203.0.113.10 --exclude 'backup,logs,tmp'

Dry Run Test:

./migrate-miab.sh --username admin --target-host mail2.example.com --new-ip 203.0.113.10 --dry-run

Migration Process

1. Preparation:

   • Validates all input parameters
   • Generates a temporary SSH key pair
   • Prompts you to add the key to the target server

2. Service Management (if --stop-services is used):

   • Stops all Mail-in-a-Box services on the source server
   • This helps prevent file corruption during transfer

3. Data Transfer:

   • Uses rsync to efficiently transfer all Mail-in-a-Box data
   • Handles partial transfers with interactive prompting

4. Configuration Update:

   • Updates the mailinabox.conf file with the new IP address
   • Transfers the updated configuration to the target server

5. Service Restoration:

   • Restarts any services that were stopped (if applicable)
   • Ensures the source server returns to its original state

Important Notes

Partial Transfers

When transferring large Mail-in-a-Box installations, you may encounter "partial transfer" errors (rsync code 23). This typically happens because:

• Some files are actively being used (open files)
• Permission issues prevent access to certain files
• Special system files cannot be transferred normally

The script provides two ways to handle this:

1. Interactive prompt: Choose whether to continue or abort
2. Automatic continuation: Use the --ignore-partial flag

Post-Migration Steps

After the migration completes successfully, you MUST:

1. Reinstall Mail-in-a-Box on the target server:

   curl -s https://mailinabox.email/setup.sh | sudo bash
   

   This ensures all configurations are properly updated while preserving your transferred data.

2. Update DNS records to point to the new server IP address

3. Test mail functionality on the new server

Troubleshooting

Common Issues

1. SSH Connection Failures:

   • Ensure the public key was added to ~/.ssh/authorized_keys on the target server
   • Verify the SSH port is correct (default: 22)
   • Check for firewall rules blocking SSH connections

2. File Transfer Errors:

   • Consider using the --stop-services option to prevent open file issues
   • Use --exclude to skip problematic directories
   • For partial transfers, use --ignore-partial if you're confident in the data integrity

3. Configuration File Not Found:

   • If your Mail-in-a-Box has a non-standard configuration path, use the --config-path option

Security Considerations

• The script generates a temporary SSH key pair for the migration
• Keys are automatically deleted after the migration completes
• No passwords are stored or transmitted
• All data is transferred over encrypted SSH connections

License

This script is provided as-is with no warranty. Use at your own risk.