NAME

vmware-cmd - perform virtual machine operations


SYNOPSIS

General Options

  vmware-cmd [--help | -q | -v]

Server Operations

 vmware-cmd -s <conn_option> 
   [-l |
    -s register <config_file_path> [<datacenter>] [<resource_pool>] |
    -s unregister <config_file_path> ]

Virtual Machine Operations

 vmware-cmd <conn_option> <config_file_path>
    [answer |
     connectdevice <device_name> |
     createsnapshot <name> <description> quiesce [0|1] memory [0|1] |
     disconnectdevice <device_name> |
     getconfigfile |
     getguestinfo <variable> |
     getproductinfo [product|platform|build|majorversion|minorversion] |
     getstate |
     gettoolslastactive |
     getuptime |
     hassnapshot |
     reset [soft|hard] |
     removesnapshots
     revertsnapshot |
     setguestinfo <variable> <value> |
     start |
     suspend [soft|hard] ]


DESCRIPTION

vmware-cmd provides an interface to perform operations on a virtual machine. You can retrieve information such as the power state, register and unregister the virtual machine, set configuration variables, and manage snapshots.


OPTIONS

CONNECTION OPTIONS

The vmware_cmd vSphere CLI command connection options differ from those of most other vSphere CLI commands.

-H <host>

Specifies an ESX/ESXi host or a vCenter Server system.

-h | --vihost <esx_host>

Specifies a target host if the host specified by -H <host> is a vCenter Server system.

-O <port>

Specifies an alternative port. Default is 443

-U <user_name>

Name of the user who connects to the target. This user must have privileges to perform the operation.

-P <password>

Password of the user specified by <username>. Required if a user is specified.

--config <connection_config_file>

Location of a configuration file that specifies connection information.

--credstore <cred_store>

Name of a credential store file.

--sessionfile <session_file>

Name of a session file that was saved earlier using the vSphere SDK for Perl session/save_session.pl script.

--passthroughauth <passthroughauth>

If you specify this option, the system attempts to connect using Microsoft Windows Security Support Provider Interface (SSPI).

GENERAL OPTIONS

--help

Prints a help message for each command-specific and each connection option. Calling the script with no arguments or with --help has the same effect.

-q

Turns on quiet mode with minimal output.

-v

Turns on verbose mode.


OPERATIONS

The following operations require that you specify the path to the virtual machine configuration file. Choose one of the following formats:

Datastore prefix style: [ds_name] <relative_path>

For example:

  '[myStorage1] testvms/VM1/VM1.vmx' (Linux) 
  "[myStorage1] testvms\VM1\VM1.vmx" (Windows)

UUID-based path: folder/subfolder/file

For example:

  '/vmfs/volumes/mystorage/testvms/VM1/VM1.vmx' (Linux) 
  "/vmfs/volumes/mystorage/testvms/VM1/VM1.vmx" (Windows)

SERVER OPERATIONS

-l

Lists all registered virtual machines.

-s register <config_file_path [<datacenter>] [<resource_pool>]

Registers a virtual machine.

If -H specifies a vCenter Server system, you must specify the datacenter and the resource pool to register the virtual machine in. The default datacenter is ha-datacenter and the default resource pool is Resources.

If -H specifies an ESX/ESXi system, you usually do not specify the resource pool and datacenter. However, if two virtual machines with the same name exist in two resource pools, you must specify the resource pool.

-s unregister

Unregisters a virtual machine.

VIRTUAL MACHINE OPERATIONS

<config_file_path> answer

Prompts the user to answer a question for a virtual machine waiting for user input.

connectdevice <config_file_path> <device_name>

Connects a virtual device to a virtual machine.

<config_file_path> createsnapshot <name> <description> quiesce 0|1 memory 0|1

Creates a snapshot of the specified virtual machine, providing a name and description for the snapshot.

If the <quiesce> flag is 1 and the virtual machine is powered on when the snapshot is taken, VMware Tools is used to quiesce the file system in the virtual machine. Quiescing a file system is a process of bringing the on-disk data of a physical or virtual computer into a state suitable for backups. This process might include such operations as flushing dirty buffers from the operating system's in-memory cache to disk, or other higher-level application-specific tasks.

If the <memory> flag is 1, a dump of the internal state of the virtual machine is included in the snapshot. Memory snapshots take longer to create.

<config_file_path> disconnectdevice

Disconnects the specified virtual device from the virtual machine.

<config_file_path> getconfigfile

Returns a string containing the name of the virtual machine configuration file. This command fails if the virtual machine is not connected.

<config_file_path> getguestinfo

Retrieves the value for a GuestInfo variable. The variable contains the attributes of the guest operating system of a virtual machine. For example, you can run the following command to retrieve the IP address of a virtual machine: vmware-cmd <config_file-path> getguestinfo ip You usually use this command when VMware Technical Support or a VMware Knowledge Base article instruct you to do so.

<config_file_path> getproductinfo

Returns information about the product, where <prodinfo> is product, platform, build, majorversion (product major version number), or minorversion (product minor version number). If product is specified, the return value is one of the following:

  esx -- VMware ESX
  embeddedESX -- VMware ESXi
  unknown (unknown product type)

If platform is specified, the return value is one of the following:

  win32-x86 -- x86-based Windows system
  linux-x86 -- x86-based Linux system
  vmnix-x86 -- x86 ESX/ESXi microkernel
<config_file_path> getstate

Retrieves the execution state of a virtual machine. The state can be on, off, suspended, or unknown.

<config_file_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 the first heartbeat, the value is always greater than zero until the virtual machine is power cycled again. The command can return one of the following:

<config_file_path> getuptime

Returns the uptime (in seconds) of the guest operating system on the virtual machine.

<config_file_path> hassnapshot

Returns 1 if the virtual machine already has a snapshot. Returns 0 otherwise.

<config_file_path> removesnapshots

Removes all snapshots belonging to the virtual machine. If no snapshot exists, does nothing.

<config_file_path> reset [soft|hard]

Shuts down, and then reboots a virtual machine. The powerop_mode can be hard or soft. Default is soft.

<config_file_path> revertsnapshot

Reverts the virtual machine to the current snapshot. If no snapshot exists, does nothing and leaves the virtual machine state unchanged.

<config_file_path> setguestinfo<variable> <value>

Writes a GuestInfo variable into memory. This is an advanced command. You usually use this command when VMware Technical Support or a VMware Knowledge Base article instruct you to do so.

<config_file_path> start

Powers on a previously powered-off virtual machine or resumes a suspended virtual machine.

<config_file_path> stop

Shuts down and powers off a virtual machine. The powerop_mode can be hard or soft. Default is soft.

<config_file_path> suspend [soft|hard]

Suspends a virtual machine. The default powerop_mode is soft.


EXAMPLES

The following examples assume you are specifying connection options, either explicitly or, for example, by specifying the server, user name, and password. Run vmware-cmd --help for a list of common options including connection options.

SERVER OPERATIONS

List all the registered virtual machines:

 vmware-cmd <connection_options> -l

Register a virtual machine:

 vmware-cmd <connection_options>
    -s register /vmfs/volumes/storage1/MyVM/MyVM.vmx

Unregister a virtual machine:

 vmware-cmd <connection_options>
    -s unregister /vmfs/volumes/storage1/MyVM/MyVM.vmx

VIRTUAL MACHINE OPERATIONS

Get the execution state of a virtual machine:

 vmware-cmd <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx getstate

Power on a virtual machine with 'soft' power mode (requires VMware Tools):

 vmware-cmd <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx start soft

Power on a virtual machine with 'hard' power mode:

 vmware-cmd <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx start hard

Set a guest info variable for a virtual machine:

 vmware-cmd <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx setguestinfo VarABC 102

Retrieve the value for a guest info variable for a virtual machine:

 vmware-cmd <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx getguestinfo VarABC

Get the platform information:

 vmware-cmd <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx getproductinfo platform

Get the build information:

 vmware-cmd <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx getproductinfo build

Connect a virtual CD/DVD drive to a virtual machine:

 vmware-cmd <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx connectdevice "CD/DVD Drive 2"

Disconnect a virtual CD/DVD drive from a virtual machine:

 vmware-cmd <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx disconnectdevice "CD/DVD Drive 2"

Retrieve the path to the configuration file for a virtual machine:

 vmware-cmd <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx getconfigfile

Retrieve the uptime of a virtual machine's guest OS:

 vmware-cmd <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx getuptime

Answer a question for a virtual machine requesting input:

 vmware-cmd <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx answer

Retrieve the VMware tools status:

 vmware-cmd -U <connection_options>
    /vmfs/volumes/storage1/MyVM/MyVM.vmx gettoolslastactive

DATACENTER OPERATIONS

You can perform any of the datacenter operations on a vCenter Server system by specifying the vCenterServer system using the -H option and the ESX/ESXi host using the --vihost | -h option. To register a virtual machine on a vCenter Server system, you have to specify the datacenter and resource pool name. For example:

Register a virtual machine.

 vmware-cmd -U <myuser> -P <mypassword> -H VCServerABC --vihost ESXHost
    -s register /vmfs/volumes/storage1/MyVM/MyVM.vmx DatacenterA PoolC

Get the execution state of a virtual machine.

 vmware-cmd -U <myuser> -P <mypassword> -H VCServerABC -h ESXHost
    /vmfs/volumes/storage1/MyVM/MyVM.vmx getstate

Get the product information.

 vmware-cmd -U <myuser> -P <mypassword> -H VCServerABC --vihost ESXHost
    /vmfs/volumes/storage1/MyVM/MyVM.vmx getproductinfo product

Determine if the virtual machine has snapshot.

 vmware-cmd -U <myuser> -P <mypassword> -H VCServerABC -h ESXHost
    /vmfs/volumes/storage1/MyVM/MyVM.vmx hassnapshot

Create a snapshot.

 vmware-cmd -U <myuser> -P <mypassword> -H VCServerABC -h ESXHost
    /vmfs/volumes/storage1/MyVM/MyVM.vmx createsnapshot  <name> <description>
       <quiesce> <memory>

Revert the virtual machine to the last snapshot.

 vmware-cmd -U <myuser> -P <mypassword> -H VCServerABC -h ESXHost
    /vmfs/volumes/storage1/MyVM/MyVM.vmx revertsnapshot

Remove all the snapshots of virtual machine

 vmware-cmd -U <myuser> -P <mypassword> -H VCServerABC -h ESXHost
    /vmfs/volumes/storage1/MyVM/MyVM.vmx removesnapshots