VM Migration Series – Guest Customization for HCX Bulk Migrations

About VMware HCX

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 in the UI:

  • 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 the HCX “Extend the Network” and “Keep Your IP/MAC and VM Identity” is an excellent migration strategy (the one that I would personally recommend in most cases since it eliminates inhibitors), there are scenarios where an alternate approach is unavoidable or preferable:

  • 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.
  • Perhaps there is a DNS/NTP or other common management infrastructure in the cloud that the server should update to.

In these cases, a personalization script can be used to reduce manual steps per guest migration, and can reduce the time it will take for a refactored virtual machine to become fully operational at the destination according to an updated infrastructure design.

What is Required?

Guest Customization in the Migration Interface
mini-demo of guest customization options
Additional 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).
  • Guest customization is not available with Cold, vMotion, RAV or OSAM migrations.

Guest Customization with Personalization Scripts

One of the more powerful aspects of HCX Guest Customization is the ability to execute OS-based shell commands (bash scripts on Linux systems and batch/powershell scripts on Windows Server systems). The Personalization Script interface allows you to execute scripts (up to 1500 characters).

Windows Shell Command Reference

Powershell Command Reference

Bash Command Reference

Personalization Script Timing

When you add a customization script with the “precustomization” command-line parameter, it is called before the guest customization begins. As a result, the virtual NIC is disconnected and you cannot access the network.

When you add a customization script with the “postcustomization” command-line parameter, it is called after the guest customization finishes. As a result, the script is scheduled in the initialization process after the virtual machine powers on, the NIC is connected, and you can access the network. The time for the script to run is not included in the default timeout period and you avoid a guest customization failure.

Sample Personalization Scripts

Disclaimer: The examples below provide an example of the personalization syntax. These specific examples may or may not work depending on the specific operating systems and shell settings. We recommend building and validating the commands directly on the operating system prior to replacing the commands in the sample scripts below.
(As an example, the linux scripts below were prepared using CentOS, someone has pointed out that they will not work on Ubuntu. This disclaimer applies.)

Script Syntax Example for Windows Systems

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

Script Syntax Example for Linux Systems

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

Linux Syntax Example Replace the Guest DNS Server Entry

if [ x$1 == x"precustomization" ]; then
 echo Do Precustomization tasks >> /dev/null;
elif [ x$1 == x"postcustomization" ]; then
 echo Do Postcustomization tasks >> /dev/null;
 echo "nameserver" > /etc/resolv.conf
 echo "nameserver" >> /etc/resolv.conf

Windows – Execute a Powershell Script

rem this syntax will execute the PS script.
powershell.exe -File F:\createFile.ps1

Windows – PS Script After VM vNICS Are Connected

@echo off
if "%1%" == "precustomization" ( echo "do pre-customization tasks" )
else if "%1%" == "postcustomization" ( powershell.exe -File F:\createFile.ps1 )

Good luck! Fair winds and following seas!



  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


  3. How can I do a changes to the destination VM where the VM has completely replicated, but before it could be PoweredOn on the destination run a PowerCLI script to perform virtual hardware customization and/or validation


    • It’s possible to set up pre- and post- network connection OS scripts. The feature today doesn’t allow scripts to be run while powered off, the closest thing would be to independently perform the changes in the OS prior to the switchover.


    • Today it’s not possible to do that.

      In your mind does that mean after we finish replicating and powering off the source VM, we finish the process with a powered off VM? (Extended downtime?) or do you mean being over an isolated vm that can be powered off, not connected to the network or current VM, so it can be customized, etc (but some degree out of sync with the original)


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 )

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