The intent of this article is to cover the steps for leveraging scripting within guest customization. A vCloud user may wish to peruse this as an avenue of automatically installing additional software that is hostname specific, e.g. security management software that integrates a Linux OS to Active Directory.
I am going to assume the reader knows how to login to vCloud Director, either within an organization or within the system context. I also assume that an existing virtual machine exists that we will work with, in my example I will use Linux (CentOS).
- Stop the vApp if it is currently running (we cannot edit the properties of a running VM)
- Open the vApp so that we can see the individual virtual machines
- Right click the virtual machine (or use the action menu) to access the Properties
- Switch to the Guest OS Customization tab
- Select the option to “Enable guest customization”
- This enables basic guest customization, such as configuring the guest OS hostname, setting the root password and network configuration.
- Scroll down within the guest customization tab
- You will see a text box, we can input script content within this text box. Alternatively you can upload the script that will be injected into the guest OS during the customization process. I will first start with a simple script that calls an existing shell script within the guest OS. Please also notice that we have specific sections for “precustomization” and “postcustomization”, pre-customization is before the standard vCloud Director customization process and the other is post this process. If the script that you wish to use is dependent upon the hostname or network connectivity, then you would be best served by using a post-customization script.
In my example I am calling out to two scripts myscript-pre.sh and myscript-post.sh — these scripts must be in place within the OS file system before it can be ran
NOTE: If you wish to upload a script using the Browse button it must be a text only script, it cannot be an executable binary.
- Click OK to save those changes
- Power on the virtual machine as usual
- Create your script within the guest OS in the path you specified
- My test script is quite lame, so don’t laugh. The goals are to answer questions that I’ve seen, such as if the network is available and which user context the script runs under.
- Shutdown your virtual machine
- Right click and select to Power On and Force Recustomization
- After customization completes, login and verify that your script ran.
There seems to be little documentation from VMware on “when” exactly a pre-customization script is ran vs a post-customization script. The time is only 23 seconds apart, so what exactly occurs during those 23 seconds? Logging services (syslogd) and most other system services do not start until after the pre-customization script has ran, so little output exists for what occurs during that window (or prior). It appears that pre-customization occurs at the time that vmware-tools start, on my system that is S03…which is the 2nd service to start (after microcode_ctl). You can also compare your time stamps to /var/log/messages in order to see what events are occurring.
In looking at the /var/log/vmware-imc/customization.log we can see a bit more detail as to timing.
Pre-customization occurs before the default vCloud Director customization scripts set execute, which set hostname and network configs (and generate SID or join an AD domain on Windows).
Post-customization is likely the area that most scripts will need to be executed, after the network configuration is set. In testing I encountered a situation that a script that was dependent on additional network services (e.g. to support NFS) would fail if executed directly as a post-customization script, a work around that resolved this was just adding a “sleep 30” prior to the script execution.
An area of challenge is troubleshooting these scripts as there is no way to run customization in an interactive form. The easiest way to confirm things are going to work is making sure the script can run as root if you execute it directly from a login shell. Next you can insert it into the post-customization process and assume that it will work. VMware has published a couple of KB articles that discuss which log files are relevant to the process, you can review those logs for any errors. Ideally your script itself will have error logging capability.
If you wish for advanced customization capabilities, then your best bet is probably to not use the vCloud Director customization at all…or at least only use it to configure the networking. vCenter Orchestrator is far more feature rich and extensible, the limitations on what can be done in vCenter are most likely only constrained by the amount of effort you put into developing your workflows. The customization process used within vCloud Director is more similar to that of Lab Manager than of vCenter, so if you run into trouble you may try searching under Lab Manager discussion groups.
- VMware Lab Manager Online Library: http://pubs.vmware.com/labmanager3/wwhelp/wwhimpl/js/html/wwhelp.htm
- VMware vCloud Director Online Library: http://pubs.vmware.com/vcloud-director-1-5/wwhelp/wwhimpl/js/html/wwhelp.htm#href=user/GUID-655D00F0-CA72-48AB-BE8B-0FEACD84951A.html
- VMware KB Article 1026614 “Setting the customization script for virtual machines in VMware vCloud Director”: http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1026614
- VMware KB Article 1026317 “Troubleshooting guest operating system customization issues using VMware vCloud Director”: http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1026317