Using vmrun to Control Virtual Machines
VMware Workstation 7.0 VMware Fusion 3.0 VMware vSphere 4 VMware Server 2.0 This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs. EN-000222-2, You can find the most up-to-date technical documentation on the VMware Web site at: http://www.vmware.com/support/ The VMware Web site also provides the latest product updates. If you have comments about this documentation, submit your feedback to: email is hidden Copyright © 2008, 2009 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents. VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies. VMware, Inc. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com 2 VMware, Inc.,
About This Book 5 Using vmrun to Control Virtual Machines 7 About the vmrun Utility 7 Power Commands 7 Snapshot Commands 7 Record and Replay Commands 7 Guest Operating System Commands 8 Maintenance Commands 8 VProbes Commands 8 Limitations 8 Setting Up vmrun 8 How to Get vmrun 8 Linux Setup 8 Windows Setup 9 Mac OS X Setup 9 Specifying the VMware Product Platform 9 Encrypted Virtual Machines 9 Guest Operations 9 Running Hosted Platforms Locally 9 Running VMware vSphere Remotely 10 Running VMware Server Remotely 10 Virtual Machine Run Reference 10 Path to VMX File 10 Disabling Dialog Boxes 10 Syntax of vmrun Commands 11 Examples of Using vmrun 15 Reboot Commands 15 Power Commands 15 Snapshot Commands 16 Record and Replay Commands 16 Running Guest Applications 16 Guest to Host File Operations 17 Maintenance Commands 18 Index 19 VMware, Inc. 3, 4 VMware, Inc.,
About This Book
This manual, Using vmrun to Control Virtual Machines, documents the vmrun utility, which helps you manage a collection of virtual machines on a VMware® host.
This book is revised with each release of the product or when necessary. A revised version can contain minor or major changes. Table 1 summarizes the significant changes in each version of this guide. Table 1. Revision History Revision Description 2009‐10‐20 For VMware Workstation 7.0, VMware Player 3.0, and VMware Fusion 3.0. 2009‐09‐09 For the VIX API 1.7 release, which provided support for ESX/ESXi hosts and VMware vSphere 4. 2008‐12‐31 New information about null interpreter for RunScriptInGuest on Windows. 2008‐08‐15 More examples for VMware Server 2.0 RC2 and Workstation 6.5 RC. 2008‐07‐24 Initial release, including support for VMware Fusion on Intel‐based Macintosh OS X hosts. 2008‐06‐23 Initial draft for the VMware Server 2.0 RC1 and Workstation 6.5 Beta2 releases.
This book is intended for developers and system administrators who want to control guest virtual machines on various VMware product platforms. Supported platforms include Workstation, Player, VMware Fusion®, VMware Server, and VMware vSphere™ (ESX™/ESXi hosts with vCenter™ Server).
VMware welcomes your suggestions for improving our documentation. Send your feedback to email is hidden.
Technical Support and Education Resources
The following sections describe the technical support resources available to you. To access the current versions of other VMware books, go to http://www.vmware.com/support/pubs.
Online and Telephone Support
To use online support to submit technical support requests, view your product and contract information, and register your products, go to http://www.vmware.com/support. VMware, Inc. 5,
To find out how VMware support offerings can help meet your business needs, go to http://www.vmware.com/support/services.
VMware Professional Services
VMware Education Services courses offer extensive hands‐on labs, case study examples, and course materials designed to be used as on‐the‐job reference tools. Courses are available onsite, in the classroom, and live online. For onsite pilot programs and implementation best practices, VMware Consulting Services provides offerings to help you assess, plan, build, and manage your virtual environment. To access information about education classes, certification programs, and consulting services, go to http://www.vmware.com/services. 6 VMware, Inc.,
Using vmrun to Control Virtual Machines
This document contains the following sections: “About the vmrun Utility” on page 7 “Setting Up vmrun” on page 8 “Specifying the VMware Product Platform” on page 9 “Virtual Machine Run Reference” on page 10 “Examples of Using vmrun” on page 15
About the vmrun Utility
You can use the vmrun command‐line utility to control virtual machines and automate guest operations on VMware virtual machines. The vmrun utility is included with the VIX API libraries. The vmrun utility runs on most VMware product platforms, including Workstation, Player, VMware Fusion, VMware vSphere (ESX/ESXi hosts managed by vCenter Server), and VMware Server. On these platforms, the VIX API libraries and the vmrun utility are often the best way to automate guest operations. Capabilities of vmrun are summarized in the sections below.
Power commands control these virtual machine operations: start (power on), stop (power off), reset (reboot), suspend (but allow local work to resume), pause (without interrupting), and unpause (continue). Workstation can group virtual machines in teams and apply power operations to the whole team.
A snapshot captures the state of a virtual machine at the time of the snapshot, including all data on virtual disks. You can then use the snapshot to revert the virtual machine to its previous state. Snapshots are useful for data backup, and as a placeholder for development and testing. Snapshot commands list existing snapshots of a virtual machine, create a snapshot, delete a snapshot, and revert a virtual machine to its state at the time of a snapshot. VMware Server limits each virtual machine to one snapshot. VMware Fusion supports snapshots in a line only.
Record and Replay Commands
You can record virtual machine events for later replay. The recording is called a replay snapshot. It is similar to a movie. Currently, only Workstation supports record and replay. These commands begin or end the recording of events, and begin or end the replay of a recording. VMware, Inc. 7,
Guest Operating System Commands
You can use the vmrun utility to interact with a guest operating system in the following ways: Run an executable program in the guest operating system, or run an interpreted script that you provide. Check if a file exists in the guest, delete a file, rename a file, list files, and create or delete a directory. Copy a file from the host to the guest, or from the guest to the host. Add a shared folder from the host, make a shared folder writable in the guest, or remove a shared folder. Capture a screen image from the guest (Workstation and VMware Fusion only). List the processes running in the guest operating system, or end a process (with permission). Read or write a variable in the guest operating system’s environment or virtual machine state. The timeout (wait for VMware Tools) is five minutes for all guest‐related commands.
This category includes commands to list all running virtual machines, upgrade the virtual machine hardware version, and install VMware Tools in the guest operating system. Additionally, except on VMware Server, you can clone a virtual machine image to another virtual machine. On VMware vSphere and VMware Server, you can register and unregister virtual machines.
On Workstation and Fusion, vmrun can interact with VProbes, a facility for instrumenting a powered‐on guest operating system, its processes, and the virtualization layer. See the VProbes Programming Reference for details.
VMware Fusion does not support snapshot trees, or record and replay. Player does not support pause and unpause, snapshot operations, virtual machine cloning, virtual hardware upgrade, or record and replay. VMware Server does not support teams, shared folders, cloning, record and replay, or multiple snapshots. When you try to create a second snapshot, the UI asks you to overwrite your existing snapshot.
Setting Up vmrun
The procedure for setting up vmrun varies based on the operating system of the client computer.
How to Get vmrun
The vmrun utility installs with Workstation and VMware Fusion. For use with remote product platforms, you can obtain vmrun by installing the VIX standalone libraries, available free of charge on the VMware download site.
To use the vmrun utility on Linux 1 In a command or terminal window, type vmrun to see command‐line options. 2 If this fails on an old Linux distribution: as root or superuser, edit the /etc/ld.so.conf file, add the following line with the default location of the VIX library, save the file, and run the ldconfig command. /usr/lib/vmware-vix/lib 8 VMware, Inc.,
To use the vmrun utility on Windows 1 The vmrun utility is installed in this folder by default: C:\Program Files\VMware\VMware VIX 2 If VMware Workstation is already in your system Path, this step is unnecessary because a copy of vmrun is installed there. If not, add the VIX folder location to your system path. On Windows XP, click: Computer > Properties > Advanced > Environment Variables > System variables > Path > Edit With the right arrow key, move the insertion point to the end of line, add a semicolon, add the full path of the folder where vmrun is located, and click OK three times. 3 In a command window, type vmrun to see command‐line options.
Mac OS X Setup
To use the vmrun utility on Mac OS 1 In a Terminal window, add the VMware Fusion directory to your system path. export PATH="$PATH:/Library/Application Support/VMware Fusion" 2 Type vmrun to see command‐line options.
Specifying the VMware Product Platform
The vmrun utility accepts option flags, commands, and parameters in the following syntax: vmrun In the following syntax examples, options enclosed in angle brackets indicate variables that you supply.
Encrypted Virtual Machines Encrypted virtual machines require a password for most operations. -vp
Guest Operations Guest operations require authentication by the guest operating system, so their command descriptions in Table 2, “vmrun Commands and Parameters,” on page 11 say that a “valid guest login” is required. Use the following flags to specify the guest login: -gu -gp
Running Hosted Platforms Locally On Workstation and VMware Fusion, vmrun controls guest operating systems on the local host. You do not need to specify a remote host name or port. For Workstation, Player, and VMware Fusion, use the -T flag: vmrun -T ws vmrun -T player vmrun -T fusion NOTE On Workstation, Player, and VMware Fusion, powering on a virtual machine with the default gui option requires a window system (user interface) to be running on the host. VMware vSphere and VMware Server do not impose this requirement. VMware, Inc. 9,
Running VMware vSphere Remotely In VMware vSphere, use the -T flag to connect to an ESX/ESXi 4.0 host. vmrun -T esx In VMware vSphere, use the -T flag to connect to the vCenter Server. vmrun -T vc VMware vSphere requires additional flags for connections to an ESX/ESXi host or the vCenter Server: -h https:///sdk -P -u -p The port number defaults to 443. You can also specify the port number in the -h option after the host name or IP address, separated by a colon, in standard URL syntax. For example, the following command lists all running virtual machines on a remote server: vmrun -T esx -h https://esx.example.com:8333/sdk -u root -p secretpw list
Running VMware Server Remotely To set the host type for remote access to VMware Server 2.0, use the -T option with -h and other options. vmrun -T server -h https://vm2.example.com:443/sdk -u root -p secretpw list To set the host type for remote access to VMware Server 1.0.x, use the -T option, the -h option with the host name instead of the URL, and the -P option with the port number. vmrun -T server1 -h vm1.example.com -P 443 -u root -p secretpw list
Virtual Machine Run Reference This section documents the syntax of commands in the vmrun utility.
Path to VMX File VMware stores virtual machines as a package that includes the virtual machine settings file (.vmx) and the virtual disks. When required, you must provide the complete path to the .vmx file. The .vmtn file is similar, for teams. Here are examples of where the .vmx file might be located: Datastore on an ESX/ESXi host [Storage1] Win XP/Win XP.vmx VMware Server datastore [standard] Win XP/Win XP.vmx Workstation for Windows path C:\Documents and Settings\\My Documents\My Virtual Machines\Win XP\Win XP.vmx Workstation for Linux path /home//VirtualMachines/Ubuntu/Ubuntu.vmx VMware Fusion for Mac OS X path ~/Documents/Virtual Machines.localized/Windows XP Home.vmwarevm/Windows XP Home.vmx
Disabling Dialog Boxes With virtual machines that require user input through a dialog box, the vmrun utility might time out and fail. To disable dialog boxes, insert the following line in the virtual machine configuration file (.vmx): msg.autoAnswer = TRUE 10 VMware, Inc.,
Syntax of vmrun Commands Table 2 lists vmrun commands and parameters according to their function. Parameters are listed one per line. Parameters enclosed in square brackets are optional. The vertical bar indicates a keyword choice. Table 2. vmrun Commands and Parameters Command Description Parameters Power Commands start Starts a virtual machine (.vmx file) or team (.vmtm file). (Teams supported only on The default gui option starts the machine interactively, [ gui | nogui ] Workstation.) which is required to display a VMware user interface. The nogui option suppresses the user interface, including the startup dialog box, to allow noninteractive scripting. stop Stops a virtual machine (.vmx file) or team (.vmtm file). (Teams supported only on Use the soft option to power off the guest after running [ hard | soft ] Workstation.) shutdown scripts. Use the hard option to power off the guest without running scripts, as if you pressed the power button. The default is to use the powerType value specified in the .vmx file, if present. reset Resets a virtual machine (.vmx file) or team (.vmtm file). (Teams supported only on Use the soft option to run shutdown scripts before [ hard | soft ] Workstation.) rebooting the guest. Use the hard option to reboot the guest without running scripts, as if you pressed the reset button. The default is to use the powerType value specified in the .vmx file, if present. suspend Suspends a virtual machine (.vmx file) or team (.vmtm) (Teams supported only on without shutting down, so local work can resume later. [ hard | soft ] Workstation.) The soft option suspends the guest after running system scripts. On Windows guests, these scripts release the IP address. On Linux guests, the scripts suspend networking. The hard option suspends the guest without running the scripts. The default is to use the powerType value specified in the .vmx file, if present. To resume virtual machine operation after suspend, use the start command. On Windows, the IP address is retrieved. On Linux, networking is restarted. pause Pauses a virtual machine (.vmx file). You can use this (Pause supported only on either to pause replay or to pause normal operation. Workstation.) unpause Resumes operation of a virtual machine (.vmx file) from (Unpause supported only on where you paused replay or normal operation. Workstation.) Snapshot Commands listSnapshots Lists all snapshots in a virtual machine (.vmx file). The showtree option displays snapshots in tree format, [ showtree ] with children indented under their parent. snapshot Creates a snapshot of a virtual machine (.vmx file). For (VMware Server does not products that support multiple snapshots, you must support multiple snapshots. provide the snapshot name. VMware Fusion does not Because the forward slash defines pathnames, do not support snapshot trees.) use the slash character in a snapshot name, because that makes it difficult to specify the snapshot path later. VMware, Inc. 11,
Table 2. vmrun Commands and Parameters (Continued) Command Description Parameters deleteSnapshot Removes a snapshot from a virtual machine (.vmx file). (VMware Server always For products that support multiple snapshots, you must deletes the root snapshot.) provide the snapshot name. [ andDeleteChildren ] The virtual machine must be powered off or suspended. If the snapshot has children, they become children of the deleted snapshot’s parent, and subsequent snapshots continue as before from the end of the chain. The andDeleteChildren option deletes the specified snapshot and its children recursively. See revertToSnapshot for solutions to name conflicts. revertToSnapshot Sets the virtual machine to its state at snapshot time. (VMware Server always However, if the virtual machine was powered on at the reverts to the root snapshot.) time of the snapshot, vmrun reverts it to suspended state. If a snapshot has a unique name within a virtual or machine, revert to that snapshot by specifying the path to the virtual machine’s configuration file and the unique snapshot name. If several snapshots have the same name, specify the snapshot by including a full pathname for the snapshot. A pathname is a series of snapshot names, separated by forward slash characters (/). Each name specifies a new snapshot in the tree. For example, the pathname Snap1/Snap2 identifies a snapshot named Snap2 that was taken from the state of a snapshot named Snap1. Record and Replay Commands beginRecording Begins recording a running virtual machine (.vmx file), (Recording supported only storing activity in the specified snapshot object, with on Workstation.) optional description for your convenience. [ ] Only one recording or replay can be active at a time. endRecording Ends the recording of a virtual machine (.vmx file) that is in progress, and closes its snapshot object. beginReplay Begins replaying the recorded activity of a powered off (Replay supported only on virtual machine (.vmx file) from a snapshot object, Workstation.) powering off the virtual machine if necessary. Only one recording or replay can be active at a time. You can pause replay with the pause command, and resume replay with the unpause command. endReplay Ends replay of the recorded virtual machine (.vmx file) that is underway. Guest Operating System Commands The timeout (wait for VMware Tools) is five minutes for all guest‐related commands. runProgramInGuest Runs a specified program in the guest operating system. The -noWait option returns a prompt immediately after [ -noWait | the program starts in the guest, rather than waiting for it -activeWindow | to finish. This option is useful for interactive programs. -interactive ] The -activeWindow option ensures that the Windows GUI is visible, not minimized. It has no effect on Linux. [ ] The -interactive option forces interactive guest login. It is useful for Windows Vista guests to make the program visible in the console window. You must provide the full pathname of a program accessible to the guest. Also provide full accessible pathnames for any files specified in the program arguments, according to requirements of the program. VMware Tools and a valid guest login are required. 12 VMware, Inc.,
Table 2. vmrun Commands and Parameters (Continued) Command Description Parameters fileExistsInGuest Checks whether the specified file exists in the guest operating system. VMware Tools and a valid guest login are required. setSharedFolderState Modifies the writability state of a specified folder shared (VMware vSphere and between the host and a guest virtual machine (.vmx file). VMware Server do not The share name is a mount point in the guest file system. support shared folders.) The path to folder is the exported directory on the host. writable | readonly A shared folder can be made writable or read‐only. addSharedFolder Adds a folder to be shared between the host and guest. (VMware vSphere and The share name is a mount point in the guest file system. VMware Server do not The path to folder is the exported directory on the host. support shared folders.) On Windows guests, there might be a delay before shared folders are visible to the InGuest commands. removeSharedFolder Removes the guest virtual machine’s access to a shared (VMware vSphere and folder on the host. The share name is a mount point in VMware Server do not the guest file system. support shared folders.) enableSharedFolders Allows the guest virtual machine, specified by .vmx file, (VMware vSphere and to share folders with its host. After enabling, run [runtime] VMware Server do not addSharedFolder to specify each host folder to share. support shared folders.) The optional runtime argument means to share folders only until the virtual machine is powered off. Otherwise, the setting persists at next power on. disableSharedFolders Stops the guest virtual machine, specified by .vmx file, (VMware vSphere and from sharing folders with its host. [runtime] VMware Server do not The optional runtime argument means to stop sharing support shared folders.) folders only until the virtual machine is powered off. Otherwise, the setting persists at next power on. listProcessesInGuest Lists all processes running in the guest operating system. VMware Tools and a valid guest login are required. killProcessInGuest Stops a specified process in the guest operating system. VMware Tools and a valid guest login are required. The process ID can be any number listed after pid= in the output of listProcessesInGuest. runScriptInGuest Runs the specified command script in the guest operating system. VMware Tools and a valid guest login are required.