Veeam vCenter Migration Utility
Veeam offers a vCenter Migration Utility. It’s not officially supported by Veeam Technical Support but very helpful if you have to relink a complex backup environment. (You’ll need a Veeam customer account to download).
Unzip the package on your Veeam server that holds the database. Use a short path like “C:\tmp\Migration-Tool”.
Requirements and preparations
- disable all jobs and wait until they’re all finished gracefully
- make sure you have the latest Veeam Backup Software Update installed and it supports your new vCenter version.
- make an image or snapshot of your Veeam server. I prefer cold snapshots (VM shut down) because they’re more robust and consistent.
- Backup your Veeam configuration; backup your Veeam database (to an alternate location!)
Migration procedure
[Optional] Update existing VMs BIOS_UUID in VeeamBackup Database
This step is optional and can be executed while the old vCenter is still in production. It’s a cleanup maintenance. You need to use the vCenter DNS name that is referenced in Veeam Backup Console. In our case the ‘real’ name of old vCenter was an IP address but in Veeam it was referenced by ‘vcenter.mydomain.org’.
Veeam.Backup.VmMigrator.exe prepareformigration <name_of_old_vCenter>
Below you can see the console output.
------- Veeam VM Migrator Tool Started ------- Input arguments: prepareformigration vcenter.mydomain.org Preparing for migration started Getting VMs from vcenter.mydomain.org Got 211 VMs from vcenter.mydomain.org Preparing for migration finished
Migrate to new vCenter
Now it is time to migrate all hosts and VMs to the new vCenter. A step that wasn’t clear in the documentation.
After you’ve moved all Hosts and VMs to the new vCenter, shut down the old one.
Rename old vCenter in Veeam database
If you’re planning to use the same DNS name for vCenter again, Veeam needs to replace the old vCenter name in its database. If you’re going to use a new vCenter name this step may be skipped.
Veeam.Backup.VmMigrator.exe renameoldhost <name_of_old_vCenter>
Output not shown, because I have skipped this step and used a new vCenter name instead. If you execute this command, your old vCenter will get an _old extension to its name in Veeam console.
Register new vCenter to Veeam
Now you need to register your new vCenter in Veeam Console. You may reuse the old name if you have renamed the old vCenter in Veeam database as shown in the last step. If you’re using a new name, you don’t have to care about naming at all.
If you look into one of your existing jobs (just for curiosity), you can see that there’s no size information (N/A) next to VM objects. That’s because Veeam has still the old MORef IDs in its database, but VMs already have new ones.
Prepare mapping list
Now we will create a mapping list.
Veeam.Backup.VmMigrator.exe preparemigrationtask <name_of_old_vCenter> <name_of_new_vCenter>
If you have executed the vCenter renaming task from above, you need to add the _old suffix to your old vCenter name. For example:
Veeam.Backup.VmMigrator.exe preparemigrationtask vcenter.mydomain.org_old vcenter.mydomain.org
If you’re changing names anyway, don’t worry about that.
Output:
------- Veeam VM Migrator Tool Started ------- Input arguments: preparemigrationtask vcenter.mydomain.org vc.mydomain.org Building DbObjects to VMs mapping started Getting VMs from vc.mydomain.org Got 202 VMs from vc.mydomain.org Building DbObjects to VMs mapping finished Writing migration task into file started Writing migration task into file finished: created task file - vcenter.mydomain.org_to_vc.mydomain.org_migration_task Migration task contains some mappings to the same VM. Please select one mapping for each VM and delete comment symbols in it
Now you will find a text file within your Migration-Utility folder with a name similar to: vcenter.mydomain.org_to_vc.mydomain.org_migration_task. Open this file in a text editor like notepad++ or else. Do not use Word.
Check and edit mapping
The file ending with ‘_migration_task’ contains several sections (taken from Migration Utility documentation).
//host names
This section contains the vCenter server names (old and new).
//solid
This section lists the VMs which existed in the old vCenter (as per database information) and are currently existing in the new vCenter with the same VM name and BIOS_UUID.
The Utility ties to match old and new VM names. Those pairings which are highly probable will be listed in section //solid.
//probable
In this section we will find pairings that are probable, but need verification. This includes:
- VMs with the same BIOS_UUID but with different names
- VMs with the same name but different BIOS_UUIDs
- VMs having more than one instance of the same VM name and BIOS_UUID present in the database
//old duplicates
For entries having several database records with the same name and BIOS_UUID, mapping is defined only for the VMs whose last restore point is the newest restore point. The rest of such objects fall into this old duplicates group; mapping for these objects is not specified (commented out).
//already migrated
This section lists the VMs which are already linked to the new vCenter (as per database records), with the names and BIOS_UUIDs same as the current values on the new vCenter.
//not found
This section lists all VMs that did not fall into other sections but previously existed in the old vCenter.
Usually you’ll find most pairings in section //solid. The table is formatted like
old_VM_ID old_VM-name BIOS_UUID –> new_VM_ID new_VM_name
Example:
vm-478 DNS1.mydomain.org fcab600b-c678-44c0-b46a-3b608ba3b42b -> vm-205 DNS1.mydomain.org
Have a look at the other sections. To exclude pairings from the list you may either delete the whole line or insert two forward slashes after –>.
Example: Here’s a matching in section //probable. As long as there’s a double forward slash before the new VM-Name it won’t be migrated.
vm-138076 NTServ163.mydomain.org_restored 38e77753-f395-4e47-a7f4-5e34fe154879 -> // vm-124 NTServ163.mydomain.org
After you’ve finished editing, save your task file.
Execute Migration Task
We now execute the migration task. Our edited migration-task-file will be the base fort the task. As long as the file remains in the same folder as the VMMigrator.exe there’s no need for a path.
Veeam.Backup.VmMigrator.exe executemigrationtask <migration_task_spec_file_name>
Output
------- Veeam VM Migrator Tool Started ------- Input arguments: executemigrationtask vcenter.mydomain.org_to_vc.mydomain.org_migration_task Parsing migration task file vcenter.mydomain.org_to_vc.mydomain.org_migration_task started Parsing source and destination hosts names Found hosts names: source - vcenter.mydomain.org; destination - vc.mydomain.org Getting VMs from vc.mydomain.org Got 202 VMs from vc.mydomain.org Parsing VMs mapping Parsing migration task file vcenter.mydomain.org_to_vc.mydomain.org_migration_task finished Execution of migration task started Execution of migration task finished
Re-add objects to Backup jobs
If you start a backup job now it will fail, because we’re not finished yet. You need to open every job, remove old objects (referencing to old vcenter) and re-add the same object from the new vcenter. You can check by clicking “Re-Calculate” to make sure the VM size is displayed. Special settings for guest processing will be kept.
Conclusion
Sometimes things are interlinked like cogwheels in a gearbox. You cannot change just one part without affecting other elements. That’s why the customer had to turn his environment literally inside out.
- cross migration upgrade of vCenter 6.0 -> 6.7
- replace vStandard-Switches by vDistributed Switches
- replace vShield by NSX
- upgrade guest introspection 3rd party solution
All he wanted to do was to change the IP address of vCenter. 🙂