Using vmrun

to Control Virtual Machines

VMware Fusion 5
VMware Workstation 9 and Player 5
VMware vSphere 5.x

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-001006-00

Using vmrun to Control Virtual Machines

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:
docfeedback@vmware.com

Copyright 20082012 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

VMware, Inc.

Contents

AboutThisBook

UsingvmruntoControlVirtualMachines

AboutthevmrunUtility 7
PowerCommands 7
SnapshotCommands 7
GuestOperatingSystemCommands 7
MaintenanceCommands 8
VProbesCommands 8
Limitations 8
SettingUpvmrun 8
HowtoGetvmrun 8
LinuxSetup 8
WindowsSetup 9
MacOSXSetup 9
SpecifyingtheVMwareProductPlatform 9
EncryptedVirtualMachines 9
GuestOperations 9
RunningHostedPlatformsLocally 9
RunningVMwarevSphereRemotely 10
RunningVMwareServerRemotely 10
VirtualMachineRunReference 10
PathtoVMXFile 10
DisablingDialogBoxes 11
SyntaxofvmrunCommands 11
ExamplesofUsingvmrun 15
RebootCommands 15
PowerCommands 15
SnapshotCommands 16
RunningGuestApplications 16
GuesttoHostFileOperations 17
GuestVariablesandEnvironment 17
MaintenanceCommands 18

Index 19

VMware, Inc.

Using vmrun to Control Virtual Machines

VMware, Inc.

About This Book

Thismanual,Usingvmrunto Control Virtual Machines,documentsthevmrunutility,whichhelpsyoumanagea

collectionofvirtualmachinesonaVMwarehost.

Revision History
Thisbookisrevisedwitheachreleaseoftheproductorwhennecessary.Arevisedversioncancontainminor
ormajorchanges.Table 1summarizesthesignificantchangesineachversionofthisguide.
Table 1. Revision History
Revision

Description

20121004

FortheVIXAPI1.12release.AddedcreateTempFileInGuestcommand.ChangedFusioninstalllocation.

20110421

FortheVIXAPI1.11release,whichsupportedvSphere5.0,Workstation8.0,andFusion4.0.

20100719

FortheVIXAPI1.10release,whichsupportedvSphere4.1,Workstation7.1,andFusion3.1.

20091020

FortheVIXAPI1.8release,whichsupportedVMwareWorkstation7.0,Player3.0,andVMwareFusion3.0.

20090909

FortheVIXAPI1.7release,whichprovidedsupportforESX/ESXihostsandVMwarevSphere4.

20081231

NewinformationaboutnullinterpreterforRunScriptInGuestonWindows.

20080815

MoreexamplesforVMwareServer2.0RC2andWorkstation6.5RC.

20080724

Initialrelease,includingsupportforVMwareFusiononIntelbasedMacintoshOSXhosts.

20080623

InitialdraftfortheVMwareServer2.0RC1andWorkstation6.5Beta2releases.

Intended Audience
Thisbookisintendedfordevelopersandsystemadministratorswhowanttocontrolguestvirtualmachines
onvariousVMwareproductplatforms.SupportedplatformsincludeVMwareWorkstation,VMwarePlayer,
VMwareFusion,andVMwarevSphere(ESX/ESXihostswithvCenterServer).
ThevmrunutilityisassociatedwiththeVIXAPI.OnsomeVMwareplatformproducts,youmustinstallthe
VIXlibrariesbeforeyoucanusevmrun.

VMware Technical Publications Glossary

VMwareTechnicalPublicationsprovidesaglossaryoftermsthatmightbeunfamiliartoyou.Fordefinitions
oftermsastheyareusedinVMwaretechnicaldocumentationgotohttp://www.vmware.com/support/pubs.

Document Feedback
VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Sendyourfeedbackto
docfeedback@vmware.com.

VMware, Inc.

Using vmrun to Control Virtual Machines

VMware, Inc.

Using vmrun to Control Virtual Machines

Thisdocumentcontainsthefollowingsections:

AboutthevmrunUtilityonpage 7

SettingUpvmrunonpage 8

SpecifyingtheVMwareProductPlatformonpage 9

VirtualMachineRunReferenceonpage 10

ExamplesofUsingvmrunonpage 15

About the vmrun Utility

Youcanusethevmruncommandlineutilitytocontrolvirtualmachinesandautomateguestoperationson
VMwarevirtualmachines.ThevmrunutilityisincludedwiththeVIXAPIlibraries.
ThevmrunutilityrunsonmostVMwareproductplatforms,includingWorkstation,Player,VMwareFusion,
andVMwarevSphere(ESX/ESXihostsmanagedbyvCenterServer).Ontheseplatforms,theVIXAPIlibraries
andthevmrunutilityareoftenthebestwaytoautomateguestoperations.
Capabilitiesofvmrunaresummarizedinthesectionsbelow.

Power Commands
Powercommandscontrolthesevirtualmachineoperations:start(poweron),stop(poweroff),reset(reboot),
suspend(butallowlocalworktoresume),pause(withoutinterrupting),andunpause(continue).
Workstationcangroupvirtualmachinesinteamsandapplypoweroperationstothewholeteam.

Snapshot Commands
Asnapshotcapturesthestateofavirtualmachineatthetimeofthesnapshot,includingalldataonvirtual
disks.Youcanthenusethesnapshottorevertthevirtualmachinetoitspreviousstate.Snapshotsareuseful
fordatabackup,andasaplaceholderfordevelopmentandtesting.
Snapshotcommandslistexistingsnapshotsofavirtualmachine,createasnapshot,deleteasnapshot,and
revertavirtualmachinetoitsstateatthetimeofasnapshot.Reverttosnapshotdoesnotresumerunninga
virtualmachine,evenifitwasrunningatthetimeofasnapshot.
VMwareFusionsupportssnapshotsinalineonly.VMwareServer(discontinued)limitseachvirtualmachine
toonesnapshot.

Guest Operating System Commands

Youcanusethevmrunutilitytointeractwithaguestoperatingsysteminthefollowingways:

Runanexecutableprogramintheguestoperatingsystem,orrunaninterpretedscriptthatyouprovide.

VMware, Inc.

Using vmrun to Control Virtual Machines

Checkifafileordirectoryexistsintheguest,deleteafileordirectory,renameafile,listfiles,orcreatea
newdirectory.

Copyafilefromthehosttotheguest,orfromtheguesttothehost.

Createatemporaryfileintheguestoperatingsystem.

Addasharedfolderfromthehost,makeasharedfolderwritableintheguest,orremoveasharedfolder.

Captureascreenimagefromtheguest(WorkstationandVMwareFusiononly).

Listtheprocessesrunningintheguestoperatingsystem,orendaprocess(withpermission).

Readorwriteavariableintheguestoperatingsystemsenvironmentorvirtualmachinestate.

Thetimeout(waitforVMwareTools)isfiveminutesforallguestrelatedcommands.

Maintenance Commands
Thiscategoryincludescommandstolistallrunningvirtualmachines,upgradethevirtualmachinehardware
version,andinstallVMwareToolsintheguestoperatingsystem.
Additionally,exceptonVMwareServer(discontinued),youcancloneavirtualmachineimagetoanother
virtualmachine.
OnVMwarevSphereandVMwareServer(discontinued),youcanregisterandunregistervirtualmachines.

VProbes Commands
OnWorkstationandFusion,vmruncaninteractwithVProbes,afacilityforinstrumentingapoweredonguest
operatingsystem,itsprocesses,andthevirtualizationlayer.SeetheVProbesProgrammingReferencefordetails.

Limitations
VMwareFusiondoesnotsupportsnapshottrees.
VMwarePlayerdoesnotsupportpauseandunpause,snapshotoperations,virtualmachinecloning,orvirtual
hardwareupgrade.
VMwareServer(discontinued)didnotsupportteams,sharedfolders,virtualmachinecloning,ormultiple
snapshots.Whenyoutriedtocreateasecondsnapshot,theUIaskedtooverwriteyourexistingsnapshot.
TherecordandreplaycommandsweredeprecatedforWorkstation7.1andremovedinWorkstation8.

Setting Up vmrun
Theprocedureforsettingupvmrunvariesbasedontheoperatingsystemoftheclientcomputer.

How to Get vmrun

ThevmrunutilityinstallswithWorkstationandVMwareFusion.
Forusewithremoteproductplatforms,youcanobtainvmrunbyinstallingtheVIXstandalonelibraries,
availablefreeofchargeontheVMwaredownloadsite.

Linux Setup
To use the vmrun utility on Linux
1

Inacommandorterminalwindow,typevmruntoseecommandlineoptions.

IfthisfailsonanoldLinuxdistribution:asrootorsuperuser,editthe/etc/ld.so.conffile,addthe
followinglinewiththedefaultlocationoftheVIXlibrary,savethefile,andruntheldconfigcommand.
/usr/lib/vmware-vix/lib

VMware, Inc.

Using vmrun to Control Virtual Machines

Windows Setup
To use the vmrun utility on Windows
1

IfyouarerunningVMwareWorkstation,acopyofvmrunisincludedinthefolderwhereyouinstalled
Workstation.IfyouinstalltheVIXAPI,apossiblynewervmrunisplacedinoneofthesefolders:
32bitsystemsC:\Program Files\VMware\VMware VIX
64bitsystemsC:\Program Files (x86)\VMware\VMware VIX

(Optional)Mostusersfinditconvenienttoaddthevmruninstalllocation,eitherVMwareWorkstationor
VMwareVIX,tothesystempath.OnWindows7:
(rightclick)Computer>(click)Properties>AdvancedSystemSettings>EnvironmentVariables>
(inlistof)SystemVariables>(select)Path>(click)Edit
Withtherightarrowkey,movetheinsertionpointtotheendofline,addasemicolon,addthefullpath
ofthefolderwherevmrunislocated,andclickOKthreetimes.

Inacommandwindow,typevmruntoseecommandlineoptions.

Mac OS X Setup
To use the vmrun utility on Mac OS
1

InaTerminalwindow,addtheVMwareFusion(4.0andlater)directorytoyoursystempath.
export PATH="$PATH:/Applications/VMware\ Fusion.app/Contents/Library"

Typevmruntoseecommandlineoptions.

Specifying the VMware Product Platform

Thevmrunutilityacceptsoptionflags,commands,andparametersinthefollowingsyntax:
vmrun <flags> <command> <parameters>

Inthefollowingsyntaxexamples,optionsenclosedinanglebracketsindicatevariablesthatyousupply.

Encrypted Virtual Machines

Encryptedvirtualmachinesrequireapasswordformostoperations.
-vp <password for encrypted virtual machine>

Guest Operations
Guestoperationsrequireauthenticationbytheguestoperatingsystem,sotheircommanddescriptionsin
Table 2,vmrunCommandsandParameters,onpage 11saythatavalidguestloginisrequired.Usethe
followingflagstospecifytheguestlogin:
-gu <userName in guest OS>
-gp <userPassword in guest OS>

AsoftheVIX1.10release,younolongerneedtospecifyaguestusernameandpassword,oranencryption
password.Ifvmrunneedsauthenticationinformation,itpromptsforit.

Running Hosted Platforms Locally

OnWorkstationandVMwareFusion,vmruncontrolsguestoperatingsystemsonthelocalhost.Youdonot
needtospecifyaremotehostnameorport.Usethe-TflagforWorkstation,Player,andVMwareFusion:
vmrun -T ws
vmrun -T player
vmrun -T fusion

VMware, Inc.

Using vmrun to Control Virtual Machines

NOTEOnVMwareFusion,Workstation,andPlayer,poweringonavirtualmachinewiththedefaultgui
optionrequiresawindowsystem(userinterface)toberunningonthehost.ESX/ESXihosts,vCenterServer,
andVMwareServer(discontinued)donotimposethisrequirement.

Running VMware vSphere Remotely

InVMwarevSphere,usethe-TflagtoconnecttoanESX/ESXihostortothevCenterServer.
vmrun -T esx
vmrun -T vc

VMwarevSphererequiresadditionalflagsforconnectionstoanESX/ESXihostortovCenterServer(VC):
-h
-P
-u
-p

<hostName or IPaddr>
<portNumber>
<adminLogin on ESX/ESXi or VC>
<adminPassword on ESX/ESXi or VC>

Theportnumberdefaultsto443.Youcanalsospecifytheportnumberinthe-hoptionafterthehostnameor
IPaddress,separatedbyacolon,usingstandardURLsyntax.Forexample,thefollowingcommandlistsall
runningvirtualmachinesonaremoteESX/ESXihost:
vmrun -T esx -h esx.example.com:8333 -u root -p secretpw list

AsoftheVIX1.10release,ifyoudonotspecifyadministratorloginnameandpassword,vmrunpromptsyou
forauthenticationinformation.AlsoasoftheVIX1.10release,youdonotneedtospecifyleadinghttps://
andtrailing/sdkwiththe-hoption.

Running VMware Server Remotely

TosetthehosttypeforremoteaccesstoVMwareServer2.0,usethe-Toptionwith-handotheroptions.
vmrun -T server -h vm2.example.com:443 -u root -p secretpw list

TosetthehosttypeforremoteaccesstoVMwareServer1.0.x,usethemandatory-Toption,the-hoptionwith
thehostnameinsteadoftheURL,andthe-Poptionwiththeportnumber.
vmrun -T server1 -h vm1.example.com -P 443 -u root -p secretpw list

Virtual Machine Run Reference

Thissectiondocumentsthesyntaxofcommandsinthevmrunutility.

Path to VMX File

VMwarestoresvirtualmachinesasapackagethatincludesthevirtualmachinesettingsfile(<vnname>.vmx)
andthevirtualdisks.Whenrequired,youmustprovidethecompletepathtothe.vmxfile.The.vmtnfileis
similar,forteams.Hereareexamplesofwherethe.vmxfilemightbelocated:

DatastoreonanESX/ESXihost
[datastore1] Win XP/Win XP.vmx

WorkstationforWindowspath
C:\Documents and Settings\<username>\My Documents\My Virtual Machines\Win XP\Win XP.vmx

WorkstationforLinuxpath
/home/<username>/VirtualMachines/Ubuntu/Ubuntu.vmx

VMwareFusionforMacOSXpath
~/Documents/Virtual Machines.localized/Windows XP Home.vmwarevm/Windows XP Home.vmx

IMPORTANTForthevmruncommandsthatrequireVMwareTools,youmustinstallthelatestVMwareTools
packageand,especiallyafteroperatingsystemupdates,keepVMwareToolsuptodate.

10

VMware, Inc.

Using vmrun to Control Virtual Machines

Disabling Dialog Boxes

Withvirtualmachinesthatrequireuserinputthroughadialogbox,thevmrunutilitymighttimeoutandfail.
Todisabledialogboxes,insertthefollowinglineinthevirtualmachineconfigurationfile(.vmx):
msg.autoAnswer = TRUE

Syntax of vmrun Commands

Table 2listsvmruncommandsandparametersaccordingtotheirfunction.Parametersarelistedoneperline.
Parametersenclosedinsquarebracketsareoptional.Theverticalbarindicatesakeywordchoice.
Table 2. vmrun Commands and Parameters
Command

Description

Parameters

Power Commands
start
(Teamssupportedonlyon
Workstation.)

stop
(Teamssupportedonlyon
Workstation.)

reset
(Teamssupportedonlyon
Workstation.)

suspend
(Teamssupportedonlyon
Workstation.)

Startsavirtualmachine(.vmxfile)orteam(.vmtmfile).
Thedefaultguioptionstartsthemachineinteractively,
whichisrequiredtodisplayaVMwareuserinterface.
Thenoguioptionsuppressestheuserinterface,
includingthestartupdialogbox,toallownoninteractive
scripting.

<pathto.vmxor.vmtmfile>
[ gui | nogui ]

Stopsavirtualmachine(.vmxfile)orteam(.vmtmfile).
Usethesoftoptiontopowerofftheguestafterrunning
shutdownscripts.Usethehardoptiontopoweroffthe
guestwithoutrunningscripts,asifyoupressedthe
powerbutton.ThedefaultistousethepowerTypevalue
specifiedinthe.vmxfile,ifpresent.

<pathto.vmxor.vmtmfile>

Resetsavirtualmachine(.vmxfile)orteam(.vmtmfile).
Usethesoftoptiontorunshutdownscriptsbefore
rebootingtheguest.Usethehardoptiontorebootthe
guestwithoutrunningscripts,asifyoupressedthereset
button.ThedefaultistousethepowerTypevalue
specifiedinthe.vmxfile,ifpresent.

<pathto.vmxor.vmtmfile>

Suspendsavirtualmachine(.vmxfile)orteam(.vmtm)
withoutshuttingdown,solocalworkcanresumelater.
Thesoftoptionsuspendstheguestafterrunning
systemscripts.OnWindowsguests,thesescriptsrelease
theIPaddress.OnLinuxguests,thescriptssuspend
networking.Thehardoptionsuspendstheguest
withoutrunningthescripts.Thedefaultistousethe
powerTypevaluespecifiedinthe.vmxfile,ifpresent.

<pathto.vmxor.vmtmfile>

[ hard | soft ]

[ hard | soft ]

[ hard | soft ]

Toresumevirtualmachineoperationaftersuspend,use
thestartcommand.OnWindows,theIPaddressis
retrieved.OnLinux,networkingisrestarted.
pause
(Pausesupportedonlyon
Workstation.)
unpause
(Unpausesupportedonlyon
Workstation.)

Pausesavirtualmachine(.vmxfile).Youcanusethisto
suspendvirtualmachineoperation.

<pathto.vmxfile>

Resumesoperationofavirtualmachine(.vmxfile)from
whereyoupausednormaloperation.

<pathto.vmxfile>

Snapshot Commands
listSnapshots

snapshot
(VMwareServerdoesnot
supportmultiplesnapshots.
VMwareFusiondoesnot
supportsnapshottrees.)

VMware, Inc.

Listsallsnapshotsinavirtualmachine(.vmxfile).

<pathto.vmxfile>

Theshowtreeoptiondisplayssnapshotsintreeformat,
withchildrenindentedundertheirparent.

[ showtree ]

Createsasnapshotofavirtualmachine(.vmxfile).For
productsthatsupportmultiplesnapshots,youmust
providethesnapshotname.

<pathto.vmxfile>
<snapshotname>

Becausetheforwardslashdefinespathnames,donot
usetheslashcharacterinasnapshotname,becausethat
makesitdifficulttospecifythesnapshotpathlater.

11

Using vmrun to Control Virtual Machines

Table 2. vmrun Commands and Parameters (Continued)

Command

Description

Parameters

deleteSnapshot

Removesasnapshotfromavirtualmachine(.vmxfile).
Forproductsthatsupportmultiplesnapshots,youmust
providethesnapshotname.

<pathto.vmxfile>

(VMwareServeralways
deletestherootsnapshot.)

<snapshotname>
[ andDeleteChildren ]

Thevirtualmachinemustbepoweredofforsuspended.
Ifthesnapshothaschildren,theybecomechildrenofthe
deletedsnapshotsparent,andsubsequentsnapshots
continueasbeforefromtheendofthechain.
TheandDeleteChildrenoptiondeletesthespecified
snapshotanditschildrenrecursively.
SeerevertToSnapshotforsolutionstonameconflicts.
revertToSnapshot
(VMwareServeralways
revertstotherootsnapshot.)

Setsthevirtualmachinetoitsstateatsnapshottime.
Howeverifthevirtualmachinewaspoweredonatthe
timeofthesnapshot,vmrunrevertsittosuspendedstate,
butdoesnotresumerunningthevirtualmachine.
Ifasnapshothasauniquenamewithinavirtual
machine,reverttothatsnapshotbyspecifyingthepath
tothevirtualmachinesconfigurationfileandthe
uniquesnapshotname.

<pathto.vmxfile>
<snapshotname>
or
<pathto.vmxfile>
<snap1/snap2/snapN>

Ifseveralsnapshotshavethesamename,specifythe
snapshotbyincludingafullpathnameforthesnapshot.
Apathnameisaseriesofsnapshotnames,separatedby
forwardslashcharacters(/).Eachnamespecifiesanew
snapshotinthetree.Forexample,thepathname
Snap1/Snap2identifiesasnapshotnamedSnap2that
wastakenfromthestateofasnapshotnamedSnap1.
Guest Operating System Commands
Thetimeout(waitforVMwareTools)isfiveminutesforallguestrelatedcommands.
runProgramInGuest

Runsaspecifiedprogramintheguestoperatingsystem.

<pathto.vmxfile>

The-noWaitoptionreturnsapromptimmediatelyafter
theprogramstartsintheguest,ratherthanwaitingforit
tofinish.Thisoptionisusefulforinteractiveprograms.

[ -noWait |
-activeWindow |
-interactive ]

The-activeWindowoptionensuresthattheWindows
GUIisvisible,notminimized.IthasnoeffectonLinux.

<programname>
[<programarguments>]

The-interactiveoptionforcesinteractiveguestlogin.
ItisusefulforVistaandWindows7gueststomakethe
programvisibleintheconsolewindow.
Youmustprovidethefullpathnameofaprogram
accessibletotheguest.Alsoprovidefullaccessible
pathnamesforanyfilesspecifiedintheprogram
arguments,accordingtorequirementsoftheprogram.
VMwareToolsandavalidguestloginarerequired.
runScriptInGuest

Runsthespecifiedcommandscriptintheguest
operatingsystem.
SeerunProgramInGuestforanexplanationofoptions.
Theinterpreterpathisthecommandthatrunsthescript.
Providethecompletetextofthescript,notafilename.

<pathto.vmxfile>
[ -noWait |
-activeWindow |
-interactive ]
<interpreterpath>

VMwareToolsandavalidguestloginarerequired.

<scripttext>

listProcessesInGuest

Listsallprocessesrunningintheguestoperating
system.VMwareToolsandavalidguestloginare
required.

<pathto.vmxfile>

killProcessInGuest

Stopsaspecifiedprocessintheguestoperatingsystem.
VMwareToolsandavalidguestloginarerequired.

<pathto.vmxfile>
<processID>

TheprocessIDcanbeanynumberlistedafterpid=in
theoutputoflistProcessesInGuest.
fileExistsInGuest

12

Checkswhetherthespecifiedfileexistsintheguest
operatingsystem.VMwareToolsandavalidguestlogin
arerequired.

<pathto.vmxfile>
<pathtofileonguest>

VMware, Inc.

Using vmrun to Control Virtual Machines

Table 2. vmrun Commands and Parameters (Continued)

Command

Description

Parameters

renameFileInGuest

Renamesormovesafileintheguestoperatingsystem.
VMwareToolsandavalidguestloginarerequired.

<pathto.vmxfile>

Specifythesourcename(original)beforethedestination
(new).

<newfilename>

Deletesthegivefilefromtheguestoperatingsystem.
VMwareToolsandavalidguestloginarerequired.

<pathto.vmxfile>

deleteFileInGuest

<originalfilename>

<pathtofileonguest>

ForVistaandWindows7restrictionsonthiscommand,
seenoteinGuesttoHostFileOperationsonpage 17.
directoryExistsInGuest

createDirectoryInGuest

Checkswhetherthespecifieddirectoryexistsinthe
guestoperatingsystem.VMwareToolsandavalidguest
loginarerequired.

<pathto.vmxfile>

Createsthespecifieddirectoryintheguestoperating
system.VMwareToolsandavalidguestloginare
required.

<pathto.vmxfile>

<directorypathonguest>

<directorypathonguest>

ForVistaandWindows7restrictionsonthiscommand,
seenoteinGuesttoHostFileOperationsonpage 17.
listDirectoryInGuest

deleteDirectoryInGuest

Listscontentsofthespecifieddirectoryintheguest
operatingsystem.VMwareToolsandavalidguestlogin
arerequired.

<pathto.vmxfile>

Deletesthespecifieddirectoryfromtheguestoperating
system.VMwareToolsandavalidguestloginare
required.

<pathto.vmxfile>

<directorypathonguest>

<directorypathonguest>

ForVistaandWindows7restrictionsonthiscommand,
seenoteinGuesttoHostFileOperationsonpage 17.
copyFileFromHostToGuest

Copiesafilefromthehosttotheguestoperatingsystem.
VMwareToolsandavalidguestloginarerequired.

<pathto.vmxfile>

Specifythesourcefile(host)beforethedestinationfile
(guest).

<filepathinguest>

<filepathonhost>

ForVistaandWindows7restrictionsonthiscommand,
seenoteinGuesttoHostFileOperationsonpage 17.
copyFileFromGuestToHost

createTempfileInGuest

Copiesafilefromtheguestoperatingsystemtothehost.
VMwareToolsandavalidguestloginarerequired.

<pathto.vmxfile>

Specifythesourcefile(guest)beforethedestinationfile
(host).

<filepathonhost>

Createsatemporaryfileintheguestoperatingsystem,
andreturnsthepathnameofthetemporaryfilecreated.
Pathnamevariesaccordingtotheoperatingsystem.You
canrundeleteFileInGuesttoremovethefile.

<pathto.vmxfile>

<filepathinguest>

VMwareToolsandavalidguestloginarerequired.
enableSharedFolders
(VMwarevSphereand
VMwareServerdonot
supportsharedfolders.)

disableSharedFolders
(VMwarevSphereand
VMwareServerdonot
supportsharedfolders.)
addSharedFolder
(VMwarevSphereand
VMwareServerdonot
supportsharedfolders.)

VMware, Inc.

Allowstheguestvirtualmachine,specifiedby.vmxfile,
tosharefolderswithitshost.Afterenabling,run
addSharedFoldertospecifyeachhostfoldertoshare.

<pathto.vmxfile>
[runtime]

Theoptionalruntimeargumentmeanstosharefolders
onlyuntilthevirtualmachineispoweredoff.Otherwise,
thesettingpersistsatnextpoweron.
Stopstheguestvirtualmachine,specifiedby.vmxfile,
fromsharingfolderswithitshost.

<pathto.vmxfile>
[runtime]

Theoptionalruntimeargumentmeanstostopsharing
foldersonlyuntilthevirtualmachineispoweredoff.
Otherwise,thesettingpersistsatnextpoweron.
Addsafoldertobesharedbetweenthehostandguest.
Thesharenameisamountpointintheguestfilesystem.
Thepathtofolderistheexporteddirectoryonthehost.
OnWindowsguests,theremightbeadelaybefore
sharedfoldersarevisibletotheInGuestcommands.

<pathto.vmxfile>
<sharename>
<pathtofolderonhost>

13

Using vmrun to Control Virtual Machines

Table 2. vmrun Commands and Parameters (Continued)

Command

Description

Parameters

removeSharedFolder

Removestheguestvirtualmachinesaccesstoashared
folderonthehost.Thesharenameisamountpointin
theguestfilesystem.

<pathto.vmxfile>

(VMwarevSphereand
VMwareServerdonot
supportsharedfolders.)
setSharedFolderState
(VMwarevSphereand
VMwareServerdonot
supportsharedfolders.)
captureScreen

Modifiesthewritabilitystateofaspecifiedfoldershared
betweenthehostandaguestvirtualmachine(.vmxfile).

<sharename>

<pathto.vmxfile>
<sharename>

Thesharenameisamountpointintheguestfilesystem.
Thepathtofolderistheexporteddirectoryonthehost.
Asharedfoldercanbemadewritableorreadonly.

<pathtofolderonhost>

Capturesthescreenofthevirtualmachinetoalocalfile.
ThespecifiedoutputfileonthehostisinPNGformat.

<pathto.vmxfile>

writable |readonly

<outputpathonhost>

Avalidguestloginisrequired.
writeVariable

Writesavariabletothevirtualmachinestateorguest.
Youcanseteitheranonpersistentguestvariable
(guestVar),aruntimeconfigurationparameteras
storedinthe.vmxfile,oranenvironmentvariable
(guestEnv)intheguestoperatingsystem.Aguest
variableisaruntimeonlyvaluethatprovidesasimple
waytopassruntimevaluesinandoutoftheguest.
EnvironmentvariablesrequireVMwareToolsandvalid
guestlogin.WithLinux,settingtheguestenvironment
alsorequiresrootlogin.

<pathto.vmxfile>
[ guestVar |
runtimeConfig |
guestEnv ]
<variablename>
<variablevalue>

Providethevariablenameanditsvalue.
readVariable

Readsavariablefromthevirtualmachinestateorguest.
Youcangetaguestvariable,aruntimeconfigurationas
storedinthe.vmxfile,orenvironmentvariablesinthe
guestoperatingsystem.ReadingtheguestEnvrequires
avalidguestlogin.
Seeaboveforadescriptionofvariabletypes.

<pathto.vmxfile>
[ guestVar |
runtimeConfig |
guestEnv ]
<variablename>

Maintenance Commands
list

Listsallrunningvirtualmachines.

None

upgradevm

Upgradesavirtualmachinetothecurrentversionof
virtualhardware.Hasnoeffectifthevirtualhardware
versionisthemostrecentsupported.

<pathto.vmxfile>

installTools

PreparestoinstallVMwareToolsintheguestoperating
system.InWindowsguestswithautorunenabled,the
VMwareToolsinstallerstartsbyitself.InLinuxguests
withoutautorun,thiscommandconnectsthevirtual
CDROMdrivetotheVMwareToolsISOimagesuitable
fortheguest,buttheinstallerdoesnotstart.Youmust
completetheinstallationwithadditionalmanualsteps,
asdescribedintheproductdocumentation.

<pathto.vmxfile>

register

Registersthespecifiedvirtualmachine,addingittothe
hostsinventory.Pathformatdependsontheproduct.
ForESX/ESXihosts,"[datastore1] vm/vm.vmx"
(startingwiththedatastore)istypical.

<pathto.vmxfile>

Unregistersthespecifiedvirtualmachine,removingit
fromthehostsinventory.Pathformatdependsonthe
product.ForESX/ESXi,"[datastore1] vm/vm.vmx"
(startingwiththedatastore)istypical.

<pathto.vmxfile>

(Registrationnotsupported
onWorkstationoron
VMwareFusion.)
listRegisteredVM

Listsallregisteredvirtualmachines.

None

deleteVM

Removesthespecifiedvirtualmachine.

<pathto.vmxfile>

(Registrationnotsupported
onWorkstationoron
VMwareFusion.)
unregister

14

VMware, Inc.

Using vmrun to Control Virtual Machines

Table 2. vmrun Commands and Parameters (Continued)

Command

Description

Parameters

clone

Createsacopyofthevirtualmachineandguest.Provide
boththesourceandthedestination.vmxfilepathname.
Youcancreateeitherafullcloneoralinkedclone.To
createtheclonefromasnapshot,ratherthanfromthe
currentvirtualmachinestate,specifyasnapshotname.

<pathto.vmxfile>

(Cloningnotsupportedon
VMwareServeroron
VMwareFusion.)

<destination.vmxfilepath>
full |linked
[<snapshotname>]

VProbes Commands
(VProbespermittedonlyonWorkstationandVMwareFusion.)
vprobeVersion

ShowstheVProbesversiononthevirtualmachine.

<pathto.vmxfile>

vprobeLoad

LoadsaVPscriptontothevirtualmachine.

<pathto.vmxfile>
<textoftheVPscript>

vprobeLoadFile

LoadsaVPscriptfileontothevirtualmachine.

<pathto.vmxfile>
<pathtoVPscript>

vprobeReset

DisablesallVProbesonthevirtualmachine.

<pathto.vmxfile>

vprobeListProbes

ListsactiveVProbesonthevirtualmachine.

<pathto.vmxfile>

vprobeListGlobals

ListsVProbesglobalvariablesonthevirtualmachine.

<pathto.vmxfile>

Examples of Using vmrun

ThefollowingcommandlineexamplesworkonWorkstation(-Tws),VMwareFusion(-Tfusion),or
VMwareESX/ESXihosts(-Tesx).
Youcanderivetheguestoperatingsystemtypeinexamplesbydistinguishing/forLinuxand\forWindows.

Reboot Commands
RebootavirtualmachinerunningonWorkstationforLinux:
vmrun -T ws reset /path/to/vm/RHEL4/RHEL4.vmx soft

RebootavirtualmachinerunningonWorkstationforWindows:
cd "C:\Documents and Settings\<user>\My Documents\My Virtual Machines"
vmrun -T ws reset "WindowsXP\WindowsXP.vmx" soft

RebootavirtualmachinerunningonVMwareFusion:
vmrun -T fusion reset ~/Documents/VirtualMachines.localized/WindowsXP.vmwarevm/WindowsXP.vmx soft

RebootavirtualmachinerunningonanESX/ESXihost:
vmrun -T esx -h 10.0.1.8 -u root reset "[datastore1] WinXP/WinXP.vmx" soft
Host password: <pass>

Power Commands
PoweronavirtualmachinewithWorkstationonaWindowshost:
vmrun start "C:\Documents and Settings\<user>\My Documents\My Virtual Machines\WinXP\WinXP.vmx"

ThiserrormessagefollowingthiscommandindicatesthattheVIXpackageyouinstalleddoesnotsupport
VMwareServer:
vmrun -T server start "My Virtual Machines\WinXP\WinXP.vmx"
Error: The specified service provider was not found

PoweroffavirtualmachinewithWorkstationonaWindowshost:
vmrun stop "C:\Documents and Settings\<user>\My Documents\My Virtual Machines\WinXP\WinXP.vmx"

OntheremoteESX/ESXihostwithIPaddress10.0.1.8,poweronavirtualmachine:
VMware, Inc.

15

Using vmrun to Control Virtual Machines

vmrun -T esx -h 10.0.1.8 -u root -p <pass> start "[datastore1] WinXP/WinXP.vmx"

IfHTTPSserviceisnotconfiguredonport443,specifytheappropriateportafterthecolon:
vmrun -T esx -h 10.0.1.9:8333 -u root -p <pass> start "[datastore1] WinXP/WinXP.vmx"

OntheremoteESX/ESXihostwithIPaddress10.0.1.8,poweroffthevirtualmachine:
vmrun -T esx -h 10.0.1.8 -u root -p <pass> start "[datastore1] WinXP/WinXP.vmx"

ForvCenterServerinstalledonWindowsServer,the-uuserisusuallyAdministrator,notroot.
vmrun -T vc -h 10.0.1.8 -u Administrator -p <pass> start "[datastore1] WinXP/WinXP.vmx"

Snapshot Commands
CreateasnapshotofavirtualmachinewithWorkstationonaLinuxhostorVMwareFusion:
vmrun -T ws snapshot /path/to/vm/Ubuntu/Ubuntu.vmx mySnapshot

Listsnapshotsonthevirtualmachine,showingtheonemadeinthepreviouscommand:
vmrun -T ws listSnapshots /path/to/vm/Ubuntu/Ubuntu.vmx
Total snapshots: 1
mySnapshot

Reverttothesnapshotyoumade,whichsuspendsthevirtualmachine,andrestarttoresumeoperation:
vmrun -T ws revertToSnapshot /path/to/vm/Ubuntu/Ubuntu.vmx mySnapshot
vmrun -T ws start /path/to/vm/Ubuntu/Ubuntu.vmx

Deletethesnapshotbyspecifyingitsname:
vmrun -T ws deleteSnapshot /path/to/vm/Ubuntu/Ubuntu.vmx mySnapshot

Running Guest Applications

MostvmrunguestoperationsrequireVMwareToolstobeinstalledontheguestoperatingsystem.
Startthecommandtool,minimized,onaWindowsguest:
vmrun -T ws -gu <user> runProgramInGuest WinXP\WinXP.vmx cmd.exe
Guest password: <pass>

StartthecommandtoolonaWindowsguestasanactivewindowonthedesktop:
vmrun -T ws -gu <user> runProgramInGuest WinXP\WinXP.vmx -activeWindow cmd.exe
Guest password: <pass>

RunabatchscriptfileonaWindowsguest,withPerlasthescriptinterpreter:
vmrun -T ws -gu <user> runScriptInGuest Win2k\Win2k.vmx C:\perl\perl.exe C:\script.pl
Guest password: <pass>

Runabatchscriptandkeeprunningafterwards.Tousecmd.exeonWindows,youmustspecifythescript
interpreterasnull:
vmrun -T ws -gu <user> -gp <pass> runScriptInGuest WindowsXP\WindowsProfessionalXP.vmx ""
"cmd.exe /k \"C:\\Program Files\\Microsoft Visual Studio\\VC\\vcvarsall.bat\" x86"

RunaBashshellscriptcalledrunitonaLinuxguest:
vmrun -T ws -gu <user> -gp <pass> runScriptInGuest Ubuntu/Ubuntu.vmx /bin/bash /home/<user>/runit

StartanXclockonaLinuxguest(thisrequiresthe-displayoptiontoappearontheconsole).
vmrun -gu <user> -gp <pass> runProgramInGuest SUSE/SUSE.vmx /usr/bin/xclock -display :0

RunthesameXclockcommand,butreturncontrolbacktotheconsoleimmediately:
vmrun -gu <user> -gp <pass> runProgramInGuest SUSE/SUSE.vmx -noWait /usr/bin/xclock -display :0

NewversionsofFirefoxsupportthe--displayflagfromX11,sotheoptionlooksabitdifferent:
vmrun -gu <user> -gp <pass> runProgramInGuest Ubuntu/Ubuntu.vmx /usr/bin/firefox --display=:0

16

VMware, Inc.

Using vmrun to Control Virtual Machines

Forcommandsthatrequireanenvironmentvariable,youcansetitfirst,orexportitformultiplecommands:
vmrun -gu <user> -gp <pass> runProgramInGuest SUSE/SUSE.vmx "DISPLAY=:0 /usr/bin/salesgui"
vmrun -gu <user> -gp <pass> runProgramInGuest SUSE/SUSE.vmx "export REL=7; /opt/cmd1; /opt/cmd2"

SettingtheguestenvironmentwithguestEnvrequiresrootpermissiononLinux,becausethechangeaffects
subsequentcommandsissuedbyotherusers:
vmrun -T ws -gu root -gp <rootpass> writeVariable SUSE/SUSE.vmx guestEnv SRC tmp.example.com:1666

ListprocessesinaLinuxguest,andendtheprocessnumbered8192:
vmrun -T ws -gu <user> -gp <pass> listProcessesInGuest Ubuntu/Ubuntu.vmx
vmrun -T ws -gu <user> -gp <pass> killProcessInGuest Ubuntu/Ubuntu.vmx 8192

RunaPerlscriptonaLinuxguesttoremoveDOSstylecarriagereturnsfromafile:
vmrun -T ws -gu <user> -gp <pass> runProgramInGuest Ubuntu/Ubuntu.vmx /usr/bin/perl -e
"open(FILE, '>/tmp/unix.txt'); while (<>) { s/\r\n/\n/ ; print FILE}" /tmp/dos.txt

RunaPerlscriptonaWindowsguesttoinsertDOSstylecarriagereturnsinafile:
vmrun -T ws -gu <user> -gp <pass> runProgramInGuest WinXP\WinXP.vmx C:\cygwin\bin\perl.exe -e
"open(FILE, >C:\dos.txt); while (<>) { s/\n/\r\n/ ; print FILE}" C:\unix.txt

RunaprograminaLinuxvirtualmachineonanESX/ESXihost:
vmrun -T esx -h 10.0.1.8 -u root -p <pass> -gu <user> -gp <userpass> runProgramInGuest
"[datastore1] RHEL4/RHEL4.vmx" /usr/X11R6/bin/xclock -display :0

Guest to Host File Operations

Tocopyafilefromthehosttoaguest,theusermusthavewritepermissiononthedestination:
vmrun -gu <user> -gp <pass> copyFileFromHostToGuest Ubuntu\Ubuntu.vmx C:\Temp\img.db /tmp/img.db

Tocopyafilefromaguesttothehost,theusermusthavereadpermissiononthesourcefile:
vmrun -gu <user> -gp <pass> copyFileFromGuestToHost Ubuntu\Ubuntu.vmx /home/<user>/addr addr.txt

Beforesharingfolders,youmustenablethemwiththeenabledSharedFolderscommand,orbyselecting
VM>Settings>Options>SharedFolders>Enabledintheuserinterface.OnLinuxguests,the/mnt/hgfs
directoryisavailableforsharing,butyoucanuseadifferentdirectoryforsharedfolders.
ToshareafolderonaWindowshostwithaparticularLinuxguest:
vmrun -T ws addSharedFolder Ubuntu\Ubuntu.vmx <sharedFolderName> C:\Share

Sharedfoldersarewritablebydefault.Tomakeasharedfolderreadonlyortodeletethesharedfolder:
vmrun -T ws setSharedFolderState Ubuntu\Ubuntu.vmx <sharedFolderName> C:\Share readonly
vmrun -T ws removeSharedFolder Ubuntu\Ubuntu.vmx <sharedFolderName>

NOTEOnWindows7andVista,onlytheAdministratoraccountcanusecopyFileFromHostToGuestand
deleteFileInGuesttowriteanddeletefilesinC:\andsystemfolders,orusecreateDirectoryInGuest
anddeleteDirectoryInGuesttomodifysystemdirectories.Regularusers,eventhosewithadministrator
privilege,cannotperformtheseoperations.

Guest Variables and Environment

Fromthehost,setaguestvariableontwovirtualmachines:
vmrun writeVariable WindowsXP/WindowsXP.vmx guestVar vmstartdate 21April2011
vmrun writeVariable Ubuntu10/Ubuntu10.vmx guestVar vmstartdate 21April2011

Ontheguestoperatingsystems,readtheguestvariablethatyoujustset:
> vmware-rpctool.exe "info-get vmstartdate"
$ vmware-rpctool "info-get vmstartdate"

Fromthehost,setaguestenvironmentvariableonaLinuxvirtualmachines,andverifybywritingthe
environmentvariablesintoatemporaryfile:
VMware, Inc.

17

Using vmrun to Control Virtual Machines

vmrun
Guest
Guest
vmrun
Guest
Guest

writeVariable Ubuntu10/Ubuntu10.vmx guestEnv LD_LIBRARY_PATH /usr/local/lib

user: root
password:
runScriptInGuest Ubuntu10/Ubuntu10.vmx /bin/bash "usr/bin/env > /tmp/env.out"
user: root
password:

NooutputcomestothehostfromrunScriptInGuest,solookat/tmp/env.outontheguest.
OnaLinuxguest,determinetheIPaddressandsetitinaguestvariable:
$ ipaddr=ifconfig eth0 | grep inet.addr
$ vmware-rpctool "info-set guestinfo.ip $ipaddr"

Fromthehost,retrievetheIPaddressthatwasjustsetontheguest:
vmrun readVariable Ubuntu10/Ubuntu10.vmx guestVar guestinfo.ip

Maintenance Commands
ListrunningvirtualmachinesonWorkstation:
vmrun -T ws list
Total running VMs: 2
C:\Documents and Settings\user\My Documents\My Virtual Machines\Ubuntu\Ubuntu.vmx
C:\Documents and Settings\user\My Documents\My Virtual Machines\Windows7\Windows7.vmx

PreparetoinstallVMwareToolsonVMwareFusion:
vmrun -T fusion installTools RedHatEnt5/RedHatEnt5.vmx

RegisteranewvirtualmachineinstalledonanESX/ESXihost:
vmrun -T esx -h 10.0.1.5 -u root -p <pass> register "[datastore1] RHEL5/RHEL5.vmx"

UnregisteranoldvirtualmachinegoingoutofserviceonanESX/ESXihost:
vmrun -T esx -h 10.0.1.5 -u root -p <pass> unregister "[datastore1] RHEL3/RHEL3.vmx"

OnvCenterServer,thevmrunutilitysupportsthesameformofpathtoVMXspecificationasESX/ESXihosts.
vmrun -T vc -h 10.0.1.9 -u Administrator -p <pw> register "[datastore1] RHEL5/RHEL5.vmx"

YoucannotreachavirtualmachinefilethroughitsresourcepoolorvApp.

18

VMware, Inc.

Index

readVariable 14
removeSharedFolder 14
renameFileInGuest 13
runProgramInGuest 12
runScriptInGuest 12
setSharedFolderState 14
user name and password 9
writeVariable 14

addSharedFolder command 13, 17

C
captureScreen command 14
clone command 15
command-line flags 9
copyFileFromGuestToHost command 13, 17
copyFileFromHostToGuest command 13, 17
createDirectoryInGuest command 13
createTempFileInGuest command 13

I
installTools command 14, 18

deleteDirectoryInGuest command 13
deleteFileInGuest command 13
deleteSnapshot command 12, 16
deleteVM command 14
dialog boxes, disabling 11
directoryExistsInGuest command 13
disableSharedFolders command 13

killProcessInGuest command 12, 17

Linux setup 8
list command 14, 18
listDirectoryInGuest command 13
listProcessesInGuest command 12, 17
listRegisteredVM command 14
listSnapshots command 11, 16

enableSharedFolders 13
ESX/ESXi hosts, flags for 10

F
fileExistsInGuest command 12
flags on command line 9
Fusion, flags for 9

G
guest operations 7
addSharedFolder 13
captureScreen 14
copyFileFromGuestToHost 13
copyFileFromHostToGuest 13
createDirectoryInGuest 13
createTempFileInGuest 13
deleteDirectoryInGuest 13
deleteFileInGuest 13
directoryExistsInGuest 13
disableSharedFolders 13
enableSharedFolders 13
fileExistsInGuest 12
killProcessInGuest 12
listDirectoryInGuest 13
listProcessesInGuest 12
VMware, Inc.

Mac OS setup 9
maintenance commands 8
clone 15
deleteVM 14
installTools 14
list 14
listRegisteredVM 14
register 14
unregister 14
upgradevm 14

P
path to VMX file 10
pause command 11
power commands 7
pause 11
reset 11
start 11
stop 11
suspend 11
unpause 11

19

Using vmrun to Control Virtual Machines

R
record and replay commands 8
register command 14, 18
removeSharedFolder command 14, 17
renameFileInGuest command 13
reset command 11, 15
revertToSnapshot command 12, 16
runProgramInGuest command 12, 16
runScriptInGuest command 12, 16

S
Server, flags for 10
setSharedFolderState command 14, 17
setup on Linux 8
setup on Mac OS 9
setup on Windows 9
snapshot command 11, 16
snapshot commands 7
deleteSnapshot 12
listSnapshots 11
revertToSnapshot 12
snapshot 11
start command 11, 15
stop command 11, 15
suspend command 11

U
unpause command 11
unregister command 14, 18
upgradevm command 14

V
vCenter Server, flags for 10
vmrun utility 7
VMware Fusion, flags for 9
VMware Server, flags for 10
VMware vSphere, flags for 10
VMware Workstation, flags for 9
VMX file, specifying 10
VProbes commands 8
vprobeListGlobals 15
vprobeListProbes 15
vprobeLoad 15
vprobeLoadFile 15
vprobeReset 15
vprobeVersion 15

W
Windows setup 9
Workstation, flags for 9
writeVariable command 14, 17

20

VMware, Inc.