Daniel Langenhan

IT Consulting and Architecture for Automation and Cloud

CoolRun

This package enables vRealize Orchestratior (vRO) to run scripts of various types inside a VM using VMware tools.

Versions

Version
(of "CoolRun Subsystem")
DateChange
5.014.09.20vRO 8.x ONLY 
  • changes for vRO 8.x
  • added fireAndForget option (not waiting for exit code on VM)
  • added new DiskExtend and DiskAdd scripts for Windows in Powershell
4.4.016.10.19
  • Added failOnError flag. This will fail the execution if the error code is not 0
 4.3.0 20.09.19
  • Added showPassword and showScript to the property options.
  • Update to this page. Explaining some prerequisits for coolRun. 
  • updated to vRO 7.6 files (full compatible with older vRO versions) 
4.2.016.08.19
  • Added windows Registry Import wrapper
  • added delLocalFile property which stops deleting the local vRO copy of the excutable
  • new Workflow "Clean up vro local files" that will delet all coolRun files that start with cR- and CRRet-
  • new Workflow (beta) "coolRun GetResults" that copies input back from the VM to vRO
  • Cleaned up configuration file, naming and version numbers
  • Addapted for vRO HTML Client
  • cleanup this documentation
4.0.620.11.18
  • Added missing Process ID to log
  • added new wrapper "powershell64" which uses C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe the normal powershell wreapper executes c:\windows\syswow64\WindowsPowerShell\v1.0\powershell.exe
4.0.513.11.18Build problems....
  • the Action “vim3WaitToolsStartedSilent” needs to be in the folder “de.vleet.cool.helpers”
  • PreRequisite Checker needed update due to the fact that a SecureString is automaticly converted to a String inside a Property

Special thanks to Kjeld Thorlund for finding the bugs.

4.0.312.11.18Pre-requisite Checker
Cleaned up Schema and added comments
added debug Flag option
added more logging
added clean-up for Carriage return for Linux Scripts
added check for Working Directory and creating it if necessary
extra Workflow for clean-up of local vRO File
Clean-up example workflows
added exit code as output
0.323.07.18added showPassword (VMpassword is not shown in debugglog)
added interactive (to trigger interactive session
fixed testing and debugging issues
0.204.07.18Support for MacOS, Added optional value OSName, Working Directory is not a required field anymore.fixed configuration workflow and file.
0.1.322.12.17fixed Centos detection, added cmdPowershell extention
0.1.121.09.17
Initial Web published version

Highlights

  • Easy to use script ruinning engine
  • Replace {tags} in the script template with values from vRO
  • Can use Windows, Linux, (virtual) ESXi, MAC and Photon OS  
  • Runs Linux Bash, Linux PHP, Linux Python, Linux Perl, Windows DOS, Windows PowerShell, Windows Diskpart
  • Can be easily addapted to run other OSs or Script types
  • Stores Configuration centraly and differentiates between Linux and Windows login credentials

Description

CoolRun enables you to run scripts inside a VM without caring to much about copy, run, check etc. Using {tags} in the script you can replace these tags with any value from vRO. The workflow has the correct script exection setting for Linux Bash, Linux PHP, Linux Python, Linux Perl, Windows DOS, Windows PowerShell, Windows Diskpart build in. This for example allows a user to create a workflow that would add a new Disk to a Windows VM and then runs Windows Diskpart to create a partition, formatting it and assign a lab to it.

CoolRun is also built in such a way that it can be easily adapted to other script languages as well as OSs.   


Varibales

The input variable for CoolRun is a property and is defined as:

Property Key Name

Type

Required

vm

VC:VirtualMachine

yes

script

Resource Element

yes

wrapper

String
[dos | bash | php | perl | python | powershell | diskpart | cmdPowershell | powershell64 | regImport]

yes

vmUsername

String 

No

vmPassword

Secure String

No

timeout

number (default: 0)

No

waitTime

number (default: 5 sec)

No

delGuestFile

Boolean (default: false)

No

delLocalFile
Boolean (deafult: true)No

environment

array of string

No

workingDirectory

string

No

OSName
stringNo
debugFlagBoolean (default: true)NO
interactiveBoolean (default: false)
No
showScriptBoolean (default:true)No
showPasswordBoolean (default: false)No
failOnErrorBoolean (default: false)No
fireAndForgetBoolean (default: false)
No

scriptVariables

Property Key Name

Type

Required

script Tag

String

yes

No


All variables that are not required can be used optionally to overwrite the existing values defined in the configuration element.

Optional function

Usage

vmUsername

Overwrites the configured Linux or Windows username

vmPassword

Overwrites the configured Linux or Windows password

timeout

maximal time in seconds CoolRun is waiting until it kills the script process. If set to 0 timeout is disabled. Default: 0.

waitTime

time in seconds to wait before each check if the script has finished. Default: 5

delGuestFile

should the script file in the guest VM be deleted after it has been executed?

delLocalFile
Should the scipt filr in the vRO appliance be deleted after it has been executed? 

environment

Overwrites the configured Linux or Windows environment variables

workingDirectory

in what directory should the script be executed.
Default Windows: c:\ Default Linux: /tmp/

OSName
Name of the OS. If not present vm.guestOS will be used.
debugFlag
Switching on or off debugging via payload
interactive
use interactive session for VM connection. e.g. If executing "net use" commands, only interactive commands are working correctly
showPasswordShows the vmPassword in the log file
showScriptShows the script taht is send to the VM in the log file. As this may contains cleartext passwords this setting disables showing the script.
failOnErrorCoolRun will exit with an error if the ExitCode of the script exectution was not 0 (zero)
fireAndForget
Do not wait for exit code of the script, just execute the script and be done. Will ignore failOnError, Dos not work with interactive

Wrappers

Optional function

Usage

dos

Run a script using Windows CMD

phpRun a script using linux php
bash
Run a script using linus Bash
perl
Run a scipt using Linux perl
python
Run a script using Linux python
powershell
Run a script using Windows PowerShell  32bit
c:\windows\syswow64\WindowsPowerShell\v1.0\powershell.exe
diskpart
Run a script using the Windows diskpart program
cmdPowershell
Run a script using Windows PowerShell started via CMD call
c:\windows\system32\cmd.exe /c powershell.exe -ExecutionPolicy RemoteSigned
powershell64
Run PowerShell 64bit
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
regImport
Import Windows registy files that have been exported with reg export
reg import

HowTo

Installation and configuration

  1. Import the vRO package into your vRO appliance
  2. run the workflow configure CoolRun

The configuration program will ask for all the required information to run a script inside a VM. The configuration is saved in a Configuration file and a DOS or BASH Test can be run.

The example will ask for for a VM your name as well as a working directory. The advanced feature lets you define different credentials.

Basic Usage

 1.       Create a scipt  (see bash/dos example beneath)

echo "Hello {user.name}, have fun with coolRun" > {user.dir}text.txt

    2.       Save the script as a Text file and upload it into vRO as an resource element

3.       Create a new workflow

4.       Add the coolRun SubSystem workflow

5.       Create an attribute of type ResoruceElement and link it to the script you uploaded

6.       Use a Scriptable task with an OUT-attribute of type Properties, called payload.

7.       Define the following workflow input variable:

Name

Type

Usage

vm

VC:VirtualMachine

VM on which to execute

name

string

your name

workingDirectory

string

directory where the output should be stored

8.       In the scriptable task define the payload (see example beneath, all bold names are variables)

var payload= new Properties();
payload.put("vm",vm);
payload.put("wrapper","dos");
payload.put("script",exampleScript);
payload.put("workingDirectory",workingDirectory); 
var scriptVariables= new Properties();
scriptVariables.put("user.name",name);
scriptVariables.put("user.dir",workingDirectory);
payload.put("scriptVariables",scriptVariables);

9.       Pass the Payload to the coolRun Subsystem workflow

10.     Run the workflow  

Modifications and extentions

CoolRun is built so that it can be easily extended to run with other OS types and script types. In order to add a OS or script type, you just need to configure the switch element before either the OS Type or the Script Type.

For OS the follwing output variables are needed:

Name

Type

Usage

workingDirectory

string

where should the program run (e.g. c:\ or /tmp/)

vmUsername

string

final username to be used

vmPassword

string

final password to be used

vmEnvironment

array of strings

(can be empty) final Environment variables to be used

For scipts the folowing output varibales are needed:

Name

Type

Usage

arguments

string

arguments of the program to be executed (e.g. /tmp/script.txt)

guestFilePath

string

where should the program be put on the VM (e.g. /tmp/script.txt)

programPath

string

path of the program to be executes (e.g. /bin/bash)

If you want to overwrite existing settings with user input use the following litte function

function exists(prop,key,alt){
  temp=prop.get(key);
  if (temp==null){
    return alt;
  } else {
    return temp;
  }
}

vmUsername=exists(payload,"vmUsername",WinvmUsername);

Under the covers

CoolRun is based on the VMware vRO library functions of the guestOperationsManager, at some stage known as VIX. What the guestOperationsManager does is using VMware tools in the VMs OS to interact with the ESXi the VM is residing on.

It is actually only a wrapper that makes it easier to execute commands using the Guest Operations, it cleans up the code, it escapes characters such as \, makes sure that directories exist and so on.

The prerequisites are the following
(as far as I have found them…cause I couldn’t find any clean documentation):

  • VMware tools must be installed
  • The user login into a Windows VM must have local Admin rights
  • VRO must be able to access the underlaying ESXi host on port TCP 902 and with Admin rights
  • In Windows it can get tricky with UAC and other such things. I normally just use “.\administrator”. After finishing up, I reset the local Administrator password.

Package content

This Package contains three workflows:

  • CoolRun core workflow
  • WaitForGuestProcess workflow
  • Delete vRO local files
  • a configuration program
  • five example workflows that showcase Bash, Dos, PowerShell, python (linux) and Diskpart (Windows)
  • a configuration to centrally store login information and settings
  • four example scripts

Dowload Links:

The following Software is distributed under the GNU General Public Licence, which allows you to use, copy, modify and distribute (keeping my name as Author). If you modify the programm,please let me know and share your ideas. 

TheSoftware is written for vRealize Ochrestrator and works with Version 5.5 or better

Download vRealize Orchestrator Package