Executing VIX Scripts on Guest VMs

This chapter contains the following sections:

Executing VIX Scripts in Cisco UCS Director

A VIX script executes Linux and Windows commands on a Guest VM. Cisco UCS Director provides the following methods to execute VIX scripts:

  • The Execute VIX Scripts task, which executes the Linux or Windows command on a Guest OS.

  • The userAPIExecuteVIXScript API (JSON based) and the EXECUTE_VIX_SCRIPT API (XML based)


    Note

    However, the Rest APIs have the following limitations:

    • The response displays only the status code. The response does not display the output of the valid command.

    • To view error messages, you must use the userAPIExecuteVIXScriptWithOutput command.

Support for Guest Operations APIs

The VIX API is deprecated in VMware vSphere versions after VMware vSphere version 6.0. Starting with VMware vSphere version 5.0, VIX APIs are integrated into the VMware vSphere Web Services SDK.

The Execute VIX Script task supports the option to use the Guest Operations API (VMware vSphere SDK). To execute Linux and Windows command using the VMware vSphere SDK, check Invoke Guest Operation API. When the Guest Operations API option is enabled, the Execute VIX Script automatically uses the latest Guest OS API layer instead of calling the VIX APIs.

The VMware vCenter version 6.5 VIX command is supported using the new Guest Operations API. If you are using vCenter version 6.5, you must select this option and update any existing workflows.

The VMware vCenter version 6.0 VIX command supports the use of both VIX API and Guest Operations APIs.


Note

The Invoke Guest Operation API check box addresses the upgrade path from VIX APIs to Guest Operations APIs without modifying the commands or scripts used within the Execute VIX Script task.

By default, the Guest Operations API is not enabled. A warning message appears in the SR logs stating that the VIX API will be deprecated in future releases of VMware vSphere.

You can view log details for a service request.

See the Cisco UCS Director Administration Guide.

Examples with Output Display Option Enabled

The Output Display option is available in the Execute VIX Script task. You can choose to enable the Output Display option whenever you use the Execute VIX Scripts task.

When the Output Display option is enabled for running Windows commands on a VM, a batch file and an output file are created in the /opt/infra/vix_temp_files directory. The batch file contains the command to be executed on the selected VM. After the command is executed on the VM, an output file is created. The output file contains the status code of the batch file execution.

When the Output Display option is enabled for running Linux commands on a VM, just an output file is created. The output file captures the status code of the batch file execution.

The following examples illustrate how you can use the Execute VIX Script Task for running commands on Windows and Linux VMs, with the Output Display option enabled.

Executing a Single-Line Windows Command

In this example, we execute a single-line Windows command using the Execute VIX Script task, with the Output Display option enabled. When the Output Display option is enabled for running Windows commands on a VM, a batch file is created. The batch file contains the command to be executed on the selected VM. An output file captures the status code of the batch execution.

Enter the following information in the Execute VIX Scripts task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. In the Script field, enter the following sample Windows command: 

    C:\\WINDOWS\\system32\\cmd.exe mkdir C:\\test_Dir_9867

  4. Check Output Display.

After executing the task, you see the following information in the log: 

Service Request ID: 536

Mar 21, 2016 10:03:00 UTC Request Submitted

Mar 21, 2016 10:03:03 UTC Executing workflow item number 1

Mar 21, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Mar 21, 2016 10:03:09 UTC Executing workflow item number 2

Mar 21, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Mar 21, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Mar 21, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Mar 21, 2016 10:03:09 UTC VIX API will be deprecated in future release.

Mar 21, 2016 10:03:13 UTC  [VIXActionHandler] - account details VMName : Win_2k12 , Host: 172.31.234.46, OS Type: microsoft windows server 2012 (64-bit), ExitCode :0

Mar 21, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 3 seconds

Mar 21, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Mar 21, 2016 10:03:13 UTC [Local Input: Select VM = 3312)

Mar 21, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Mar 21, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Mar 21, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Mar 21, 2016 10:03:13 UTC [Local Input: Script - C:\\WINDOWS\\system32\\cmd.exe mkdir C:\\test_Dir_9867]

Mar 21, 2016 10:03:13 UTC [Local Input: Undo Script =  ]

Mar 21, 2016 10:03:13 UTC (Local Input: Error Codes = ]

Mar 21, 2016 10:03:13 UTC [Local Input: Output display = true]

Mar 21, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 0]

Mar 21, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Mar 21, 2016 10:03:13 UTC Completed workflow item number 1, with status completed

As seen in the log, the script returns status code 0, which means that the task has been executed successfully.

A batch file is created in the following location: 

/opt/infra/vix_temp_files/vixbatch-03_21_2016_10_03_09_835.bat

The content of the batch file is as follows: 

@echo off 
mkdir C:\\test_Dir_9867
echo status_code: %ERRORLEVEL%

The output file is created in the following location: 

 /opt/infra/vix_temp_files/vixoutput-03_21_2016_10_03_09_835.txt

The content of the output file is as follows: 

status_code: 0

Executing a Multiline Windows Command

In this example, we execute a multiline Windows command using the Execute VIX Script task, with the Output Display option enabled. When the Output Display option is enabled for running Windows commands on a VM, a batch file is created. The batch file contains the command to be executed on the selected VM. An output file captures the status code of the batch file execution.

Enter the following information in the Execute VIX Scripts task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. In the Script field, enter the following sample Windows command: 

    C:\\Windows\\system32\\cmd.exe echo 1sttt file > c:\\One1.txt && echo 2nddd file > 
c:\\Three.txt

    Note

    Use && for multiline commands. Multiline commands do not support &.

  4. Check Output Display.

After executing the task, you see the following information in the SR log: 

Apr 06, 2016 12:06:00 UTC Request Submitted

Apr 06, 2016 12:06:03 UTC Executing workflow item number 1

Apr 06, 2016 12:06:03 UTC Completed workflow item number 0, with status completed

Apr 06, 2016 12:06:09 UTC Executing workflow item number 2

Apr 06, 2016 12:06:00 UTC Trigger context executeWorkflowStep called

Apr 06, 2016 12:06:09 UTC Executing custom action VIX2008 (Execute VIX Script)

Apr 06, 2016 12:06:09 UTC Executing custom action VIX2008 (Execute VIX Script)

Apr 06, 2016 12:06:09 UTC VIX API will be deprecated in future release.

Apr 06, 2016 12:06:13 UTC  [VIXActionHandler] - account details VMName : vm-DEF-SR119 , Host: 172.31.234.85, OS Type: microsoft windows server 2012 (64-bit), ExitCode :0

Apr 06, 2016 12:06:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 3 seconds

Apr 06, 2016 12:06:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 06, 2016 12:06:13 UTC [Local Input: Select VM = 392)

Apr 06, 2016 12:06:13 UTC [Local Input: Credential type = Login]

Apr 06, 2016 12:06:13 UTC [Local Input: Login =  administrator]

Apr 06, 2016 12:06:13 UTC [Local Input: Password = "masked-value")

Apr 06, 2016 12:06:13 UTC [Local Input: Script - C:\\WINDOWS\\system32\\cmd.exe /c fsutil file x.txt | echo.hi > C:\\util.txt]

Apr 06, 2016 12:06:13 UTC [Local Input: Undo Script =  ]

Apr 06, 2016 12:06:13 UTC (Local Input: Error Codes = ]

Apr 06, 2016 12:06:13 UTC [Local Input: Output display = true]

Apr 06, 2016 12:06:13 UTC (Output: EXIT_STATUS_CODE = 0]

Apr 06, 2016 12:06:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Apr 06, 2016 12:06:13 UTC Completed workflow item number 1, with status completed 

Apr 06, 2016 12:06:13 UTC Completed workflow item number 3 

Apr 06, 2016 12:06:13 UTC Completed workflow item number 2, with status completed

As seen in the log, the script returns status code 0, which means that the task has been executed successfully.

A batch file is created in the following location: 

/opt/infra/vix_temp_files/vixbatch-04_07_2016_02_01_34_231.bat

The content of the batch file is as follows: 

@echo off 
echo 1sttt file > c:\\One1.txt && echo 2nddd file > c:\\Three.txt
echo status_code: %ERRORLEVEL%

The output file is created in the following location: 

 /opt/infra/vix_temp_files/vixoutput-04_07_2016_02_01_34_231.txt

The content of the output file is as follows: 

status_code: 0

Executing a Windows Command with Error Codes Specified

In this example, we execute a single-line Windows command using the Execute VIX Script task, with the Output Display option enabled and an error code specified. When the Output Display option is enabled for running Windows commands on a VM, a batch file is created. The batch file contains the command to be executed on the selected VM. An output file captures the status code of the batch file execution.

Enter the following information in the Execute VIX Scripts task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. In the Script field, enter the following invalid Windows command: 

    C:\\WINDOWS\\system32\\cmd.exe mkkdir C:\\test_error_code

  4. In the Error Codes field, enter 9009.

  5. Check Output Display.

As the user has passed an invalid command and specified the error code (9009), the task checks against the user-provided error code and fails the task. 

Service Request ID: 486

Apr 21, 2016 09:05:00 UTC Request Submitted

Apr 21, 2016 09:05:03 UTC Executing workflow item number 1

Apr 21, 2016 09:05:03 UTC Completed workflow item number 0, with status completed

Apr 21, 2016 09:05:09 UTC Executing workflow item number 2

Apr 21, 2016 09:05:00 UTC Trigger context executeWorkflowStep called

Apr 21, 2016 09:05:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 21, 2016 09:05:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 21, 2016 09:05:09 UTC VIX API will be deprecated in future release.

Apr 21, 2016 09:05:13 UTC  [VIXActionHandler] - account details VMName : Win_2k12 , Host: 172.31.234.46, OS Type: microsoft windows server 2012 (64-bit), ExitCode :0

Apr 21, 2016 09:05:13 UTC Action Execute VIX Script: Task failed with Error Code: 9009 and status message: "mkkdir"
not recognized as an internal or external command, operable program or batch file

Apr 21, 2016 09:05:13 UTC Task: (vix_script (Execute VIX Script) failed with error - Task failed with Error Code: 9009 and status message: 'mkkdir'
not recognized as an internal or external command, operable program or batch file. , selectedContext=<None>

Apr 21, 2016 09:05:13 UTC Task#1 (vix_script (Execute VIX Script)) failed after 6 seconds

Apr 21, 2016 09:05:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 21, 2016 09:05:13 UTC [Local Input: Select VM = 3312)

Apr 21, 2016 09:05:13 UTC [Local Input: Credential type = Login]

Apr 21, 2016 09:05:13 UTC [Local Input: Login =  administrator]

Apr 21, 2016 09:05:13 UTC [Local Input: Password = "masked-value")

Apr 21, 2016 09:05:13 UTC [Local Input: Script - C:\\WINDOWS\\system32\\cmd.exe mkdir C:\\test_error_code]

Apr 21, 2016 09:05:13 UTC [Local Input: Undo Script =  ]

Apr 21, 2016 09:05:13 UTC (Local Input: Error Codes = 9009]

Apr 21, 2016 09:05:13 UTC [Local Input: Output display = true]

Apr 21, 2016 09:05:13 UTC (Output: EXIT_STATUS_CODE = 9009]

Apr 21, 2016 09:05:13 UTC (Output: ERROR_STATUS_MESSAGE = 'mkkdir' not recognized as an internal or external command, operable program or batch file.]

Apr 21, 2016 09:05:13 UTC Completed workflow item number 1, with status failed

As seen in the log, the script returns status code 9009, which was the value provided in the Error Code field.

If the command is invalid, but the error code is not provided, the task does not check the guest error code against the user field error code. So the task is shown as successful. The task returns an appropriate guest error code as follows: 

Service Request ID: 523

Apr 21, 2016 10:05:00 UTC Request Submitted

Apr 21, 2016 10:05:03 UTC Executing workflow item number 1

Apr 21, 2016 10:05:03 UTC Completed workflow item number 0, with status completed

Apr 21, 2016 10:05:09 UTC Executing workflow item number 2

Apr 21, 2016 10:05:00 UTC Trigger context executeWorkflowStep called

Apr 21, 2016 10:05:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 21, 2016 10:05:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 21, 2016 09:05:09 UTC VIX API will be deprecated in future release.

Apr 21, 2016 10:05:13 UTC  [VIXActionHandler] - account details VMName : Win_2k12 , Host: 172.31.234.46, OS Type: microsoft windows server 2012 (64-bit), ExitCode :0

Apr 21, 2016 10:05:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully after 3 seconds

Apr 21, 2016 10:05:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 21, 2016 10:05:13 UTC [Local Input: Select VM = 3312)

Apr 21, 2016 10:05:13 UTC [Local Input: Credential type = Login]

Apr 21, 2016 10:05:13 UTC [Local Input: Login =  administrator]

Apr 21, 2016 10:05:13 UTC [Local Input: Password = "masked-value")

Apr 21, 2016 10:05:13 UTC [Local Input: Script - C:\\WINDOWS\\system32\\cmd.exe mkkdir C:\\test_error_code]

Apr 21, 2016 10:05:13 UTC [Local Input: Undo Script =  ]

Apr 21, 2016 10:05:13 UTC (Local Input: Error Codes = ]

Apr 21, 2016 10:05:13 UTC [Local Input: Output display = true]

Apr 21, 2016 10:05:13 UTC (Output: EXIT_STATUS_CODE = 9009]

Apr 21, 2016 10:05:13 UTC (Output: ERROR_STATUS_MESSAGE = 'mkkdir' is not recognized as an internal or external command, operable program or batch file.]

Apr 21, 2016 10:05:13 UTC Completed workflow item number 1, with status completed

Executing a Single-Line Linux Command

In this example, we execute a single-line Linux command using the Execute VIX Script task, with the Output Display option enabled. When the Output Display option is enabled for running Linux commands on a VM, an output file is created. The output file captures the status code of the batch execution.

Enter the following information in the Execute VIX Scripts task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. In the Script field, enter the following sample Linux command: 

    /bin/mkdir /tmp/testdir

  4. Check Output Display.

After executing the task, you see the following information in the SR log: 

Apr 22, 2016 12:06:00 UTC Request Submitted

Apr 22, 2016 12:06:03 UTC Executing workflow item number 1

Apr 22, 2016 12:06:03 UTC Completed workflow item number 0, with status completed

Apr 22, 2016 12:06:09 UTC Executing workflow item number 2

Apr 22, 2016 12:06:00 UTC Trigger context executeWorkflowStep called

Apr 22, 2016 12:06:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 22, 2016 12:06:09 UTC Executing custom action Vix_script (Execute VIX Script)

Apr 22, 2016 12:06:09 UTC VIX API will be deprecated in future release.

Apr 22, 2016 12:06:13 UTC  [VIXActionHandler] - account details VMName : vm-DEF-SR119 , Host: 172.31.234.85, OS Type: red hat enterprise linux 4(32-bit), ExitCode :0

Apr 22, 2016 12:06:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 4 seconds

Apr 22, 2016 12:06:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 22, 2016 12:06:13 UTC [Local Input: Select VM = 9801)

Apr 22, 2016 12:06:13 UTC [Local Input: Credential type = Login]

Apr 22, 2016 12:06:13 UTC [Local Input: Login =  administrator]

Apr 22, 2016 12:06:13 UTC [Local Input: Password = "masked-value")

Apr 22, 2016 12:06:13 UTC [Local Input: Script - /bin/mkdir /tmp/testdir]

Apr 22, 2016 12:06:13 UTC [Local Input: Undo Script =  ]

Apr 22, 2016 12:06:13 UTC (Local Input: Error Codes = ]

Apr 22, 2016 12:06:13 UTC [Local Input: Output display = true]

Apr 22, 2016 12:06:13 UTC (Output: EXIT_STATUS_CODE = 0]

Apr 22, 2016 12:06:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Apr 22, 2016 12:06:13 UTC Completed workflow item number 1, with status completed

As seen in the log, the script returns status code 0, which means that the task has been executed successfully.

Unlike Windows, a separate shell script is not created. Only an output file is created. The output file is created in the following location: 

 /opt/infra/vix_temp_files/vixoutput-04_07_2016_10_03_09_835.txt

The content of the output file is as follows: 

status_code: 0

Examples with Output Display Option Disabled

When the Output Display option in the Execute VIX Scripts task is unchecked, the commands are directly executed on the Windows or Linux VM. A batch file or an output file is not created.

The following examples illustrate how you can use the Execute VIX Script Task for running commands on Windows and Linux VMs, with Output Display option not enabled.

Executing A Single-Line Windows Command

In this example, we execute a single-line Windows command using the Execute VIX Script task, with the Output Display option disabled. When the Output Display option is unchecked, the Windows command is directly executed on the VM. A Batch file or an output file is not created.

Enter the following information in the Execute VIX Scripts task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. In the Script field, enter the following sample Windows command: 

    C:\\WINDOWS\\system32\\cmd.exe /c mkdir C:\\test_Dir_1234

  4. Uncheck Output Display, if it is checked.

After executing the task, you see the following information in the log: 

Service Request ID: 458

Mar 21, 2016 10:03:00 UTC Request Submitted

Mar 21, 2016 10:03:03 UTC Executing workflow item number 1

Mar 21, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Mar 21, 2016 10:03:09 UTC Executing workflow item number 2

Mar 21, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Mar 21, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Mar 21, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Mar 21, 2016 10:03:09 UTC VIX API will be deprecated in future release.

Mar 21, 2016 10:03:13 UTC  [VIXActionHandler] - account details VMName : Win_2k12 , Host: 172.31.234.46, OS Type: microsoft windows server 2012 (64-bit), ExitCode :0

Mar 21, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 3 seconds

Mar 21, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Mar 21, 2016 10:03:13 UTC [Local Input: Select VM = 3312)

Mar 21, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Mar 21, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Mar 21, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Mar 21, 2016 10:03:13 UTC [Local Input: Script - C:\\WINDOWS\\system32\\cmd.exe /c mkdir C:\\test_Dir_1234]

Mar 21, 2016 10:03:13 UTC [Local Input: Undo Script =  ]

Mar 21, 2016 10:03:13 UTC (Local Input: Error Codes = ]

Mar 21, 2016 10:03:13 UTC [Local Input: Output display = true]

Mar 21, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 0]

Mar 21, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Mar 21, 2016 10:03:13 UTC Completed workflow item number 1, with status completed

Mar 21, 2016 10:03:13 UTC Completed workflow item number 3 

Mar 21, 2016 10:03:13 UTC Completed workflow item number 2, with status completed

As seen in the log, the command is executed directly on the VM.

Executing a Multiline Windows Command

In this example, we execute a multiline Windows command using the Execute VIX Script task, with the Output Display option disabled. When the Output Display option is unchecked, the multiline Windows command is directly executed on the VM. A Batch file or an output file is not created.

Enter the following information in the Execute VIX Scripts task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. In the Script field, enter the following sample Windows command: 

    C:\\WINDOWS\\system32\\cmd.exe /c mkdir C:\\testfolder_line1  &&     
C:\\WINDOWS\\system32\\cmd.exe /c mkdir C:\\testfolder_line2

  4. Uncheck Output Display, if it is checked.

After executing the task, you see the following information in the log: 

Service Request ID: 448

Mar 21, 2016 10:03:00 UTC Request Submitted

Mar 21, 2016 10:03:03 UTC Executing workflow item number 1

Mar 21, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Mar 21, 2016 10:03:09 UTC Executing workflow item number 2

Mar 21, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Mar 21, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Mar 21, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Mar 21, 2016 10:03:09 UTC VIX API will be deprecated in future release.

Mar 21, 2016 10:03:13 UTC  [VIXActionHandler] - account details VMName : Win_2k12 , Host: 172.31.234.46, OS Type: microsoft windows server 2012 (64-bit), ExitCode :0

Mar 21, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 3 seconds

Mar 21, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Mar 21, 2016 10:03:13 UTC [Local Input: Select VM = 3312)

Mar 21, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Mar 21, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Mar 21, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Mar 21, 2016 10:03:13 UTC [Local Input: Script - C:\\WINDOWS\\system32\\cmd.exe /c mkdir C:\\testfolder_line1  && 
C:\\WINDOWS\\system32\\cmd.exe /c mkdir C:\\testfolder_line2
]

Mar 21, 2016 10:03:13 UTC [Local Input: Undo Script =  ]

Mar 21, 2016 10:03:13 UTC (Local Input: Error Codes = ]

Mar 21, 2016 10:03:13 UTC [Local Input: Output display = true]

Mar 21, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 0]

Mar 21, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Mar 21, 2016 10:03:13 UTC Completed workflow item number 1, with status completed

Mar 21, 2016 10:03:13 UTC Completed workflow item number 3 

Mar 21, 2016 10:03:13 UTC Completed workflow item number 2, with status completed

As seen in the log, the command is executed directly on the VM.

Executing a Single-Line Linux Command

In this example, we execute a single-line Linux command using the Execute VIX Script task, with the Output Display option disabled. When the Output Display option is disabled, the Linux command is directly executed on the VM. No output file is created.

Enter the following information in the Execute VIX Scripts task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. In the Script field, enter the following sample Linux command: 

    /bin/mkdir /tmp/testdir1

  4. Uncheck Output Display, if it is checked.

After executing the task, you see the following information in the SR log: 

Apr 22, 2016 12:06:00 UTC Request Submitted

Apr 22, 2016 12:06:03 UTC Executing workflow item number 1

Apr 22, 2016 12:06:03 UTC Completed workflow item number 0, with status completed

Apr 22, 2016 12:06:09 UTC Executing workflow item number 2

Apr 22, 2016 12:06:00 UTC Trigger context executeWorkflowStep called

Apr 22, 2016 12:06:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 22, 2016 12:06:09 UTC Executing custom action Vix_script (Execute VIX Script)

Apr 22, 2016 12:06:09 UTC VIX API will be deprecated in future release.

Apr 22, 2016 12:06:13 UTC  [VIXActionHandler] - account details VMName : vm-DEF-SR119 , Host: 172.31.234.85, OS Type: red hat enterprise linux 4(32-bit), ExitCode :0

Apr 22, 2016 12:06:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 4 seconds

Apr 22, 2016 12:06:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 22, 2016 12:06:13 UTC [Local Input: Select VM = 9801)

Apr 22, 2016 12:06:13 UTC [Local Input: Credential type = Login]

Apr 22, 2016 12:06:13 UTC [Local Input: Login =  administrator]

Apr 22, 2016 12:06:13 UTC [Local Input: Password = "masked-value")

Apr 22, 2016 12:06:13 UTC [Local Input: Script - /bin/mkdir /tmp/testdir1]

Apr 22, 2016 12:06:13 UTC [Local Input: Undo Script =  ]

Apr 22, 2016 12:06:13 UTC (Local Input: Error Codes = ]

Apr 22, 2016 12:06:13 UTC [Local Input: Output display = true]

Apr 22, 2016 12:06:13 UTC (Output: EXIT_STATUS_CODE = 0]

Apr 22, 2016 12:06:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Apr 22, 2016 12:06:13 UTC Completed workflow item number 1, with status completed

As seen in the log, the Linux command is executed directly on the VM.

Examples with Guest Operations API Option Enabled

When the Invoke Guest Operations API option in the Execute VIX Scripts task is checked, the task uses the latest Guest OS access API layer instead of the VIX API. A batch file or an output file is not created.

The following examples illustrate how you can use the Execute VIX Script Task for running commands on Windows and Linux VMs, with the Guest Operations API option enabled.

Executing A Single-Line Windows Command

In this example, we execute a multiline Windows command using the Execute VIX Script task, with the Guest Operations API option enabled.

Enter the following information in the Execute VIX Scripts task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. In the Script field, enter the following sample Windows command: 

    C:\\WINDOWS\\system32\\cmd.exe /c mkdir C:\\test_Dir_1234

  4. Check Invoke Guest Operations API.

After executing the task, you see the following information in the log: 

Service Request ID: 458

Mar 21, 2016 10:03:00 UTC Request Submitted

Mar 21, 2016 10:03:03 UTC Executing workflow item number 1

Mar 21, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Mar 21, 2016 10:03:09 UTC Executing workflow item number 2

Mar 21, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Mar 21, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Mar 21, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Mar 21, 2016 10:03:09 UTC Invoking Guest Operations API

Mar 21, 2016 10:03:13 UTC [VIXActionHandler] - Completed executing guest command

Mar 21, 2016 10:03:13 UTC Command invoked with Exit Code :0

Mar 21, 2016 10:03:13 UTC [VIXActionHandler] - account details VMName : Win_2k12 , Host: 172.31.234.46, OS Type: microsoft windows server 2012 (64-bit), ExitCode :0

Mar 21, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 3 seconds

Mar 21, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Mar 21, 2016 10:03:13 UTC [Local Input: Select VM = 3312)

Mar 21, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Mar 21, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Mar 21, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Mar 21, 2016 10:03:13 UTC [Local Input: Script - C:\\WINDOWS\\system32\\cmd.exe /c mkdir C:\\test_Dir_1234]

Mar 21, 2016 10:03:13 UTC [Local Input: Undo Script =  ]

Mar 21, 2016 10:03:13 UTC (Local Input: Error Codes = ]

Mar 21, 2016 10:03:13 UTC [Local Input: Output display = true]

Mar 21, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 0]

Mar 21, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Mar 21, 2016 10:03:13 UTC Completed workflow item number 1, with status completed

Mar 21, 2016 10:03:13 UTC Completed workflow item number 3 

Mar 21, 2016 10:03:13 UTC Completed workflow item number 2, with status completed

As seen in the log, the command is executed using the Guest Operations API.

Executing a Multiline Windows Command

In this example, we execute a multiline Windows command using the Execute VIX Script task, with the Guest Operations API option enabled.

Enter the following information in the Execute VIX Scripts task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. In the Script field, enter the following sample Windows command: 

    C:\\WINDOWS\\system32\\cmd.exe /c mkdir C:\\testfolder_line1  &&     
C:\\WINDOWS\\system32\\cmd.exe /c mkdir C:\\testfolder_line2

  4. Check Invoke Guest Operations API.

After executing the task, you see the following information in the log: 

Service Request ID: 448

Mar 21, 2016 10:03:00 UTC Request Submitted

Mar 21, 2016 10:03:03 UTC Executing workflow item number 1

Mar 21, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Mar 21, 2016 10:03:09 UTC Executing workflow item number 2

Mar 21, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Mar 21, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Mar 21, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Mar 21, 2016 10:03:09 UTC Invoking Guest Operations API

Mar 21, 2016 10:03:13 UTC [VIXActionHandler] - Completed executing guest command

Mar 21, 2016 10:03:13 UTC Command invoked with Exit Code :0

Mar 21, 2016 10:03:13 UTC  [VIXActionHandler] - account details VMName : Win_2k12 , Host: 172.31.234.46, OS Type: microsoft windows server 2012 (64-bit), ExitCode :0

Mar 21, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 3 seconds

Mar 21, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Mar 21, 2016 10:03:13 UTC [Local Input: Select VM = 3312)

Mar 21, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Mar 21, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Mar 21, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Mar 21, 2016 10:03:13 UTC [Local Input: Script - C:\\WINDOWS\\system32\\cmd.exe /c mkdir C:\\testfolder_line1  && 
C:\\WINDOWS\\system32\\cmd.exe /c mkdir C:\\testfolder_line2
]

Mar 21, 2016 10:03:13 UTC [Local Input: Undo Script =  ]

Mar 21, 2016 10:03:13 UTC (Local Input: Error Codes = ]

Mar 21, 2016 10:03:13 UTC [Local Input: Output display = true]

Mar 21, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 0]

Mar 21, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Mar 21, 2016 10:03:13 UTC Completed workflow item number 1, with status completed

Mar 21, 2016 10:03:13 UTC Completed workflow item number 3 

Mar 21, 2016 10:03:13 UTC Completed workflow item number 2, with status completed

As seen in the log, the command is executed using the Guest Operations API.

Executing a Single-Line Linux Command

In this example, we execute a multiline Windows command using the Execute VIX Script task, with the Guest Operations API option enabled.

Enter the following information in the Execute VIX Scripts task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. In the Script field, enter the following sample Linux command: 

    /bin/mkdir /tmp/testdir1

  4. Check Invoke Guest Operations API.

After executing the task, you see the following information in the SR log: 

Apr 22, 2016 12:06:00 UTC Request Submitted

Apr 22, 2016 12:06:03 UTC Executing workflow item number 1

Apr 22, 2016 12:06:03 UTC Completed workflow item number 0, with status completed

Apr 22, 2016 12:06:09 UTC Executing workflow item number 2

Apr 22, 2016 12:06:00 UTC Trigger context executeWorkflowStep called

Apr 22, 2016 12:06:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 22, 2016 12:06:09 UTC Executing custom action Vix_script (Execute VIX Script)

Apr 22, 2016 12:06:09 UTC Invoking Guest Operations API

Apr 22, 2016 12:06:13 UTC [VIXActionHandler] - Completed executing guest command

Apr 22, 2016 12:06:13 UTC Command invoked with Exit Code :0

Apr 22, 2016 12:06:13 UTC  [VIXActionHandler] - account details VMName : vm-DEF-SR119 , Host: 172.31.234.85, OS Type: red hat enterprise linux 4(32-bit), ExitCode :0

Apr 22, 2016 12:06:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 4 seconds

Apr 22, 2016 12:06:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 22, 2016 12:06:13 UTC [Local Input: Select VM = 9801)

Apr 22, 2016 12:06:13 UTC [Local Input: Credential type = Login]

Apr 22, 2016 12:06:13 UTC [Local Input: Login =  administrator]

Apr 22, 2016 12:06:13 UTC [Local Input: Password = "masked-value")

Apr 22, 2016 12:06:13 UTC [Local Input: Script - /bin/mkdir /tmp/testdir1]

Apr 22, 2016 12:06:13 UTC [Local Input: Undo Script =  ]

Apr 22, 2016 12:06:13 UTC (Local Input: Error Codes = ]

Apr 22, 2016 12:06:13 UTC [Local Input: Output display = true]

Apr 22, 2016 12:06:13 UTC (Output: EXIT_STATUS_CODE = 0]

Apr 22, 2016 12:06:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Apr 22, 2016 12:06:13 UTC Completed workflow item number 1, with status completed

As seen in the log, the command is executed using the Guest Operations API.

Executing VIX Scripts Using Rest APIs

The following examples illustrate how you can execute Linux or Windows commands on a VM using the following REST APIs:

  • userAPIExecuteVIXScript

  • EXECUTE_VIX_SCRIPT

  • userAPIExecuteVIXScriptWithOutput

Executing a Windows Command Using the userAPIExecuteVIXScript API

In this example, we execute a Windows command using the userAPIExecuteVIXScript API task. The limitation of this API is that the response shows only the status code, and not the output message.

Enter the following information in the userAPIExecuteVIXScript API task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. Click Generate URL and enter the following parameters: 

    /app/api/rest?formatType=json&opName=genericvm:userAPIExecuteVIXScript&opData=
{param0:642,param1:"administrator",param2:"cloupia345",param3:"C:\\WINDOWS\\system32\\cmd.exe mkdir C:\\test_Dir"}

    Note

    • Here param0 is the VM ID, param1 and param2 provide the administrator credentials for the VM, and param3 is the Windows command.

    • Use four backslashes in this API command if the command contains '\'. Verify the script in the service request (SR) logs.

  4. Click Execute REST API.

If the command is valid, you see the following response: 

{ "serviceResult":126, "serviceError":null, "serviceName":"InfraMgr", "opName":"genericvm:userAPIExecuteVIXScript" }

If the command has been executed successfully, you see the following information in the SR log: 

Service Request ID: 445

Apr 19, 2016 10:03:00 UTC Request Submitted

Apr 19, 2016 10:03:03 UTC Executing workflow item number 1

Apr 19, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Apr 19, 2016 10:03:09 UTC Executing workflow item number 2

Apr 19, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC VIX API will be deprecated in future release.

Apr 19, 2016 10:03:13 UTC  [VIXActionHandler] - account details VMName : Win_2k12 , Host: 172.31.234.46, OS Type: microsoft windows server 2012 (64-bit), ExitCode :0

Apr 19, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 6 seconds

Apr 19, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 19, 2016 10:03:13 UTC [Local Input: Select VM = 642)

Apr 19, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Apr 19, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Apr 19, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Apr 19, 2016 10:03:13 UTC [Local Input: Script - C:\\WINDOWS\\system32\\cmd.exe mkdir C:\\test_Dir]

Apr 19, 2016 10:03:13 UTC [Local Input: Undo Script =  ]

Apr 19, 2016 10:03:13 UTC (Local Input: Error Codes = ]

Apr 19, 2016 10:03:13 UTC [Local Input: Output display = true]

Apr 19, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 0]

Apr 19, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Apr 19, 2016 10:03:13 UTC Completed workflow item number 1, with status completed

As seen in the log, the script returns status code 0, which means that the task has been executed successfully.

If the command is invalid (for example you provide an incorrect command: C:\\WINDOWS\\system32\\cmd.exe testxml), the status code returns an appropriate error code in the SR log: 

Service Request ID: 445

Apr 19, 2016 10:03:00 UTC Request Submitted

Apr 19, 2016 10:03:03 UTC Executing workflow item number 1

Apr 19, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Apr 19, 2016 10:03:09 UTC Executing workflow item number 2

Apr 19, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC VIX API will be deprecated in future release.

Apr 19, 2016 10:03:13 UTC  [VIXActionHandler] - account details VMName : Win_2k12 , Host: 172.31.234.46, OS Type: microsoft windows server 2012 (64-bit), ExitCode :0

Apr 19, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully after 6 seconds

Apr 19, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 19, 2016 10:03:13 UTC [Local Input: Select VM = 642)

Apr 19, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Apr 19, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Apr 19, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Apr 19, 2016 10:03:13 UTC [Local Input: Script - C:\\WINDOWS\\system32\\cmd.exe testxml]

Apr 19, 2016 10:03:13 UTC [Local Input: Undo Script =  ]

Apr 19, 2016 10:03:13 UTC (Local Input: Error Codes = ]

Apr 19, 2016 10:03:13 UTC [Local Input: Output display = true]

Apr 19, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 9009]

Apr 19, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = 'testxml' is not recognized as an internal or external command, operable program or batch file.]

Apr 19, 2016 10:03:13 UTC Completed workflow item number 1, with status completed

In this example, the status code 1 means an unknown error.

Executing a Linux Command Using the userAPIExecuteVIXScript API

In this example, we execute a Linux command using the userAPIExecuteVIXScript API task. The limitation of this API is that the response shows only the status code, and not the output message.

Enter the following information in the userAPIExecuteVIXScript API task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. Click Generate URL and enter the following parameters: 

    /app/api/rest?formatType=json&opName=genericvm:userAPIExecuteVIXScript&opData=
{param0:279,param1:"root",param2:"cloupia345",param3:"/bin/mkdir /temp/test1"}

    Note

    Here param0 is the VM ID, param1 and param2 provide the root credentials for the VM, and param3 is the Linux command.

  4. Click Execute REST API.

If the command is valid, you see the following response: 

{ "serviceResult":81, "serviceError":null, "serviceName":"InfraMgr", "opName":"genericvm:userAPIExecuteVIXScript" }

If the command has been executed successfully, you see the following information in the SR log: 

Service Request ID: 495

Apr 19, 2016 10:03:00 UTC Request Submitted

Apr 19, 2016 10:03:03 UTC Executing workflow item number 1

Apr 19, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Apr 19, 2016 10:03:09 UTC Executing workflow item number 2

Apr 19, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC VIX API will be deprecated in future release.

Apr 19, 2016 10:03:13 UTC  [VIXActionHandler] - account details VMName :SDK-VIX, Host :172.29.110.75 , OS Type :red hat enterprise linux 5 (64-bit), ExitCode :0

Apr 19, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 6 seconds

Apr 19, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 19, 2016 10:03:13 UTC [Local Input: Select VM = 279)

Apr 19, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Apr 19, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Apr 19, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Apr 19, 2016 10:03:13 UTC [Local Input: Script - /bin/mkdir /temp/test1]

Apr 19, 2016 10:03:13 UTC [Local Input: Undo Script =  ]

Apr 19, 2016 10:03:13 UTC (Local Input: Error Codes = ]

Apr 19, 2016 10:03:13 UTC [Local Input: Output display = true]

Apr 19, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 0]

Apr 19, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Apr 19, 2016 10:03:13 UTC Completed workflow item number 1, with status completed

As seen in the log, the script returns status code 0, which means that the task has been executed successfully.

If the command is invalid (for example you provide an incorrect command: ///abcd/test/123), the status code returns an appropriate error code in the SR log: 

Service Request ID: 495

Apr 19, 2016 10:03:00 UTC Request Submitted

Apr 19, 2016 10:03:03 UTC Executing workflow item number 1

Apr 19, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Apr 19, 2016 10:03:09 UTC Executing workflow item number 2

Apr 19, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC VIX API will be deprecated in future release.

Apr 19, 2016 10:03:13 UTC  [VIXActionHandler] - account details VMName :SDK-VIX, Host :172.29.110.75 , OS Type :red hat enterprise linux 5 (64-bit), ExitCode :0

Apr 19, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 3 seconds

Apr 19, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 19, 2016 10:03:13 UTC [Local Input: Select VM = 279)

Apr 19, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Apr 19, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Apr 19, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Apr 19, 2016 10:03:13 UTC [Local Input: Script - ///abcd/test/123]

Apr 19, 2016 10:03:13 UTC [Local Input: Undo Script =  ]

Apr 19, 2016 10:03:13 UTC (Local Input: Error Codes = ]

Apr 19, 2016 10:03:13 UTC [Local Input: Output display = true]

Apr 19, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 9009]

Apr 19, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = 'abcd/test/123' is not recognized as an internal or external command, operable program or batch file.]

Apr 19, 2016 10:03:13 UTC Completed workflow item number 1, with status completed

In this example, the status code 1 means an unknown error.

Executing a Windows Command Using the EXECUTE_VIX_SCRIPT API

In this example, we execute a Windows command using the EXECUTE_VIX_SCRIPT API task. The limitation of this API is that the response shows only the status code, and not the output message.

Enter the following information in the EXECUTE_VIX_SCRIPT API task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. In the Script field, enter the following sample Windows command: 

    C:\\WINDOWS\\system32\\cmd.exe mkdir C:\\test_xml_api

  4. Click Execute REST API.

If the command is valid, you see the following response: 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cuicOperationResponse>
				<Log>
									<Messages>1</Messages>
									<Message>
												<TimeStamp>2016-04-26 08:11:26.864</TimeStamp>
												<Severity>INFO</Severity>
												<Text>[VIXActionHandler] - account details VMName :SDK-VIX, Host :172.29.110.75 , OS Type :microsoft windows server 2008 r2 (64-bit), ExitCode:0</Text>
									</Message>
			</Log>
			<operationStatus>0</operationStatus>
			<response>
							<ExecuteVIXScriptResponse>
											<EXIT_STATUS_CODE>0</EXIT_STATUS_CODE>
							</ExecuteVIXScriptResponse>
		</response>
		<responsemap>
					<entry>
							<key>ERROR_STATUS_CODE</key>			
							<value>0</value>
					</entry>
		</responsemap>
</cuicOperationResponse>

As seen in the response, the status code returns 0, which means the command has been executed successfully.

If the command is invalid (for example you provide an incorrect command: C:\\WINDOWS\\system32\\cmd.exe testxml), the status code returns an appropriate error code in the Response field: 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cuicOperationResponse>
				<Log>
									<Messages>1</Messages>
									<Message>
												<TimeStamp>2016-04-26 03:12:29.864</TimeStamp>
												<Severity>INFO</Severity>
												<Text>[VIXActionHandler] - account details VMName :SDK-VIX, Host :172.29.110.75 , OS Type :red hat enterprise linux 5 (64-bit), ExitCode:0</Text>
									</Message>
				</Log>
				<operationStatus>0</operationStatus>
				<response>
							<ExecuteVIXScriptResponse>
											<EXIT_STATUS_CODE>9009</EXIT_STATUS_CODE>
											<ERROR_STATUS_MESSAGE>"testxml" is not recognized as an internal or external command, operable program or batch file.</ERROR_STATUS_MESSAGE>
							</ExecuteVIXScriptResponse>
				</response>
				<responsemap>
						<entry>
								<key>ERROR_STATUS_CODE</key>			
								<value>0</value>
						</entry>
						<entry>
								<key>ERROR_STATUS_MESSAGE</key>
								<value></value>
						</entry>
			</responsemap>
</cuicOperationResponse>

In this example, the status code 1 means an unknown error.

Executing a Linux Command Using the EXECUTE_VIX_SCRIPT API

In this example, we execute a Linux command using the EXECUTE_VIX_SCRIPT API task. The limitation of this API is that the response shows only the status code, and not the output message.

Enter the following information in the EXECUTE_VIX_SCRIPT API task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. In the Script field, enter the following sample Linux command: 

    /bin/date

  4. Click Execute REST API.

If the command is valid, you see the following response: 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cuicOperationResponse>
				<Log>
									<Messages>1</Messages>
									<Message>
												<TimeStamp>2016-04-26 03:11:26.864</TimeStamp>
												<Severity>INFO</Severity>
												<Text>[VIXActionHandler] - account details VMName :SDK-VIX, Host :172.29.110.75 , OS Type :red hat enterprise linux 5 (64-bit), ExitCode:0</Text>
									</Message>
			</Log>
			<operationStatus>0</operationStatus>
			<response>
							<ExecuteVIXScriptResponse>
											<EXIT_STATUS_CODE>0</EXIT_STATUS_CODE>
											<ERROR_STATUS_MESSAGE></ERROR_STATUS_MESSAGE>
							</ExecuteVIXScriptResponse>
		</response>
		<responsemap>
					<entry>
							<key>ERROR_STATUS_CODE</key>			
							<value>0</value>
					</entry>
				<entry>
						<key>ERROR_STATUS_MESSAGE</key>
						<value></value>
				</entry>
		</responsemap>
</cuicOperationResponse>

As seen in the response, the status code returns 0, which means the command has been executed successfully.

If the command is invalid, the status code returns an appropriate error code in the Response field: 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cuicOperationResponse>
			<Log>
									<Messages>1</Messages>
									<Message>
												<TimeStamp>2016-04-26 03:11:26.864</TimeStamp>
												<Severity>INFO</Severity>
												<Text>[VIXActionHandler] - account details VMName :SDK-VIX, Host :172.29.110.75 , OS Type :red hat enterprise linux 5 (64-bit), ExitCode:0</Text>
									</Message>
			</Log>
			<operationStatus>0</operationStatus>
			<response>
							<ExecuteVIXScriptResponse>
											<EXIT_STATUS_CODE>1</EXIT_STATUS_CODE>
											<ERROR_STATUS_MESSAGE></ERROR_STATUS_MESSAGE>
							</ExecuteVIXScriptResponse>
			</response>
			<responsemap>
						<entry>
								<key>ERROR_STATUS_CODE</key>			
								<value>0</value>
								</entry>
					<entry>
								<key>ERROR_STATUS_MESSAGE</key>
								<value></value>
					</entry>
			</responsemap>
</cuicOperationResponse>

In this example, the status code 1 means an unknown error.

Executing a Windows Command Using the userAPIExecuteVIXScriptWithOutput API

In this example, we execute a Windows command using the userAPIExecuteVIXScriptWithOutput API.

When you execute a Windows command using the userAPIExecuteVIXScriptWithOutput API, the API creates

  • An output file (the file extension is .txt) in the file path location, /opt/infra/vix_temp_files.

  • An Input/Output report that lists the input parameters and output variables for the workflow task.

  • A batch file (the file extension is .bat) to verify the batch command (only for Windows VM).

Enter the following information in the userAPIExecuteVIXScriptWithOutput API task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. Click Generate URL and enter the following parameters: 

    /app/api/rest?formatType=json&opName=genericvm:userAPIExecuteVIXScriptWithOutput&opData=
{param0:247,param1:"administrator",param2:"cloupia123",param3:"C:\\WINDOWS\\system32\\cmd.exe echo hi"}

    Note

    • Here param0 is the VM ID, param1 and param2 provide the administrator credentials for the VM, and param3 is the Windows command.

    • For multiline commands, separate each line by \n. For example: 
      /app/api/rest?formatType=json&opName=genericvm:userAPIExecuteVIXScriptWithOutput&opData=
{param0:247,param1:"administrator",param2:"cloupia123",param3:"C:\\WINDOWS\\system32\\cmd.exe 
echo hi\n echo this is secondline"}

  4. Click Execute REST API.

If the command is valid, you see the following response: 

{ "serviceResult":126, "serviceError":null, "serviceName":"InfraMgr", "opName":"genericvm:userAPIExecuteVIXScriptWithOutput" }

If the command has been executed successfully, you see the following information in the SR log: 

Service Request ID: 435

Apr 19, 2016 10:03:00 UTC Request Submitted

Apr 19, 2016 10:03:03 UTC Executing workflow item number 1

Apr 19, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Apr 19, 2016 10:03:09 UTC Executing workflow item number 2

Apr 19, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC VIX API will be deprecated in future release.

Apr 19, 2016 10:03:13 UTC  [VIXActionHandler] - account details VMName : Win_2k12 , Host: 172.31.234.46, OS Type: microsoft windows server 2012 (64-bit), ExitCode :0

Apr 19, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 6 seconds

Apr 19, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 19, 2016 10:03:13 UTC [Local Input: Select VM = 247)

Apr 19, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Apr 19, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Apr 19, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Apr 19, 2016 10:03:13 UTC [Local Input: Script - /app/api/rest?formatType=json&opName=genericvm:userAPIExecuteVIXScriptWithOutput&opData=
{param0:247,param1:"administrator",param2:"cloupia123",param3:"C:\\WINDOWS\\system32\\cmd.exe echo hi"}
]

Apr 19, 2016 10:03:13 UTC [Local Input: Undo Script =  ]

Apr 19, 2016 10:03:13 UTC (Local Input: Error Codes = ]

Apr 19, 2016 10:03:13 UTC [Local Input: Output display = true]

Apr 19, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 0]

Apr 19, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Apr 19, 2016 10:03:13 UTC Completed workflow item number 1, with status completed

As seen in the log, the script returns status code 0, which means that the task has been executed successfully.

The API also creates an Input/Output report that lists the input parameters and output variables (status code and status message) for the workflow task.

If an invalid Windows command is sent through the “userAPIExecuteVIXScriptWithOutput” API, you see the following report in the SR log: 

Service Request ID: 435

Apr 19, 2016 10:03:00 UTC Request Submitted

Apr 19, 2016 10:03:03 UTC Executing workflow item number 1

Apr 19, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Apr 19, 2016 10:03:09 UTC Executing workflow item number 2

Apr 19, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC VIX API will be deprecated in future release.

Apr 19, 2016 10:03:13 UTC  [VIXActionHandler] - account details VMName : Win_2k12 , Host: 172.31.234.46, OS Type: microsoft windows server 2012 (64-bit), ExitCode :0

Apr 19, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 9 seconds

Apr 19, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 19, 2016 10:03:13 UTC [Local Input: Select VM = 247)

Apr 19, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Apr 19, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Apr 19, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Apr 19, 2016 10:03:13 UTC [Local Input: Script - /app/api/rest?formatType=json&opName=genericvm:userAPIExecuteVIXScriptWithOutput&opData=
{param0:247,param1:"administrator",param2:"cloupia123",param3:"C:\\WINDOWS\\system32\\cmd.exe whatsapp"}
]

Apr 19, 2016 10:03:13 UTC [Local Input: Undo Script =  ]

Apr 19, 2016 10:03:13 UTC (Local Input: Error Codes = ]

Apr 19, 2016 10:03:13 UTC [Local Input: Output display = true]

Apr 19, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 9009]

Apr 19, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = 'whatsapp' is not recognized as an internal or external command, operable program or batch file.]

Apr 19, 2016 10:03:13 UTC Completed workflow item number 1, with status completed

As seen in the log, the script returns an appropriate status code and an error message that the command is invalid. The same error status code and error status message also appear in the Input/Output report.

The API creates a batch file in the following location: 

/opt/infra/vix_temp_files/vixbatch-04_07_2016_02_01_34_231.bat

The API creates an output file in the following location: 

 /opt/infra/vix_temp_files/vixoutput-04_07_2016_02_01_34_231.txt

Executing a Linux Command Using the userAPIExecuteVIXScriptWithOutput API

In this example, we execute a Linux command using the userAPIExecuteVIXScriptWithOutput API.

Enter the following information in the userAPIExecuteVIXScriptWithOutput API task available on the UCS Director appliance:

  1. Select the VM where you want to run the VIX script.

  2. Enter the administrator credentials of the VM.

  3. Click Generate URL and enter the following parameters: 

    /app/api/rest?formatType=json&opName=genericvm:userAPIExecuteVIXScriptWithOutput&opData=
{param0:244,param1:"root",param2:"cloupia123",param3:"/bin/date"}

    Note

    Here param0 is the VM ID, param1 and param2 provide the administrator credentials for the VM, and param3 is the Linux command.

  4. Click Execute REST API.

If the command is valid, you see the following response: 

{ "serviceResult":228, "serviceError":null, "serviceName":"InfraMgr", "opName":"genericvm:userAPIExecuteVIXScriptWithOutput" }

If the command has been executed successfully, you see the following information in the SR log: 

Service Request ID: 491

Apr 19, 2016 10:03:00 UTC Request Submitted

Apr 19, 2016 10:03:03 UTC Executing workflow item number 1

Apr 19, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Apr 19, 2016 10:03:09 UTC Executing workflow item number 2

Apr 19, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC VIX API will be deprecated in future release.

Apr 19, 2016 10:03:13 UTC  [VIXActionHandler] - account details VMName :SDK-VIX, Host :172.29.110.75 , OS Type :red hat enterprise linux 5 (64-bit), ExitCode :0

Apr 19, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 6 seconds

Apr 19, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 19, 2016 10:03:13 UTC [Local Input: Select VM = 244)

Apr 19, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Apr 19, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Apr 19, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Apr 19, 2016 10:03:13 UTC [Local Input: Script - /bin/date}
]

Apr 19, 2016 10:03:13 UTC [Local Input: Undo Script =  ]

Apr 19, 2016 10:03:13 UTC (Local Input: Error Codes = ]

Apr 19, 2016 10:03:13 UTC [Local Input: Output display = true]

Apr 19, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 0]

Apr 19, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = ]

Apr 19, 2016 10:03:13 UTC Completed workflow item number 2, with status completed

As seen in the log, the script returns status code 0, which means that the task has been executed successfully.

The API also creates an Input/Output report that lists the input parameters and output variables (status code and status message) for the workflow task.

If an invalid Linux command (for example, "abcd") is sent through the “userAPIExecuteVIXScriptWithOutput” API, you see the following report in the SR log: 

Service Request ID: 491

Apr 19, 2016 10:03:00 UTC Request Submitted

Apr 19, 2016 10:03:03 UTC Executing workflow item number 1

Apr 19, 2016 10:03:03 UTC Completed workflow item number 0, with status completed

Apr 19, 2016 10:03:09 UTC Executing workflow item number 2

Apr 19, 2016 10:03:00 UTC Trigger context executeWorkflowStep called

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC Executing custom action vix_script (Execute VIX Script)

Apr 19, 2016 10:03:09 UTC VIX API will be deprecated in future release.

Apr 19, 2016 10:03:13 UTC  [VIXActionHandler] - account details VMName :SDK-VIX, Host :172.29.110.75 , OS Type :red hat enterprise linux 5 (64-bit), ExitCode :0

Apr 19, 2016 10:03:13 UTC Task#1 (vix_script (Execute VIX Script)) completed successfully in 9 seconds

Apr 19, 2016 10:03:13 UTC Input/Output values for Task#1 (vix_script (Execute VIX Script)):

Apr 19, 2016 10:03:13 UTC [Local Input: Select VM = 244)

Apr 19, 2016 10:03:13 UTC [Local Input: Credential type = Login]

Apr 19, 2016 10:03:13 UTC [Local Input: Login =  administrator]

Apr 19, 2016 10:03:13 UTC [Local Input: Password = "masked-value")

Apr 19, 2016 10:03:13 UTC [Local Input: Script - abcd}

Apr 19, 2016 10:03:13 UTC [Local Input: Undo Script = null]

Apr 19, 2016 10:03:13 UTC (Output: EXIT_STATUS_CODE = 127]

Apr 19, 2016 10:03:13 UTC (Output: ERROR_STATUS_MESSAGE = sh:abcd: command not found]

Apr 19, 2016 10:03:13 UTC Completed workflow item number 2, with status completed

As seen in the log, the script returns an appropriate status code and an error message that the command is invalid. The same error status code and error status message also appear in the input/output report.