REST API - create

vcenter vm guest processes: create

Starts a program in the guest operating system.

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

. Warning: This operation is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Request:

HTTP request

POST https://{server}/rest/vcenter/vm/{vm}/guest/processes?action=create

Path Parameters

Name	Type	Description
Required
vm	string	Virtual machine to perform the operation on.

Request Body Structure:

{
    "credentials" : {
        "password" : "secret string",
        "user_name" : "string",
        "saml_token" : "secret string",
        "type" : "USERNAME_PASSWORD",
        "interactive_session" : true
    },
    "spec" : {
        "path" : "string",
        "environment_variables" : [
            {
                "value" : "string",
                "key" : "string"
            }
        ],
        "start_minimized" : true,
        "arguments" : "string",
        "working_directory" : "string"
    }
}

Request Body Parameters:

Name	Type	Description
bold = required
credentials	credentials	The guest authentication data. See vcenter.vm.guest.credentials. The program will be run as the user associated with this data.
credentials.interactive_session	boolean	If set, the operation will interact with the logged-in desktop session in the guest. This requires that the logged-on user matches the user specified by the vcenter.vm.guest.credentials. This is currently only supported for USERNAME_PASSWORD. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
credentials.type	string	The guest credentials type. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Types of guest credentials. Warning: This enumeration is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Value is one of: USERNAME_PASSWORD: USERNAME_PASSWORD credentials contains the information necessary to authenticate within a guest using a username and password. This method of authentication is stateless. To use USERNAME_PASSWORD, populate userName and password with the appropriate login information. Once populated, you can use USERNAME_PASSWORD in any guest operations function call. . Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. SAML_BEARER_TOKEN: SAML_BEARER_TOKEN contains the information necessary to authenticate within a guest using a SAML token. SAML Bearer token credentials relies on a guest alias that associates a guest account with the subject and certificate encoded in a SAML Bearer token obtained from the VMware SSO Server. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
credentials.user_name	string	For SAML_BEARER_TOKEN, this is the guest user to be associated with the credentials. For USERNAME_PASSWORD this is the guest username. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. It is only relevant when type has value [USERNAME_PASSWORD, SAML_BEARER_TOKEN]. If no user is specified for SAML_BEARER_TOKEN, a guest dependent mapping will decide what guest user account is applied.
credentials.password	secret	password. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. It is only relevant when type has value USERNAME_PASSWORD. This field is optional and it is only relevant when the value of `type` is USERNAME_PASSWORD.
credentials.saml_token	secret	SAML Bearer Token. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. It is only relevant when type has value SAML_BEARER_TOKEN. This field is optional and it is only relevant when the value of `type` is SAML_BEARER_TOKEN.
spec	create_spec	The arguments describing the program to be started.
spec.path	string	The absolute path to the program to start. For Linux guest operating systems, /bin/bash is used to start the program. For Solaris guest operating systems, if /bin/bash exists, its used to start the program, otherwise /bin/sh is used. If /bin/sh is used, then the process ID returned by create will be that of the shell used to start the program, rather than the program itself, due to the differences in how /bin/sh and /bin/bash work. This PID will still be usable for watching the process with list to find its exit code and elapsed time. For Windows, no shell is used. Using a simple batch file instead by prepending `c:\windows\system32\cmd.exe /c` will allow stdio redirection to work if passed in the `arguments` parameter. . Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
spec.arguments	string	The arguments to the program. Characters which must be escaped to the shell should also be escaped in `arguments`. In Linux and Solaris guest operating systems, stdio redirection arguments may be used. For Windows, stdio redirection can be added to the argments if `path` is prefixed with `c:\windows\system32\cmd.exe /c`. . Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. If this value is unset no arguments are passed to the program.
spec.working_directory	string	The absolute path of the working directory for the program to be run. VMware recommends explicitly setting the working directory for the program to be run. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. If this value is unset or is an empty string, the behavior depends on the guest operating system. For Linux guest operating systems, if this value is unset or is an empty string, the working directory will be the home directory of the user associated with the guest authentication. For other guest operating systems, if this value is unset, the behavior is unspecified.
spec.environment_variables	list	A map of environment variables, specified using the guest OS rules (for example `PATH, c:\bin;c:\windows\system32` or `LD_LIBRARY_PATH,/usr/lib:/lib`), to be set for the program being run. Note that these are not additions to the default environment variables; they define the complete set available to the program. If this value is empty, then the environment variables used are guest dependent defaults. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. If this value is unset, the environment variables used are guest dependent defaults.
spec.start_minimized	boolean	Makes any program window start minimized in Windows operating systems. Returns an error if set for non-Windows guests. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. Defaults to false.

Response:

HTTP Status Code: 200

Representation:

{
"value" : 1
}

Response Type:

Name	Type	Description
bold = required
value	long	The process id of the program started.

Errors:

HTTP Status Code	Type	Description
400	invalid_argument	if the vcenter.vm.guest.processes.create_spec.start_minimized field is set and the guest is not a Windows operating system.
400	not_allowed_in_current_state	if the virtual machine `vm` is not running.
404	not_found	if the virtual machine `vm` is not found.
500	resource_busy	if the virtual machine is busy.
503	service_unavailable	if the VMware tools are not running.
500	unable_to_allocate_resource	if the program fails to start. XXX may not work today; hostd doesn't map VIX_E_PROGRAM_NOT_STARTED.
401	unauthenticated	if the `credentials` was not valid.
403	unauthorized	if the `path` field of `spec` cannot be accessed.
400	unsupported	if the operation is not supported by the VMware tools in the guest OS.