Managed Object - GuestProcessManager

Property of: GuestOperationsManager
See also: GuestAuthentication, GuestProcessInfo, GuestProgramSpec, VirtualMachine
Since: vSphere API 5.0

Managed Object Description

ProcessManager is the managed object that provides APIs to manipulate the guest operating system processes.

Properties

Name	Type	Description
None

Methods

Methods defined in this Managed Object
ListProcessesInGuest, ReadEnvironmentVariableInGuest, StartProgramInGuest, TerminateProcessInGuest

ListProcessesInGuest

List the processes running in the guest operating system, plus those started by StartProgramInGuest that have recently completed.

Required Privileges: None

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the GuestProcessManager used to make the method call.
vm P	ManagedObjectReference to a VirtualMachine	Virtual machine to perform the operation on.
auth	GuestAuthentication	The guest authentication data. See GuestAuthentication.
pids*	xsd:long[]	If set, only return information about the specified processes. Otherwise, information about all processes are returned. If a specified processes does not exist, nothing will be returned for that process.

*Need not be set P Required privilege: VirtualMachine.GuestOperations.Query

Return Value

Type	Description
GuestProcessInfo[]	The list running processes is returned in an array of GuestProcessInfo structures.

Faults

Type	Description
GuestComponentsOutOfDate	Thrown if the guest agent is too old to support the operation.
GuestOperationsFault	Thrown if there is an error processing a guest operation.
GuestOperationsUnavailable	Thrown if the VM agent for guest operations is not running.
GuestPermissionDenied	Thrown if there are insufficient permissions in the guest OS.
InvalidGuestLogin	Thrown if the the guest authentication information was not accepted.
InvalidPowerState	Thrown if the VM is not powered on.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state.
OperationDisabledByGuest	Thrown if the operation is not enabled due to guest agent configuration.
OperationNotSupportedByGuest	Thrown if the operation is not supported by the guest OS.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ListProcessesInGuest" type="vim25:ListProcessesInGuestRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ListProcessesInGuestResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:GuestProcessInfo" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

ReadEnvironmentVariableInGuest

Reads an environment variable from the guest OS

If the authentication uses interactiveSession, then the environment being read will be that of the user logged into the desktop. Otherwise it's the environment of the system user.

Required Privileges: None

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the GuestProcessManager used to make the method call.
vm P	ManagedObjectReference to a VirtualMachine	Virtual machine to perform the operation on.
auth	GuestAuthentication	The guest authentication data. See GuestAuthentication.
names*	xsd:string[]	The names of the variables to be read. If not set, then all the environment variables are returned.

*Need not be set P Required privilege: VirtualMachine.GuestOperations.Query

Return Value

Type	Description
xsd:string[]	A string array containing the value of the variables, or all environment variables if nothing is specified. The format of each string is "name=value". If any specified environment variable isn't set, then nothing is returned for that variable.

Faults

Type	Description
GuestComponentsOutOfDate	Thrown if the guest agent is too old to support the operation.
GuestOperationsFault	Thrown if there is an error processing a guest operation.
GuestOperationsUnavailable	Thrown if the VM agent for guest operations is not running.
GuestPermissionDenied	Thrown if there are insufficient permissions in the guest OS.
InvalidGuestLogin	Thrown if the the guest authentication information was not accepted.
InvalidPowerState	Thrown if the VM is not powered on.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state.
OperationDisabledByGuest	Thrown if the operation is not enabled due to guest agent configuration.
OperationNotSupportedByGuest	Thrown if the operation is not supported by the guest OS.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy. accepted by the guest OS.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ReadEnvironmentVariableInGuest" type="vim25:ReadEnvironmentVariableInGuestRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ReadEnvironmentVariableInGuestResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

StartProgramInGuest

Starts a program in the guest operating system.

A process started this way can have its status queried with ListProcessesInGuest. When the process completes, its exit code and end time will be available for 5 minutes after completion.

Required Privileges: None

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the GuestProcessManager used to make the method call.
vm P	ManagedObjectReference to a VirtualMachine	Virtual machine to perform the operation on.
auth	GuestAuthentication	The guest authentication data. See GuestAuthentication.
spec	GuestProgramSpec	The arguments describing the program to be started.

P Required privilege: VirtualMachine.GuestOperations.Execute

Return Value

Type	Description
xsd:long	The pid of the program started.

Faults

Type	Description
CannotAccessFile	Thrown if the program path cannot be accessed.
FileFault	Thrown if there is a file error in the guest operating system.
FileNotFound	Thrown if the program path does not exist.
GuestComponentsOutOfDate	Thrown if the guest agent is too old to support the operation.
GuestOperationsFault	Thrown if there is an error processing a guest operation.
GuestOperationsUnavailable	Thrown if the VM agent for guest operations is not running.
GuestPermissionDenied	Thrown if the program path cannot be run because the guest authentication will not allow the operation.
InvalidGuestLogin	Thrown if the the guest authentication information was not accepted.
InvalidPowerState	Thrown if the VM is not powered on.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state.
OperationDisabledByGuest	Thrown if the operation is not enabled due to guest agent configuration.
OperationNotSupportedByGuest	Thrown if the operation is not supported by the guest OS.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="StartProgramInGuest" type="vim25:StartProgramInGuestRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="StartProgramInGuestResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:long"/>
               </sequence>
            </complexType>
         </element>

TerminateProcessInGuest

Terminates a process in the guest OS.

Required Privileges: None

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the GuestProcessManager used to make the method call.
vm P	ManagedObjectReference to a VirtualMachine	Virtual machine to perform the operation on.
auth	GuestAuthentication	The guest authentication data. See GuestAuthentication.
pid	xsd:long	Process ID of the process to be terminated

P Required privilege: VirtualMachine.GuestOperations.Execute

Return Value

Type	Description
None

Faults

Type	Description
GuestComponentsOutOfDate	Thrown if the guest agent is too old to support the operation.
GuestOperationsFault	Thrown if there is an error processing a guest operation.
GuestOperationsUnavailable	Thrown if the VM agent for guest operations is not running.
GuestPermissionDenied	Thrown if the process cannot be terminated because the guest authentication will not allow the operation.
GuestProcessNotFound	Thrown if the pid does not refer to a valid process.
InvalidGuestLogin	Thrown if the the guest authentication information was not accepted.
InvalidPowerState	Thrown if the VM is not powered on.
InvalidState	Thrown if the operation cannot be performed because of the virtual machine's current state.
OperationDisabledByGuest	Thrown if the operation is not enabled due to guest agent configuration.
OperationNotSupportedByGuest	Thrown if the operation is not supported by the guest OS.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress	Thrown if the virtual machine is busy.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="TerminateProcessInGuest" type="vim25:TerminateProcessInGuestRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="TerminateProcessInGuestResponse">
            <complexType/>
         </element>