Reference

::vix

Introduction

This package provides an interface to the VIX library for manipulating VMware virtual machines. The package uses the VIX COM interface and therefore only runs on Windows although the virtual machines themselves may run any operating system.

This document describes V1.0 of the vix package and is intended to be a command reference. For a more complete example of usage, see http://www.magicsplat.com/blog/automating-vmware-with-vix.

Prerequisites

The package has the following prerequisites:

  • Tcl 8.6
  • The twapi_com package available from http://twapi.sf.net
  • The VMware VIX library. This is installed as part of the VMware Workstation product and is also available as a separate free download from VMware.

Download and Installation

The package is available from the Files area of the SourceForge project at http://sourceforge.net/p/tcl-vix.

It is distributed as a Tcl module 'vix-VERSION.tm'. Place this file anywhere in a directory included in the list of module directories searched by Tcl. Alternatively, install it with the command

    tclsh vix-VERSION.tm install ?TARGETDIR?

If TARGETDIR is not specified, it will install to a suitable directory in the module path.

Usage

Load the module

    package require vix

All commands are placed within the vix namespace. The package must be initialized before any other calls are made:

    vix::initialize

This allocates internal resources required for further use of the package. Conversely, resources should be released when the package is not required:

    vix::finalize

Note that all objects created using the Host and VM classes must be destroyed before calling finalize.

These calls may be made multiple times in an application as long any other VIX calls are made after an initialize call without an intermediate finalize call.

To manipulate a virtual machine, first connect to the VMware host that contains it.

    vix::Host create host

The above call will connect to a VMware Workstation host on the local system. For connecting to other VMware products and remote systems, see the documentation for the Host class.

Once connected to a host, we can obtain an object corresponding to a virtual machine:

    set vm [host open "c:/Virtual Machines/vm1-win8pro/vm1-win8pro.vmx"]

The specified path may be a file path to the virtual machine's VMS file as in the case of VMware Workstation or a storage path as in the case of the ESX/ESXi products.

You can open multiple virtual machines from a single Host object. All such VM objects must be destroyed before destroying the owning Host object.

The above call returns a VM object which may then be used to manipulate the associated virtual machine using any of the methods of the VM class. For example,

    $vm power_on

will power on the virtual machine. The supported methods include commands to manipulate system state, copy files to and from the virtual machine, start programs and so on.

There are some additional important points to be noted about using these methods. See the documentation of the VM.wait_for_tools and VM.login for details.

When no longer needed, the objects should be destroyed.

   $vm destroy
   host destroy

Note that this does *not* change the state of the VMware host or the virtual machines themselves.

Commands

finalize [::vix]

vix, Top

Finalizes the vix package

finalize

Description

Finalizes the vix package

This command must be called after finishing with the use of the vix package to release internal resources. Before calling this command, all vix objects should have been destroyed.

Once this command returns, the initialize command must be called before the application makes use of the package again.

initialize [::vix]

vix, Top

Initializes the vix package

initialize

Description

Initializes the vix package

This command initializes internal resources used for interfacing to VMware hosts. It must be called before using any other commands from the package.

Classes

Host [::vix]

vix, Top

connectEstablishes a connection to the host system represented by this object.
constructorConstructor for the class
destructorDestructor for the class
disconnectDisconnects the object from the associated VMware host.
openReturns a VM object representing a virtual machine on this VMware host
registerRegisters a virtual machine with a VMware host
registered_vmsReturns a list of virtual machines that are registered on the host
running_vmsReturns a list of virtual machines that are running on the host
trace_VMInternal command to track virtual machines. Do not call directly.
typeReturns the type of the VMware host software
unregisterUnregisters a virtual machine with a VMware host.
versionReturns a string containing the version of the VMware host software
wrappeeReturns the underlying twapi::Automation COM object
Mixins

::vix::_VixHandle

constructor [::vix::Host]

Host, Top

Class representing a host system running VMware software

::vix::Host create args

Parameters
argsAdditional options.
-connect BOOLEAN if true (default), automatically connects to the host. If false, caller must separately call the connect method.
-hostname HOSTNAME specifies the name of the host system. Defaults to the local system. Cannot be specified if HOSTTYPE is workstation or player. Must be specified in other cases.
-hosttype HOSTTYPE specifies the type of VMware host software. HOSTTYPE must be one of workstation for VMware Workstation (default), workstation_server for VMware Workstation in shared mode, server for VMware Server 1.0, player for VMware Player and vi_server for VMware Server 2.0, vCenter and ESX/ESXi.
-password PASSWORD the password associated with the account. Ignored if -hostname is not specified.
-port PORTNUMBER specifies the port number to connect to on the host. Ignored if -hostname is not specified.
-username USER name of the account to use to connect to the host system. Ignored if -hostname is not specified.
Description

Class representing a host system running VMware software

The specified host is not contacted until the connect method is invoked.

destructor [::vix::Host]

Host, Top

OBJECT destroy

connect [::vix::Host]

Host, Top

Establishes a connection to the host system represented by this object.

OBJECT connect

Description

Establishes a connection to the host system represented by this object.

This method must be called before any virtual machines can be opened on the host system. The method may be called multiple times with calls being no-ops if the connection is already established.

disconnect [::vix::Host]

Host, Top

Disconnects the object from the associated VMware host.

OBJECT disconnect force

Parameters
force(optional, default 0) if 0, an error is raised if any associated VM objects exist. If 1, the associated VM objects are forcibly destroyed before disconnecting.
Description

Disconnects the object from the associated VMware host.

The application should normally ensure that all VM objects associated with this host have been closed before calling disconnect.

The connect method may be called to reestablish the connection.

open [::vix::Host]

Host, Top

Returns a VM object representing a virtual machine on this VMware host

OBJECT open vm_path

Parameters
vm_path absolute path to the VMX file for the virtual machine on the VMware host. The path must be in the syntax expected by the VMware host operating system.
Return value

Returns a VM object representing a virtual machine on this VMware host

Description

For VMware server and ESX/ESXi hosts, the virtual machine must have been registered.

register [::vix::Host]

Host, Top

Registers a virtual machine with a VMware host

OBJECT register vm_path

Parameters
vm_path absolute path to the VMX file for the virtual machine on the VMware host. The path must be in the syntax expected by the VMware host operating system.
Description

Registers a virtual machine with a VMware host

For VMware Server and ESX/ESXi hosts, a virtual machine must be registered before it can be accessed with the open call. For other VMware host types, this call is ignored. Registration is a one-time operation and may also be done through the VMware command line or user interface.

registered_vms [::vix::Host]

Host, Top

Returns a list of virtual machines that are registered on the host

OBJECT registered_vms

Return value

Returns a list of virtual machines that are registered on the host

Description

Each element of the returned list contains the path of the registered virtual machine. This command is only relevant for ESX/ESXi and VMware Server hosts.

running_vms [::vix::Host]

Host, Top

Returns a list of virtual machines that are running on the host

OBJECT running_vms

Return value

Returns a list of virtual machines that are running on the host

Description

Each element of the returned list contains the path from which the virtual machine was created.

trace_VM [::vix::Host]

Host, Top

Internal command to track virtual machines. Do not call directly.

OBJECT trace_VM oldname newname op

Parameters
oldname
newname
op
Description

Internal command to track virtual machines. Do not call directly.

type [::vix::Host]

Host, Top

Returns the type of the VMware host software

OBJECT type

Return value

Returns the type of the VMware host software

Description

The returned value is one of the values accepted for the '-hosttype' option to the connect method.

unregister [::vix::Host]

Host, Top

Unregisters a virtual machine with a VMware host.

OBJECT unregister vm_path

Parameters
vm_path absolute path to the VMX file for the virtual machine on the VMware host. The path must be in the syntax expected by the VMware host operating system.
Description

Unregisters a virtual machine with a VMware host.

For VMware Server and ESX/ESXi hosts, a virtual machine must be registered before it can be accessed with the open call. This method removes a registered VM from the host inventory.

version [::vix::Host]

Host, Top

Returns a string containing the version of the VMware host software

OBJECT version

Return value

Returns a string containing the version of the VMware host software

Description

Returns a string containing the version of the VMware host software

wrappee [::vix::Host]

Host, Top

Returns the underlying twapi::Automation COM object

OBJECT wrappee

Return value

Returns the underlying twapi::Automation COM object

Description

The command will raise an error if there is no associated wrapped COM object.

Snapshot [::vix]

vix, Top

childReturns a child snapshot
constructorConstructor for the class
descriptionReturns the description name of the snapshot
destructorDestructor for the class
display_nameReturns the display name of the snapshot
number_of_childrenReturns the number of children of the snapshot
parentReturns the parent snapshot
wrappeeReturns the underlying twapi::Automation COM object
Mixins

::vix::_VixHandle

constructor [::vix::Snapshot]

Snapshot, Top

Represents a snapshot of a virtual machine.

::vix::Snapshot create comobj

Parameters
comobj Wrapped VIX Automation object
Description

Represents a snapshot of a virtual machine.

Objects of this class should not be created directly. They are returned by various methods of objects of this class and the VM class.

The methods of this class allow invoking of various operations on virtual machine snapshots.

destructor [::vix::Snapshot]

Snapshot, Top

OBJECT destroy

child [::vix::Snapshot]

Snapshot, Top

Returns a child snapshot

OBJECT child index

Parameters
index index of the children snapshots
Return value

Returns a Snapshot object representing the child snapshot at the specified index position.

Description

Returns a child snapshot

description [::vix::Snapshot]

Snapshot, Top

Returns the description name of the snapshot

OBJECT description

Return value

Returns the description name of the snapshot

Description

Returns the description name of the snapshot

display_name [::vix::Snapshot]

Snapshot, Top

Returns the display name of the snapshot

OBJECT display_name

Return value

Returns the display name of the snapshot

Description

Returns the display name of the snapshot

number_of_children [::vix::Snapshot]

Snapshot, Top

Returns the number of children of the snapshot

OBJECT number_of_children

Return value

Returns the number of children of the snapshot

Description

Returns the number of children of the snapshot

parent [::vix::Snapshot]

Snapshot, Top

Returns the parent snapshot

OBJECT parent

Return value

Returns the parent snapshot

Description

Returns the parent snapshot

wrappee [::vix::Snapshot]

Snapshot, Top

Returns the underlying twapi::Automation COM object

OBJECT wrappee

Return value

Returns the underlying twapi::Automation COM object

Description

The command will raise an error if there is no associated wrapped COM object.

VM [::vix]

vix, Top

add_shared_folderAdds a shared folder to the virtual machine.
constructorConstructor for the class
copy_from_vmCopies a file or directory from the virtual machine.
copy_to_vmCopies a file or directory to the virtual machine.
create_snapshotCreates a new snapshot of the virtual machine.
current_snapshotReturns a Snapshot object representing the current snapshot of the virtual machine
delete_snapshotDeletes a snapshot of the virtual machine and all associated state
destructorDestructor for the class
dirReturns the contents of a directory in the virtual machine.
disable_shared_foldersDisables the use of shared folders for the virtual machine.
enable_shared_foldersEnables the use of shared folders for the virtual machine.
execExecutes a program in the virtual machine.
fstatReturns information about a file or directory.
get_snapshotReturns a Snapshot object representing the named snapshot of the virtual machine
getconfigReturns the value of an variable in the virtual machine configuration
getenvReturns the value of an environment variable in the virtual machine
getvarReturns the value of a guest variable in the virtual machine
isdirCheck if the specified path is a directory
isfileCheck if the specified path is a regular file.
killTerminates a process in the virtual machine.
loginEstablishes a login context on the associated virtual machine.
logoutLogs out of a login context
memory_sizeReturns the memory size configured for the virtual machine
mkdirCreates a new directory in the virtual machine
nameReturns the name of the virtual machine
ncpusReturns the number of CPU's configured for the virtual machine
osReturns the operating system running in the virtual machine
pathReturns the full path of the VMX file for the virtual machine
pausePauses the execution of the virtual machine.
pidsReturns a list of process ids running in the virtual machine.
power_offPowers off the associated virtual machine.
power_onPowers on the associated virtual machine.
power_stateReturns the power state of the virtual machine
processesRetrieves detailed information about the processes running in the virtual machine.
read_fileReturns a content of a file in the virtual machine
readonly?
rebootReboots the associated virtual machine.
remove_shared_folderRemoves a shared folder from the virtual machine.
renameRenames a file or directory in the virtual machine.
resetResets the associated virtual machine.
revert_to_snapshotReverts the virtual machine to the specified snapshot
rmdirDeletes a directory in the virtual machine
rmfileDeletes a file in the virtual machine
root_snapshotReturns a Snapshot object corresponding to the root snapshot at the specified position
root_snapshot_countReturns the number of root snapshots of the virtual machine.
running?Returns '1' if the virtual machine running, else '0'
scriptRuns a script in the virtual machine using the specified program
setenvSets the value of an environment variable in the virtual machine
setvarSets the value of a guest variable in the virtual machine
shared_folder_pathReturns the shared folder path in the virtual machine
shared_foldersReturns list of shared folders in the virtual machine.
shutdownShuts down the associated virtual machine.
ssl_error
suspendSuspends the associated virtual machine.
team_member?Returns '1' if the virtual machine is a member of a team, else '0'
team_pathReturns the path to the virtual machine team
tempfileCreates a temporary file in the virtual machine.
tools_stateReturns the state of VMware tools in the virtual machine
trace_SnapshotInternal command to track virtual machines. Do not call directly.
unpauseResumes the execution of a paused virtual machine.
upgrade_hardwareUpgrades the hardware of the virtual machine
upgrade_vmware_toolsUpgrades VMware Tools in the virtual machine
wait_for_toolsWaits for VMware Tools to be running in the virtual machine.
wrappeeReturns the underlying twapi::Automation COM object
write_fileReturns content to a file in the virtual machine
Mixins

::vix::_VixHandle

constructor [::vix::VM]

VM, Top

Represents a virtual machine on a VMware host.

::vix::VM create comobj

Parameters
comobj Wrapped VIX Automation object
Description

Represents a virtual machine on a VMware host.

Objects of this class should not be created directly. They are returned by the open method of an Host object.

The methods of this class allow invoking of various operations on the associated virtual machine.

The associated VM may or may not be running.

destructor [::vix::VM]

VM, Top

OBJECT destroy

add_shared_folder [::vix::VM]

VM, Top

Adds a shared folder to the virtual machine.

OBJECT add_shared_folder share_name host_path args

Parameters
share_name the share name in the virtual machine
host_path path of the directory on the host system to be shared
argsAdditional options.
-mode MODE the sharing mode, r or readonly (default) for read-only shared and rw or readwrite for shares that can be read or written
Description

Adds a shared folder to the virtual machine.

NOTE: on Windows there may be a delay before the shared path is usable in the virtual machine.

This method requires VMtools to be running in the virtual machine.

copy_from_vm [::vix::VM]

VM, Top

Copies a file or directory from the virtual machine.

OBJECT copy_from_vm guest_path local_path

Parameters
guest_path file or directory path in the guest virtual machine. This must be an absolute path in a format valid for the guest operating system.
local_path target local file path where the file or directory is to be copied
Description

Copies a file or directory from the virtual machine.

The method copies a file or a directory tree from the virtual machine to the local file system overwriting existing files and merging directories. Errors may result in partial copies.

This method requires a login context to have been established.

copy_to_vm [::vix::VM]

VM, Top

Copies a file or directory to the virtual machine.

OBJECT copy_to_vm local_path guest_path

Parameters
local_path target local file path where the file or directory is to be copied
guest_path file or directory path in the guest virtual machine. This must be an absolute path in a format valid for the guest operating system.
Description

Copies a file or directory to the virtual machine.

The method copies a file or a directory tree from the local file system to the virtual machine, overwriting existing files and merging directories. Errors may result in partial copies.

This method requires a login context to have been established.

create_snapshot [::vix::VM]

VM, Top

Creates a new snapshot of the virtual machine.

OBJECT create_snapshot name args

Parameters
name name to assign to the snapshot. This need not be unique
argsAdditional options.
-description TEXT a text description for the snapshot
-includememory BOOLEAN If false (default), memory is not saved with the snapshot. If true, the current memory content is saved.
Description

Creates a new snapshot of the virtual machine.

current_snapshot [::vix::VM]

VM, Top

Returns a Snapshot object representing the current snapshot of the virtual machine

OBJECT current_snapshot

Return value

Returns a Snapshot object representing the current snapshot of the virtual machine

Description

Returns a Snapshot object representing the current snapshot of the virtual machine

delete_snapshot [::vix::VM]

VM, Top

Deletes a snapshot of the virtual machine and all associated state

OBJECT delete_snapshot snapshot args

Parameters
snapshot the Snapshot object to be removed
argsAdditional options.
-recurse BOOLEAN if specified as true, children of the specified snapshot are also deleted. Default is false.
Description

Deletes a snapshot of the virtual machine and all associated state

Note this deletes the actual snapshot of the virtual machine. The snapshot object has to be destroyed by the caller after the method returns.

dir [::vix::VM]

VM, Top

Returns the contents of a directory in the virtual machine.

OBJECT dir path args

Parameters
path absolute directory path in the virtual machine.
argsAdditional options.
-details BOOLEAN by default, the method returns a list of names. If this option is specified as true, the details of each directory entry is returned.
Return value

Returns the contents of a directory in the virtual machine.

Description

This method requires a login context to have been established.

disable_shared_folders [::vix::VM]

VM, Top

Disables the use of shared folders for the virtual machine.

OBJECT disable_shared_folders

Description

Disables the use of shared folders for the virtual machine.

This method requires VMtools to be running in the virtual machine.

enable_shared_folders [::vix::VM]

VM, Top

Enables the use of shared folders for the virtual machine.

OBJECT enable_shared_folders

Description

Enables the use of shared folders for the virtual machine.

This method requires VMtools to be running in the virtual machine.

exec [::vix::VM]

VM, Top

Executes a program in the virtual machine.

OBJECT exec program args

Parameters
program absolute path of the program to run
argsAdditional options.
-activatewindow BOOLEAN specifies if the program window should be activated. See below for more
-cmdargs CMDLINE command line to pass to the program
-wait BOOLEAN Specifies whether to wait for the program to complete (default 0)
Return value

Returns the process id, exit code and elapsed time in seconds as a triple.

Description

Executes a program in the virtual machine.

The program must not assume a specific working directory and any passed arguments should not be based on that assumption either.

Programs that interact with the user and need to display on the desktop console require that login context have been created with the -interactive option to Host.login. The -activatewindow option is only relevant for such programs. A true value for the option ensures that the created window is visible and not minimized. This option is only effective for Windows virtual machines.

Note that if -wait is not specified as true, only the process id element in the return value is valid.

This method requires a login context to have been established.

fstat [::vix::VM]

VM, Top

Returns information about a file or directory.

OBJECT fstat path

Parameters
path file path in the virtual machine. This must be an absolute path in a format valid for the guest operating system.
Return value

Returns information about a file or directory.

Description

This method requires a login context to have been established.

get_snapshot [::vix::VM]

VM, Top

Returns a Snapshot object representing the named snapshot of the virtual machine

OBJECT get_snapshot name

Parameters
name name of the snapshot. This can include a path through the snapshot tree with each snapshot separated by '/'
Return value

Returns a Snapshot object representing the named snapshot of the virtual machine

Description

VMware does not enforce uniqueness of snapshot names. In case of duplicates, the method raises an exception.

getconfig [::vix::VM]

VM, Top

Returns the value of an variable in the virtual machine configuration

OBJECT getconfig var

Parameters
var name of the environment variable
Return value

Returns the value of an variable in the virtual machine configuration

Description

This method requires the virtual machine to be running.

getenv [::vix::VM]

VM, Top

Returns the value of an environment variable in the virtual machine

OBJECT getenv envvar

Parameters
envvar name of the environment variable
Return value

Returns the value of an environment variable in the virtual machine

Description

This method requires a user login context to have been established and the returned value is based on that user context.

getvar [::vix::VM]

VM, Top

Returns the value of a guest variable in the virtual machine

OBJECT getvar var

Parameters
var name of the guest variable
Return value

Returns the value of a guest variable in the virtual machine

Description

This method requires the virtual machine to be running.

isdir [::vix::VM]

VM, Top

Check if the specified path is a directory

OBJECT isdir path

Parameters
path directory path in the virtual machine. This must be an absolute path in a format valid for the guest operating system.
Return value

Returns 1 if the specified path is a directory and false otherwise.

Description

Check if the specified path is a directory

This method requires a login context to have been established.

isfile [::vix::VM]

VM, Top

Check if the specified path is a regular file.

OBJECT isfile path

Parameters
path file path in the virtual machine. This must be an absolute path in a format valid for the guest operating system.
Return value

Returns 1 if the specified path is a regular file and false otherwise.

Description

Check if the specified path is a regular file.

Note in particular that the method will return 0 even in the case that the path exists but is not a regular file, such as a directory or a device.

This method requires a login context to have been established.

kill [::vix::VM]

VM, Top

Terminates a process in the virtual machine.

OBJECT kill pid

Parameters
pid process id of the process to be terminated
Description

Terminates a process in the virtual machine.

This method requires a login context to have been established.

login [::vix::VM]

VM, Top

Establishes a login context on the associated virtual machine.

OBJECT login username password args

Parameters
username the login account name
password the password for the account
argsAdditional options.
-interactive BOOLEAN Indicates whether the login session requires an interactive context. See more below.
Description

Establishes a login context on the associated virtual machine.

Several VM operations, for example the ones for files, require a login context on the virtual machine. This method establishes such a context. The virtual machine operating system will enforce access permissions based on this context.

The method may be called multiple times to change the login context. To invalidate the context, use the logout method.

By default, the login context does not have an interactive desktop associated with it. Specifying the -interactive option as true will create such a interactive context which may be required for executing programs with a graphical user interface with the run method. However, note that creation of an interactive context requires the same user to be currently logged in to the virtual machine console.

Note that not all guest operating systems are supported by the login method. Moreover, Linux virtual machines must be running X11 for interactive contexts.

This method requires VMWare Tools to be running in the virtual machine.

logout [::vix::VM]

VM, Top

Logs out of a login context

OBJECT logout

Description

Logs out of a login context

The current context created with the login method is closed. Any methods that require a user context on the virtual machine should not be called until a new context is reestablished.

This method requires VMWare Tools to be running in the virtual machine.

memory_size [::vix::VM]

VM, Top

Returns the memory size configured for the virtual machine

OBJECT memory_size

Return value

Returns the memory size configured for the virtual machine

Description

Returns the memory size configured for the virtual machine

mkdir [::vix::VM]

VM, Top

Creates a new directory in the virtual machine

OBJECT mkdir path

Parameters
path directory path in the guest virtual machine. This must be an absolute path in a format valid for the guest operating system.
Description

Creates a new directory in the virtual machine

The directory is created if it does not exist. It is not an error for the directory to already exist.

This method requires a login context to have been established.

name [::vix::VM]

VM, Top

Returns the name of the virtual machine

OBJECT name

Return value

Returns the name of the virtual machine

Description

Returns the name of the virtual machine

ncpus [::vix::VM]

VM, Top

Returns the number of CPU's configured for the virtual machine

OBJECT ncpus

Return value

Returns the number of CPU's configured for the virtual machine

Description

Returns the number of CPU's configured for the virtual machine

os [::vix::VM]

VM, Top

Returns the operating system running in the virtual machine

OBJECT os

Return value

Returns the operating system running in the virtual machine

Description

The returned value is an internal VMware name specific to an operating system, for example winxppro.

path [::vix::VM]

VM, Top

Returns the full path of the VMX file for the virtual machine

OBJECT path

Return value

Returns the full path of the VMX file for the virtual machine

Description

Returns the full path of the VMX file for the virtual machine

pause [::vix::VM]

VM, Top

Pauses the execution of the virtual machine.

OBJECT pause

Description

Pauses the execution of the virtual machine.

When the virtual machine is paused, method that operate on the guest should not be called except those related to machine state such as power_off, reset etc.

Call the unpause method to resume execution of the virtual machine.

WARNING: do NOT call any commands that require virtual machine operation while it is paused.

pids [::vix::VM]

VM, Top

Returns a list of process ids running in the virtual machine.

OBJECT pids

Return value

Returns a list of process ids running in the virtual machine.

Description

This method requires a login context to have been established.

power_off [::vix::VM]

VM, Top

Powers off the associated virtual machine.

OBJECT power_off

Description

Powers off the associated virtual machine.

The virtual machine, which must have been powered on, is turned off with the equivalent of a hardware switch. Unlike the shutdown method, the virtual machine's operating system is not involved and VMware Tools need not be running on it.

power_on [::vix::VM]

VM, Top

Powers on the associated virtual machine.

OBJECT power_on args

Parameters
argsAdditional options.
-hide BOOLEAN If false (default), the user interface is displayed on Workstation and Player VMware hosts. If true, the user interface is not shown.
Description

Powers on the associated virtual machine.

The associated virtual machine is powered on or resumed from a suspended state. Note that after powering on commands that require the use of VMware Tools on the virtual machine should not be used until the latter is up and running. The command wait_for_tools can be used for this purpose.

power_state [::vix::VM]

VM, Top

Returns the power state of the virtual machine

OBJECT power_state

Return value

Returns the power state of the virtual machine

Description

The returned value is a list of one or more values from the following: powering_off, powered_off, powering_on, powered_on suspending, suspended, tools_running, resetting, blocked_on_msg, paused, resuming.

processes [::vix::VM]

VM, Top

Retrieves detailed information about the processes running in the virtual machine.

OBJECT processes

Description

Retrieves detailed information about the processes running in the virtual machine.

The return value is a sextuple containing

  • the process id
  • image name
  • account
  • command line,
  • the process start time (in seconds since the epoch), and
  • an indication if the process is running under a debugger (only on Windows virtual machines).

This method requires a login context to have been established.

read_file [::vix::VM]

VM, Top

Returns a content of a file in the virtual machine

OBJECT read_file guest_path args

Parameters
guest_path file or directory path in the guest virtual machine. This must be an absolute path in a format valid for the guest operating system.
args options are passed to the fconfigure Tcl command to control CRLF mode, encoding etc.
Return value

Returns a content of a file in the virtual machine

Description

Returns a content of a file in the virtual machine

readonly? [::vix::VM]

VM, Top

OBJECT readonly?

reboot [::vix::VM]

VM, Top

Reboots the associated virtual machine.

OBJECT reboot

Description

Reboots the associated virtual machine.

The virtual machine, which must be in a running state, is shut down cleanly using the running operating system and restarted. This is in contrast to the reset method.

The command requires VMware Tools to be running on the virtual machine.

remove_shared_folder [::vix::VM]

VM, Top

Removes a shared folder from the virtual machine.

OBJECT remove_shared_folder share_name

Parameters
share_name the share name in the virtual machine
Description

Removes a shared folder from the virtual machine.

This method requires VMtools to be running in the virtual machine.

rename [::vix::VM]

VM, Top

Renames a file or directory in the virtual machine.

OBJECT rename from to

Parameters
from absolute file path in the virtual machine.
to absolute file path in the virtual machine.
Description

Renames a file or directory in the virtual machine.

This method requires a login context to have been established.

reset [::vix::VM]

VM, Top

Resets the associated virtual machine.

OBJECT reset

Description

Resets the associated virtual machine.

The virtual machine, which must have been powered on, is turned off and on with the equivalent of a hardware reset. Unlike the reboot method, the virtual machine's operating system is not involved and VMware Tools need not be running on it.

revert_to_snapshot [::vix::VM]

VM, Top

Reverts the virtual machine to the specified snapshot

OBJECT revert_to_snapshot snapshot args

Parameters
snapshot The Snapshot object to revert to
argsAdditional options.
-hide BOOLEAN If false (default), the user interface is displayed on Workstation and Player VMware hosts. If true, the user interface is not shown. Only applies if the snapshot was taken with the virtual machine powered on.
-poweroff BOOLEAN If true, the restored virtual machine is powered off even if it was powered on when the snapshot was taken. Default is false.
Description

Reverts the virtual machine to the specified snapshot

The virtual machine state is restored to that when the snapshot was taken. Note that after reverting to a snapshot, commands that require the use of VMware Tools on the virtual machine should not be used until the latter is up and running. The command wait_for_tools can be used for this purpose.

rmdir [::vix::VM]

VM, Top

Deletes a directory in the virtual machine

OBJECT rmdir path

Parameters
path directory path in the guest virtual machine. This must be an absolute path in a format valid for the guest operating system.
Description

Deletes a directory in the virtual machine

The entire tree under the specified directory is deleted. It is not an error if the directory does not exist.

This method requires a login context to have been established.

rmfile [::vix::VM]

VM, Top

Deletes a file in the virtual machine

OBJECT rmfile path

Parameters
path file path in the guest virtual machine. This must be an absolute path in a format valid for the guest operating system.
Description

Deletes a file in the virtual machine

The specified file is deleted. It is not an error if it does not exist.

This method requires a login context to have been established.

root_snapshot [::vix::VM]

VM, Top

Returns a Snapshot object corresponding to the root snapshot at the specified position

OBJECT root_snapshot index

Parameters
index position of the root snapshot
Return value

Returns a Snapshot object corresponding to the root snapshot at the specified position

Description

Returns a Snapshot object corresponding to the root snapshot at the specified position

root_snapshot_count [::vix::VM]

VM, Top

Returns the number of root snapshots of the virtual machine.

OBJECT root_snapshot_count

Return value

Returns the number of root snapshots of the virtual machine.

Description

Returns the number of root snapshots of the virtual machine.

running? [::vix::VM]

VM, Top

Returns 1 if the virtual machine running, else 0

OBJECT running?

Return value

Returns 1 if the virtual machine running, else 0

Description

Returns 1 if the virtual machine running, else 0

script [::vix::VM]

VM, Top

Runs a script in the virtual machine using the specified program

OBJECT script program script args

Parameters
program absolute path of the script interpreter to run
script the text of the script to run. The size of the script is limited to about 60,000 characters.
argsAdditional options.
-wait BOOLEAN Specifies whether to wait for the program to complete (default 0)
Return value

Returns the process id, exit code and elapsed time in seconds as a triple.

Description

Runs a script in the virtual machine using the specified program

The program and script must not assume a specific working directory.

Note that if -wait is not specified as true, only the process id element in the return value is valid.

This method requires a login context to have been established.

setenv [::vix::VM]

VM, Top

Sets the value of an environment variable in the virtual machine

OBJECT setenv envvar val

Parameters
envvar name of the environment variable
val value to set for the variable
Description

Sets the value of an environment variable in the virtual machine

The method sets the value of the specified environment variable in the virtual machine.

This method requires a user login context to have been established and the returned value is based on that user context. The scope of the set environment variable in the virtual machine is dependent on its operating system. On Windows guests, UAC has to be disabled for this command to work.

setvar [::vix::VM]

VM, Top

Sets the value of a guest variable in the virtual machine

OBJECT setvar var val

Parameters
var name of the guest variable
val value to set for the variable
Description

Sets the value of a guest variable in the virtual machine

The method sets the value of the specified guest variable in the virtual machine. Guest variables are simply a means to associate data with a virtual machine and only exist while it is running. Use the getvar method to set the value of a guest variable.

This method requires the virtual machine to be running.

shared_folder_path [::vix::VM]

VM, Top

Returns the shared folder path in the virtual machine

OBJECT shared_folder_path

Return value

Returns the shared folder path in the virtual machine

Description

This method requires VMware Tools to be running in the virtual machine.

shared_folders [::vix::VM]

VM, Top

Returns list of shared folders in the virtual machine.

OBJECT shared_folders

Return value

Returns list of shared folders in the virtual machine.

Description

The return value consists of triples each containing information about one shared folder. The first element of the triple is the share name in the virtual machine, the second is the shared directory on the host, and the third is either readonly or readwrite.

shutdown [::vix::VM]

VM, Top

Shuts down the associated virtual machine.

OBJECT shutdown

Description

Shuts down the associated virtual machine.

The virtual machine, which must be in a running state, is shut down cleanly using the running operating system. This is in contrast to the power_off method.

The command requires VMware Tools to be running on the virtual machine.

ssl_error [::vix::VM]

VM, Top

OBJECT ssl_error

suspend [::vix::VM]

VM, Top

Suspends the associated virtual machine.

OBJECT suspend

Description

Suspends the associated virtual machine.

The virtual machine, which must have been powered on, is suspended. It can be resumed by calling the power_on method.

team_member? [::vix::VM]

VM, Top

Returns 1 if the virtual machine is a member of a team, else 0

OBJECT team_member?

Return value

Returns 1 if the virtual machine is a member of a team, else 0

Description

Returns 1 if the virtual machine is a member of a team, else 0

team_path [::vix::VM]

VM, Top

Returns the path to the virtual machine team

OBJECT team_path

Return value

Returns the path to the virtual machine team

Description

The command will raise an error if the virtual machine is not part of a team. Use the team_member? method to check.

tempfile [::vix::VM]

VM, Top

Creates a temporary file in the virtual machine.

OBJECT tempfile

Return value

Returns the full path to the created file.

Description

Creates a temporary file in the virtual machine.

Creates a temporary file in the virtual machine. The deletion of the file, if required, is up to the application.

This method requires a login context to have been established.

tools_state [::vix::VM]

VM, Top

Returns the state of VMware tools in the virtual machine

OBJECT tools_state

Return value

Returns the state of VMware tools in the virtual machine

Description

The returned value is one of unknown, running, or not_installed.

trace_Snapshot [::vix::VM]

VM, Top

Internal command to track virtual machines. Do not call directly.

OBJECT trace_Snapshot oldname newname op

Parameters
oldname
newname
op
Description

Internal command to track virtual machines. Do not call directly.

unpause [::vix::VM]

VM, Top

Resumes the execution of a paused virtual machine.

OBJECT unpause

Description

Resumes the execution of a paused virtual machine.

upgrade_hardware [::vix::VM]

VM, Top

Upgrades the hardware of the virtual machine

OBJECT upgrade_hardware

Description

Upgrades the hardware of the virtual machine

The machine must be powered off before attempting to upgrade the virtual hardware; otherwise the method returns an error.

upgrade_vmware_tools [::vix::VM]

VM, Top

Upgrades VMware Tools in the virtual machine

OBJECT upgrade_vmware_tools

Description

Upgrades VMware Tools in the virtual machine

Some version of VMware Tools must already be running in the virtual machine.

wait_for_tools [::vix::VM]

VM, Top

Waits for VMware Tools to be running in the virtual machine.

OBJECT wait_for_tools timeout

Parameters
timeout(optional, default 10) specifies a timeout in seconds to wait. If the tools are not running within this time, the command completes with an error. A 0 or negative value indicates an indefinite wait. Default value is 10 seconds.
Description

Waits for VMware Tools to be running in the virtual machine.

Several VM methods require VMware Tools to be running. An application can call this method to wait for this. Generally this is only required after powering on or resuming a virtual machine.

wrappee [::vix::VM]

VM, Top

Returns the underlying twapi::Automation COM object

OBJECT wrappee

Return value

Returns the underlying twapi::Automation COM object

Description

The command will raise an error if there is no associated wrapped COM object.

write_file [::vix::VM]

VM, Top

Returns content to a file in the virtual machine

OBJECT write_file guest_path data args

Parameters
guest_path file or directory path in the guest virtual machine. This must be an absolute path in a format valid for the guest operating system.
data
args options are passed to the fconfigure Tcl command to control CRLF mode, encoding etc.
Return value

Returns content to a file in the virtual machine

Description

Returns content to a file in the virtual machine

Document generated by Ruff!