vCenter Appliance Migration Upgrade

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 ‘’.

Veeam.Backup.VmMigrator.exe prepareformigration <name_of_old_vCenter>

Below you can see the console output.

------- Veeam VM Migrator Tool Started -------
Input arguments: prepareformigration
Preparing for migration started
Getting VMs from
Got 211 VMs from
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

If you’re changing names anyway, don’t worry about that.


------- Veeam VM Migrator Tool Started -------
Input arguments: preparemigrationtask
Building DbObjects to VMs mapping started
Getting VMs from
Got 202 VMs from
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).


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.


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


vm-478 fcab600b-c678-44c0-b46a-3b608ba3b42b -> vm-205

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

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>


------- 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 -; destination -
Getting VMs from
Got 202 VMs from
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.


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.   🙂


Leave a Reply

Your email address will not be published. Required fields are marked *