1 Introduction

After an enterprise bulk deploys or clones VMs, the system configuration (such as the network, hostname, installed software, and security enhancement) needs to be initialized in scenarios of large-scale deployment (dozens/hundreds of VMs), automated deployment, and bulk replacement. In the traditional deployment process, users need to wait until VMs are created and started and the network connection is ready. Then, they need to execute the initialization script and install necessary software through SSH connections, the console, or other maintenance methods. The entire process is time-consuming, incurs certain manual costs, and cannot adapt to automated processes. The customization specification feature simplifies the initialization script execution and necessary software installation operations into fixed initialization templates. During VM creation and startup, customization specifications (covering shell scripts, Sysprep answer files, and Windows batch processing programs) can be automatically executed to complete initialization without manual intervention. In large-scale deployment scenarios, different VMs can use the same customization specification to significantly improve efficiency.

Customization specifications leverage vmTools's capability to communicate with hosts to inject scripts into VMs for execution. The execution process is shown in the figure below.

Execution scenarios: In the following scenarios, you can specify customization specifications for VMs and enable them to be executed automatically upon the first startup of VMs:

1. Create VMs using built-in images.

2. Clone existing VMs.

3. Migrated VMs with a customization specification specified but not executed.

You need to configure a network connection for VMs. The platform will wait for the network connection configuration to take effect (VM NIC IP addresses are ready) before executing customization specifications. If no network connection is configured for VMs, the system will not wait but will execute customization specifications after vmTools is ready.

2 Precautions

1. Only VMs created using built-in images or cloned VMs support customization specifications.

2. Customization specifications will be executed upon the first startup of newly created VMs. First startup includes automatic startup as scheduled when VMs are created and manual startup after VMs are created. They will not be executed when VMs are restarted.

3. vmTools requirements: Customization specifications can only be referenced when the vmTools is installed on images/VMs and a flag file exists.

4. When a VM with a customization specification specified but not executed is migrated to another cluster, the migrated VM will automatically inherit the customization specification of the source VM. The customization specification will be executed upon the first startup of the migrated VM.

5. Limit on the number of VM customization specifications: SCP supports creating up to 100 customization specifications.

6. Limit on the custom script length: The text length of user-defined scripts (custom Sysprep answer files, BAT scripts, and Linux executable scripts) cannot exceed 3 MB.

7. The platform will wait up to 10 minutes starting from VM startup. If vmTools fails to start normally or the VM network configuration does not take effect, customization specification execution will be terminated.

8. VM customization specifications are supported on most mainstream operating systems, except for certain operating systems. After test, the following operating systems support customization specifications:

Windows 7 (86-bit)

Windows 7 (64-bit)

Windows 10

Windows 11

Windows Server 2008 R2 (32-bit)

Windows Server 2008 R2 (64-bit)

Windows Server 2012

Windows Server 2016

Windows Server 2019

CentOS 6 (32-bit)

CentOS 6 (64-bit)

CentOS 7.3

Ubuntu 11 (32-bit)

Ubuntu 11 (64-bit)

Ubuntu 16

Ubuntu 18

RHEL 6

RHEL 8.2

Debian 8

Debian 9

SUSE 12

SUSE 15

Windows Vista SP2 and earlier versions, as well as Windows Server 2008 R1 and earlier versions, do not support VM customization specifications. For other operating systems, you can verify whether the customization specification feature can work properly. If any execution error occurs, please contact technical support for troubleshooting.

9. If a customization specification fails to be executed, the platform will report a related alert. You can check the failure cause through the alert and the corresponding operation logs.

3 Prerequisites

1. vmTools has been installed on images or VMs to be cloned.

2. A customization specification flag file has been created as required for built-in images or VMs to be cloned.

For a created or cloned VM, please confirm that a flag file exists in the installation directory of vmTools for the selected image or parent VM. To create a flag file for the selected image, go to Images to update the image. To create a flag file for the parent VM, click Console to access the VM's file system, and configure as follows.

Default installation directory for Windows:

32-bit operating system: C:\Program Files\Sangfor VMSTool

64-bit operating system: C:\Program Files (x86)\Sangfor VMSTool

Open the Command Prompt and execute the following command with administrator privileges to create a flag file:

cd "C:\Program Files (x86)\Sangfor VMSTool"

echo.> custom_exec_enabled

Default installation directory for Linux: /usr/local

Open the endpoint and execute the following command to create a flag file:

touch /usr/local/custom_exec_enabled

The flag file is used for verification before script execution. If the file is not found, script execution will be blocked.

The flag file will be automatically deleted after script execution. To mitigate security risks from residual data, you are advised to manually delete the flag file and promptly respond to any related alerts.

4 Procedure

1. Manage VM customization specifications

You can perform basic management operations on VM customization specifications, including creation, editing, and deletion. VM customization specifications are supported on both Windows and Linux systems. Windows systems support manually configuring specifications or using user-defined Sysprep answer files or batch files (BAT files). Linux systems support executable scripts.

Take custom script creation for Linux as an example. Go to Resource Center > Settings > VM Customization Specs, and click Create.

Enter the content of the custom script, or upload a script. Then, click Next.

Click Confirm to complete creation.

For customization specifications for cloned VMs, if you want to debug or modify such specifications, you can use the cloning feature to create a copy to avoid affecting the original specifications.

Import and export VM customization specifications: You can export VM customization specifications as files for archiving and versioning (Git, SVN, and so on). The import feature facilitates the copying of customization specifications across data centers (SCP), avoids repetitive creation operations, and reduces the misoperation rate.

2. Create a VM and reference a customization specification

Go to the Resource Center page and click New.

Note: The HCI version of the resource pool for VM creation should be 6.11.3 or later.

Select a built-in image of a Linux operating system and click Next.

In the Configuration step, find Customization Specification in the Advanced section, and select a customization specification. After the VM is created, the customization specification will be automatically executed upon startup of the VM.

3. Clone a VM and reference a customization specification

Select a VM using a Linux operating system, click Clone, and enter the configuration page.

Find Customization Specification on the Advanced tab and select a customization specification. The customization specification will be automatically executed upon the first startup of the cloned VM.

4. View logs

After a VM is started for the first time, you can find the VM in the VM list and click Tasks to check whether the customization specification is executed successfully.

If the execution fails, an alert will be generated on the Tasks page.

You can go to the Management > Tasks page to view the detailed execution result. If the execution fails, the failure cause will be displayed.