Technical Note

Transporting VIX Guest Operations to the vSphere API

vSphere 5
Thisdocumentdescribeshowtoperformguestoperations,thatis,interactionwiththeguestoperatingsystem runninginavirtualmachine,usingthevSphereAPIinsteadoftheVIXAPI.

New in vSphere 5
VIXhasalwaysbeenparticularlystrongintheAPIsitprovidesforguestoperations.ThevSphereAPIdidnot offeranyequivalentfunctionalityuntilthe5.0release,whichaddsthefollowingguestoperations:

GuestAuthManageracquirecredentials,releasecredentials,validatecredentials. GuestFileManagerchangefileattributes,createtemporarydirectoryorfile,deletedirectoryorfile, initiatefiletransferfromguestorfiletransfertoguest,listfiles,makedirectory,movedirectoryorfile. GuestProcessManagerlistprocesses,readenvironmentvariable,start(run)program,terminateprocess.

YoucanprogramtheVIXAPIinC/C++,Perl,orCOM(VisualBasicorC#). ThevSphereAPIguestoperationsinrelease5.0canbeusedwithanylanguagethathandlesVMwareWSDL. JavasourcecodesamplesbasedonJAXWSareavailableinthevSphereWebServicesSDK.Guestscriptingis possiblewiththevSphereSDKforPerl.TheVMwarePowerCLIincludessomeguestoperations,listedunder PowerCLIforPowerShellonpage 8.

About Guest Operations

ThesectionsbelowdefineguestoperationsforVIXdeveloperswhoarenotcertainwhichAPIstheyinclude. Guestoperationsmanipulateprocesses,files,folders,andenvironmentvariablesinaguestoperatingsystem.

Virtual Machine and Datacenter Operations

Virtualmachineoperationsaffectvirtualhardwarestate,includingpoweron,poweroff,suspend,resume, takesnapshot,andreverttosnapshot.TheVIXAPIhasthese,butsodidthevSphereAPI. Datacentermanagementoperationsperformcloudscaleconfigurationofcomputeandstorageresources,and includecrosshostoperationssuchasvMotionandFaultTolerance(FT).TheVIXAPIneverhadthese.

Easy Interfaces for Guest Operations

AfteryouinstalltheVIXpackageonaWindowsorLinuxclient,manyVIXguestoperationsareavailablefrom thevmruncommandlineutility.Thevmrunutilityisconvenientforuseinshellscriptsandbatchfiles,works withESXihostsandvCenter,andisadditionallyavailablewithFusionforMacOS. VMwareLabsoffersanunsupportedVIXbasedVMwareguestconsole(VGC)tomanagefilesandprocesses inaguestoperatingsystem.Itisavailablefordownloadatthehttp://labs.vmware.com/flings/vgcWebsite.
VMware, Inc. 1

Transporting VIX Guest Operations to the vSphere API

Usefulness of Guest Operations

Inadatacenter,guestcustomizationscriptscansimplifymanagementtasksforWindowsandLinuxsystems. Figure 1showshowascriptcanuseexecutable,batch,orshellscripttomodifytheguestandreturnalogfile. Figure 1. Guest Customization

(5) 1 2 3 4 5 Poweron. Copyfilestoguest,includingscripts,installers,anddata. Runprogramsintheguest,andproducealog. Copythelogfilebacktotheclientenvironment. RepeatasneededonothervirtualmachinesacrossallESXihostsinadatacenter.

Components for Guest Operations

VIXguestoperationsrelyonthefollowingcomponents:

VIXclientlibraryloadedintoyourprogram(thevSphereAPIreplacesthis) VMXprocessesonthehosttomanagetheruntimestateofeachvirtualmachinehostedbyESXi VMwareToolsrunningineachguestoperatingsystem

Thefollowingfivesections(untilWebServicesReplacetheVIXClientonpage 4)describetheVIXclient.

Authentication by Host and Guest with VIX

VIXclientprogramsauthenticateonthehostusingVixHost_Connect,whichtakesasparametersausername andpasswordfortheESXhostorvCenterServer.TheusermusthaveappropriatevSpherecredentials. InvSphere4.1,aprivilegenamedAcquireguestcontrolticketwasestablished.Toperformguestoperations, anauthenticatedvSphereusermusthavethisroleassigned.Otherwiserequeststorunguestoperationsthrow theerrorVIX_E_HOST_USER_PERMISSIONS. Guestoperationsrequirefurtherauthentication,forinstanceusingVixVM_LoginInGuesttospecifyusername andpasswordfortheguestOS.Inthefuture,certificatebasedorSSOtokenauthenticationmayberequired. Theguestagent(here,partofVMwareTools)impersonatesauserusingtheusersspecifiedguestcredentials, andrunswithpermissionsofthatuser.Thisisunlikealoginshell,becausenosessionisestablishedwiththe guestagent.AfteryoucallVixVM_LoginInGuest,credentialsarestoredintheclientprogram,andsentaspart ofeveryrequest.Theguestagentvalidatesthesecredentialsbeforeprocessingeachguestoperationsrequest. TheVMwareToolsguestagentexecutesauthenticatedguestoperationswithvmtools.exeonWindowsor thevmtoolsdprocessonLinux. IfVixVM_LoginInGuestoptionVIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENTisspecified, guestoperationsareredirectedtoadifferentprocessrunningintheinteractiveconsolesession.Youmustuse thisoptiontorunaprogramintheguestthatcreatesawindowthatisvisibleintheguestconsolesession,or toaccesscertainresourcesinWindowsguests.
VMware, Inc. 2

Transporting VIX Guest Operations to the vSphere API

Disabling Guest Operations with VIX

Guestoperationscanbedisabledpervirtualmachine,orhostwide.Onavirtualmachine,setthefollowing attributeintheVMXconfigurationfile.Forahost,setthisattributeinthehostwideconfigurationfile. HoweverbewarnedthatthisdisablescertainvSpherefeaturesthatdependuponguestoperations,suchasthe vCenterUpdateManager(VUM),andvCenterguestfilesystemquiescingforsnapshotbasedbackup.
guest.commands.enabled = "FALSE"

GuestoperationscanbedisabledperuserbyremovingtheusersAcquireguestcontrolticketprivilege.

VIX Guest Operations on Workstation

ThecontrolpathforWorkstationissimple:theVIXclientprogramrunslocally,ontheWorkstationhost. Figure 2. Control Path on Workstation and Player

1 2 3 4

VIXclientprogramcallsafunctionintheVIXlibrary. VIXsendsacommandoverlocalIPCtoWorkstation. WorkstationrelaysthecommandtoVMwareToolsintheguest. VMwareToolshastheGuestOSexecutetheguestoperation.

VIX Guest Operations with an ESXi Host

Figure 3illustratesthecontrolpathwhenaVIXclientprogramisusedwithanESXihost.UnlikeWorkstation, whereVIXclientcoderunsdirectlyontheWorkstationhost,VIXclientcoderunsremotelyonanESXihost. Figure 3. Control Path on ESXi

1 2

VIXclientprogramcallsafunctionintheVIXlibrary. VIXsendsacommandoveraTCPconnection(onport902)tothevirtualmachinesVMXprocess. Bycontrast,virtualmachineanddatacenteroperationsarehandledbythehostagentprocess,hostd.

3 4
VMware, Inc.

VMXrelaystheguestoperationcommandtoVMwareToolsintheguest. VMwareToolshastheGuestOSexecutetheguestoperation.
3

Transporting VIX Guest Operations to the vSphere API

VIX Guest Operations with vCenter Server

Figure 4illustratesthecontrolpathwhenaVIXclientprogramisdirectedthroughvCenterServer.Notethat VIXguestoperationsdonotfollowthesamedatapathasvirtualmachineanddatacenteroperations. Figure 4. Control Path with vCenter Server

1 2

VIXclientprogramcallsafunctionintheVIXlibrary. VIXsendsacommandoveraTCPconnection(onport902)tothevirtualmachinesVMXprocess. TheTCPconnectionforVIXguestoperationsgoesdirectlytoVMXontheESXihost,bypassingthe vCenterServer,andthehostagentprocess.Bycontrast,virtualmachineanddatacenteroperationsare proxiedbyvCenterServerusingSOAP/httpsonport443,andrelayedtothehostagent.

3 4

VMXrelaysthecommandtoVMwareToolsintheguest. VMwareToolshastheGuestOSexecutetheguestoperation.

Web Services Replace the VIX Client

ForVIXguestoperationsinWorkstation,onESXihosts,orthroughvCenter,yourunprogramsonaVIXclient usingthewrapperlibrary,astublibrarythatdynamicallyloadsasuitableVIXimplementationfortheclient. OnWindows,thewrapperlibraryisimplementedasVixAllProducts.lib,astaticlibrary.OnLinux,the wrapperlibraryisimplementedaslibVixAllProducts.so,adynamic(sharedobject)library. Figure 5showsvSphereguestoperations.UsingJavaorC#methodsforexample,yourclientapplicationcalls aclientproxyinterfacethatprovideslanguagespecificWSDLbindings(stubs).Theclientproxyencapsulates yourmethodinvocationinaSOAPlayer.RespondingonanHTTPSport,vSphereexecutesthemethod,often asynchronously.TheWSDLbindingsandclientproxyinterfacecanbeidenticalonWindowsandLinux. Figure 5. SOAP communications with WSDL, a different model
WSDL2Java, wsdl.exe, or other tool
stubs

WSDL files

client application client proxy interface (Java, C#, or other) vSphere Server SOAP-encoded WSDL network connection method execution

method invocation

VMware, Inc.

Transporting VIX Guest Operations to the vSphere API

New Guest Operations for the vSphere API

Previously,writingapplicationsoftwaretorunonVMwareplatformproductswascomplicatedbyhavingto usethevSphereAPIforcertainoperations,andtheVIXAPIforotheroperations.Thiscomplicationhasbeen eliminatedinvSphere5byfoldingVIXguestoperationsintothevSphereAPI. Figure 6. Old and New API Designs

Benefits of the New API Set

Thebenefitsarethatyoucanusethesamelanguagebindings,aunifiedobjectmodel,andsinglesignonto thehost.SecurityisenhancedbecauseofbetterintegrationwiththevSphereuserandrolepermissionsmodel. MonitoringisimprovedbyalignmentwiththeeventsandauditingfeaturesofvSphere.Thenewmodelmakes itpossibletofollowguestsaftervMotionoftheirvirtualmachines. Mostimportantly,networkconnectivityissimplifiedbyhavingeverythinggooverhttpsasaWebservice, ratherthanrequiringdatacenterstoopenTCPport902forVIXcommunications.InFigure 7,comparethe formerVIXcontrolpath(Figure 4)tothenewvSpherecontrolpaththroughvCenterServer.Guestoperations nowfollowthesamecontrolpathasvirtualmachineanddatacenteroperations. Figure 7. Simplified Control Path with vSphere 5

1 2 3 4 5

AvSphereWebservicesclientprogramcallsafunctioninthevSphereAPI. TheclientsendsaSOAPcommandoverhttps(port443)tovCenterServer. ThevCenterServerpassesthecommandtothehostagentprocesshostd,whichsendsittoVMX. VMXrelaysthecommandtoVMwareToolsintheguest. VMwareToolshastheGuestOSexecutetheguestoperation.

Comparison of Guest Operations

Table 1,GuestOperationsinVIXandvSphere,onpage 6comparesmethodsofthenewvSphereAPIwith vmrunandtheVIXAPIfunctioncallsforC/C++.TheVIXAPIcallsforPerlandCOMhavesimilarnamesbut withouttheVixandVixVMpreface,respectively.Authorizationmethodsarenotthesame.VIXprogramscall loginonce,runguestoperations,thenlogout.InvSphere,thecredentialsaresentwitheveryrequest.

VMware, Inc.

Transporting VIX Guest Operations to the vSphere API

Inthethirdcolumn,itemsendinginManageraremanagedobjectsthathavethemethodslistedunderthem. Table 1. Guest Operations in VIX and vSphere

VIX API for C/C++ VixHost_RegisterVM Connections VixHost_Connect(somewhatequivalent) VixVM_LoginInGuest VixHost_Disconnect VixHost_OpenVMsupersedesVixVM_Open File Operations VixVM_CreateTempFileInGuest VixVM_DeleteDirectoryInGuest VixVM_DeleteFileInGuest VixVM_CopyFileFromGuestToHost VixVM_CopyFileFromHostToGuest VixVM_ListDirectoryInGuest VixVM_CreateDirectoryInGuest (usefilerename) VixVM_RenameFileInGuest VixVM_DirectoryExistsInGuest VixVM_FileExistsInGuest VixVM_WaitForToolsInGuest VixVM_InstallTools Processes and Variables VixVM_ListProcessesInGuest VixVM_ReadVariable VixVM_RunProgramInGuest VixVM_KillProcessInGuest VixVM_RunScriptInGuest Shared Folder Operations listProcessesInGuest readVariableguestEnv runProgramInGuest killProcessInGuest runScriptInGuest *SharedFolder* deleteDirectoryInGuest deleteFileInGuest copyFileFromGuestToHost copyFileFromHostToGuest listDirectoryInGuest createDirectoryInGuest (usefilerename) renameFileInGuest directoryExistsInGuest fileExistsInGuest installTools hhost uuserppassword endofscript path/to/vm.vmx GuestFileManager ChangeFileAttributesInGuest CreateTemporaryDirectoryInGuest CreateTemporaryFileInGuest DeleteDirectoryInGuest DeleteFileInGuest InitiateFileTransferFromGuest InitiateFileTransferToGuest ListFilesInGuest MakeDirectoryInGuest MoveDirectoryInGuest MoveFileInGuest vix.vm.GuestInfo.guestOperationsReady ...interactiveGuestOperationsReady GuestProcessManager ListProcessesInGuest ReadEnvironmentVariableInGuest StartProgramInGuest TerminateProcessInGuest (useStartProgramInGuest) notsupportedonvSphere vmrun Command register vSphere API Inventory GuestAuthManager AcquireCredentialsInGuest ValidateCredentialsInGuest ReleaseCredentialsInGuest

Notes on New vSphere APIs

ChangeFileAttributesInGuestandCreateTemporaryDirectoryInGuestarenewAPIswithnoVIXequivalents. AcquireCredentialsInGuestisthemethodtogetasessionsecurityticket.Currentlytheonlyavailableticketis fromtheSecuritySupportProviderInterface(SSPI).SSPIperformsachallengeresponseauthenticationofthe credentials.Ifvalid,thevirtualmachinesguestoperationscomponentissuesasessionticket,typesspiToken indataobjectSSPIAuthentication.Clientsauthenticatewiththeticketuntilitexpires.SSPIisusefulforwhen theclientenvironmentandguestoperatingsystemarebothWindowsinstancesjoinedtothesamedomain,so SSPIcanpassaWindowsdomainloginsessiontokenfromtheclienttotheguestagentwithoutrequiringan explicitusernameandpassword.

VMware, Inc.

Transporting VIX Guest Operations to the vSphere API

ValidateCredentialsInGuestchecksforvalidcredentials.Youpassitamanagedobjectreferencetotheguests virtualmachine,andtheGuestAuthenticationdataobjectwithsspiToken,orusernameandpassword.You passthesameauth(authorization)credentialineveryvSphereguestoperationmethod.

Object Class Diagram

Figure 8showstheobjectsthatinheritfromGuestOperationsManager. Figure 8. Guest Operations Class Design

InthevSphereAPI,theVirtualMachineandGuestInfomanagedobjectscontaininformationaboutwhatguest operationsmightberunningandrelevantvirtualmachinestate:
vim.VirtualMachine.guest() vim.vm.GuestInfo.guestOperationsReady vim.vm.GuestInfo.interactiveGuestOperationsReady

VMwareToolsmuststillbepresenttorunguestoperations,asbefore.Toperforminteractiveguestoperations, theusermustbeloggedintotheconsole,forexamplethroughthevSphereClient. OtherguestinterfacesincludetheGuestSDKforguestmonitoringandtheHAApplicationMonitoringSDK.

Permissions for vSphere Guest Operations

VIXstoresguestauthorizationstateforyou,sothetypicalusageisforaprogramtoLoginInGuest,runsome guestoperations,thenLogoutFromGuest. WiththevSphereguestoperationsAPIs,nostateisstoredontheclientside,soauthorizationinformationmust beincludedaspartofeveryguestoperationsmethodcall.VMwareToolsdonotcacheguestcredentials,so evenafterVixVM_LoginInGuest,authorizationinformationgoeswitheachrequest,buttheVIXclientlibrary storesyourcredentialsbetweenrequests.HoweverbecausevSpherecommunicatesbyWSDL,guestoperation methodscannotcacheyourcredentials,sotheauthorizationAPImustbestateless. AguestcredentialisencapsulatedbytheabstractclassGuestAuthentication,andtheclientpassesanobjectof thistypewitheachguestoperationcall.Toauthenticatewiththeguestusingausernameandpassword,you instantiateanobjectoftypeNamePasswordAuthentication(childclassofGuestAuthentication)andsetthe usernameandpasswordfieldsappropriately.Theothercurrentlysupportedtypeofguestauthenticationis SSPIpassthrough,fromaWindowsclienttoaWindowsguestinstance.Fordetailsonhowtoimplementthis, seethevSphereAPIReferencefortheGuestAuthManagersacquireCredentialsInGuestmethod. ThevSphereguestoperationsrequirethreeadditionalvCenterprivilegesthataffectauthentication,whichare documentedinthevSphereAPIReferenceasbeingrequiredbythevmparameter,amanagedobjectreferenceto thevirtualmachineonwhichaguestoperationisperformed.

VirtualMachine.GuestOperations.Queryrequiredforauthorizationonavirtualmachine. VirtualMachine.GuestOperations.Modifyrequiredforfilemanagementonavirtualmachine. VirtualMachine.GuestOperations.Executerequiredforprocessexecutiononavirtualmachine.

VMware, Inc.

Transporting VIX Guest Operations to the vSphere API

PermissionsforvSphereguestoperationsfollowtheread/write/executemodel.EachAPIrequiresadifferent privilegetofititsfunction:forexamplequeryforlistFiles,modifyfordeleteFile,executeforterminateProcess. AsstatedinAuthenticationbyHostandGuestwithVIXonpage 2,VIXrequiredtheAcquireguestcontrol ticketprivilege.ThisisalsorequiredforvSphereguestoperations.

VirtualMachine.Interact.GuestControlsameasAcquireguestcontrolticketintheUI.

Licensing
ApaidESXiorvSpherelicense(notfreevSphereHypervisor)isrequiredtousetheVIXAPIorvSphereAPI. NoadditionallicenseisrequiredtousetheseAPIs.

PowerCLI for PowerShell

GuestoperationsinPowerCLI5.0usethenewvSphereAPIs.Thischangedoesnotaffectscriptcompatibility. PowerCLIstillpackagesVIXlibrariesforbackwardcompatibility.PowerCLIguestoperationsinclude:

CopyVMGuestFilesamefunctionalityascopyFileFromGuestToHostandcopyFileFromHostToGuest. GetVMGuestprovidesinformationaboutthetypeofguestoperatingsystem. InvokeVMScriptsamefunctionalityasrunScriptInGuestorrunProgramInGuest. MountToolsandUpdateToolssamefunctionalityasinstallToolsInGuest.

Perl Script for Guest Operations

TheSourceForgevghettoprojectcontainstheguestOpsManagement.plPerlscript,whichimplementsthe majorityofvSphereguestoperationsformanagementbyacentralizedscript.Itrequiresaclientsystemwith vCLI5.0installed,orthevMA5.0virtualappliance,andESXi5.0mustberunningvirtualmachineswiththe latestVMwareToolsinstalled.Hereisanintroductiontothescriptandthe12guestoperationsitsupports: http://www.virtuallyghetto.com/2011/07/automatingnewintegratedvixguest.html TheguestOpsManagement.plscriptiswrittenandownedbyathirdparty.ItisnotsupportedbyVMware. HoweveryoucanlookatthePerlcodetogetanideahowtoworkwiththevSphereAPI.

Java Source Code Samples

FourJavacodesamplesbasedonJAXWSareavailableinthevSphereSDKforWebservices,inthisdirectory: SDK/vsphere-ws/java/JAXWS/samples/com/vmware/guest

CreateTemporaryFile.java
Thissamplecreatesatemporaryfileinsideavirtualmachine,bycallingthefollowingmethod:
vimPort.createTemporaryFileInGuest(fileManagerRef, vmMOR, auth, prefix, suffix, directoryPath);

DownloadGuestFile.java
Thissampledownloadsafilefromtheguesttoaspecifiedpathonthehostwheretheclientisrunning.
vimPort.initiateFileTransferFromGuest(fileManagerRef, vmMOR, auth, guestFilePath);

Thedestination,alocalfileontheclienthost,isspecifiedonthecommandlineas--localfilepath.

RunProgram.java
Thissamplerunsaspecifiedprograminsideaguestoperatingsystem,withoutputredirectedtoatemporary file,anddownloadstheresultingoutputtoafileonthelocalclient.
vimPort.startProgramInGuest(processManagerRef, vmMOR, auth, spec);

Theprogrammustalreadyexistontheguest,andisspecifiedonthecommandlineas--guestprogrampath. Theoutputfiletostoreontheclienthostisspecifiedonthecommandlineas--localoutputfilepath.

VMware, Inc.

Transporting VIX Guest Operations to the vSphere API

UploadGuestFile.java
Thissampleuploadsafilefromtheclientmachinetoaspecifiedlocationinsidetheguest.
vimPort.initiateFileTransferToGuest(fileManagerRef, vmMOR, auth, guestFilePath, guestFileAttributes, fileSize, optionsmap.containsKey("overwrite"));

Thesource,alocalfileontheclienthost,isspecifiedonthecommandlineas--localfilepath.

If you have comments about this documentation, submit your feedback to: docfeedback@vmware.com VMware, Inc. 3401 Hillview Ave., Palo Alto, CA 94304 www.vmware.com Copyright 2011 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. Item: EN-000703-00 9/7/11