PowerProtect DM: How to Migrate Avamar File System Backup Metadata Using GSAN Mover

TABLE OF CONTENTS

1. Overview
2. Key Features
3. Prerequisites
4. Pre-Migration Checklist
5. Download and Installation
6. Configuration
7. Migration Procedure
8. Verification Steps
9. Troubleshooting
10. Best Practices

---

1. OVERVIEW

The GSAN Mover Tool is a specialized utility designed to facilitate the migration of Avamar file system backup metadata to Dell PowerProtect Data Manager. This tool enables customers to migrate their file system assets from Avamar to PowerProtect Data Manager while preserving historical backup metadata and maintaining data integrity.

IMPORTANT NOTICE:
The GSAN Mover migrates METADATA ONLY. The backup data remains on the Data Domain system and is not moved or modified during the migration process.

Applies To:

• Dell PowerProtect Data Manager 20.1 and later
• Dell Avamar (all supported versions) 
• Dell Data Domain (all supported versions)
• File System backups only

---

2. KEY FEATURES

The GSAN Mover tool provides the following capabilities:

• Metadata Migration
  Transfers backup metadata from Avamar to PowerProtect Data Manager without moving data
• Data Preservation
  Backup data remains on Data Domain (no data movement required)
•  Batch Processing
   Supports migration of multiple clients simultaneously
• Historical Backup Retention
  All backup copies remain accessible postmigration.
• Non-Disruptive
  Metadata migration does not impact existing backup data.

---

3. PREREQUISITES

3.1 System Requirements

• Access Requirements:
  • PowerProtect Data Manager server or designated working host with network connectivity to:
    • Avamar server
    • Data Domain system
    • PowerProtect Data Manager server
• Credentials Required:
  • Avamar root username and password
  • Data Domain DD Boost username and password
  • PowerProtect Data Manager administrator credentials
• Network Requirements:
  • SSH or SCP access to transfer files.
  • Network connectivity between all systems (Avamar, Data Domain, PowerProtect Data Manager)
  • Firewall rules configured to allow required ports.
• Software Requirements:
  • Linux UNIX environment with bash shell
  • Sufficient disk space for tool and logs (minimum 1 GB recommended)
  • wget or curl utility for downloading the tool

3.2 Environment Verification

Before proceeding, verify the following:

• Avamar Environment:
  • Avamar server is operational and accessible.
  • File system clients are successfully backed up.
  • Avamar domain structure is documented.
  • Root access is available.
• Data Domain Environment:
  • Data Domain system is operational.
  • DD Boost is configured for Avamar.
  • TLS configuration is known (enabled or disabled)
  • Sufficient capacity is available.
• PowerProtect Data Manager Environment:
  • PowerProtect Data Manager server is operational (version 20.1 or later)
  • Administrator access is available.
  • PowerProtect Data Manager File System Agent is available for installation.
  • Network connectivity to Avamar and Data Domain is verified.

---

4. PRE-MIGRATION CHECKLIST

Complete the following tasks before starting migration:

[ ] Verify that all file system clients are backed up successfully in Avamar.
[ ] Document current Avamar domain structure and client list
[ ] Ensure that the Data Domain has sufficient capacity for continued operations.
[ ] Verify TLS configuration on Data Domain (enabled or disabled)
[ ] Backup current Avamar configuration
[ ] Ensure that the PowerProtect Data Manager File System Agent is available for target restore hosts.
[ ] Verify network connectivity between all systems.
[ ] Schedule maintenance window for migration activities
[ ] Notify stakeholders of planned migration.
[ ] Prepare a rollback plan if needed.

---

5. DOWNLOAD AND INSTALLATION

5.1 Download the GSAN Mover Tool.

The tool is available from the Dell Downloads server at URL: https://dl.dell.com/downloads/HMP51_PTPP-GSAN-Data-Mover.gz (Log in to Dell Support is required for access)

• Method 1: Using wget
wget https://dl.dell.com/downloads/HMP51_PTPP-GSAN-Data-Mover.gz (Log in to Dell Support is required for access)
• Method 2: Using curl
curl -O https://dl.dell.com/downloads/HMP51_PTPP-GSAN-Data-Mover.gz (Log in to Dell Support is required for access)

5.2 Transfer to Target Host.

Transfer the downloaded file to your PowerProtect Data Manager server or designated working host:

scp HMP51_PTPP-GSAN-Data-Mover.gz <user>@<target_host>:/tmp/

Replace <user> and <target_host> with your environment values.

5.3 Extract the Package.

Extract the compressed file:

gunzip HMP51_PTPP-GSAN-Data-Mover.gz

If the file is a tarball (.tar.gz):

tar -xzf HMP51_PTPP-GSAN-Data-Mover.gz

5.4 Set Executable Permissions.

Make the binary executable:

chmod +x ./gsan-mover

Verify that the file is executable:

ls -l ./gsan-mover

Expected output should show execute permissions (such as, -rwxr-xr-x).

---

6. CONFIGURATION

The GSAN Mover tool requires two configuration files:

6.1 Configuration File (YAML Format)

Create a file named config_input.yaml with your environment details:

File: config_input.yaml

Avamar:
  username: root
  password: <avamar_root_password>

DataDomains:
ip: <data_domain_ip_address>
username: <dd_boost_username>
password: <dd_boost_password>
tls: <true/false>

Configuration Parameters:

Parameter                                        Description                                                                                                    Example
─────────────────────      ─────────────────────────────────────────────      ──────────────────────
Avamar.username               Root username for the Avamar server                                                            root
Avamar.password               Root password for the Avamar server                                                            YourSecurePassword123
DataDomains.ip                IP address or FQDN of Data Domain system          192.168.1.100 or dd01.example.com
DataDomains.username          DD Boost username configured for Avamar           ddboost_user
DataDomains.password          DD Boost user password                                                                                 DDBoostPassword456
DataDomains.tls               TLS encryption setting (true or false)                                                              true or false
                              Must match Data Domain TLS configuration.

SECURITY NOTICE:
Protect the configuration file with restricted permissions to safeguard.

Credentials:

chmod 600 config_input.yaml

Verify permissions:

ls -l config_input.yaml

Expected output:

-rw------- (owner read/write only)

6.2 Clients Input File (CSV Format)

Create a file named clients_input.csv listing the file system clients to migrate:

File: clients_input.csv

name,domain
client1.example.com,/clients
client2.example.com,/clients
client3.example.com,/production

CSV Column Definitions:

Column           Description                                               Example
────────      ────────────────────────────────────────────────────      ──────────────────────────
name             Fully Qualified Domain Name (FQDN) of the file            fileserver01.corp.example.com

domain           Avamar domain path where the client resides               /clients or /production/fileservers

Example with Multiple Clients:

name,domain
fileserver01.corp.example.com,/clients
fileserver02.corp.example.com,/clients
fileserver03.corp.example.com,/production
nas01.corp.example.com,/production/nas
nas02.corp.example.com,/production/nas

 

---

7. MIGRATION PROCEDURE

Follow these steps in the order presented:

STEP 1: Run the GSAN Mover Tool. 

Run the tool with your configuration files:

./gsan-mover --config-file <config_file_path> --clients-file <path_to_clients_file>

Example:

./gsan-mover --config-file ./config_input.yaml --clients-file ./clients_input.csv

Recommended: Capture Logs
For troubleshooting and audit purposes, capture the output to a log file:

./gsan-mover --config-file ./config_input.yaml --clients-file ./clients_input.csv 2>&1 | tee gsan-mover-$(date +%Y%m%d-%H%M%S).log

This creates a timestamped log file (for example, gsan-mover-20260512-143022.log) for future reference.

Monitor Execution:

• Monitor the tool's output for progress updates.
• Wait for the tool to report successful completion.
• Review any warnings or errors in the output.
• Verify the log file for detailed execution information.
• Do NOT go to Step 2 until this step completes successfully.

STEP 2: Disable Avamar Backup Policy.

This is a CRITICAL STEP - DO NOT SKIP!
Before proceeding with migration in PowerProtect Data Manager UI, you MUST disable the backup policy on the Avamar server for the assets you want to migrate. This is a required step for PowerProtect Data Manager to recognize the assets as available for migration.

Procedure:

1. Log in to the Avamar Administration Console.
2. Go to Administration → Policies.
3. Select the backup policy associated with the file system clients being migrated.
4. Click Disable to stop the policy.
5. Confirm that the policy is disabled (status should show "Disabled" or "Stopped")

Important:

• The policy must remain disabled during the migration process.
• You can reenable it after migration is complete if needed.
• Document which policies were disabled for reference.

STEP 3: Add Avamar as Asset Source in PowerProtect Data Manager.

3.1 Add Avamar Asset Source.

1. Log in to the PowerProtect Data Manager UI as Administrator
2. Go to Infrastructure → Asset Sources
3. Click + Add.
4. Select Avamar from the list.
5. Enter the Avamar server's FQDN or IP address.
6. Click Verify
7. Provide Avamar credentials when prompted.
8. Click Save

3.2 Wait for Discovery Job

1. Go to Jobs → System Jobs
2. Locate the discovery and precheck job for the Avamar asset source.
3. Monitor the job progress.
4. Wait for the job to complete successfully.
5. Verify that no errors are reported in the job details.

Expected Duration: 5 -15 minutes (depending on environment size)

STEP 4: Migrate Assets in PowerProtect Data Manager.

4.1 Go to Assets.

1. In PowerProtect Data Manager UI, go to Infrastructure → Assets
2. Click the Non-Migrated tab
3. Verify that the file system clients appear in the list.

If clients do not appear:

• Verify Step 2 was completed (Avamar policy disabled).
• Wait for discovery job to complete.
• Refresh the page.
• Check PowerProtect Data Manager logs for errors.

4.2 Initiate Migration.

1. Select the file system clients that you want to migrate. (Use Ctrl+Click or Shift+Click to select multiple clients.)
2. Click Migrate to Data Manager button.
3. Review the migration confirmation dialog.
4. Click Confirm to start the migration.

4.3 Monitor Migration Progress

1. Go to Jobs → System Jobs
2. Locate the migration job or jobs.
3. Monitor the job progress.
4. Wait until the job completes successfully.
5. Review job details for any warnings or issues.

Expected Duration: Varies based on metadata volume (typically 5 - 30 minutes per client)

STEP 5: Verify Migration. 

Perform the following verification steps after migration completes:

5.1 Verify Asset Status.

1. Go to Infrastructure → Assets
2. Click the Migrated tab
3. Confirm that migrated assets appear in the list.
4. Verify that asset details are correct:

• • Hostname matches expected FQDN.
  • Domain path is correct.
  • Status shows as Protected or Active

5.2 Verify Backup Copies.

1. Select a migrated asset from the list.
2. Click View Copies (or similar option)
3. Verify that all historical backup copies are visible.
4. Check the following for each backup copy:

• • Backup date and time match Avamar records
  • Backup size is reasonable.
  • Backup status shows as Available or Successful

5.3 Perform Test Restore.

1. Go to Restore → Assets (or Restore → File System)
2. Select a migrated asset.
3. Choose a backup copy to restore (preferably a recent copy)
4. Select specific files or folders to restore.
5. Choose a target restore host. (It must have PowerProtect Data Manager File System Agent installed and registered)
6. Configure restore options as required.
7. Click Restore to run the operation.
8. Monitor the restore job in Jobs → Restore Jobs
9. After completion, verify restored data integrity:

• • Check file contents.
  • Verify file permissions.
  • Confirm file timestamps.

 

---

8. VERIFICATION STEPS

After completing the migration procedure, perform these additional verifications steps:

8.1 Verify Data Domain Connectivity.

1. In PowerProtect Data Manager UI, go to Infrastructure → Storage Systems.
2. Verify that the Data Domain system is listed and shows Connected status.
3. Check capacity and health indicators.

8.2 Verify Protection Policies.

1. Go to Protection → Protection Policies.
2. Create or update protection policies for migrated assets.
3. Assign policies to migrated file system clients.
4. Run a manual backup to verify functionality.

8.3 Verify Agent Status (for Restore Operations)

1. Go to Infrastructure → Agents
2. Verify that PowerProtect Data Manager File System Agent is installed on target hosts.
3. Check agent status shows as Registered or Active
4. Verify that the agent version is compatible with PowerProtect Data Manager version.

8.4 Document Migration Results

• Record all migrated clients and their status.
• Document any issues encountered and resolutions.
• Update runbooks and operational procedures
• Archive configuration files and log files

---

9. TROUBLESHOOTING

This section provides solutions for common issues encountered during migration.

ISSUE 1: Connection Timeout to Avamar or Data Domain

Symptoms:

• The tool fails with connection timeout errors.
• Unable to reach Avamar or Data Domain.
• Error messages indicating network connectivity issues

Resolution:

1. Verify network connectivity:   

ping <avamar_ip>

ping <data_domain_ip>

2. Check firewall rules:

• • Ensure that required ports are open.
  • Verify that no network ACLs are blocking traffic.

3. Verify credentials:

• • Test Avamar credentials: ssh root@<avamar_ip>
  • Verify DD Boost credentials on Data Domain.

4. Check service status:

• • Ensure that Avamar services are running.
  • Verify that Data Domain services are operational.

5. Review network configuration:

• • Check DNS resolution.
  • Verify routing between systems.

ISSUE 2: Authentication Failures

Symptoms:

• Authentication failed error messages.
• Invalid credentials errors
• Access denied messages

Resolution:

1. Verify username and password in config_input.yaml:

• • Check for typos or extra spaces.
  • Ensure that the password is correct.

2. Test credentials manually:

• • SSH to Avamar: ssh root@<avamar_ip>
  • Test DD Boost credentials on Data Domain console

3. Check for special characters in passwords:

• • Some special characters may require escaping in YAML.
  • Consider using single quotes around the password.

4. Verify account status:

• • Ensure that the account is not locked.
  • Check password expiration policy.
  • Verify that the account has required permissions.

ISSUE 3: TLS Configuration Mismatch 

Symptoms:

• TLS handshake failures
• SSL/TLS errors in logs
• Certificate validation errors

Resolution:

1. Verify Data Domain TLS configuration:

• • Log in to PowerProtect DD System Manager
  • Check DD Boost TLS settings.

2. Match configuration in config_input.yaml:

• • If a Data Domain has TLS enabled, set: tls: true
  • If a Data Domain has TLS disabled, set: tls: false

3. Verify certificate validity (if TLS is enabled):

• • Check certificate expiration.
  • Verify the certificate chain.

4. Test DD Boost connectivity:

• • Use DD Boost test utilities.
  • Verify that the TLS handshake succeeds.

ISSUE 4: Assets Not Appearing in PowerProtect Data Manager Non-Migrated Tab

Symptoms:

• Migrated metadata not visible in PowerProtect Data Manager
• Assets missing from Non-Migrated list
• Empty asset list after discovery

Resolution:

1. Verify that the Avamar backup policy is disabled (Step 2):

• • Log in to the Avamar Administration Console.
  • Check policy status.
  • Disable the policy if not already disabled.

2. Wait for the PowerProtect Data Manager discovery job to complete:

• • Go to Jobs → System Jobs
  • Verify that discovery job has been completed successfully.
  • Check job duration (may take 10-15 minutes)

3. Refresh the Assets page:

• • Click refresh button in the PowerProtect Data Manager UI.
  • Log out and log back in.
  • Clear browser cache if needed

4. Check PowerProtect Data Manager logs for discovery errors:

• • Go to System → Logs
  • Filter for discovery-related errors
  • Review error messages for specific issues

5. Verify Avamar asset source configuration:

• • Go to Infrastructure → Asset Sources
  • Verify that the Avamar server is listed.
  • Check connection status.
  • Reverify credentials if needed.

ISSUE 5: Migration Job Fails in PowerProtect Data Manager.

Symptoms:

• Migration job shows failed status.
• Error messages in System Jobs
• Job completes with no errors.

Resolution:

1. Review detailed job logs in PowerProtect Data Manager:

• • Go to Jobs → System Jobs
  • Click the failed migration job
  • Review error messages and stack traces

2. Verify Data Domain connectivity from PowerProtect Data Manager:

• • Go to Infrastructure → Storage Systems
  • Check Data Domain connection status.
  • Test connectivity

3. Check Data Domain capacity and health:

• • Log in to PowerProtect DD System Manager
  • Verify sufficient capacity.
  • Check for any alerts or warnings.

4. Ensure that DD Boost is configured correctly:

• • Verify DD Boost user credentials.
  • Check DD Boost storage unit configuration.
  • Verify Avamar DD Boost configuration.

5. Verify the GSAN Mover tool completed successfully:

• • Review GSAN Mover log files
  • Ensure that no errors were reported.
  • Rerun GSAN Mover if needed

6. Retry migration:

• • After resolving issues, retry the migration.
  • Select the asset again and click Migrate.

ISSUE 6: Restore Operation Fails. 

Symptoms:

• Restore job fails or times out.
• Data not restored to target host.
• Error messages during restore

Resolution:

1. Verify that PowerProtect Data Manager File System Agent is installed on the target host:

• • Check agent installation.
  • Verify agent version compatibility.

2. Check agent registration status in PowerProtect Data Manager:

• • Go to Infrastructure → Agents
  • Verify agent shows as Registered
  • Re-register agent if needed

3. Verify network connectivity:

• • Test connectivity between PowerProtect Data Manager and target host
  • Check firewall rules.
  • Verify DNS resolution.

4. Check Data Domain connectivity and performance:

• • Verify that the Data Domain is accessible.
  • Check Data Domain performance metrics.
  • Ensure no capacity issues.

5. Review restore job logs:

• • Go to Jobs → Restore Jobs
  • Click the failed restore job.
  • Review error messages for specific issues

6. Verify restore permissions:

• • Ensure that the target directory is writable.
  • Check file system permissions.
  • Verify sufficient disk space on target.

9.1 Log File Locations

• GSAN Mover Logs:

Location: gsan-mover-<timestamp>.log (in execution directory)

Contains: Tool execution details, errors, and progress information

• PowerProtect Data Manager Logs:

Location: Available in PowerProtect Data Manager UI under Jobs → System Jobs → Job Details

Contains: Discovery, migration, and restore job details.

• Avamar Logs:

Location: /usr/local/avamar/var/ on Avamar server

Contains: Avamar system logs and backup job details

• Data Domain Logs:

Location: Accessible by Data Domain System Manager

Contains: DD Boost logs and system events

9.2 Collecting Diagnostic Information

When contacting Dell Technical Support, collect the following:

• GSAN Mover log files (all timestamped logs)
• Configuration files (config_input.yaml and clients_input.csv)

 

 

• PowerProtect Data Manager job logs (exported from System Jobs)
• Screenshots of error messages
• Environment details:
  • PowerProtect Data Manager version
  • Avamar version
  • Data Domain version
  • Network topology diagram (if available)

---

10. BEST PRACTICES

10.1 Planning Phase

• Pilot Migration
  • Test with a small subset of clients (2-3) first
  • Validate the entire process before full-scale migration
  • Document lessons learned
• Maintenance Window
  • Schedule migration during off-peak hours
  • Allow sufficient time for completion and verification.
  • Plan for potential rollback if needed
• Documentation
  • Document all client FQDNs, domains, and policies
  • Create a detailed migration plan.
  • Prepare rollback procedures.
• Communication
  • Notify stakeholders of migration schedule.
  • Communicate expected downtime (if any)
  • Provide status updates during migration.

10.2 Execution Phase

• Batch Size
  • Migrate clients in manageable batches (10-20 at a time)
  • Allows for better monitoring and troubleshooting
  • Reduces the risk of large-scale failures
• Log Retention
  • Keep all log files for audit and troubleshooting.
  • Use timestamped log files for better identification.
  • Archive logs after successful migration
• Verification
  • Verify each batch before proceeding to the next.
  • Perform test restores for each batch.
  • Document verification results
• Backup Configuration
  • Save copies of all configuration files.
  • Document any custom settings
  • Keep configuration files for future reference.

10.3 Post-Migration Phase

• Policy Recreation
  • Create new protection policies in PowerProtect Data Manager.
  • Assign policies to migrated assets.
  • Schedule first backup jobs
• Monitoring
  • Monitor the first few backup jobs closely.
  • Verify backup success and performance.
  • Address any issues immediately.
• Documentation Update
  • Update runbooks and operational procedures
  • Document new PowerProtect Data Manager workflows
  • Train staff on new procedures
• Cleanup
  • Archive or remove old Avamar policies after successful migration.
  • Clean up temporary files and logs.
  • Update asset inventory
• Performance Baseline
  • Establish performance baselines for the new environment.
  • Monitor backup windows and durations.
  • Optimize as needed.

FREQUENTLY ASKED QUESTIONS (FAQ)

• Q1: Does the GSAN Mover tool move backup data?

• Q2: Can backing up continue to Avamar during migration?

A: No - You must disable the Avamar backup policy for the assets being migrated. This is a required step for PowerProtect Data Manager to recognize the assets as available for migration. You can reenable the policy after migration if needed, or create new policies in PowerProtect Data Manager.

• Q3: Do historical backups be available after migration?

A: Yes - All historical backup copies are visible in PowerProtect Data Manager after migration and can be used for restore operations. The metadata migration ensures that all backup history is preserved.

• Q4: Can migration to multiple clients happen at once?

A: Yes - You can list multiple clients in the clients_input.csv file, and the tool processes them in batch. However, it is recommended to migrate in manageable batches (10-20 clients) for better monitoring and troubleshooting.

• Q5: What happens if the migration fails partway through?

A: Review the log files to identify the failure point. You can rerun the tool after resolving the issue. Already migrated metadata is not duplicated. The tool is idempotent for most operations.

• Q6: Must reinstallation of agents on file system clients occur?

A: For restore operations, the target host must have the PowerProtect Data Manager File System Agent installed. For ongoing backups, you must configure PowerProtect Data Manager protection policies. The agent installation is separate from the metadata migration.

• Q7: Can migration from multiple Avamar servers occur?

A: Yes - But you must run the tool separately for each Avamar server with appropriate configuration files. Each Avamar server requires its own config_input.yaml file with the correct credentials.

• Q8: How long does the migration take?

A: Migration time depends on the number of clients and the amount of metadata. Typically, metadata migration is fast (5-30 minutes per client), but PowerProtect Data Manager discovery and verification may take longer. Plan for 2-4 hours for a typical migration of 10-20 clients.

• Q9: Can the migration be rolled back?

A: The original data remains in Avamar and on Data Domain. You can reenable Avamar policies if needed. However, metadata in PowerProtect Data Manager cannot be automatically removed. Plan your migration carefully and test with a pilot group first.

• Q10: Is there any downtime during migration?

A: Backups to Avamar must be stopped (policy disabled), but the data remains accessible for restores. Plan for a maintenance window to complete the full migration process. Typically, there is no downtime for restore operations from existing backups.

• Q11: What versions of PowerProtect Data Manager are supported?

A: The GSAN Mover tool supports PowerProtect Data Manager version 20.1 and later. Verify your PowerProtect Data Manager version before starting migration. Refer to the Dell PowerProtect Data Manager Release Notes for specific version compatibility.

• Q12: Can application backups (SQL, Oracle, and so forth) be migrated?

A: No - The GSAN Mover tool is designed solely for file system backups. Application backups require different migration procedures. Contact Dell Technical Support for guidance on migrating application backups.

• Q13: What if an error is encountered that is not covered in this article?

A: Contact Dell Technical Support with the following information:

• • GSAN Mover log files
  • Configuration files (with passwords redacted)
  • PowerProtect Data Manager job logs
  • Error messages and screenshots
  • Environment details (PowerProtect Data Manager, Avamar, Data Domain versions)

• Q14: Can migration to a different Data Domain system occur?

A: No - The GSAN Mover tool migrates metadata while keeping data on the same Data Domain system. If you must migrate to a different Data Domain, additional steps are required. Contact Dell Technical Support for guidance.

• Q15: How to verify that the migration was successful?

A: Follow the verification steps in Section 8:

• • Verify that assets appear in the PowerProtect Data Manager-Migrated list.
  • Verify that all backup copies are visible.
  • Perform test restores to validate data integrity.
  • Run a new backup job to verify ongoing protection.