Using the vmware-cmd Utility

VMware ESX Server 2.1
Features | Documentation | Knowledge Base | Discussion Forums

You can use the vmware-cmd utility to perform various operations on a virtual machine, including registering a virtual machine (on the local server), getting the power state of a virtual machine, setting configuration variables, and so on.

Note: The previous vmware-control utility is deprecated. If you are using scripts with the vmwarecontrol utility, update your scripts with the new vmware-cmd utility or they will not work with VMware GSX Server 2.x or ESX Server Click here to change current version number.

By default, the vmware-cmd utility is installed in the /usr/bin directory (Linux operating system) or in C:\Program Files\VMware\VMware VmPerl Scripting API (Windows operating system).

Options

The vmware-cmd utility takes the following options.


Option	Description
-H	Specifies an alternate host other than the local host. If the -H option is used, then the -U and -P options must also be specified.
-O	Specifies an alternative port. The default port number is 902.
-U	Specifies the username.
-P	Specifies the user's password.
-h	Prints a help message, listing the options for this utility.
-q	Turns on the quiet option with minimal output. The specified operation and arguments are not specified in the output.
-v	Turns on the verbose option.

vmware-cmd Operations on a Server

The syntax for this utility on a server is:

vmware-cmd -s <options> <server-operation> <arguments>

The vmware-cmd utility performs the following operations on a VMware server.


Server Operation	Description
vmware-cmd -l	Lists the virtual machines on the local server. Unlike the other server operations, this option does not require the `-s` option.
vmware-cmd -s register <vm-cfg-path>	Registers a virtual machine specified by <vm-cfg-path> on the server.
vmware-cmd -s unregister <vm-cfg-path>	Unregisters a virtual machine specified by <vm-cfg-path> on the server
vmware-cmd -s getresource <vm-cfg-path> <variable_name> Note: These methods apply only to ESX Server.	Gets the value of the ESX Server system resource variable specified by system.<variable_name>.
vmware-cmd -s setresource <variable_name> <value> Note: These methods apply only to ESX Server.	Sets the value of the ESX Server system resource variable specified by system.<variable_name>.

vmware-cmd Operations on a Virtual Machine

The syntax for this utility on a virtual machine is:

vmware-cmd <options> <vm-cfg-path> <vm-operation> <arguments>

The vmware-cmd utility performs the following operations on a virtual machine, where <vmcfgpath> represents the complete path to the virtual machine's configuration file.

Note: The following table includes some ESX Server-specific methods, and are specifically noted.


Virtual Machine Operation	Description
vmware-cmd <vm-cfg-path> getstate	Retrieves the execution state of a virtual machine: on, off, suspended, stuck (requires user input) or unknown.
vmware-cmd <vm-cfg-path> start <powerop_mode>	Powers on a previously powered-off virtual machine or resumes a suspended virtual machine. Hard, soft or trysoft specifies the behavior of the power operation <powerop_mode>. If <powerop_mode> is not specified, the default behavior is soft. For more information, see <powerop_mode> Values.
vmware-cmd <vm-cfg-path> stop <powerop_mode>	Shuts down and powers off a virtual machine. Hard, soft or trysoft specifies the behavior of the power operation <powerop_mode>. If <powerop_mode> is not specified, the default behavior is soft. For more information, see <powerop_mode> Values.
vmware-cmd <vm-cfg-path> reset <powerop_mode>	Shuts down, then reboots a virtual machine. Hard, soft or trysoft specifies the behavior of the power operation <powerop_mode>. If <powerop_mode> is not specified, the default behavior is soft. For more information, see <powerop_mode> Values.
vmware-cmd <vm-cfg-path> suspend <powerop_mode>	Suspends a virtual machine. Hard, soft or trysoft specifies the behavior of the power operation <powerop_mode>. If <powerop_mode> is not specified, the default behavior is soft. For more information, see <powerop_mode> Values.
vmware-cmd <vm-cfg-path> addredo <disk_device_name> Note: This operation applies only to ESX Server.	This operation adds a redo log to a running virtual SCSI disk specified by <disk_device_name>, that is associated with the virtual machine specified by <vm-cfg-path>. Changes made to the virtual disk accumulate in the new redo log. This disk must be a ESX Server virtual disk stored on a VMFS volume. The virtual disk can be in persistent, undoable or append mode. The redo log for a virtual disk in persistent mode uses the file name of the virtual disk with `.REDO` appended to it (for example, if the disk is called, `vm.dsk`, the redo log is called `vm.dsk.REDO`). A virtual disk in undoable or append mode already has a redo log associated with it, so the new redo log you create is called `vm.dsk.REDO.REDO`, whose parent is the existing redo log, `vm.dsk.REDO`. This operation fails if the specified virtual disk does not exist, the specified virtual disk is in nonpersistent mode, an online commit is already in progress, or the virtual disk already has two redo logs associated with it. If you add a redo log using the `vmware-cmd addredo` command, but do not commit your changes with the `vmware-cmd commit` command, then the redo is automatically committed when the virtual machine is powered off.
vmware-cmd <vm-cfg-path> commit <disk_device_name> <level> <freeze> <wait> Note: This operation applies only to ESX Server.	This method commits the changes in a redo log to a running virtual SCSI disk specified by <disk_device_name> that is associated with the virtual machine specified by <vm-cfg-path>. <level> can be `0` or `1`. When <level> is `0`, there can be one or two redo logs associated with the disk. If <level> is `0`, then the top-most redo log (the redo log being modified) is committed to its parent. For example, if there is currently only the disk `vm.dsk` with a single redo log `vm.dsk.REDO`, then the changes in `vm.dsk.REDO` are committed to `vm.dsk`. If a second REDO log `vm.dsk.REDO.REDO` has been added, then the changes in `vm.dsk.REDO.REDO` are committed to `vm.dsk.REDO`. <level> can be `1` only when there are two redo logs associated with the disk, `vm.dsk.REDO` and `vm.dsk.REDO.REDO`. When <level> is `1`, the changes in the next-to-top REDO log, `vm.dsk.REDO`, are committed to `vm.dsk`. In this case, the virtual machine is not frozen while the redo log is being committed. Also, when the log is committed, `vm.dsk.REDO.REDO` is renamed to `vm.dsk.REDO`. <freeze> can be `0` or `1`. If <freeze> is `0`, then the virtual machine is not frozen when changes are committed, though it runs more slowly. If <freeze> is `1`, then the virtual machine is frozen until the commit operation finishes. If <level> is `0`, then the virtual machine must be frozen when changes are committed and <freeze> is ignored. <wait> can be `0` or `1`. If <wait> is `0`, then the method returns as soon as the commit begins. If <wait> is `1`, then the method does not return until the commit completes. The method fails if the specified virtual disk does not exist, the specified virtual disk is in nonpersistent mode, an online commit is already in progress, or the virtual disk currently has no redo logs.
vmware-cmd <vm-cfg-path> setconfig <variable> <value>	Sets a configuration variable for the virtual machine connected to the remote console.
vmware-cmd <vm-cfg-path> getconfig <variable>	Retrieves the value for a configuration variable for the virtual machine connected to the remote console.
vmware-cmd <vm-cfg-path> setguestinfo <variable> <value>	Writes a GuestInfo variable into memory. The variable is discarded when the virtual machine process terminates.
vmware-cmd <vm-cfg-path> getguestinfo <variable>	Retrieves the value for a GuestInfo variable.
vmware-cmd <vm-cfg-path> getproductinfo <prodinfo>	Returns information about the product, where <prodinfo> is product, platform, build, majorversion (product's major version number), minorversion (product's minor version number) or revision. If product is specified, the return value is one of the following: ws (VMware Workstation), gsx (VMware GSX Server) esx (VMware ESX Server) or unknown (unknown product type). If platform is specified, the return value is one of the following: windows (Microsoft Windows), linux (Linux operating system) or unknown (unknown platform type).
vmware-cmd <vm-cfg-path> connectdevice <device_name>	Connects the specified virtual device to a virtual machine.
vmware-cmd <vm-cfg-path> disconnectdevice <device_name>	Disconnects the specified virtual device from the virtual machine.
vmware-cmd <vm-cfg-path> getconfigfile	Returns a string containing the configuration file name for the virtual machine. This method fails if the virtual machine is not connected.
vmware-cmd <vm-cfg-path> getheartbeat	Returns the current heartbeat count generated by the VMware Tools service running in the guest operating system. The count is initialized to zero when the virtual machine is powered on. The heartbeat count is typically incremented at least once per second when the VMware Tools service is running under light load conditions. The count stays constant if this service is not running.
vmware-cmd <vm-cfg-path> gettoolslastactive	Returns an integer indicating how much time has passed, in seconds, since the last heartbeat was detected from the VMware Tools service. This value is initialized to zero when the virtual machine powers on. It stays at zero until the first heartbeat is detected, after which the value is always greater than zero until the virtual machine is powercycled again.
vmware-cmd <vm-cfg-path> answer	Prompts the user to answer a question for a virtual machine waiting for user input.
vmware-cmd getresource <vm-cfg-path> <variable_name> Note: This method applies only to ESX Server.	Gets the value of the virtual machine resource variable specified by <variable_name>. For a list of ESX Server virtual machine resource variables, see the VMware Scripting API User's Manual.
vmware-cmd setresource <vm-cfg-path> <variable_name> <value> Note: This method applies only to ESX Server.	Sets the value of the virtual machine resource variable specified by <variable_name>. For a list of ESX Server virtual machine resource variables, see the VMware Scripting API User's Manual.
vmware-cmd <vm-cfg-path> getuptime Note: This method applies only to ESX Server.	Accesses the uptime of the guest operating system on the virtual machine.
vmware-cmd <vm-cfg-path> getid Note: This method applies only to ESX Server.	Returns the unique (world) ID for a running virtual machine.
vmware-cmd <vm-cfg-path> getpid Note: This method applies only to ESX Server.	Returns the process ID of a running virtual machine.
vmware-cmd <vm-cfg-path> getcapabilities Note: This method applies only to ESX Server.	Returns the access permissions for the current user. This number is a bit vector, where 4=read, 2=write, and 1=execute. For a user with all three permissions, a value of 7 is returned when this property is used in a script.
vmware-cmd <vm-cfg-path> getremoteconnections Note: This method applies only to ESX Server.	Returns the number of remotely connected users. This value includes the number of remote consoles, Scripting APIs, and Web-based management interface connections to the virtual machine.

<powerop_mode> Values

The following table describes hard, soft and trysoft power operations.


Powerop_mode Values	Description
soft To succeed, soft power operations require the current version of VMware Tools to be installed and running in the guest operating system.	Start when a virtual machine is suspended — After resuming the virtual machine, the operation attempts to run a script in the guest operating system. The Start operation always succeeds. However, if VMware Tools is not present or is malfunctioning, the running of the script may fail. Start when virtual machine is powered off — After powering on the virtual machine, it attempts to run a script in the guest operating system when the VMware Tools service becomes active. The default script does nothing during this operation as there is no DHCP lease to renew. The Start operation always succeeds. However, if VMware Tools is not present or is malfunctioning, the running of the script may fail. Stop — Attempts to shut down the guest operating system and then powers off the virtual machine. Reset — Attempts to shut down the guest operating system, then reboots the virtual machine. Suspend — Attempts to run a script in the guest operating system before suspending the virtual machine.
hard	Start — Starts or resumes a virtual machine without running any scripts; a standard power on or resume. Stop, reset or suspend — Immediately and unconditionally powers off, resets, or suspends the virtual machine.
trysoft	First attempts to perform the soft power transition operation. If this fails, the hard power operation is performed.

vmware-cmd Utility Examples

This section includes examples of using the vmware-cmd utility on a virtual machine.

Retrieving the State of a Virtual Machine

The following examples illustrate retrieving the execution state of a virtual machine.

Change directories to the directory (folder) containing the vmware-cmd utility or include the full path to the utility when typing the following on a command line. Note that you must use double quotes when specifying a path with spaces; for example,
"C:\Program Files\VMware\VMware VmPerl Scripting API\vmware-cmd".

In a Linux guest operating system:

vmware-cmd /home/vmware/win2000.vmx getstate

where /home/vmware/win2000.vmx is the path to the virtual machine's configuration file.

In a Windows guest operating system:

vmware-cmd C:\home\vmware\win2000.vmx getstate

where C:\home\vmware\win2000.vmx is the path to the virtual machine's configuration file.

Performing a Power Operation

The following examples illustrate performing a power operation. The first example illustrates powering on a virtual machine and the second example illustrates performing a hard reset.

In a Linux guest operating system:

vmware-cmd -v /home/vmware/win2000.vmx start

where -v indicates the verbose option, /home/vmware/win2000.vmx is the path to the virtual machine's configuration file and start is the power operation. Since a <powerop_mode> is not specified, the default soft behavior is performed.

Similarly, in a Windows guest operating system:

vmware-cmd -q C:\home\vmware\win2000.vmx reset hard

where -q indicates the quiet option (only the results of the operation are printed), C:\home\vmware\win2000.vmx is the path to the virtual machine's configuration file and reset is the power operation. This example specifies a hard reset so the virtual machine is immediately and unconditionally reset.

Setting a Configuration Variable

The following example illustrates setting a configuration variable in a Linux guest operating system.

Change directories to the directory (folder) containing the vmware-cmd utility or include the full path to the utility when typing the following on a command line.

vmware-cmd foo.vmx setconfig ide1:0.file /tmp/cdimages/foo.iso

where foo.vmx is the virtual machine's configuration file, ide1:0.file is the variable and its value is /tmp/cdimages/foo.iso.

Connecting a Device

The following example illustrates connecting a virtual IDE device in a Windows guest operating system.

vmware-cmd D:\foo.vmx connectdevice ide1:0

where D:\foo.vmx is the virtual machine's configuration file and ide1:0 is the device name.

Prev Contents Last Next