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

2 VMware, Inc.
Contents

AboutThisBook 5

UsingvmruntoControlVirtualMachines 7
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. 3
Using vmrun to Control Virtual Machines

4 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. 5
Using vmrun to Control Virtual Machines

6 VMware, Inc.
 l

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. 7
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.

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

8 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

2 (Optional)Mostusersfinditconvenienttoaddthevmruninstalllocation,eitherVMwareWorkstationor
VMwareVIX,tothesystempath.OnWindows7:

(rightclick)Computer>(click)Properties>AdvancedSystemSettings>EnvironmentVariables>
(inlistof)SystemVariables>(select)Path>(click)Edit

Withtherightarrowkey,movetheinsertionpointtotheendofline,addasemicolon,addthefullpath
ofthefolderwherevmrunislocated,andclickOKthreetimes.

3 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"

2 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. 9
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 <hostName or IPaddr>
-P <portNumber>
-u <adminLogin on ESX/ESXi or VC>
-p <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 Startsavirtualmachine(.vmxfile)orteam(.vmtmfile). <pathto.vmxor.vmtmfile>

(Teamssupportedonlyon Thedefaultguioptionstartsthemachineinteractively, [ gui | nogui ]
Workstation.) whichisrequiredtodisplayaVMwareuserinterface.
Thenoguioptionsuppressestheuserinterface,
includingthestartupdialogbox,toallownoninteractive
scripting.
stop Stopsavirtualmachine(.vmxfile)orteam(.vmtmfile). <pathto.vmxor.vmtmfile>
(Teamssupportedonlyon Usethesoftoptiontopowerofftheguestafterrunning [ hard | soft ]
Workstation.) shutdownscripts.Usethehardoptiontopoweroffthe
guestwithoutrunningscripts,asifyoupressedthe
powerbutton.ThedefaultistousethepowerTypevalue
specifiedinthe.vmxfile,ifpresent.

reset Resetsavirtualmachine(.vmxfile)orteam(.vmtmfile). <pathto.vmxor.vmtmfile>

(Teamssupportedonlyon Usethesoftoptiontorunshutdownscriptsbefore [ hard | soft ]
Workstation.) rebootingtheguest.Usethehardoptiontorebootthe
guestwithoutrunningscripts,asifyoupressedthereset
button.ThedefaultistousethepowerTypevalue
specifiedinthe.vmxfile,ifpresent.

suspend Suspendsavirtualmachine(.vmxfile)orteam(.vmtm) <pathto.vmxor.vmtmfile>

(Teamssupportedonlyon withoutshuttingdown,solocalworkcanresumelater.
Workstation.)
[ hard | soft ]
Thesoftoptionsuspendstheguestafterrunning
systemscripts.OnWindowsguests,thesescriptsrelease
theIPaddress.OnLinuxguests,thescriptssuspend
networking.Thehardoptionsuspendstheguest
withoutrunningthescripts.Thedefaultistousethe
powerTypevaluespecifiedinthe.vmxfile,ifpresent.
Toresumevirtualmachineoperationaftersuspend,use
thestartcommand.OnWindows,theIPaddressis
retrieved.OnLinux,networkingisrestarted.

pause Pausesavirtualmachine(.vmxfile).Youcanusethisto <pathto.vmxfile>

(Pausesupportedonlyon suspendvirtualmachineoperation.
Workstation.)

unpause Resumesoperationofavirtualmachine(.vmxfile)from <pathto.vmxfile>

(Unpausesupportedonlyon whereyoupausednormaloperation.
Workstation.)

Snapshot Commands

listSnapshots Listsallsnapshotsinavirtualmachine(.vmxfile). <pathto.vmxfile>

Theshowtreeoptiondisplayssnapshotsintreeformat, [ showtree ]
withchildrenindentedundertheirparent.

snapshot Createsasnapshotofavirtualmachine(.vmxfile).For <pathto.vmxfile>

(VMwareServerdoesnot productsthatsupportmultiplesnapshots,youmust <snapshotname>
supportmultiplesnapshots. providethesnapshotname.
VMwareFusiondoesnot Becausetheforwardslashdefinespathnames,donot
supportsnapshottrees.) usetheslashcharacterinasnapshotname,becausethat
makesitdifficulttospecifythesnapshotpathlater.

VMware, Inc. 11
Using vmrun to Control Virtual Machines
Table 2. vmrun Commands and Parameters (Continued)
Command
deleteSnapshot
(VMwareServeralways
deletestherootsnapshot.)
revertToSnapshot
(VMwareServeralways
revertstotherootsnapshot.) timeofthesnapshot,vmrunrevertsittosuspendedstate,
Guest Operating System Commands
runProgramInGuest
runScriptInGuest
listProcessesInGuest
killProcessInGuest
fileExistsInGuest
12
Description Parameters
Removesasnapshotfromavirtualmachine(.vmxfile). <pathto.vmxfile>
Forproductsthatsupportmultiplesnapshots,youmust <snapshotname>
providethesnapshotname.
[ andDeleteChildren ]
Thevirtualmachinemustbepoweredofforsuspended.
Ifthesnapshothaschildren,theybecomechildrenofthe
deletedsnapshotsparent,andsubsequentsnapshots
continueasbeforefromtheendofthechain.
TheandDeleteChildrenoptiondeletesthespecified
snapshotanditschildrenrecursively.
SeerevertToSnapshotforsolutionstonameconflicts.
Setsthevirtualmachinetoitsstateatsnapshottime. <pathto.vmxfile>
Howeverifthevirtualmachinewaspoweredonatthe <snapshotname>
butdoesnotresumerunningthevirtualmachine.
or
Ifasnapshothasauniquenamewithinavirtual
machine,reverttothatsnapshotbyspecifyingthepath
tothevirtualmachinesconfigurationfileandthe <pathto.vmxfile>
uniquesnapshotname. <snap1/snap2/snapN>
Ifseveralsnapshotshavethesamename,specifythe
snapshotbyincludingafullpathnameforthesnapshot.
Apathnameisaseriesofsnapshotnames,separatedby
forwardslashcharacters(/).Eachnamespecifiesanew
snapshotinthetree.Forexample,thepathname
Snap1/Snap2identifiesasnapshotnamedSnap2that
wastakenfromthestateofasnapshotnamedSnap1.
Thetimeout(waitforVMwareTools)isfiveminutesforallguestrelatedcommands.
Runsaspecifiedprogramintheguestoperatingsystem. <pathto.vmxfile>
The-noWaitoptionreturnsapromptimmediatelyafter [ -noWait |
theprogramstartsintheguest,ratherthanwaitingforit -activeWindow |
tofinish.Thisoptionisusefulforinteractiveprograms. -interactive ]
The-activeWindowoptionensuresthattheWindows <programname>
GUIisvisible,notminimized.IthasnoeffectonLinux. [<programarguments>]
The-interactiveoptionforcesinteractiveguestlogin.
ItisusefulforVistaandWindows7gueststomakethe
programvisibleintheconsolewindow.
Youmustprovidethefullpathnameofaprogram
accessibletotheguest.Alsoprovidefullaccessible
pathnamesforanyfilesspecifiedintheprogram
arguments,accordingtorequirementsoftheprogram.
VMwareToolsandavalidguestloginarerequired.
Runsthespecifiedcommandscriptintheguest <pathto.vmxfile>
operatingsystem. [ -noWait |
SeerunProgramInGuestforanexplanationofoptions. -activeWindow |
Theinterpreterpathisthecommandthatrunsthescript. -interactive ]
Providethecompletetextofthescript,notafilename. <interpreterpath>
VMwareToolsandavalidguestloginarerequired. <scripttext>
Listsallprocessesrunningintheguestoperating <pathto.vmxfile>
system.VMwareToolsandavalidguestloginare
required.
Stopsaspecifiedprocessintheguestoperatingsystem. <pathto.vmxfile>
VMwareToolsandavalidguestloginarerequired. <processID>
TheprocessIDcanbeanynumberlistedafterpid=in
theoutputoflistProcessesInGuest.
Checkswhetherthespecifiedfileexistsintheguest <pathto.vmxfile>
operatingsystem.VMwareToolsandavalidguestlogin <pathtofileonguest>
arerequired.
VMware, Inc.
 Using vmrun to Control Virtual Machines

Table 2. vmrun Commands and Parameters (Continued)

Command Description Parameters

renameFileInGuest Renamesormovesafileintheguestoperatingsystem. <pathto.vmxfile>

VMwareToolsandavalidguestloginarerequired. <originalfilename>
Specifythesourcename(original)beforethedestination <newfilename>
(new).

deleteFileInGuest Deletesthegivefilefromtheguestoperatingsystem. <pathto.vmxfile>

VMwareToolsandavalidguestloginarerequired. <pathtofileonguest>
ForVistaandWindows7restrictionsonthiscommand,
seenoteinGuesttoHostFileOperationsonpage 17.

directoryExistsInGuest Checkswhetherthespecifieddirectoryexistsinthe <pathto.vmxfile>

guestoperatingsystem.VMwareToolsandavalidguest <directorypathonguest>
loginarerequired.

createDirectoryInGuest Createsthespecifieddirectoryintheguestoperating <pathto.vmxfile>

system.VMwareToolsandavalidguestloginare <directorypathonguest>
required.
ForVistaandWindows7restrictionsonthiscommand,
seenoteinGuesttoHostFileOperationsonpage 17.

listDirectoryInGuest Listscontentsofthespecifieddirectoryintheguest <pathto.vmxfile>

operatingsystem.VMwareToolsandavalidguestlogin <directorypathonguest>
arerequired.

deleteDirectoryInGuest Deletesthespecifieddirectoryfromtheguestoperating <pathto.vmxfile>

system.VMwareToolsandavalidguestloginare <directorypathonguest>
required.
ForVistaandWindows7restrictionsonthiscommand,
seenoteinGuesttoHostFileOperationsonpage 17.
copyFileFromHostToGuest Copiesafilefromthehosttotheguestoperatingsystem. <pathto.vmxfile>
VMwareToolsandavalidguestloginarerequired. <filepathonhost>
Specifythesourcefile(host)beforethedestinationfile <filepathinguest>
(guest).
ForVistaandWindows7restrictionsonthiscommand,
seenoteinGuesttoHostFileOperationsonpage 17.

copyFileFromGuestToHost Copiesafilefromtheguestoperatingsystemtothehost. <pathto.vmxfile>

VMwareToolsandavalidguestloginarerequired. <filepathinguest>
Specifythesourcefile(guest)beforethedestinationfile <filepathonhost>
(host).

createTempfileInGuest Createsatemporaryfileintheguestoperatingsystem, <pathto.vmxfile>

andreturnsthepathnameofthetemporaryfilecreated.
Pathnamevariesaccordingtotheoperatingsystem.You
canrundeleteFileInGuesttoremovethefile.
VMwareToolsandavalidguestloginarerequired.

enableSharedFolders Allowstheguestvirtualmachine,specifiedby.vmxfile, <pathto.vmxfile>

(VMwarevSphereand tosharefolderswithitshost.Afterenabling,run [runtime]
VMwareServerdonot addSharedFoldertospecifyeachhostfoldertoshare.
supportsharedfolders.) Theoptionalruntimeargumentmeanstosharefolders
onlyuntilthevirtualmachineispoweredoff.Otherwise,
thesettingpersistsatnextpoweron.

disableSharedFolders Stopstheguestvirtualmachine,specifiedby.vmxfile, <pathto.vmxfile>

(VMwarevSphereand fromsharingfolderswithitshost. [runtime]
VMwareServerdonot Theoptionalruntimeargumentmeanstostopsharing
supportsharedfolders.) foldersonlyuntilthevirtualmachineispoweredoff.
Otherwise,thesettingpersistsatnextpoweron.

addSharedFolder Addsafoldertobesharedbetweenthehostandguest. <pathto.vmxfile>

(VMwarevSphereand Thesharenameisamountpointintheguestfilesystem. <sharename>
VMwareServerdonot Thepathtofolderistheexporteddirectoryonthehost.
<pathtofolderonhost>
supportsharedfolders.) OnWindowsguests,theremightbeadelaybefore
sharedfoldersarevisibletotheInGuestcommands.

VMware, Inc. 13
Using vmrun to Control Virtual Machines

Table 2. vmrun Commands and Parameters (Continued)

Command Description Parameters

removeSharedFolder Removestheguestvirtualmachinesaccesstoashared <pathto.vmxfile>

(VMwarevSphereand folderonthehost.Thesharenameisamountpointin <sharename>
VMwareServerdonot theguestfilesystem.
supportsharedfolders.)

setSharedFolderState Modifiesthewritabilitystateofaspecifiedfoldershared <pathto.vmxfile>

(VMwarevSphereand betweenthehostandaguestvirtualmachine(.vmxfile). <sharename>
VMwareServerdonot Thesharenameisamountpointintheguestfilesystem. <pathtofolderonhost>
supportsharedfolders.) Thepathtofolderistheexporteddirectoryonthehost.
writable |readonly
Asharedfoldercanbemadewritableorreadonly.

captureScreen Capturesthescreenofthevirtualmachinetoalocalfile. <pathto.vmxfile>

ThespecifiedoutputfileonthehostisinPNGformat. <outputpathonhost>
Avalidguestloginisrequired.

writeVariable Writesavariabletothevirtualmachinestateorguest. <pathto.vmxfile>

Youcanseteitheranonpersistentguestvariable [ guestVar |
(guestVar),aruntimeconfigurationparameteras runtimeConfig |
storedinthe.vmxfile,oranenvironmentvariable guestEnv ]
(guestEnv)intheguestoperatingsystem.Aguest
<variablename>
variableisaruntimeonlyvaluethatprovidesasimple
<variablevalue>
waytopassruntimevaluesinandoutoftheguest.
EnvironmentvariablesrequireVMwareToolsandvalid
guestlogin.WithLinux,settingtheguestenvironment
alsorequiresrootlogin.
Providethevariablenameanditsvalue.

readVariable Readsavariablefromthevirtualmachinestateorguest. <pathto.vmxfile>

Youcangetaguestvariable,aruntimeconfigurationas [ guestVar |
storedinthe.vmxfile,orenvironmentvariablesinthe runtimeConfig |
guestoperatingsystem.ReadingtheguestEnvrequires guestEnv ]
avalidguestlogin.
<variablename>
Seeaboveforadescriptionofvariabletypes.

Maintenance Commands

list Listsallrunningvirtualmachines. None

upgradevm Upgradesavirtualmachinetothecurrentversionof <pathto.vmxfile>
virtualhardware.Hasnoeffectifthevirtualhardware
versionisthemostrecentsupported.
installTools PreparestoinstallVMwareToolsintheguestoperating <pathto.vmxfile>
system.InWindowsguestswithautorunenabled,the
VMwareToolsinstallerstartsbyitself.InLinuxguests
withoutautorun,thiscommandconnectsthevirtual
CDROMdrivetotheVMwareToolsISOimagesuitable
fortheguest,buttheinstallerdoesnotstart.Youmust
completetheinstallationwithadditionalmanualsteps,
asdescribedintheproductdocumentation.

register Registersthespecifiedvirtualmachine,addingittothe <pathto.vmxfile>

(Registrationnotsupported hostsinventory.Pathformatdependsontheproduct.
onWorkstationoron ForESX/ESXihosts,"[datastore1] vm/vm.vmx"
VMwareFusion.) (startingwiththedatastore)istypical.

unregister Unregistersthespecifiedvirtualmachine,removingit <pathto.vmxfile>

(Registrationnotsupported fromthehostsinventory.Pathformatdependsonthe
onWorkstationoron product.ForESX/ESXi,"[datastore1] vm/vm.vmx"
VMwareFusion.) (startingwiththedatastore)istypical.

listRegisteredVM Listsallregisteredvirtualmachines. None

deleteVM Removesthespecifiedvirtualmachine. <pathto.vmxfile>

14 VMware, Inc.
 Using vmrun to Control Virtual Machines

Table 2. vmrun Commands and Parameters (Continued)

Command Description Parameters

clone Createsacopyofthevirtualmachineandguest.Provide <pathto.vmxfile>

(Cloningnotsupportedon boththesourceandthedestination.vmxfilepathname. <destination.vmxfilepath>
VMwareServeroron Youcancreateeitherafullcloneoralinkedclone.To
full |linked
VMwareFusion.) createtheclonefromasnapshot,ratherthanfromthe
currentvirtualmachinestate,specifyasnapshotname. [<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 writeVariable Ubuntu10/Ubuntu10.vmx guestEnv LD_LIBRARY_PATH /usr/local/lib

Guest user: root
Guest password:
vmrun runScriptInGuest Ubuntu10/Ubuntu10.vmx /bin/bash "usr/bin/env > /tmp/env.out"
Guest user: root
Guest 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

A readVariable 14
addSharedFolder command 13, 17 removeSharedFolder 14
renameFileInGuest 13
C runProgramInGuest 12
captureScreen command 14 runScriptInGuest 12
clone command 15 setSharedFolderState 14
command-line flags 9 user name and password 9
copyFileFromGuestToHost command 13, 17 writeVariable 14
copyFileFromHostToGuest command 13, 17
createDirectoryInGuest command 13 I
createTempFileInGuest command 13 installTools command 14, 18

D K
deleteDirectoryInGuest command 13 killProcessInGuest command 12, 17
deleteFileInGuest command 13
deleteSnapshot command 12, 16
L
deleteVM command 14 Linux setup 8
dialog boxes, disabling 11 list command 14, 18
directoryExistsInGuest command 13 listDirectoryInGuest command 13
disableSharedFolders command 13 listProcessesInGuest command 12, 17
listRegisteredVM command 14
E listSnapshots command 11, 16
enableSharedFolders 13
ESX/ESXi hosts, flags for 10
M
Mac OS setup 9
F maintenance commands 8
fileExistsInGuest command 12 clone 15
flags on command line 9 deleteVM 14
Fusion, flags for 9 installTools 14
list 14
G listRegisteredVM 14
guest operations 7 register 14
addSharedFolder 13 unregister 14
captureScreen 14 upgradevm 14
copyFileFromGuestToHost 13
copyFileFromHostToGuest 13 P
createDirectoryInGuest 13 path to VMX file 10
createTempFileInGuest 13 pause command 11
deleteDirectoryInGuest 13 power commands 7
deleteFileInGuest 13 pause 11
directoryExistsInGuest 13 reset 11
disableSharedFolders 13 start 11
enableSharedFolders 13 stop 11
fileExistsInGuest 12 suspend 11
killProcessInGuest 12 unpause 11
listDirectoryInGuest 13
listProcessesInGuest 12

VMware, Inc. 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.