3.15.1 Script execution through the vCenter server
Function
This service template functions in the VMware vSphere environment to transmit the specified non-interactive script file from the execution target server to the guest OS on the virtual server through the vCenter server, and then executes the script file on the guest OS. The script file can be deleted if it is no longer needed after execution.
The following servers are required for this service template:
- vCenter server
Server where VMware vCenter Server is installed.
- ESX server
Server where VMware vSphere ESXi is installed.
- vCenter control server (execution target server)
Server where VMware vSphere PowerCLI is installed. Plug-ins are transferred to this server and executed by this product.
- Virtual server
Virtual server that is managed by the vCenter server and VMware vSphere ESX.
An overview of the processing is provided as follows:
(1) Execute the PowerCLI commandlet Copy-VMGuestFile on the execution target server to transmit the specified script from the execution target server to the guest OS on the virtual server.
(2) Execute the PowerCLI commandlet Invoke-VMScript on the execution target server to execute the script transmitted in (1). At this time, execute the scripts on the virtual server by using the following codes:
- Windows batch file (extension bat)
"& 'script-file-path-on-the-guest-OS-(vmware.scriptFileOnGuest-property)' 'script-argument-(vmware.scriptParameter-property)' ; exit $LASTEXITCODE"
- Windows PowerShell script (extension ps1)
"Set-ExecutionPolicy RemoteSigned -Scope Process ; & 'script-file-path-on-the-guest-OS-(vmware.scriptFileOnGuest-property)' 'script-argument-(vmware.scriptParameter-property)' ; exit $LASTEXITCODE"
- Shell script (extension sh)
"/bin/bash 'script-file-path-on-the-guest-OS-(vmware.scriptFileOnGuest-property)' 'script-argument-(vmware.scriptParameter-property)' "
The standard output and standard error output of each script executed on the virtual server are stored in the file on the execution target server that is specified as the output file path (vmware.scriptOutputFilePath property) of the script.
(3) If yes is specified for whether to delete the script (vmware.deleteScriptEnabled property), the script transmitted from the execution target server to the guest OS on the virtual server can be deleted. To delete the script, use the following code applicable to the virtual server environment:
- Windows
"Remove-Item -LiteralPath 'script-file-path-on-the-guest-OS-(vmware.scriptFileOnGuest-property)' -Force "
- UNIX
"/bin/rm -f 'script-file-path-on-the-guest-OS-(vmware.scriptFileOnGuest-property)' "
Consider the following precautions when setting the properties:
(1) You can specify the following script files for the script file path on the guest OS (vmware.scriptFileOnGuest property): Windows batch file (extension bat), Windows PowerShell script (extension ps1), and shell script (extension sh).
(2) When you specify multiple arguments for the script argument (vmware.scriptParameter property), you can separate arguments by using a single-byte comma (,) or single-byte hyphen (-).
For details, see the specifications for each plug-in.
Prerequisites
For the most recent information about the prerequisite products for the system, prerequisite products for the execution-target server, and the supported OSs for the prerequisite products for the execution-target server, see the Release Notes.
Prerequisite products for the system:
JP1/Automatic Operation 12-00 or later
Prerequisite products for the service-template-execution-target server:
- VMware vSphere PowerCLI 6.3 Release1, 6.0 Release3, 6.0 Release1, 5.8 Release1, 5.5 Release2, 5.5 Release1, 5.1 Release2, or 5.0
- VMware PowerCLI 6.5 Release1
- VMware PowerCLI 6.5.1, 6.5.4
- VMware PowerCLI 10.1.0, 10.1.1, 11.3.0, 12.0.0, 12.1.0
Prerequisite products for the service-template-execution-target system:
(1) Prerequisite products for the vCenter server
- VMware vCenter Server 7.0, 6.7, 6.5, 6.0, 5.5, 5.1, or 5.0
(2) VMware vSphere ESXi controlling the virtual server
- VMware vSphere ESXi 7.0, 6.7, 6.5, 6.0, 5.5, 5.1, or 5.0
(3) Prerequisite OSs for the virtual server
- The following OSs are supported in a configuration that is supported by the prerequisite products for the vCenter server, as well as the prerequisite products for VMware vSphere ESXi and the vCenter control server that manage the virtual server:
- Windows Server 2008 R2 Standard/Enterprise/Datacenter
- Windows Server 2012 Standard/Datacenter, Windows Server 2012 R2 Standard/Datacenter
- Windows Server 2016 Standard/Datacenter
- Windows Server 2019 Standard/Datacenter
- Red Hat Enterprise Linux Server 6 (32-bit x86), Red Hat Enterprise Linux Server 6 (64-bit x86_64)
- Red Hat Enterprise Linux Server 7 (64-bit x86_64)
- Red Hat Enterprise Linux Server 8 (64-bit x86_64)
- CentOS 6 (64-bit x86_64)
- CentOS 7 (64-bit x86_64)
- CentOS 8 (64-bit x86_64)
Supported OSs for the prerequisite products for the service-template-execution-target server:
- Windows Server 2008 R2 Standard/Enterprise/Datacenter
- Windows Server 2012 Standard/Datacenter, Windows Server 2012 R2 Standard/Datacenter
- Windows Server 2016 Standard/Datacenter
- Windows Server 2019 Standard/Datacenter
Conditions for using the prerequisite products in the service-template execution system:
(1) VMware vSphere ESXi must be managed by VMware vCenter Server.
(2) Conditions related to the settings on VMware vCenter Server
- Virtual servers must have a unique name.
- The VMware-related name shown below is case-sensitive in VMware. However, it is not case-sensitive in a vSphere PowerCLI instance that is executed from this plug-in.
- Virtual server name
(3) Conditions related to the virtual server
- The virtual server must be running.
- If the virtual server OS is Windows, Windows PowerShell 2.0 or later must be installed.
- VMwareTools must be installed on the virtual server.
Cautions
(1) If a file with the same name exists in the location specified by the path to the script file on the guest OS (vmware.scriptFileOnGuest property) or the path to the output file for the script (vmware.scriptOutputFilePath property), the existing file is overwritten. If any of the folders specified by the file path does not exist, that folder is created and the file is transmitted. Delete the created folder if it is no longer necessary.
(2) If a folder with the same name exists in the location specified by the path to the script file on the guest OS (vmware.scriptFileOnGuest property), the target script file is transmitted and stored in the existing folder without changing its file name. If this occurs, execution of the script fails and the service ends abnormally.
(3) If an error occurs during file transmission, the file that is being transmitted to the virtual server is not deleted automatically. Delete this file if it is not necessary.
(4) Do not execute interactive scripts that require user entry, or scripts that display a GUI and do not end automatically.
(5) Do not execute this service template on the same virtual server simultaneously.
(6) The script specified as the script file on the VMware vCenter control server (vmware.scriptFileOnHost property) is transferred to the guest OS in binary format. Create the script in advance on the guest OS by using executable line break codes and character codes.
Execution privilege
Users who access VMware vCenter Server must have the following permissions:
System administrator role
Version
02.50.00
Tags
Execute Script,VMware vSphere
Property list
The following shows the list of the property groups set in the property:
Property group |
Description |
Initial display |
---|---|---|
Virtual system environment information |
Specify the VMware vCenter Server information. |
Y |
Virtual server information |
Specify the information about the virtual server that executes scripts. |
Y |
Script information |
Specify the information for script execution. |
Y |
Output file storage information |
Specify the output file storage location. |
Y |
The following shows the list of the properties to be displayed in the "Service Definition" window:
- (Legend)
-
R: The property must be specified.
O: The property can be omitted. However, the property might be mandatory depending on what is specified for other properties. See the Description of each property.
Property key |
Property name |
Description |
I/O type |
Shared |
Required |
Property group |
---|---|---|---|---|---|---|
vmware.targetHost |
Host name of VMware vCenter control server |
Specify the host name or IP address of the server (a server with vSphere PowerCLI installed) that will be used to control VMware vCenter. You cannot specify an IPv6 address. |
Input |
Disabled |
R |
Virtual system environment information |
vmware.vCenterServerName |
VMware vCenter server name |
Specify the host name or IP address of the VMware vCenter server. You cannot specify an IPv6 address. |
Input |
Disabled |
R |
Virtual system environment information |
vmware.userName |
User name for VMware vCenter Server connection |
Specify the user name to use when connecting to the VMware vCenter server. |
Input |
Disabled |
R |
Virtual system environment information |
vmware.password |
Password for VMware vCenter Server connection |
Specify the password to use when connecting to the VMware vCenter server. |
Input |
Disabled |
R |
Virtual system environment information |
vmware.portNumber |
Port number for VMware vCenter Server connection |
Specify the port number to use when connecting to the VMware vCenter server (specifically, the port number of the VMware vCenter server's Web service). If you omit this property, the default value of the VMware vCenter server applies. |
Input |
Disabled |
O |
Virtual system environment information |
vmware.protocol |
Protocol for VMware vCenter Server connection |
Specify the protocol to use when connecting to the VMware vCenter server. |
Input |
Disabled |
R |
Virtual system environment information |
The following shows the list of the properties to be displayed on the "Service Definition" window and the "Submit Service" window:
Property key |
Property name |
Description |
I/O type |
Shared |
Required |
Property group |
---|---|---|---|---|---|---|
vmware.vmName |
Virtual server name |
Specify the name of the virtual server. This name is used to represent the virtual server in VMware vCenter server. It is not used as a host name by the OS. |
Input |
Disabled |
R |
Virtual server information |
vmware.guestOSUserName |
User name for logging in to the guest OS |
Specify the user name for logging in to the guest OS. |
Input |
Disabled |
R |
Virtual server information |
vmware.guestOSUserPassword |
Password for logging in to the guest OS |
Specify the password for logging in to the guest OS. |
Input |
Disabled |
R |
Virtual server information |
vmware.scriptFileOnHost |
Script file on the VMware vCenter control server |
Specify the full path of the script file on the VMware vCenter control server that is the transmission source. |
Input |
Disabled |
R |
Script information |
vmware.scriptFileOnGuest |
Script file on the guest OS |
Specify the full path of the script file on the guest OS that is the transmission destination. The script file specified for this property is executed after transmission. |
Input |
Disabled |
R |
Script information |
vmware.scriptParameter |
Script argument |
Specify a script argument. To specify multiple arguments, separate the arguments by using the specified delimiter for script arguments (a single-byte comma or single-byte hyphen). |
Input |
Disabled |
O |
Script information |
vmware.scriptParamDelimiter |
Delimiter for script arguments |
Specify a delimiter for script arguments. You can specify a single-byte comma (,) or a single-byte hyphen (-). If this property is omitted, values specified for the script argument are handled as a single argument. |
Input |
Disabled |
O |
Script information |
vmware.scriptOutputFilePath |
Script output file path |
Specify the full path of the file on the VMware vCenter control server in which the standard output and standard error output of the script are stored. |
Input |
Disabled |
R |
Output file storage information |
vmware.deleteScriptEnabled |
Whether to delete the script |
Specify whether to delete the script after execution. If yes is selected, the script is deleted. If no is selected, the script is not deleted. |
Input |
Disabled |
R |
Script information |
The following shows the list of the properties to be displayed in the "Task Details" window only:
Property key |
Property name |
Description |
I/O type |
Shared |
---|---|---|---|---|
common.scriptReturnCode |
Script return value |
Stores the return value of the script executed on the virtual server. |
Output |
Disabled |
The following shows the restrictions on inputs to the properties displayed in the "Service Definition" window:
Property key |
Characters that can be input |
---|---|
vmware.targetHost |
A maximum of 256 characters can be entered. Characters that can be used include alphanumeric characters, as well as . and -. |
vmware.vCenterServerName |
A maximum of 256 characters can be entered. Characters that can be used include alphanumeric characters, as well as . and -. |
vmware.userName |
A maximum of 512 characters can be entered. Characters that can be used include alphanumeric characters and symbols. It cannot include <, >, |, ;, &, ', ", *, ?, [, ], `, /, :, =, , , +, %. |
vmware.password |
A maximum of 127 characters can be entered. Characters that can be used include alphanumeric characters and symbols. It cannot include <, >, |, ;, &, ', ", *, ?, [, ], `, %. |
vmware.portNumber |
Integer between 1 and 65535 can be entered. |
vmware.protocol |
Select one of the following values: http,https |
The following shows the restrictions on inputs to the property displayed on the "Service Definition" window and the "Submit Service" window:
Property key |
Characters that can be input |
---|---|
vmware.vmName |
A character string of no more than 60 characters can be entered. It cannot include <, >, |, ;, &, ', ", *, ?, [, ], `, , and %. |
vmware.guestOSUserName |
No more than 32 single-byte alphanumeric characters, exclamation marks (!), hash marks (#), dollar signs ($), left parentheses ((), right parentheses ()), hyphens (-), periods (.), carets (^), underscores (_), grave accent marks (`), left curly brackets ({), right curly brackets (}), or swung dashes (~). |
vmware.guestOSUserPassword |
No more than 255 characters (excluding the following symbols: <, >, |, ", ', ;, and &). |
vmware.scriptFileOnHost |
No more than 256 single-byte alphanumeric characters, periods (.), backslashes (\), or colons (:) (excluding trailing backslashes (\)). |
vmware.scriptFileOnGuest |
No more than 256 single-byte alphanumeric characters, periods (.), forward slashes (/), backslashes (\), or colons (:) (excluding trailing backslashes (\) and trailing forward slashes (/)). |
vmware.scriptParameter |
No more than 1,024 single-byte alphanumeric characters, periods (.), forward slashes (/), backslashes (\), colons (:), commas (,), or hyphens (-). |
vmware.scriptParamDelimiter |
Select one of the following values: ,,- |
vmware.scriptOutputFilePath |
No more than 256 single-byte alphanumeric characters, periods (.), backslashes (\), or colons (:) (excluding trailing backslashes (\)). |
vmware.deleteScriptEnabled |
Select one of the following values: yes,no |
Flow specification details
The following table shows the detailed specification of the flow:
Hierarchy |
Display name |
Plug-in |
||
---|---|---|---|---|
Plug-in name |
Description |
Error recovery method |
||
1 |
vsphereSendFileToGuest |
File transmission through the vCenter server |
Transmits the specified file from the execution target server to the guest OS on the virtual server. |
After removing the cause of the error, run the service again. |
2 |
vsphereInvokeScript |
Script execution through the vCenter server |
Executes a non-interactive script file that is transmitted to the guest OS on the virtual server. |
After removing the cause of the error, execute from this step or run the service again. |
3 |
JudgeValuePlugin |
Judge Value Plug-in |
Determines whether to delete a script file transmitted to the guest OS on the virtual server. |
-- |
4 |
vsphereDeleteFileOnGuest |
File deletion through the vCenter server |
Deletes a script file that is transmitted to the guest OS on the virtual server. |
After removing the cause of the error, execute from this step or run the service again. |