Using vmrun to Control Virtual Machines

VMware vSphere 5.0 VMware Player 4.0 and Workstation 8.0 VMware Fusion 4.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-000536-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 20082011 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

5 7

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,UsingvmruntoControlVirtual Machines,documentsthevmrunutility,whichhelpsyoumanagea collectionofvirtualmachinesonaVMwarehost.

Revision History
Thisbookisrevisedwitheachreleaseoftheproductorwhennecessary.Arevisedversioncancontainminor ormajorchanges.Table 1summarizesthesignificantchangesineachversionofthisguide. Table 1. Revision History
Revision 20110421 20100719 20091020 20090909 20081231 20080815 20080724 20080623 Description FortheVIXAPI1.11and1.12releases. FortheVIXAPI1.10release,whichsupportedvSphere4.1,Workstation7.1,andFusion3.1. FortheVIXAPI1.8release,whichsupportedVMwareWorkstation7.0,Player3.0,andVMwareFusion3.0. FortheVIXAPI1.7release,whichprovidedsupportforESX/ESXihostsandVMwarevSphere4. NewinformationaboutnullinterpreterforRunScriptInGuestonWindows. MoreexamplesforVMwareServer2.0RC2andWorkstation6.5RC. Initialrelease,includingsupportforVMwareFusiononIntelbasedMacintoshOSXhosts. InitialdraftfortheVMwareServer2.0RC1andWorkstation6.5Beta2releases.

Intended Audience
Thisbookisintendedfordevelopersandsystemadministratorswhowanttocontrolguestvirtualmachines onvariousVMwareproductplatforms.SupportedplatformsincludeVMwareWorkstation,VMwarePlayer, VMwareFusion,andVMwarevSphere(ESX/ESXihostswithvCenterServer).

VMware Technical Publications Glossary

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

Document Feedback
VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Sendyourfeedbackto docfeedback@vmware.com.

Technical Support and Education Resources

Thefollowingsectionsdescribethetechnicalsupportresourcesavailabletoyou.Toaccessthecurrentversions ofotherVMwarebooks,gotohttp://www.vmware.com/support/pubs.

VMware, Inc.

Using vmrun to Control Virtual Machines

Online and Telephone Support

Touseonlinesupporttosubmittechnicalsupportrequests,viewyourproductandcontractinformation,and registeryourproducts,gotohttp://www.vmware.com/support.

Support Offerings
TofindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds,goto http://www.vmware.com/support/services.

VMware Professional Services

VMwareEducationServicescoursesofferextensivehandsonlabs,casestudyexamples,andcoursematerials designedtobeusedasonthejobreferencetools.Coursesareavailableonsite,intheclassroom,andlive online.Foronsitepilotprograms andimplementationbestpractices,VMwareConsultingServicesprovides offeringsto helpyouassess,plan,build,andmanageyourvirtualenvironment.Toaccessinformationabout educationclasses,certificationprograms,andconsultingservices,gotohttp://www.vmware.com/services.

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

Guest Operating System Commands

Youcanusethevmrunutilitytointeractwithaguestoperatingsysteminthefollowingways:

Runanexecutableprogramintheguestoperatingsystem,orrunaninterpretedscriptthatyouprovide.

VMware, Inc.

Using vmrun to Control Virtual Machines

Checkifafileordirectoryexistsintheguest,deleteafileordirectory,renameafile,listfiles,orcreatea newdirectory. Copyafilefromthehosttotheguest,orfromtheguesttothehost. Addasharedfolderfromthehost,makeasharedfolderwritableintheguest,orremoveasharedfolder. Captureascreenimagefromtheguest(WorkstationandVMwareFusiononly). Listtheprocessesrunningintheguestoperatingsystem,orendaprocess(withpermission). Readorwriteavariableintheguestoperatingsystemsenvironmentorvirtualmachinestate.

Thetimeout(waitforVMwareTools)isfiveminutesforallguestrelatedcommands.

Maintenance Commands
Thiscategoryincludescommandstolistallrunningvirtualmachines,upgradethevirtualmachinehardware version,andinstallVMwareToolsintheguestoperatingsystem. Additionally,exceptonVMwareServer,youcancloneavirtualmachineimagetoanothervirtualmachine. OnVMwarevSphereandVMwareServer,youcanregisterandunregistervirtualmachines.

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

Limitations
VMwareFusiondoesnotsupportsnapshottrees. VMwarePlayerdoesnotsupportpauseandunpause,snapshotoperations,virtualmachinecloning,orvirtual hardwareupgrade. VMwareServerdoesnotsupportteams,sharedfolders,cloning,ormultiplesnapshots.Whenyoutrytocreate asecondsnapshot,theUIasksyoutooverwriteyourexistingsnapshot. TherecordandreplaycommandsweredeprecatedinWorkstation7.1andremovedfromthisrelease.

Setting Up vmrun
Theprocedureforsettingupvmrunvariesbasedontheoperatingsystemoftheclientcomputer.

How to Get vmrun

ThevmrunutilityinstallswithWorkstationandVMwareFusion. Forusewithremoteproductplatforms,youcanobtainvmrunbyinstallingtheVIXstandalonelibraries, availablefreeofchargeontheVMwaredownloadsite.

Linux Setup
To use the vmrun utility on Linux 1 2 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 Thevmrunutilityisinstalledinoneofthesefoldersbydefault: 32bitsystemsC:\Program Files\VMware\VMware VIX 64bitsystemsC:\Program Files (x86)\VMware\VMware VIX 2 IfVMwareWorkstationisalreadyinyoursystemPath,thisstepisunnecessarybecauseacopyofvmrun isinstalledthere.Ifnot,addtheVIXfolderlocationtoyoursystempath.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,addtheVMwareFusiondirectorytoyoursystempath.
export PATH="$PATH:/Library/Application Support/VMware Fusion"

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

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

VMwareServerdatastore
[storage1] 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

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 Power Commands start (Teamssupportedonlyon Workstation.) Startsavirtualmachine(.vmxfile)orteam(.vmtmfile). Thedefaultguioptionstartsthemachineinteractively, whichisrequiredtodisplayaVMwareuserinterface. Thenoguioptionsuppressestheuserinterface, includingthestartupdialogbox,toallownoninteractive scripting. Stopsavirtualmachine(.vmxfile)orteam(.vmtmfile). Usethesoftoptiontopowerofftheguestafterrunning shutdownscripts.Usethehardoptiontopoweroffthe guestwithoutrunningscripts,asifyoupressedthe powerbutton.ThedefaultistousethepowerTypevalue specifiedinthe.vmxfile,ifpresent. Resetsavirtualmachine(.vmxfile)orteam(.vmtmfile). Usethesoftoptiontorunshutdownscriptsbefore rebootingtheguest.Usethehardoptiontorebootthe guestwithoutrunningscripts,asifyoupressedthereset button.ThedefaultistousethepowerTypevalue specifiedinthe.vmxfile,ifpresent. Suspendsavirtualmachine(.vmxfile)orteam(.vmtm) withoutshuttingdown,solocalworkcanresumelater. Thesoftoptionsuspendstheguestafterrunning systemscripts.OnWindowsguests,thesescriptsrelease theIPaddress.OnLinuxguests,thescriptssuspend networking.Thehardoptionsuspendstheguest withoutrunningthescripts.Thedefaultistousethe powerTypevaluespecifiedinthe.vmxfile,ifpresent. Toresumevirtualmachineoperationaftersuspend,use thestartcommand.OnWindows,theIPaddressis retrieved.OnLinux,networkingisrestarted. pause (Pausesupportedonlyon Workstation.) unpause (Unpausesupportedonlyon Workstation.) Snapshot Commands listSnapshots Listsallsnapshotsinavirtualmachine(.vmxfile). Theshowtreeoptiondisplayssnapshotsintreeformat, withchildrenindentedundertheirparent. snapshot (VMwareServerdoesnot supportmultiplesnapshots. VMwareFusiondoesnot supportsnapshottrees.) Createsasnapshotofavirtualmachine(.vmxfile).For productsthatsupportmultiplesnapshots,youmust providethesnapshotname. Becausetheforwardslashdefinespathnames,donot usetheslashcharacterinasnapshotname,becausethat makesitdifficulttospecifythesnapshotpathlater.
11

Description

Parameters

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

stop (Teamssupportedonlyon Workstation.)

<pathto.vmxor.vmtmfile> [ hard | soft ]

reset (Teamssupportedonlyon Workstation.)

<pathto.vmxor.vmtmfile> [ hard | soft ]

suspend (Teamssupportedonlyon Workstation.)

<pathto.vmxor.vmtmfile> [ hard | soft ]

Pausesavirtualmachine(.vmxfile).Youcanusethis eithertopausereplayortopausenormaloperation. Resumesoperationofavirtualmachine(.vmxfile)from whereyoupausedreplayornormaloperation.

<pathto.vmxfile>

<pathto.vmxfile>

<pathto.vmxfile> [ showtree ] <pathto.vmxfile> <snapshotname>

VMware, Inc.

Using vmrun to Control Virtual Machines

Table 2. vmrun Commands and Parameters (Continued)

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

killProcessInGuest

<pathto.vmxfile> <processID>

12

VMware, Inc.

Using vmrun to Control Virtual Machines

Table 2. vmrun Commands and Parameters (Continued)

Command renameFileInGuest Description Renamesormovesafileintheguestoperatingsystem. VMwareToolsandavalidguestloginarerequired. Specifythesourcename(original)beforethedestination (new). deleteFileInGuest Deletesthegivefilefromtheguestoperatingsystem. VMwareToolsandavalidguestloginarerequired. ForVistaandWindows7restrictionsonthiscommand, seenoteinGuesttoHostFileOperationsonpage 17. directoryExistsInGuest Checkswhetherthespecifieddirectoryexistsinthe guestoperatingsystem.VMwareToolsandavalidguest loginarerequired. Createsthespecifieddirectoryintheguestoperating system.VMwareToolsandavalidguestloginare required. ForVistaandWindows7restrictionsonthiscommand, seenoteinGuesttoHostFileOperationsonpage 17. listDirectoryInGuest Listscontentsofthespecifieddirectoryintheguest operatingsystem.VMwareToolsandavalidguestlogin arerequired. Deletesthespecifieddirectoryfromtheguestoperating system.VMwareToolsandavalidguestloginare required. ForVistaandWindows7restrictionsonthiscommand, seenoteinGuesttoHostFileOperationsonpage 17. copyFileFromHostToGuest Copiesafilefromthehosttotheguestoperatingsystem. VMwareToolsandavalidguestloginarerequired. Specifythesourcefile(host)beforethedestinationfile (guest). ForVistaandWindows7restrictionsonthiscommand, seenoteinGuesttoHostFileOperationsonpage 17. copyFileFromGuestToHost Copiesafilefromtheguestoperatingsystemtothehost. VMwareToolsandavalidguestloginarerequired. Specifythesourcefile(guest)beforethedestinationfile (host). enableSharedFolders (VMwarevSphereand VMwareServerdonot supportsharedfolders.) Allowstheguestvirtualmachine,specifiedby.vmxfile, tosharefolderswithitshost.Afterenabling,run addSharedFoldertospecifyeachhostfoldertoshare. Theoptionalruntimeargumentmeanstosharefolders onlyuntilthevirtualmachineispoweredoff.Otherwise, thesettingpersistsatnextpoweron. Stopstheguestvirtualmachine,specifiedby.vmxfile, fromsharingfolderswithitshost. Theoptionalruntimeargumentmeanstostopsharing foldersonlyuntilthevirtualmachineispoweredoff. Otherwise,thesettingpersistsatnextpoweron. Addsafoldertobesharedbetweenthehostandguest. Thesharenameisamountpointintheguestfilesystem. Thepathtofolderistheexporteddirectoryonthehost. OnWindowsguests,theremightbeadelaybefore sharedfoldersarevisibletotheInGuestcommands. Removestheguestvirtualmachinesaccesstoashared folderonthehost.Thesharenameisamountpointin theguestfilesystem. <pathto.vmxfile> <sharename> <pathtofolderonhost> <pathto.vmxfile> [runtime] <pathto.vmxfile> <filepathinguest> <filepathonhost> <pathto.vmxfile> [runtime] <pathto.vmxfile> <filepathonhost> <filepathinguest> <pathto.vmxfile> <directorypathonguest> <pathto.vmxfile> <directorypathonguest> <pathto.vmxfile> <directorypathonguest> <pathto.vmxfile> <directorypathonguest> Parameters <pathto.vmxfile> <originalfilename> <newfilename> <pathto.vmxfile> <pathtofileonguest>

createDirectoryInGuest

deleteDirectoryInGuest

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

<pathto.vmxfile> <sharename>

VMware, Inc.

13

Using vmrun to Control Virtual Machines

Table 2. vmrun Commands and Parameters (Continued)

Command setSharedFolderState (VMwarevSphereand VMwareServerdonot supportsharedfolders.) captureScreen Description Modifiesthewritabilitystateofaspecifiedfoldershared betweenthehostandaguestvirtualmachine(.vmxfile). Thesharenameisamountpointintheguestfilesystem. Thepathtofolderistheexporteddirectoryonthehost. Asharedfoldercanbemadewritableorreadonly. Capturesthescreenofthevirtualmachinetoalocalfile. ThespecifiedoutputfileonthehostisinPNGformat. Avalidguestloginisrequired. writeVariable Writesavariabletothevirtualmachinestateorguest. Youcanseteitheranonpersistentguestvariable (guestVar),aruntimeconfigurationparameteras storedinthe.vmxfile,oranenvironmentvariable (guestEnv)intheguestoperatingsystem.Aguest variableisaruntimeonlyvaluethatprovidesasimple waytopassruntimevaluesinandoutoftheguest. EnvironmentvariablesrequireVMwareToolsandvalid guestlogin.WithLinux,settingtheguestenvironment alsorequiresrootlogin. Providethevariablenameanditsvalue. readVariable Readsavariablefromthevirtualmachinestateorguest. Youcangetaguestvariable,aruntimeconfigurationas storedinthe.vmxfile,orenvironmentvariablesinthe guestoperatingsystem.ReadingtheguestEnvrequires avalidguestlogin. Seeaboveforadescriptionofvariabletypes. Maintenance Commands list upgradevm Listsallrunningvirtualmachines. Upgradesavirtualmachinetothecurrentversionof virtualhardware.Hasnoeffectifthevirtualhardware versionisthemostrecentsupported. PreparestoinstallVMwareToolsintheguestoperating system.InWindowsguestswithautorunenabled,the VMwareToolsinstallerstartsbyitself.InLinuxguests withoutautorun,thiscommandconnectsthevirtual CDROMdrivetotheVMwareToolsISOimagesuitable fortheguest,buttheinstallerdoesnotstart.Youmust completetheinstallationwithadditionalmanualsteps, asdescribedintheproductdocumentation. Registersthespecifiedvirtualmachine,addingittothe hostsinventory.Pathformatdependsontheproduct. ForESX/ESXihosts,"[datastore1] vm/vm.vmx" (startingwiththedatastore)istypical. Unregistersthespecifiedvirtualmachine,removingit fromthehostsinventory.Pathformatdependsonthe product.ForESX/ESXi,"[datastore1] vm/vm.vmx" (startingwiththedatastore)istypical. Listsallregisteredvirtualmachines. Removesthespecifiedvirtualmachine. Createsacopyofthevirtualmachineandguest.Provide boththesourceandthedestination.vmxfilepathname. Youcancreateeitherafullcloneoralinkedclone.To createtheclonefromasnapshot,ratherthanfromthe currentvirtualmachinestate,specifyasnapshotname. None <pathto.vmxfile> <pathto.vmxfile> [ guestVar | runtimeConfig | guestEnv ] <variablename> <pathto.vmxfile> [ guestVar | runtimeConfig | guestEnv ] <variablename> <variablevalue> Parameters <pathto.vmxfile> <sharename> <pathtofolderonhost> writable |readonly <pathto.vmxfile> <outputpathonhost>

installTools

<pathto.vmxfile>

register (Registrationnotsupported onWorkstationoron VMwareFusion.) unregister (Registrationnotsupported onWorkstationoron VMwareFusion.) listRegisteredVM deleteVM clone (Cloningnotsupportedon VMwareServeroron VMwareFusion.) VProbes Commands

<pathto.vmxfile>

<pathto.vmxfile>

None <pathto.vmxfile> <pathto.vmxfile> <destination.vmxfilepath> full |linked [<snapshotname>]

(VProbespermittedonlyonWorkstationandVMwareFusion.)

14

VMware, Inc.

Using vmrun to Control Virtual Machines

Table 2. vmrun Commands and Parameters (Continued)

Command vprobeVersion vprobeLoad Description ShowstheVProbesversiononthevirtualmachine. LoadsaVPscriptontothevirtualmachine. LoadsaVPscriptfileontothevirtualmachine. DisablesallVProbesonthevirtualmachine. ListsactiveVProbesonthevirtualmachine. ListsVProbesglobalvariablesonthevirtualmachine. Parameters <pathto.vmxfile> <pathto.vmxfile> <textoftheVPscript> vprobeLoadFile <pathto.vmxfile> <pathtoVPscript> vprobeReset vprobeListProbes vprobeListGlobals <pathto.vmxfile> <pathto.vmxfile> <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:
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"

VMware, Inc.

15

Using vmrun to Control Virtual Machines

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

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

16

VMware, Inc.

Using vmrun to Control Virtual Machines

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

VMware, Inc.

17

Using vmrun to Control Virtual Machines

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
addSharedFolder command 13, 17

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

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

I
installTools command 14, 18

K
killProcessInGuest command 12, 17

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

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

E
enableSharedFolders 13 ESX/ESXi hosts, flags for 10

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

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 deleteDirectoryInGuest 13 deleteFileInGuest 13 directoryExistsInGuest 13 disableSharedFolders 13 enableSharedFolders 13 fileExistsInGuest 12 killProcessInGuest 12 listDirectoryInGuest 13 listProcessesInGuest 12 readVariable 14 removeSharedFolder 13
VMware, Inc.

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

R
record and replay commands 8 register command 14, 18
19

Using vmrun to Control Virtual Machines

removeSharedFolder command 13, 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

T
technical support resources 5

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, 16

20

VMware, Inc.