Leveraging the Guest Script Manager package

Running commands or scripts in VM guest is something that has been done with vCO for quite a while using different mechanisms. A popular way was to use the VIX plug-in for vCO. This plug-in is not needed anymore since the VIX functionality is part of the vCenter API since vCenter 5.0 and there are guest operations workflows to copy a script and run it into a VM guest OS since vCO 5.1

Using these library workflows requires to copy scripts from the vCO filesystem or include the scripts in your workflows. Getting the script output can be tricky and if part of the script include parameters that need to be replaced with your custom workflows inputs it requires a bit more coding.

The Guest Script Manager package handles all of this for you so you do not have to reinvent the wheel. You can even create specific workflows to run existing scripts without having to do any vCO scripting !

Features

Script management : Add, edit, delete a script configuration. A script configuration contains:

  • Script type (bash, batch, Powershell) : Each type involve a different way of starting the script and getting the output.
  • Script content: The script itself. May contain parameters that will be replaced right before running the script.
  • Timeout: The time after the script execution is
  • Script interactivity: In case the script open a window that requires user interaction.
  • Script working directory: Where the script will run. Where the optional file will be copied.
  • File to copy: A file to be copied in addition to the script. For example a response file needed for the script.

The script configurations are stored as resource elements in the vCO database. This means :

  • Updating a script does not require updating a workflow
  • The scripts are in a much safer location compared to the filesystem
  • If you run a vCO cluster, the scripts are available for every vCO nodes
  • That you can export / import the script configurations in a package

The script configuration runner : “Run script in VM guest”

  • Search replace specified strings in the additional file, copy it to the guest (optional).
  • Search replace specified strings in the script, run it in the guest.
  • Get output code and output result, display these (including special characters supported by ANSI), fails the workflow if script failed.

There is also a workflow to run multiple scripts one after the other and a workflow to upload your files as resource elements.

Tutorial

First let’s run the “Add a script configuration” workflow. For the configuration name enter something descriptive like below. This will need to be a unique name.

Then set the type of script. If it is anything that can be started from cmd.exe use batch. Use bash for Linux scripts.

Script content is the actual script to run in the guest. In the script below [domain] and [userName] are parameter that we will pass at run time. You should be able to use any kind of characters to delimit your parameters.

Set a time out for the script.

Since this script does not require user interactivity, a specific working directory, an additional file we can skip the next inputs.

Submit the workflow. The script configuration has been saved. You can use “edit script configuration” if you need to apply any change

Now we can test our script. For this use the “Run script in VM guest” workflow.

  • Select a powered on VM.
  • Enter the credential for this VM.
  • Select the script you created.
  • Click on the “Not set” to set variable scripts.

Click on insert value. Enter the string you want to replace and the replacing string.

Submit.

If you look at the log you will see which variable are replaced, the content of the script and the output of the command.

If you right click on the workflow run and select “run again”, enter the password again and submit. This time the workflow fails and indicate the following error in the logs.

Create a dedicated workflow to run the script

Having a generic workflow to run your script is nice but you may want to create a workflow for each script so you can map the required parameter on specific workflow inputs.

  • Create a new workflow,
  • Drag and drop a workflow element “Run script in VM guest” on the line. Make sure this is “Run script” and not “Run scripts”
  • Click on “Setup” button at the top right to set the workflow parameters
  • Set scriptConfiguration as “Value”, click on input value and type in the filter the name of your script (in my case “Add domain user to administrator local group”). Select it.
  • Set scriptVariables as “Value”. Do not set any input value.
  • Click “promote”

If we would not have any script variables we would be done. Since we have some we need a couple extra steps.

Map the workflow inputs to the script parameters

  • Drag and drop an Action element before the “Run script in VM guest”. Choose the “addScriptVariableToArrayOfScriptVariables” action.
  • Click “Promote”
  • Rename “stringToReplace” with “domainVar” and set it to “Value”. Click on “Input value” and set it to [domain]
  • Rename “replacingString” with “domain”
  • Set the output to “scriptVariables”
  • Click “Promote”

We need to do this one more time for the username input:

  • Drag and drop an Action element before the “Run script in VM guest”. Choose the “addScriptVariableToArrayOfScriptVariables” action.
  • Click “Promote”
  • Rename “stringToReplace” with “usernameVar” and set it to “Value”. Click on “Input value” and set it to [userName]
  • Rename “replacingString” with “username”
  • Set the output to “scriptVariables”
  • Click “Promote”

Save your workflow, run it and voila !

Package your workflow

Now you may want to use your workflow on another vCO system or make your workflow available to other vCO users from your blog or with posting it in vCO communities.

For this create a new package. Name it according to your company name, department, and a meaningful name

Click on the + to add your workflow. It will add all the workflows, actions, resource elements dependencies.

To make your package leaner you can sort by folder and remove all the workflows in Library / vCenter : these are already part of the vCenter plug-in so no need to redistribute them.