vCloud Automation Center – vCAC 5.1 – Executing Scripts with the Linux Guest Agent

Caution: Articles written for technical not grammatical accuracy, If poor grammar offends you proceed with caution ;-)

I’ve been getting asked a lot of question on how to execute scripts within Linux Guest Systems using vCAC. There are a few components to executing scripts in a Linux Guest OS which I’m going to cover in this post. Those items are:

  • Linux Guest Agent
  • Custom Properties

Linux Guest Agent

The Linux guest agent has a number of feature benefits that you receive if you utilize it. The Linux guest agent is a small agent that acts very similarly to the vCAC proxy agents. When it is installed you give it the name or IP address of the vCAC server. This allows it to check in with the server when it loads on a newly provisioned machine and determine if there is anything it needs to do. If the vCAC server has work for it to do it send the instructions and the agent executes the instructions on the local guest operating system. The guest agent comes with a number of pre-built scripts and functions, but also allows you to execute your own scripts. Some of the features available with the Linux Guest Agent are:

  • Disk Operations – Partition, Format, and mount disk that is added to the machine.
  • Execute Scripts – Execute scripts after the machine is provisioned.
  • Network Operations – Configure setting for additional network interfaces added to the machine.

This article is primarily about executing scripts with the guest agent, however by installing the guest agent if you add a disk and define the proper paramaters you will be able to utilize the Disk Operations that it supports. I will discuss networking in more details in a different article.

Installing the Guest Agent

1. You will need to install the Linux Guest Agent in your VMware Template that you will be using. In my example I’m using Centos 6.3 x64.
2. You will need to get the agent into your template either by accessing it across the network or by putting it on an ISO and mounting it to the VM. The agent are part of the vCAC installation package and are located under “LinuxGuestAgentPkgs” there you will find agents for a number of flavors of Linux.
3. Once you have your agent on your template you need to install the agent package. There are generally two packages, a tar.gz as well as a RPM. I will be installing the rpm file for rhel6-amd64. The specific package name is “gugent-5.1.1-56.x86_64.rpm”.
4. Install the package by doing the following: rpm -ivh path/gugent-5.1.1-56.x86_64.rpm. In the below image mine was already installed, but you get the idea.
5. Next we need to execute the agent installer. You need to go to /usr/share/gugent and run ./ {vcac server} you can use either the IP address of hostname of the vCAC server.
Note: To perform an HTTPS installation run /usr/share/gugent and run ./ ssl {vcac server:443}
6. You can verify the proper name/IP by doing “cat” and looking at the “–host=” statement on the 6th line.
7. We next need to rename one of the scripts that is included with the Linus Guest Agent due to a bug. Navigate to “/usr/share/gugent/site/CustomizeGuestOS” In this folder you will see a script named “” this script is depreciated and not needed. Rename the script to “” by doing “mv“.
8. If you want to follow the example that I will be giving you should also create a folder on the template to be utilized as a mount point for an NFS share. I created “/Scripts” and my mount point by doing “mkdir /Scripts“.
9. Next I created a helper script in the template that I will use to mount my NFS share. I placed my script in the root of the disk, but you can place it where ever you like. A good place for it would be in “/usr/share/gugent/site/CustomizeOS“, but it really doesn’t matter where you place it.
10. My script is named “” and looks like this: “mount -t nfs $1 /Scripts” nothing fancy at all.
11. Once you have the script created go ahead and “shutdown” your template machine and “Convert it to a template” in “vCenter“.

Configure vCAC

12. If this is a “new template” that you just created you will need to “manually” perform a “Data Collection” in “vCAC“. You can do this by navigating to “Enterprise Administrator” Selecting “Compute Resources” and hover over the cluster that the template exists in and then select “Data Collection” Once there click “Request Now” under “Inventory“.
13. Once the “Data Collection” is complete your “template” will be ready for use.
14. If you don’t already have a blueprint that can deploy this “template” you will need to create one. See my article on “Connecting to vCenter” for instructions on creating a blueprint.
15.Next we are going to create a “Build Profile” that we can use to hold our properties. Navigate to “Enterprise Administrator” and select “Build Profiles” then select “New Build Profile“.
16. Give the “Build Profile” a “Name” and then we are going to add some “Custom Properties” to the profile. We need to add the following properties and values:

  • repo.path – This is a property that I made up for this example. It is not part of vCAC. The value should the the path to your “NFS” share in the format “IP:/volume/share” This is what we are going to mount to the folder we created earlier
  • VirtualMachine.Admin.UseGuestAgent – This tells vCAC to utilize the guest agent as part of the deployment process. The “value” should be “true“.
  • VirtualMachine.Customize.WaitComplete – This tells vCAC to wait until the vCenter Guest Customization is complete. If you do not use “Customization Specifications” you do not need this property. The “value” should be “true” if you use vCenter guest customization.
  • VirtualMachine.Software0.Name – Assign a name for the script you are going to execute. “Value” is a “Friendly Name” for your script.
  • VirtualMachine.Software0.ScriptPath – Path to your script including the script name. You can pass parameters to your script as well. I’m passing the value for the “repo.path” that I created earlier to my script to be utilizing as the “NFS location” to mount. The value is “/ {repo.path}“. Note: The {} brackers are required in the value.
  • VirtualMachine.Software1.Name – I’m executing a second script so I’ve used the “VirtualMachine.Software1.Name” property again only with a 1 instead of a 0 this time.
  • VirtualMachine.Software1.ScriptPath – I’m executing a second script. This one s located on the NFS share that I am mounting with my first script. My script is “” and it contains “echo “The script was successfully executed” > /Script_Successfull.txt

17. Click “Ok” to save the “Build Profile
18. Next we need to assign this build profile to our “Linux Blueprint“. Go to “Enterprise Administrator” select “Global Blueprints“, then select the “Linux Blueprint” and then “edit“.
10. Once the “Blueprint” opens select the “Properties” tab and select the “Build Profile” you just created and then click “Ok

So what does all this do

When you request a machine custom properties are associated with the machine. Some custom properties are what we call reserved properties because vCAC understands them and performs actions based on them. The “VirtualMachine.Admin.UseGuestAgent” property tells vCAC that when the machine is provisioning it needs to create workitems for the “Linux Guest Agent” to pick up. The “VirtualMachine.SoftwareX.Name” and “Virtualmachine.SoftewareX.ScriptPath” are put into the work item that is created by vCAC to instruct the ‘Linux Guest Agent” to execute those scripts.
In this example the first script will execute and mount the NFS share that I defined my my own property “repo.path”. Once complete the second script will run and execute “” which will create a txt file. The guest agent performs it’s tasks after the VMware Guest Customization if being utilized otherwise it completed it after the “Machine Provisioned” state. Once the Linux Agent completed all it’s work items it will then remove itself from loading on future loads and stop it’s service.

15 Replies to “vCloud Automation Center – vCAC 5.1 – Executing Scripts with the Linux Guest Agent”

  1. Hi,

    Do you also know how to execute scripts on a Windows template with guest agent installed?
    I tried the similar setup but got error like “error creating WorkItem CustomizeOS The given key was not present in the dictionary” in machine request.


    1. Yes. I will be posting an article on this topic this week. I’m hoping by this evening or tomorrow.

      Thanks for reading,

  2. Hi Sid, I might have an interesting question here for you. 🙂 We’re in the middle of a vCAC deployment, and we have run into a problem with passing information from the vCAC installation to the linux hosts. We want to provision a template for a matched pair of linux hosts from a single linux vm image, one being a database, one being a web front end. vCAC can successfully set the host names and IPs, and can write a file to each VM filesystem that sets a property of “db-server” or “web-server”, however, we can’t find a way to write the FQDN and IP of the DB server as file on the web server. Without this information, we cannot automatically configure the services on the web server to point to the correct database server.

    Do you have any suggestions on the most straightforward method to accomplish this?

    We are using puppet to configure the hosts after the template is instantiated, but without a way of accessing basic vCAC template information such as IP and FQDN assignments relationships for both hosts, we are stuck. A file containing all the template information regarding both hosts in the template that could be placed on either of both of the vm’s file systems would solve this issue, but we don’t see how to do that.


    1. Sean,

      There are a few ways to do this. You saw in the example you can pass parameters through with the script. You could create a custom property that defines the domain to associate with the machine and pass that through as a parameter. vCAC doesn’t know what domain the machine should belong to, but you can either define it or create a dropdown menu and let the user choose the appropriate domain to utilize for the FQDN. In you script you can just apply it to the hostname to make the FQDN. You can also pass through the machine IP address using the property VirtualMachine.Network0.Address.

      This can be daunting to do if you want to pass a lot of properties to your script. There is another option. Under the /use/share/gugent/site/CustomizeOS folder there is a file name properties.xml that contains all the custom properties associated with the machine. You can skip passing parameters through and simply parse this XML file to get whatever information you like, including IP address.

      Hope this helps,

  3. Hi Sid – found your article around vCAC to be very informative and helpful with our deployment. However, we have run into an issue where when we add a disk to a VM that’s already built, it reboots the Servers (Windows and Linux) Have you run into something like that?

    Also,when i add a disk to a Linux VM with a certain mount name for eg OPT through vCAC, how do i pass that information (name OPT) down to the VM for it lay out the disks accordingly?
    Any guidance would help!

  4. Hi Sid,
    How we can perform error handling when custom scripts are invoked on the VM ?
    For example if the custom script fails during execution and hence we need to destroy the VM. Can we handle such situations ?

  5. Hello,

    I am trying to execute a Guest script as described in your excellent article.
    It is not working for the moment.
    The only thing I found on logs is in the Guest OS part the “GuestAgent.log” log file with these 2 lines :

    Application: [Error] Failed to query machine for UUID
    Application: [Debug] Uninitializing subsystem: Logging Subsystem

    Any idea ?


    1. Hey Johnsse

      If you’re getting this:
      Application: [Error] Failed to query machine for UUID
      Application: [Debug] Uninitializing subsystem: Logging Subsystem

      Make sure the dmidecode package is installed on your system. For whatever reason it’s not listed as a dependency.

  6. Hi ,
    Thanks for this usefull info.
    I have problems with pass through properties, what is the syntax ?
    Tried :
    Name Value {VirtualMachine.Network0.Address}
    VirtualMachine.Software0.ScriptPath MyScript.bat {}
    or VirtualMachine.Network0.Address
    VirtualMachine.Software0.ScriptPath MyScript.bat {}
    VirtualMachine.Software0.ScriptPath MyScript.bat {VirtualMachine.Admin.Owner}

    This example below works as expected, but does involve not passing a build in property. MyText
    VirtualMachine.Software0.ScriptPath MyScript.bat {}

    In my case I want to pass the machine owner to a Windows bat file, but I guess the princip is the same .

    Regards Anders

    1. Hi Anders,

      The VM owner is a little different, unfortunately, and doesn’t work with property access the same way. I believe just using {Owner} works, but I’m not 100% certain. Otherwise, there is another property that works in PowerShell when you invoke it from a workflow which might be worth a shot. It’s {__Legacy.Workflow.User}.

      Let me know how you make out.


  7. Does any one know whats this error ??

    # ./
    Application.MachineQuery: [Information] uuid = 421347f4-cd16-de25-ea9e-d6e9XXXXXXX
    Application: [Debug] Using the network enabled proxy …
    Application: [Debug] The vCAC endpoint is https://IAAS-server:7444/VMPS2.
    Application: [Debug] The AXIS2C directory is axis2/.
    Application: [Debug] Requesting work for agent ID f4471342-16cd-25de-ea9e-d6e9xxxxxx.
    Application: [Debug] Fetching a work item …
    Application.Proxy: [Error]

    Application.Proxy: [Error] Error returned by axis2: Error occurred in transport
    Application.Proxy: [Error] Consult axis2 log file at axis2/logs for more detail

    Application: [Debug] Requesting work for agent ID 421347f4-cd16-de25-ea9e-d6e9xxxxxx.
    Application: [Debug] Fetching a work item …
    Application.Proxy: [Error]

    Application.Proxy: [Error] Error returned by axis2: Error occurred in transport
    Application.Proxy: [Error] Consult axis2 log file at axis2/logs for more detail

Leave a Reply