Guest script manager package

[#1]

- 2016-11-01 - Please note that this package has been relocated to the VMware Sample Exchange‌ due to the recent decommission of FlowGrab.com.

- 2015-03-24 - The package is now hosted on fowgrab to allow communities contributions

- Updated 2015-01-05 by Daniel Linsley:

• Does not break anymore with UAC but UAC may still prevent some scripts to run.
• Improved sleep for better handling of low script refresh

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 file system 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 handle 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 file system
• 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 thanks to the included cmdAnsi.exe), 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.

Links

• Guest script manager tutorial
• Batch scripts samples
• PowerShell scripts samples
• Guest script manager package https://code.vmware.com/samples?id=1317‌(updated November 2, 2016 as the package moved from flowgrab to sample exchange)

Credits

• Reuben for the original guest Operations package.
• vCO Engineering to make available guest operations workflows in vCO 5.1
• Benoit for the included / modified "run script in guest" workflow
• Pierre Torris for creating cmdAnsi. Donateware on www.ptorris.com
• Burke / Henrik for testing early releases
• Daniel Linsley for providing enhancements to the original package

Known issues

You must turn off UAC on Windows (2015-01-05) Package updated by Daniel

Use the package with the date to get the latest. The other one was kept for people needing the original.

Disclaimer: These samples workflows are provided AS IS and are not considered production quality and are not officially supported. Use at your own risk. Feel free to modify and expand and share your contributions.

[pizzle85]

I have a simple bash script where im attempting to set some bash variables in the format: variable=something

when i try to use the variable like: echo $variable i get nothing

is there something special i need to do to use a bash variable?

[pizzle85]

i figured part of it out i had to use

echo \\\$variable

i didn't figure out why it doesn't like quotes

[chrisheartland]

Hi any ideas on this?

[2015-02-15 20:27:23.979] [E] /C powershell -OutputFormat text -NoProfile -NonInteractive -ExecutionPolicy unrestricted -f C:\Users\ADMINI~1\AppData\Local\Temp\vco_vmware61.ps1 > "C:\Users\ADMINI~1\AppData\Local\Temp\vco_vmware19"

[2015-02-15 20:27:25.272] [I] Writing resource to vCO server : /var/lib/vco/app-server/temp/cmdANSI.exe

[2015-02-15 20:27:38.890] [W] Script timeout - process has been killed

[2015-02-15 20:27:39.815] [I]

[2015-02-15 20:27:40.122] [I] Unable to access file C:\Users\ADMINI~1\AppData\Local\Temp\vco_vmware19 (Workflow:Delete file in guest / Scriptable task (item1)#9)

[Robin_Schifferd]

Hello,

I have some problems with the "Run Script In Guest" Workflow. I want to stop a Service with the command "net stop xxx", but everytime it says "access denied". The specified account has admin privileges.

I'm using the latest Version from 2015-01-05.

Any Idea?

[ebgloria]

Is there any way i can export my scripts from my DEV VCO to PROD?

[pizzle85]

Someone please correct me if I'm wrong but I dont believe you can run anything that requires you to run as administator with UAC enabled. I tried and tried but UAC is just doing what it's supposed to do.

[pizzle85]

Create a vco package and add "resources". All the scripts are resources. Export the package and import it to prod.

[ebgloria]

Will all COE-created scripts be included?

[ebgloria]

Got it. Thanks a lot!!!!!

[Robin_Schifferd]

Any Idea how I can stop/start Guest-Services from the Orchestrator?

[pizzle85]

I'd post that as a question on the vRO community forums.

[willonit]

Check this package out on FlowGrab

[JMC13]

Great, hopefully someone out there will get it to run powershell as admin and then this will be crazy useful

[mrBeestig]

Hey,

I am getting the same error as listed here: guest script error - powershell script type is not valid for OS null , on my scripts. Weird thing is .. not every time. I already added a sleep in " run script in vm guest"  workflow. When i run the script separately it runs fine. It's just when run from another workflow, so it seems. guest OS is windows 2012.

We use powershell to reconfigure the nics for .. multicast, load balancer etc etc. Some have several network interfaces. So when I deploy an entire test environment and have to wait 60 seconds in each script this will delay the deployment drastically.

[AlexAllenExpedi]

I struggled with this problem as well.

OS is returning null because vCenter is responding with a null value.

From our troubleshooting it appears that OS type only returns a value when guestOperationsReady.

You can hard code the OS type to fallback to a specific operating system if vCenter returns null.

Or you can implement a check to make sure that both vmware tools is running and vm.guest.guestOperationsReady is true.

In our testing we have seen vCenter take up to several minutes to populate that OS type.

~Alex Allen C.

[stvkpln]

This is another fun quirk for cdecanini_ -- I just noticed that when I run bash scripts, the file cleanup under /tmp/vmware-root isn't happening.. Digging into it, I found in the Run Script In Guest workflow has a decision (item 37) towards the end to check whether the script is powershell or not (since they're different variables)... and the logic it's using is checking whether the workflow attribute powershellScriptGuestPath is null or not... what I found is that it always goes down the line with the powershell removal regardless of if that attribute appears to have a value or not, and what I see are errors like this:

[2015-04-07 17:24:53.446] [I] A specified parameter was not correct.

(Workflow:Delete file in guest / Scriptable task (item1)#9)

[2015-04-07 17:24:53.740] [I] A specified parameter was not correct.

(Workflow:Delete file in guest / Scriptable task (item1)#9)

All I did was changed the decision to check the scriptType attribute, and if it was set to powershell, then return true... That fixed that right up. Might be something to consider for the next update?

[willonit]

stvkpln - let me know if you want to be added to the workflow team on flowgrab so you can push your updates. FlowGrab: View Project

[cdecanini_]

Steve would be an excellent contributor to the project since he has both the skills and the experience to make the package better.

I only build the original package for a PoC and reused it a few times when needed but do not run it on a regular basis to get a feeling on all the little things that would make it better.

[stvkpln]

Absolutely... though, I'm not 100% sure how I'd push updates up if the methodology for doing that is via a vRO plugin.

[chrisheartland]

HI,i'm getting a "validation error" message during one of my workflows. I can't figure out what's wrong i.e. if it's my script or what. Any other way to determine the issue?

[tschoergez]

right click on the workflow, and select "validate". that runs the validation again, and shows the detailed results.

Very likely some workflows / actions are missing, so I recommend you re-download and re-import the newest version of the package.

[chrisheartland]

Thanks for the reply. I got past this and got one job to fully succeed. I ran it a second time and got this error:

The guest process (pid) was not found. (Workflow:Kill process in guest / Scriptable task (item1)#8)

[qc4vmware]

I found a bug in the "Check Errors" script on the "Run Script In Guest" workflow.  Line 10 calls Server.warm, should be Server.warn . 

[ChristianWehner]

We saw the same behavior.

To solve this, we changed the 'set for Linux' item in the 'Run Script In Guest' workflow and added the following line:

script = script.replace(/\$/g, "\\\\\\$");

cdecanini_ maybe you could add this into your page as well. Thanks in any case!

[rszymczak]

Do you guys have any license attached to this package? I'd love to see it on LGPL v. 3  or Apache v. 2 It would allow others to work on it without fear.

[Burke-]

I can't find the link, but there is a license associated with all content uploaded to the VMware communities. As such, we don't attach individual licensing to packages we release to the communities. The workflow packages that get shared here are free to use by any who download them. The packages are not covered by any warranty and support is only community based.

[Dan_Linsley]

Community Terms of Use | United States‌

[thawkbravo]

Keep running into this error "Failed to authenticate with the guest operating system using the supplied credentials." in a cloned machine with no network connectivity. Is this a known issue ?

[qc4vmware]

I think I've found a bug or a bit of code left over from some debugging.  If you specify a working directory when calling a bash script an error is thrown in the "Set Script Filename" scripting task.  The second line in the task is a throw with no logic around it.  I've commented it out and the workflow seems to run as expected.

[qc4vmware]

This might be a silly question but I assume you are using a local account?  Is this a windows host or a linux host?  The only time i've received this error it has been legitimate and I use this package a lot.  Can you login via the console successfully?

[rszymczak]

Thanks Dan, wasn't aware of that.

[thawkbravo]

Its a Windows machine and I was able to login to that machine from console successfully with the same credentials. It happens with both local admin account and a domain account.

[qc4vmware]

I'm guessing you are running into a timing issue.  I've seen all sorts of weird behavior when cloning a windows system.  I always check for the tools as up and running but that is often not enough.  You may need another check or need to fix something in your environment if after cloning it is taking a while for the vm to be fully online.  Are you customizing the vm as part of the cloning process?  It definitely won't be available for login while sysprep is running or may be for a short time but you'll lose access.  Have you hopped on a console immediately after the vm is provisioned to observe whats going on and also watch the workflow and see at what point it craps out?  If it is a timing issue you may need to add an additional wait buffer or maybe loop running the script.  I have to do similar looping for quite a few services in our environment as it can take anywhere from seconds to minutes for some systems to replicate or come online without a really good way of checking status.  I have definitely seen our windows systems get hung when networking is not available.  I'm pretty sure sysprep gets really finacky when there is no network and/or dhcp available on a network.

Out of curiosity how are you testing the domain login if you don't have access to a network on the cloned machine?  Are you cloning a system that is joined to a domain already and has a cached credential?

[SteveR123]

This is excellent work, thank you!. Apologies if this has been asked previously, but is it possible to use another vCO variable in the value for "replacing string" in "add script variable to array of script variables". For example to pass the "vm" parameter or another parameter from a workflow?

Thanks in advance

Steve

[pizzle85]

If i understand you correctly you want to use the vRO variable "vm" as input in a script? If so there's several ways to achieve this. The way I do it is to add the "run script in VM" workflow to my workflow then create the variables it requires. I then add a new "script" item before the "run script in VM" workflow item and put the "scriptVariables" attribute which is an "Array/CompositeType" we just created as the output of the script. I then populate the properties like this:

veeamJobScriptVariables = new Array();

var jsObj = {stringToReplace: "varRepoName", replacingString: veeamRepositoryName };

veeamJobScriptVariables.push(jsObj);

var jsObj = {stringToReplace: "varJobEntities", replacingString: veeamEntityNames};

veeamJobScriptVariables.push(jsObj);

where varRepoName is the variable in my script i want to replace and veeamRepositoryName is an input to my workflow. The same for the second one, "varJobEntities" is the text in my script i want to replace and veeamEntityNames is an array of strings.

populating the variables

[ChrisMcCann]

Great set of flows, been using them forever.  Today, after about 6 months of constant use, I had some errors in communication to the VM/host/vCenter while this package was running.  This uncovered a few errors in the error handling scriptlet.  One error was defining var message inside the for loop then trying to use it outside the loop, another error was the wording for the guest operations check message, and the third was "System.warm" instead of "System.warn".  I don't have access to flowgrab from inside this client's network so I thought I'd post the fix while I still have it fresh.  This is the whole contents of the Error Checking scriptlet below the run script block.

var message;

if (errorCode.indexOf("Failed to authenticate") > -1) {

  message = "Failed to authenticate with the guest operating system, this workflow will now terminate.";

  System.error(message);

  Server.error(message);

  throw message;

}

else if (errorCode.indexOf("The guest operating agent could not be contacted")  > -1 ) {

  message = "Retrieving the process list failed, cycling back into the loop";

}

else if (errorCode.indexOf("The guest operations agent could not be contacted") > -1) {

  message = "Retrieving the process list failed, cycling back into the loop";

}

else if (errorCode.indexOf("The operation is not allowed in the current state") > -1) {

  message = "Machine temporarily not in proper state for process retrieval, cycling back into the loop";

}

else {

  message = "Unknown error. The error handler passed the following output: "+ errorCode;

}

System.warn(message);

Server.warn(message);

[qc4vmware]

I've reported the "System.warm" typo and a few other bugs I have found as well but heard no response from the guys maintaining it.  Maybe they can add us to the FlowGrab team so we can update the flows and push out the fixes?  willonit‌, cdecanini_ can you incorporate the stuff we've reported or give us access to make the changes?

[cdecanini_]

Sorry. I had very little time to look into updating the package. I do not have the admin right on will team so either he can add you to the team or I will need to find time to update the package.

Let's see first if Will can address the first solution.

[qc4vmware]

Thanks.  These are all just small changes but I'd really like to get them into the package so I don't have to always modify it post update.  Hopefully we'll get a response from someone soon.

[willonit]

qc4vmware‌ you've been added to flowgrab. cdecanini_‌ I changed your permissions so you should be able to push updates of the packages now.  Once a new version is committed if anyone would like to volunteer to download and run it before we release that would be very helpful.

[cdecanini_]

I have downloaded and tested the version from flowgrab user ectoplasm88 successfully. I am assuming this is the update from Paul / qc4vmware. I would advise to release this version since in my opinion this is the greatest.

[willonit]

I have as well. qc4vmware‌, can you push your branch to master with a description of changes made and I will release a new version. Thank you for your contributions!!

[qc4vmware]

OK.  I committed my changes to the master.

[willonit]

Released

FlowGrab: Guest Script Manager

[SeanKohler]

It doesn't appear that any of the workflows have been up-versioned and as such are not selected on import. Which workflows/actions changed?

[qc4vmware]

Weird... I am positive that the versions were changed.  "Run Script in VM Guest" and "Run Script in Guest" were modified.  Both modifications are very minor.  Fixed the Server.warm typo and also uncommented what was seemingly a random throw statement.

This was my first attempt at collaborating on FlowGrab so hopefully I didn't miss a step of some sort.

[SeanKohler]

Yeah... I see it now, and it has a higher version. Something else going on... probably on my end.

[cdecanini_]

Did you download the package from flowgrab in the first place ? It looks you did not have the version.info that is added by flowgrab. If the initial install and the upgrade were done with different packages then vCO will notice it has been branched and will not offer to upgrade elements until you check the elements manually.

[Mnemonic]

Hi,

2 Things..

1) Great work on this, it is MOST helpful..

2) Is there any way to have authentication pass-through when running the scripts. I would like the to be run as the user starting the workflow. I could just make them authenticate again, but it seams a little redundant..

Best Regards

/Brian

[rszymczak]

Hi Brain,

I think GuestAliasManager, which was introduced with vSphere API 6.0, could be the right direction to do this. Very powerfull API call if you ask me. Haven't yet had the time / project to make use of it. But if the community decides this is usefull, I can help to implement it in the package. I had the task "refactor guest script manager package" on my todo (task 3078 of 7094) anyways,..