VM Migration Series – Guest Customization for HCX Bulk Migrations

VMware HCX provides virtual migration technology to enable mobility between distinct vSphere sites (as well non-vSphere to vSphere site with the OSAM technology). Here is a quick recap of what is available:

HCX Cold Migration – Site to site serial offline migration of virtual machines using VMware NFC technology.

HCX vMotion Migration – Site to site serial live migration of powered on virtual machines using vMotion technology.

HCX Bulk Migration – Site to site parallel low down time migration of powered on virtual machines using VMware vSphere Replication technology.

HCX RAV Migration – Site to site parallel live migration of virtual machines, using replication for the transfer phase, and converting to a vMotion during the deltasync and switchover.

This post focuses on one of the capabilities of HCX Bulk migration.

About HCX Bulk Migration

  • One of the preferable characteristics of Bulk migration is that it is resilient to harsher environment conditions (higher/variable latency/lower-bandwidth) when compared with vmotion based transfers. While a Bulk-based transfer of a single VM is slower than a single VM vmotion, the data transfers can be parallel and planned. It allows migrations to take place irrespective of CPU vendor or EVC Baseline levels (even new CPU to older CPU). Bulk migration can tolerate some amount of some refactoring of the source virtual machine (tell me more). This makes HCX Bulk migration a good option for any scenarios some planned application downtime (roughly the time of a reboot) can be tolerated.
  • There is another interesting characteristic of the HCX Bulk migration option – in that it provides the ability to perform some customization of the Guest OS. This capability was added to HCX in the R114 back in January 2019, just giving this capability some belated attention in this post.

What is Guest Customization?

Allows the user to customize certain aspects of the virtual machine as part of the migration operation, the following virtual machine attributes can be modified:

  • Guest OS Hostname
  • IP Address
  • Gateway
  • Netmask (Subnet Mask)
  • Primary DNS
  • Secondary DNS
  • Security Identifier (Windows SID)
  • Execute Pre- or Post- Guest Customization scripts.

Guest Customization is applied when powering on the virtual machine at the destination environment.

This functionality is also supported for reverse migrations.

Why Guest Customization?

In-flight Virtual Machine Transformation

While “Extend the Network” and “Keep Your IP/MAC and VM Identity” is an excellent strategy (the one that I would recommend in most cases), there are some merits in the alternate approaches.

Perhaps non-production workloads are being relocated to free up critically private prefixes. In this case, some refactoring may be unavoidable, and taking care of the refactoring inflight could be a massive time saver.

What is Required?

  • HCX Software version: All generally available versions contain this capability
  • HCX tier: HCX Advanced
  • Windows Operating Systems: Windows Vista / Server 2008 and beyond
  • Linux Operating Systems: Red Hat Enterprise Linux, CentOS, Ubuntu
  • VMware Tools: This capability requires current VMware Tools (today that is 10.1.x+)

Guest Customization in the Migration Interface

mini-demo of guest customization options

Some Caveats

Changing the SID of a Windows machine that is already the member of a Windows domain will break the domain relationship and require the machine to be re-joined.  On a domain controller, this operation can impact the domain.  The Generate New Security Identifier (SID) option is disabled by default (use with care, test things first).

The option is not available for Cold, vMotion, RAV or OSAM migrations

Sample Personalization Scripts

For Windows based systems:

@echo off 
if "%1%" == "precustomization" ( 
  echo "do pre-customization tasks"
) else if "%1%" == "postcustomization" ( 
  echo "do post-customization tasks"

For Linux based systems:

if [ x$1 == x"precustomization" ]; then 
  echo "do pre-customization tasks" 
elif [ x$1 == x"postcustomization" ]; then 
  echo "do post-customization tasks" 

Fair winds and following seas!


PS: There’s an old friend’s blog post out there that hashes out the personalization scripts and discusses Pre-/Post- timings (documentation on this is indeed scarce) See vCloud Director – Using Guest Customization Scripts (Linux).


  1. Thank you for the great article. I was looking at potentially using the guest customizations during bulk migration but I can’t seem to find a way to do configure them for Bulk migrations via PowerCLI. Any idea ? I already have bulk migrations scripted in PowerCLI since we’re doing hundreds of VMs but adding guest customizations would be even better.


  2. Hi,

    I am working on bulk migration using hcx. Checking if vmtools should be installed on vms for bulk migration mandatorily


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s