Using a Proxy with vSphere Virtual Serial Ports

vSphere Web Services SDK 4.1

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

Using a Proxy with vSphere Virtual Serial Ports

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 2009, 2010 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

1 RemoteSerialPortAccesswithaVirtualSerialPortProxy 7
VirtualSerialPortProxyCapabilities 8 ProxyasaVirtualSerialPortConcentrator 8 NetworkSerialPorts 9 BackingOptionsandBackingInformationforNetworkSerialPorts 9 NetworkConnectionsBetweenaVirtualMachine,aProxy,andaRemoteSystem 10 DeterminingBackingOptions 11 CreatingaVirtualMachinewithaNetworkSerialPort 11 VMwareTelnetSession 12 EstablishingaVMwareTelnetExtensionSession 13 vMotionandPersistentSerialPortConnections 13

2 VMwareTelnetExtensionCommandsforProxyCommunication 17
CommandSyntax 17 VMwareTelnetExtensionOption 18 OptionSubnegotiation 18 UnknownCommandResponse 19 ProxyOperation 20 vMotionNotification 20 VirtualMachineIdentification 22

Index 23

VMware, Inc.

Using a Proxy with vSphere Virtual Serial Ports

VMware, Inc.

About This Book

TheVMwareUsingaProxywithvSphereVirtualSerialPortsmanualprovidesinformationaboutdevelopinga virtualserialportconcentratorforuseinthevSphereenvironment.Thisguidedescribesthecapabilitiesofa proxyimplementationthatsupportstheVMwaretelenetextension.Italsoincludesinformationabout configuringavirtualserialportforaproxyconnection.

Revision History
Thisbookisrevisedwitheachreleaseoftheproductorwhennecessary.Arevisedversioncancontainminor ormajorchanges.Table 1summarizesthesignificantchangesineachversionofthisbook. Table 1. Revision History
Revision Date 13JUL2010 Description Initialrelease,supportedinVMwarevSphere4.1.

Intended Audience
ThisbookisintendedforanyonedevelopingavirtualserialportproxyforthevSphereenvironment.Proxy developersshouldhaveexperiencewiththetelnetprotocolandnetworkcommunication.

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.

Online and Telephone Support

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

VMware, Inc.

Using a Proxy with vSphere Virtual Serial Ports

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.

Remote Serial Port Access with a Virtual Serial Port Proxy

TheVMwarevSphereAPIsupportstheuseofvirtualserialportsonvirtualmachinesthatrunonESX hosts.Avirtualserialportrepresentsaserialportonavirtualmachine.Avirtualserialportcanoperateasa networkserialportbyusinganetworksocketonthehosttoprovideaccesstoremotesystems.Aremote systemisanysystemonthenetworkthatsupportsaserialportconnectionwithavirtualmachine.Thisfeature supportsremoteconsoleloginforsystemmanagementusinganoutofbandconnectionthatbypassesthe vSphereClient. Youcanalsouseavirtualserialportforcommunicationthroughasoftwarepipe,foroutputtoafile,andfor communicationthroughaphysicalserialportonthehost.ForinformationaboutthevSphereAPIsupportfor theseapplications,seethedescriptionoftheVirtualSerialPortobjectinthevSphereAPIReference. InaVMwaredatacenter,avCenterServerusesvMotiontomovevirtualmachinesacrosshostsaspartof resourcemanagement.vSpheredoesnotsupportvMotionoperationsonavirtualmachinethathasadirect networkserialportconnectionwitharemotesystem.NetworkserialportsusethehostIPaddress.IftheServer attemptstomoveavirtualmachinewithanetworkserialportconnection,thehostrejectsthevMotionrequest tomaintaintheconnection. TosupportvMotionforvirtualmachinesthatusenetworkserialports,youcandevelopaproxythatoperates betweenavirtualmachineandaremotesystem.ThevSphereAPIsupportstheuseofathirdpartyvirtual serialportconcentratorinthedatacenterenvironment.Avirtualserialportconcentratoractsasaproxyoran accessserverbetweenvirtualmachinesandremotesystems.Theproxymaintainscommunicationwithvirtual machinesthatareusingnetworkserialports.WhenavMotioneventoccurs,thevirtualmachineconnectsto theproxyfromitsnewhostsothattheconnectionwiththeremotesystempersists. Virtualmachinesusethetelnetprotocolforvirtualserialportproxyconnections.VMwaredefinesatelnet extensionthatincludescommandsforproxynotificationofvMotionevents. Thischapterprovidesthefollowinginformation:

VirtualSerialPortProxyCapabilitiesonpage 8 NetworkSerialPortsonpage 9 VMwareTelnetSessiononpage 12 vMotionandPersistentSerialPortConnectionsonpage 13

SeeChapter 2,VMwareTelnetExtensionCommandsforProxyCommunication,onpage 17forreference informationabouttheVMwaretelnetextensioncommands.

VMware, Inc.

Using a Proxy with vSphere Virtual Serial Ports

Virtual Serial Port Proxy Capabilities

AvirtualserialportproxyoperatesasanRFC2217compatibletelnetserver.Aproxyprovidesthefollowing capabilitiesinthevSphereenvironment.

Acceptstelnetconnectionsfromvirtualmachines SupportsVMwaretelnetextensioncommandsandrespondstoVMwaretelnetextensionmessagesfrom virtualmachines Forwardsnetworktrafficbetweenvirtualmachinesandremotesystems HandlesextensioncommandsfornotificationofvMotioneventsandredirectstrafficaccordingly

Proxy as a Virtual Serial Port Concentrator

Figure 11showsaproxythatoperatesasavirtualserialportconcentrator.Theconcentratorhasinternal connectionstoseveralvirtualmachinesinadatacenterandanexternalconnectiontoaremotesystem. Theconcentratorprovidesaremotesystemwithaccesstomultiplevirtualmachinesthatactasserialport servers.Thevirtualmachinesconnecttotheconcentrator,indicatingthattheywillacceptconnectionsfrom remotesystems.SeeBackingOptionsandBackingInformationforNetworkSerialPortsonpage 9formore informationaboutserialportservers.Theconcentratorpresentsthechoiceofvirtualmachinestotheremote systemandmaintainsanysubsequentconnection.InFigure 11,asolidlinerepresentsanactiveconnection betweentheremotesystemandavirtualmachine,anddashedlinesrepresentpotentialconnections. Figure 1-1. Virtual Serial Port Concentrator
vSphere datacenter ESX host virtual machine virtual serial port (server) virtual machine virtual serial port (server) ESX host virtual machine virtual serial port (server)

virtual serial port concentrator

remote system

Figure 11showstheconcentratoraspartofthevSpheredatacenter.Forthiskindofapplication,youcan deploytheconcentratorasavirtualappliance.Avirtualapplianceissoftwareonaplatformofoneormore virtualmachines(inthiscase,asinglevirtualmachine).Avirtualapplianceimplementationallowsyoutotake advantageofresourcemanagementthatvCenterServerprovides.ThevCenterserverusesvMotion technologytomigratethevirtualapplianceproxythroughthedatacenterwithoutinterruptingremoteserial portservice.ThevirtualapplianceusesvirtualmachineIPaddressesthatpersistacrossvMotionevents. AlthoughtheprimarypurposeoftheproxyistopreserveconnectionsduringvMotionevents,italsocan provideagatewayorfirewalltoenforcesecurity.Theproxyservesasthepointofauthenticationforremote systemsthatusevirtualserialportstoaccessvirtualmachines.

VMware, Inc.

Chapter 1 Remote Serial Port Access with a Virtual Serial Port Proxy

Network Serial Ports

Anetworkserialportisavirtualserialportthatusesanetworksocketonthehostcomputer.Anetworksocket istheendpointofanetworkconnectionandisrepresentedbyanIPaddressandaportnumber.ThevSphere APIusesUniformResourceIdentifiers(URI)toidentifytheprotocol,IPaddress,andportnumberfor endpointsofnetworkserialportconnections.SeeRFC3986forinformationaboutUniformResource Identifiers. Touseanetworkserialport,youmustverifythattheESXhostsupportsthefeatureandthencreateor reconfigureavirtualmachinetoconfiguretheport.Forinformationaboutwritinganapplicationthatusesthe vSphereAPI,seethevSphereWebServicesSDKProgrammingGuide.Asanalternative,youcanusethevSphere Clienttoconfigureanetworkserialport.Formoreinformation,seetheonlinehelpfortheVMwarevSphere Client.

Backing Options and Backing Information for Network Serial Ports

ThevSphereAPIusesbackingobjectstorepresentthehostdevicethatisassociatedwithavirtualdevice.The typesofbackingobjectsforvirtualdevicesareoptionobjectsandinformationobjects. Backingoptionobjectsidentifyhostdevicesupportforvirtualmachines.AnESXhostdefinesthesetofvirtual devicebackingoptionsthatareavailableforvirtualmachines.Touseanetworkserialport,theESXhostmust providethevirtualserialportURIbackingoption,whichisrepresentedbythe VirtualSerialPortURIBackingOptionobject.Forinformationabouthowtofindoutifthehostsupports theURIbackingoption,seeDeterminingBackingOptionsonpage 11. Backinginformationobjectssupplydataforvirtualdeviceconfiguration.Usea VirtualSerialPortURIBackingInfoobjecttobindavirtualserialporttoanetworksocket.Youcan configureavirtualserialporttouseURIbackingwhenyoucreateorreconfigureavirtualmachine.Fora descriptionofhowtoconfigureURIbackingforanetworkserialport,seeCreatingaVirtualMachinewitha NetworkSerialPortonpage 11. WhenyouspecifyURIbackingforthenetworkserialportconnection,youdefinethesecharacteristics.

Directiondefinestherolethatthevirtualmachineplaysinaconnectionwitharemotesystem(clientor server).Whenavirtualmachineactsasaserialportclient,itinitiatestheconnectionwiththeremote system.Whenavirtualmachineactsasaserialportserver,itlistensforconnectionsthatareinitiatedby remoteclients. ServiceURIidentifiesthetargetofconnections.Whenthevirtualmachineactsasaclient,theservice URIidentifiestheremotesystem.Whenthevirtualmachineactsasaserver,theserviceURIidentifies proxyaccesstothehostonwhichthevirtualmachineruns.SeeRFC3986forinformationaboutURI syntax. ProxyURIidentifiesthevirtualserialportproxy.ThepresenceoftheproxyURIdirectsthevirtual machinetoestablishaconnectionwiththeproxy.Thevirtualmachinealwaysinitiatestheconnectionwith theproxy. Youcanuseeithertelnetorsecuretelnet(telnets)fortheproxyconnection.TheproxyURIspecification mustuseoneofthefollowingformats.SeeRFC3986forinformationaboutURIsyntax.

telnet://<host>:<port> telnets://<host>:<port>

Whenthevirtualmachineperformstelnetnegotiationwiththeproxy,itsendsthedirectionandservice URIinformationtotheproxy.(SeethedescriptionoftheDO-PROXYcommandinProxyOperationon page 20.)

VMware, Inc.

Using a Proxy with vSphere Virtual Serial Ports

Network Connections Between a Virtual Machine, a Proxy, and a Remote System

Figure 12showstwovirtualmachines.Eachmachineusesaproxyforitsconnectiontoaremotesystem.

Onevirtualmachineactsasavirtualserialportserver.ThisvirtualmachineusestheserviceURIto identifyproxyaccesstothehostmachine.Thevirtualmachineinitiatesatelnetconnectionwiththeproxy. Theproxy,onbehalfofthevirtualmachine,listensforconnectionrequestsfromremotesystemsand forwardstherequeststothevirtualmachine. Onevirtualmachineactsasavirtualserialportclient.ThisvirtualmachineusestheserviceURIto identifytheremotesystem.Thevirtualmachineinitiatesatelnetconnectionwiththeproxy.Theproxy forwardstheconnectionrequesttotheremotesystem.

Theproxyhastwonetworksockets.Itusesonesocket(proxyURI)forthetelnetconnectionswiththevirtual machineandtheotherfortheconnectionwiththeremotesystem.Theexternalconnectionbetweentheproxy andaremotesystemusesthemutuallyagreeduponprotocol.Foraconnectioninitiatedbytheremotesystem, thepersonoperatingtheremotesystemmustobtaintheserviceURIbyemailorotherindependent communication. Figure 1-2. Virtual Serial Port Connections to a Remote System Through a Proxy
Virtual machine as virtual serial port server ESX Server virtual machine Virtual machine as virtual serial port client ESX Server virtual machine connection request virtual serial port network socket IP address: port number virtual serial port network socket IP address: port number

telnet

telnet

proxy URI virtual serial port proxy service URI

proxy URI virtual serial port proxy IP address: port number

IP address: port number

service URI

remote system

connection request

remote system

10

VMware, Inc.

Chapter 1 Remote Serial Port Access with a Virtual Serial Port Proxy

Determining Backing Options

YouusetheQueryConfigOptionmethodtodeterminethebackingoptionsthatareavailableonthehoston whichyouwillcreatethevirtualmachine.ThemethodreturnsaVirtualMachineConfigOptiondataobject. Thevirtualmachineconfigurationdataincludesaalistofvirtualdeviceoptionsandalistofbackingoptions. Thefollowingpseudocodeshowsthepathtothebackingoptions.
VirtualMachineConfigOption.hardwareOptions.VirtualDeviceOption[].backingOption[]

ThevirtualdeviceoptionarraymustincludetheVirtualSerialPortOptiondataobject.Fornetwork backing,thearrayofserialportbackingoptionsmustincludetheVirtualDeviceURIBackingOptiondata object.TheVirtualDeviceURIBackingOption.typepropertyspecifiesthenameofthebackingobjectyou shouldcreatewhenyouconfigurenetworkbacking.

Creating a Virtual Machine with a Network Serial Port

YoucanusetheCreateVM_Taskmethodtocreateavirtualmachineandconfigureanetworkserialport.The virtualmachineusesthevirtualserialportconfigurationtoconnecttoaproxyandtoacceptaconnectionfrom aremotesystem. 1 2 3 4 CreateaVirtualMachineConfigSpecobjectforthemethodsconfigparameter. CreateaVirtualDeviceConfigSpecobjectforthedeviceChangearrayinthe VirtualMachineConfigSpecobject. CreateaVirtualSerialPortobjectforthedevicepropertyintheVirtualDeviceConfigSpecobject. Tocontrolproxyconnectionbehavior,createaVirtualDeviceConnectInfodataobjectforthe VirtualSerialPort.connectableproperty. Thefollowingpseudocodeshowstheresultingpathtotheconnectioninformation.
VirtualMachineConfigSpec.deviceChange[].device.connectable

SetthestartConnectedpropertyintheconnectableobjecttoTRUE. ThestartConnectedpropertydetermineswhetherthevirtualmachinewillopenaconnectionwiththe proxywhenthevirtualmachinestarts.Whenthevirtualmachinepowerson,itcopiesthe startConnectedvaluetotheVirtualDeviceConnectInfo.connectedproperty.Whilethevirtual machineisrunning,youcanusetheReconfigVM_Taskmethodtosettheconnectedpropertytoopenor closetheproxyconnection.IfyoureconfigureaportwithconnectedsettoTRUE,thevirtualmachine closestheexistingconnectionandopensanewone.

CreateaVirtualDeviceURIBackingInfoobjectforthebackingpropertyintheVirtualSerialPort object. Thefollowingpseudocodeshowstheresultingpathtothebackinginformation.

VirtualMachineConfigSpec.deviceChange[].device.backing

Usethebackinginformationobjecttosupplythefollowinginformation:

Setthedirectionpropertytoservertodirectthevirtualmachinetoacceptremoteconnections. SettheserviceURIpropertytotheURIforthehostonwhichthevirtualmachineruns. SettheproxyURIpropertytotheURIforthevirtualserialportconcentrator.Youcannotincludea user/passwordsequenceintheproxyURI.

VMware, Inc.

11

Using a Proxy with vSphere Virtual Serial Ports

VMware Telnet Session

ToestablishaVMwaretelnetsessionforremoteserialportcommunication,avirtualmachineandaproxy participateinamessageexchangethatfollowsthemodelofastandardtelnetprotocolsequence.Theproxy handlesmessagesfromthevirtualmachineandsendstheappropriateresponses.Beforetheproxycan forwardcontent,thevirtualmachineandtheproxyparticipateinthefollowingprogression. 1 ThevirtualmachineandtheproxynegotiatetheuseoftheVMwaretelnetextensionoption. Bothsidesoftheconnectionmustagreetousetheoptionbeforecontinuingwithanyadditionalextension messageexchange. 2 ThevirtualmachineandtheproxyidentifytheVMwaretelnetsuboptioncommandsthattheysupport. TheproxymustsupporttheKNOWN-SUBOPTIONS-2andUNKNOWN-SUBOPTION-RCVD-2commands. Duringasession,theproxycansendtheUNKNOWN-SUBOPTION-RCVD-2commandasavalidresponseto virtualmachinemessages. 3 TheproxyagreestoactasaVMwaretelnetextensionproxyforremoteserialportcommunication.

Table 11liststheVMwaretelnetextensioncommandsalongwithbriefdescriptions.Commandsinthetable aregroupedbypurpose:VMwaretelnetextensionandsuboptions,proxy,vMotion,andidentification.The tableusescommandsymbols.AVMwaretelnetextensioncommandisatwoorthreebytecodeembeddedin atelnetcommandsequence.Formoreinformationaboutcommandsandthecodeequivalents,seeChapter 2, VMwareTelnetExtensionCommandsforProxyCommunication,onpage 17. Table 1-1. VMware Telnet Extension Commands
Command VMWARE-TELNET-EXT KNOWN-SUBOPTIONS-1 KNOWN-SUBOPTIONS-2 UNKNOWN-SUBOPTION-RCVD-1 UNKNOWN-SUBOPTION-RCVD-2 DO-PROXY WILL-PROXY WONT-PROXY VMOTION-BEGIN VMOTION-GOAHEAD VMOTION-NOTNOW VMOTION-PEER VMOTION-PEER-OK VMOTION-COMPLETE VMOTION-ABORT GET-VM-VC-UUID VM-VC-UUID GET-VM-NAME VM-NAME GET-VM-BIOS-UUID VM-BIOS-UUID Source virtualmachine,proxy virtualmachine proxy virtualmachine proxy virtualmachine proxy proxy virtualmachine proxy proxy virtualmachine proxy virtualmachine virtualmachine proxy virtualmachine proxy virtualmachine proxy virtualmachine Description TheVMwaretelnetextensionoptioncommand Suboptionssupportedbythevirtualmachine Suboptionssupportedbytheproxy Unknownsuboptionreceivedbythevirtual machine Unknownsuboptionreceivedbytheproxy Virtualmachinerequestforproxysupport Positiveproxyresponse Negativeproxyresponse NotificationofapendingvMotionoperationfora virtualmachine Positiveproxyresponse Negativeproxyresponse Virtualmachinerequestidentifyingthenewvirtual machineinstance Proxyresponseacceptingthenewvirtualmachine instance NotificationthatvMotionoperationiscomplete NotificationthatvMotionoperationwasaborted Proxyrequestforthevirtualcenterrepresentation ofvirtualmachineUUID Virtualmachineresponse Proxyrequestforthevirtualmachinename Virtualmachineresponse ProxyrequestforthevirtualmachineBIOSUUID Virtualmachineresponse
VMware, Inc.

12

Chapter 1 Remote Serial Port Access with a Virtual Serial Port Proxy

Table 1-1. VMware Telnet Extension Commands (Continued)

Command GET-VM-LOCATION-UUID VM-LOCATION-UUID Source proxy virtualmachine Description Proxyrequestforthevirtualmachinelocation UUID Virtualmachineresponse

Establishing a VMware Telnet Extension Session

IfyouspecifyaproxyURIinthevirtualserialportconfiguration,thevirtualmachinewillinitiateatelnet connectionwiththeproxy.Aftertheconnectionisestablished,thevirtualmachineinitiatesamessage exchangetoestablishaVMwaretelnetextensionsession.Thefollowingprogressiondescribesthemodelfor themessageexchangeandusessymbolstorepresentthecodes.Forthecodeequivalents,seethecommand descriptionsinChapter 2,VMwareTelnetExtensionCommandsforProxyCommunication,onpage 17. 1 StarttheVMwaretelnetsession.

VirtualMachineSendsamessagethatindicatesitwillsendVMwaretelnetextensioncommands totheproxy.
IAC WILL VMWARE-TELNET-EXT

ProxyResponds,indicatingthatitwillreceiveVMwaretelnetextensioncommands.
IAC DO VMWARE-TELNET-EXT

Identifyknownsuboptions.

VirtualMachineSendsamessagethatindicatesthesetofsuboptioncommandsthatitcansend andreceive.Thesuboptionsareexpressedasasequenceofcodesthatcorrespondtosuboption commands.

IAC SB VMWARE-TELNET-EXT KNOWN-SUBOPTIONS-1 suboptions IAC SE

ProxyResponds,sendingamessagethatindicatesthesetofsuboptioncommandsthatitcansend andreceive.
IAC SB VMWARE-TELNET-EXT KNOWN-SUBOPTIONS-2 suboptions IAC SE

Negotiateproxysupport.

VirtualMachineSendsarequestfortheproxytoactasaVMwaretelnetextensionproxy.Theproxy requestincludesdirectionandURIinformationfromthenetworkbackingforthevirtualserialport. (ForinformationaboutusingtheAPItospecifythisinformation,seeCreatingaVirtualMachine withaNetworkSerialPortonpage 11.)

IAC SB VMWARE-TELNET-EXT DO-PROXY direction uri IAC SE

ProxyResponds,indicatingthatitwillperformproxyoperations.
IAC SB VMWARE-TELNET-EXT WILL-PROXY IAC SE

vMotion and Persistent Serial Port Connections

AvirtualserialportproxyprovidessupportforpersistentremoteserialportconnectionswhenavCenter servermovesavirtualmachinetoadifferenthost.TosupportthepersistentconnectionduringthevMotion operation,theproxymustsupporttwotelnetconnectionsforthevirtualmachine. Aproxybuffersdatawhileitisforwardingcontentfromtheremotesystemtoavirtualmachine.Aproxymust respondtotheVMOTION-BEGINcommand,whichisnotificationofapendingvMotionoperation.ESXServer supportfortheVMwaretelnetextensionallowstheproxytopostponethevMotioneventuntilitfinishes forwardingcontent.AftersendingtheVMOTION-GOAHEADcommandinresponsetoVMOTION-BEGIN,theproxy mustbufferanyadditionaldataitreceivesfromtheremotesystem.WhenthevMotioneventiscomplete,the proxycontinuesthecontenttransmissiontothenewinstanceofthevirtualmachine.

VMware, Inc.

13

Using a Proxy with vSphere Virtual Serial Ports

Figure 13showstwoESXhostsandaproxyatthestartofavMotionoperation.HostAhasavirtualmachine thatwillbemovedtoHostB. Figure 1-3. VMOTION-BEGIN and VMOTION-GOAHEAD

HostA ESX Server virtual machine virtual serial port network socket vMotion begins HostB ESX Server

VMOTION-BEGIN VMOTION-GOAHEAD

virtual serial port proxy

VirtualMachineAtthebeginningofthevMotionoperation,theESXserver(HostA)usesthevirtual machinesserialportconnectiontosendaVMOTION-BEGINrequesttotheproxy.Toidentifythevirtual machine,thehostprovidesanopaquesequencevalueforthemessage.

IAC SB VMWARE-TELNET-EXT VMOTION-BEGIN sequence IAC SE

ProxyAftersendingpendingdata,theproxyrepliesbysendingaVMOTION-GOAHEADmessageto indicatethatthevMotionoperationcancontinue.ThemessageincludestheVMOTION-BEGINsequence valueandanopaquesecretvalue,whichtheproxyprovides.

IAC SB VMWARE-TELNET-EXT VMOTION-GOAHEAD sequence secret IAC SE

AftertheproxyreplieswithaVMOTION-GOAHEADresponse,thevMotionoperationbegins.Atthispoint,there isasingleconnectionbetweenthevirtualmachineandtheproxy. ThevCenterservercreatesasecondinstanceofthevirtualmachineonHostB.Whenthevirtualmachineboots ontheHostB,itconfiguresnetworkbackingforthevirtualserialportandestablishesasecondtelnet connectionwiththeproxy.BeforecontinuingwiththevMotionoperation,thenewvirtualmachineandthe proxyrenegotiatethetelnetCOM-PORT-OPTION.TheydonotrenegotiatetheComPortconfiguration.The proxyshouldbepreparedtosupportthesameComPortconfigurationthatwasestablishedfortheoriginal telnetconnection.SeeRFC2217forinformationaboutthetelnetcomportcontroloption.Theproxynow maintainsonetelnetconnectionforeachinstanceofthevirtualmachine. TostarttheVMwaretelnetextensionsessionforthenewconnection,thenewvirtualmachineinstance negotiatestheVMwaretelnetextensionoption(VMWARE-TELNET-EXT). Figure 14showsthesystemsduringthevMotionoperation.

VirtualMachine:TocontinuethevMotionoperation,HostBsendsaVMOTION-PEERmessagetotheproxy toidentifythenewinstanceasthesamevirtualmachinethatstartedthevMotionoperation.Themessage includesboththesequenceandsecretvaluestoidentifythevirtualmachineinstance.

IAC SB VMWARE-TELNET-EXT VMOTION-PEER sequence secret IAC SE

Proxy:TheproxyreplieswithaVMOTION-PEER-OKmessagetoindicatethatitacceptsthepeerconnection.
IAC SB VMWARE-TELNET-EXT VMOTION-PEER-OK sequence IAC SE

14

VMware, Inc.

Chapter 1 Remote Serial Port Access with a Virtual Serial Port Proxy

Figure 1-4. VMOTION-PEER and VMOTION-PEER-OK

HostA ESX Server virtual machine virtual serial port network socket vMotion in progress HostB ESX Server virtual machine virtual serial port network socket

VMOTION-PEER VMOTION-PEER-OK

virtual serial port proxy

Figure 15showsthecompletedvMotionoperation.Aftertheproxyacceptsthenewvirtualmachineinstance asapeer,theESXserveronHostBsendsaVMOTION-COMPLETEmessagetotheproxy.Themessageindicates thattheproxyshouldusethenewconnectionforalltraffictotheserialport.Now,theproxycanterminatethe originaltelnetconnectiontoHostA.

IAC SB VMWARE-TELNET-EXT VMOTION-COMPLETE sequence IAC SE

Figure 1-5. VMOTION-COMPLETE

HostA ESX Server HostB ESX Server virtual machine vMotion complete virtual serial port network socket

VMOTION-COMPLETE

virtual serial port proxy

VMware, Inc.

15

Using a Proxy with vSphere Virtual Serial Ports

16

VMware, Inc.

VMware Telnet Extension Commands for Proxy Communication

Thischapterincludesthefollowingsections:

CommandSyntaxonpage 17 VMwareTelnetExtensionOptiononpage 18 OptionSubnegotiationonpage 18 ProxyOperationonpage 20 vMotionNotificationonpage 20 VirtualMachineIdentificationonpage 22

Command Syntax
TheVMwaretelnetextensiondefinesatelnetproxyoptionforsendingnotificationofvSpherevMotionevents toavirtualserialportproxy.AVMwaretelnetextensioncommandsequenceusesthefollowinggeneral format:
IAC telnet-command VMWARE-TELNET-EXT [ext-command [parameters] IAC SE]

Where

IACisthetelnetescapecharacterprefix(InterpretasCommand).

telnet-commandisoneofthefollowingtelnetcommands:WILL,WONT,DO,DONT,andSB.
VMWARE-TELNET-EXTistheVMwaretelnetextensioncommand.

ext-commandisaVMwaretelnetextensioncommandthatindicatesoneoftheextensionsuboption commands.AsuboptioncommandsequencebeginswiththeVMWARE-TELNET-EXTcommandandis enclosedwithinIAC SB ... IAC SEtelnetsubnegotiationcommands. parametersindicatesoneormoreparametervalues.

IAC SEisthetelnetsequenceforcompletingasubnegotiationcommandsequence.

ThefollowingsectionscontaintablesofVMwaretelnetextensioncommands.Atableentryshowsthe command,thecorrespondingintegercode,adescription,andthecommandandcodesequences.Acode sequenceforaVMwaretelnetextensioncommandhasthefollowingcharacteristics.

Thecodesequencebeginswithcode255,thetelnetescapecharacterprefixIAC(InterpretasCommand). VMwaretelnetextensioncommandsusetwoorthreebytecodesequences. TheVMWARE-TELNET-EXTcommandcodeis232. Subnegotiationcommandsequencesincludebegin(SB)andend(SE)codes(250and240).

VMware, Inc.

17

Using a Proxy with vSphere Virtual Serial Ports

Forexample,theDO-PROXYcommandrequiresthefollowingcodesequencewithembeddedargumentsfor direction(Sforserver)andURI:
IAC SB VMWARE-TELNET-EXT DO-PROXY direction uri IAC SE 255 250 232 70 "S" "telnet://example.com" 255 240

VMware Telnet Extension Option

Table 21liststhecommandsthatestablishtheVMwaretelnetextensioncommunicationbetweenavirtual machineandaproxy.ThevirtualmachineinitiatestheconnectionbysendingaWILL VMWARE-TELNET-EXT message.IftheproxyacceptsbyrespondingwithaDO VMWARE-TELNET-EXTmessage,thevirtualmachineand theproxycancontinuenegotiation. Table 2-1. VMware Telnet Extension Command Negotiation
Command WILL VMWARE-TELNET-EXT AvirtualmachinerequestindicatingthatitiswillingtosendVMwaretelnetextensionmessagestothe proxy. IAC WILL VMWARE-TELNET-EXT 255251232 WONT VMWARE-TELNET-EXT AvirtualmachinenotificationthatitisunwillingtosendVMwaretelnetextensionmessagestothe proxy.Thevirtualmachinecanusethiscommandtoturnofftheextensionoption.Toresumemessage exchange,thevirtualmachineandproxymustnegotiatetoturnontheoptionagain(WILL VMWARE-TELNET-EXTandDO VMWARE-TELNET-EXT). IAC WONT VMWARE-TELNET-EXT 255252232 DO VMWARE-TELNET-EXT AproxyresponsethatindicatesitiswillingtoreceiveVMwaretelnetextensionmessagesfromthe virtualmachine. IAC DO VMWARE-TELNET-EXT 255253232 DONT VMWARE-TELNET-EXT AproxyresponsethatindicatesitisunwillingtoreceiveVMwaretelnetextensionmessages.Theproxy cansendthismessageatanytimetostopremoteserialportcommunication.Toresumemessage exchange,thevirtualmachineandproxymustnegotiatetoturnontheoptionagain(WILL VMWARE-TELNET-EXTandDO VMWARE-TELNET-EXT). IAC DONT VMWARE-TELNET-EXT 255254232 254232 253232 252232 Codes 251232

Option Subnegotiation
TheVMWARE-TELNET-EXTtelnetoptionrequiresvarioussuboptionstosupportremoteserialportaccess.The virtualmachineandproxyusesubnegotiationtoindicatethecommandsetsthattheycansupport. Subnegotiationidentifiesallcommandsfornegotiationaswellascommandsforproxysupport,vMotion notification,andvirtualmachineidentification.Table 22liststhecommandsforoptionsubnegotiation.

18

VMware, Inc.

Chapter 2 VMware Telnet Extension Commands for Proxy Communication

Table 2-2. Option Subnegotiation

Command KNOWN-SUBOPTIONS-1 suboptions AvirtualmachinenotificationthatindicatestheVMWARE-TELNET-EXTsuboptionsthatitcangenerateand accept.suboptionsisasequenceofoneormorecodes,eachofwhichcorrespondstoaVMwaretelnet extensioncommand. Ifthevirtualmachinesendsthismessagemorethanonceduringasession,thelistofsuboptionsisalways thesame.Thepresenceofacommandinthelistdoesnotimplythatthevirtualmachinewillusethe commandduringthesession. IAC SB VMWARE-TELNET-EXT KNOWN-SUBOPTIONS-1 suboptions IAC SE 2552502320suboptions255240 KNOWN-SUBOPTIONS-2 suboptions AproxyresponsethatindicatestheVMWARE-TELNET-EXTsuboptionsthatitcangenerateandaccept. suboptionsisasequenceofoneormorecodes,eachofwhichcorrespondstoaVMwaretelnetextension command.Theproxymustsupportthiscommand. Iftheproxysendsthismessagemorethanonceduringasession,thelistofsuboptionsmustbethesame eachtime. IAC SB VMWARE-TELNET-EXT KNOWN-SUBOPTIONS-2 suboptions IAC SE 2552502321suboptions255240 1 Code 0

Unknown Command Response

Table 23liststhecommandstoindicatereceptionofanunknowncommand.Theproxymustsend UNKNOWN-SUBOPTION-RCVD-2anytimeitreceivesacommandthatitdoesnotsupport. Table 2-3. Unknown Suboptions
Command UNKNOWN-SUBOPTION-RCVD-1 code Avirtualmachineresponsetoindicatethatitreceivedanunknownsuboptioncommandfromtheproxy. codeidentifiestheunknownsuboption. IAC SB VMWARE-TELNET-EXT UNKNOWN-SUBOPTION-RCVD-1 code IAC SE 2552502322code255240 UNKNOWN-SUBOPTION-RCVD-2 code Aproxyresponsetoindicatethatitreceivedanunknownsuboptioncommandfromthevirtualmachine.code identifiestheunknownsuboption.Theproxymustsupportthiscommand. IAC SB VMWARE-TELNET-EXT UNKNOWN-SUBOPTION-RCVD-2 code IAC SE 2552502323code255240 3 Code 2

VMware, Inc.

19

Using a Proxy with vSphere Virtual Serial Ports

Proxy Operation
Table 24liststheextensioncommandstonegotiateproxysupport. Table 2-4. VMware Telnet Extension Command Negotiation
Command DO-PROXY direction serviceUri Avirtualmachinerequestfortheproxytodoforwardingoperationsovertheconnection.Thevirtual machinesendsaDO-PROXYrequestbeforeanycontentisexchangedbetweenthevirtualmachineandthe remotesystem. Code 70

directionandserviceURIcorrespondtotheVirtualSerialPortURIBackingInfopropertiesinthe
virtualserialportconfiguration.(SeethevSphereAPIReferenceforinformationaboutthe VirtualSerialPortURIBackingInfodataobject.)

directioniseitherC(client)orS(server).Ifthedirectionindicatesthatthevirtualmachineisacting asaclient,serviceUriidentifiesaremotesystemandtheproxyinitiatesaconnectionwiththeremote system.Ifthedirectionindicatesthatthevirtualmachineisactingasaserver,serviceUriidentifiesthe

networksocketonthehostonwhichthevirtualmachineruns.Inthiscase,thevirtualmachinewillaccept aconnectioninitiatedbyaremotesystem(usingtheproxy). Ifpossible,theproxyshouldalsohandleportcontroloptions,asspecifiedby RFC2217. IAC SB VMWARE-TELNET-EXT DO-PROXY direction uri IAC SE 25525023270directionuri255240 WILL-PROXY Aproxyresponsetoindicatethatitwilldoforwardingoperations. IAC SB VMWARE-TELNET-EXT WILL-PROXY IAC SE 25525023271255240 WONT-PROXY Aproxyresponsetoindicatethatitwillnotdoforwardingoperations. IAC SB VMWARE-TELNET-EXT WONT-PROXY IAC SE 25525023273255240 73 71

vMotion Notification
Table 25liststhecommandsthathostsandproxyuseduringavMotionoperation.Inthefollowing descriptions,thesourcehostcontainstheoriginalvirtualmachineinstance,andthetargethostisthehoston whichthenewinstanceiscreated.Ahostusesthevirtualmachineserialportconnectionwiththeproxyto sendvMotionmessages.

20

VMware, Inc.

Chapter 2 VMware Telnet Extension Commands for Proxy Communication

Table 2-5. vMotion Communication

Command VMOTION-BEGIN sequence AsourcehostrequesttoindicatethatavMotionoperationispending.Theoperationrequiresa VMOTIONGOAHEADresponsetostart.Theintentistoflushallpendingdatatransmissiononthe connection. Thehostprovidesanopaquesequencevalue.AllsubsequentvMotionmessagesrelatedtotheconnection betweenthevirtualmachineandthisproxyusethissequencevalue. IAC SB VMWARE-TELNET-EXT VMOTION-BEGIN sequence IAC SE 25525023240sequence255240 VMOTION-GOAHEAD sequence secret Aproxyresponsetoindicatethatallqueueddatahasbeentransmitted,andthatthevMotionoperation canstart.TheproxysendsthismessageonlyinresponsetoaVMOTION-BEGINrequest. TheproxyreturnsthesequencevaluethatitreceivedintheVMOTION-BEGINrequest.Theproxyalso createsandreturnsanopaquesecretvalue.Thevirtualmachineusesthesequenceandsecrettoidentify itselfwhenitestablishesaproxyconnectionfromthenewhost.SeethedescriptionofVMOTION-PEER. IAC SB VMWARE-TELNET-EXT VMOTION-GOAHEAD sequence secret IAC SE 25525023241sequencesecret255240 VMOTION-NOTNOW sequence AproxyresponsetoindicatethatthevMotionoperationshouldnotstartatthistime.Thismessage includesthesequencevaluethattheproxyobtainedintheVMOTION-BEGINrequest.Theproxycansend thismessageonlyinresponsetoaVMOTION-BEGINrequest. IAC SB VMWARE-TELNET-EXT VMOTION-NOTNOW sequence IAC SE 25525023243sequence255240 VMOTION-PEER sequence secret Atargethostrequesttoindicatethatthisconnectionbelongstothevirtualmachineassociatedwith sequenceandsecret.Thesequenceandsecretidentifytheduplicateconnectionsbetweentheproxyand virtualmachineinstancesduringavMotionoperation. TheoriginalhostgeneratesthesequencevaluefortheVMOTION-BEGINmessage.Theproxygeneratesthe secretvaluefortheVMOTION-GOAHEADmessage. IAC SB VMWARE-TELNET-EXT VMOTION-PEER sequence secret IAC SE 25525023244sequencesecret255240 VMOTION-PEER-OK sequence AproxyresponsetoindicatethatthesecretintheVMOTION-PEERmessagewasaccepted.Theproxysends thismessageonlyinresponsetoaVMOTION-PEERrequest. IAC SB VMWARE-TELNET-EXT VMOTION-PEER-OK sequence IAC SE 25525023245sequence255240 VMOTION-COMPLETE sequence AtargethostnotificationthatthevMotionoperationiscomplete.Theproxymustsendallsubsequent communicationforthevirtualmachineontheconnectionassociatedwiththisVMOTION-COMPLETE message.ThehostsendsthismessageonlyaftersendingaVMOTION-PEERmessage. IAC SB VMWARE-TELNET-EXT VMOTION-COMPLETE sequence IAC SE 25525023246sequence255240 VMOTION-ABORT AsourcehostnotificationthatthevMotionoperationfailed.Theproxymustsendallcommunicationfor thevirtualmachineontheconnectionassociatedwiththisVMOTION-ABORTmessage.Thehostcansend VMOTION-ABORTonlyifithassentVMOTION-BEGINpreviouslyonthisconnection. IAC SB VMWARE-TELNET-EXT VMOTION-ABORT IAC SE 25525023248255240 48 46 45 44 43 41 Code 40

VMware, Inc.

21

Using a Proxy with vSphere Virtual Serial Ports

Virtual Machine Identification

Table 26liststhesuboptioncommandsforvirtualmachineidentification. Table 2-6. VMware Telnet Extension Commands for Virtual Machine Identification
Command VM-VC-UUID vm-uuid Avirtualmachineresponsethatcontainsitsuniversallyuniqueidentifier. IAC SB VMWARE-TELNET-EXT VM-VC-UUID vm-uuid IAC SE 25525023280vmuuid255240 GET-VM-VC-UUID Aproxyrequestforthevirtualmachinesuniversallyuniqueidentifier. IAC SB VMWARE-TELNET-EXT GET-VM-VC-UUID IAC SE 25525023281255240 VM-NAME vm-name Avirtualmachineresponsethatcontainsitsname. IAC SB VMWARE-TELNET-EXT VM-NAME vm-name IAC SE 25525023282vmname255240 GET-VM-NAME Aproxyrequestforthevirtualmachinesname. IAC SB VMWARE-TELNET-EXT GET-VM-NAME IAC SE 25525023283255240 VM-BIOS-UUID vm-uuid Avirtualmachineresponsethatcontainsitsuniversallyuniqueidentifierstoredinthevirtualmachine BIOS. IAC SB VMWARE-TELNET-EXT VM-BIOS-UUID-IS vm-uuid IAC SE 25525023284vmuuid255240 GET-VM-BIOS-UUID AproxyrequestforthevirtualmachinesuniversallyuniqueidentifierstoredinitsBIOS. IAC SB VMWARE-TELNET-EXT GET-VM-BIOS-UUID IAC SE 25525023285255240 VM-LOCATION-UUID vm-uuid Avirtualmachineresponsethatcontainsitsuniversallyuniqueidentifier. IAC SB VMWARE-TELNET-EXT VM-LOCATION-UUID vm-uuid IAC SE 25525023286vmuuid255240 GET-VM-LOCATION-UUID Aproxyrequestforthevirtualmachineslocationuniversallyuniqueidentifier. IAC SB VMWARE-TELNET-EXT GET-VM-LOCATION-UUID IAC SE 25525023287255240 87 86 85 84 83 82 81 Code 80

22

VMware, Inc.

Index

A
accepting a connection 11 access server 7 access, virtual machine 8 appliance, virtual 8 authentication 8

D
data object, configuration 11 direction 11, 20 connection 9 server 11 DO-PROXY 20

B
backing info object 11 backing options 9, 11

E
establishing a VMware telnet extension session 13

F
forwarding traffic 8

C
command syntax 17 commands DO-PROXY 20 GET-VM-BIOS-UUID 22 GET-VM-LOCATION-UUID 22 GET-VM-NAME 22 GET-VM-VC-UUID 22 KNOWN-SUBOPTIONS-1 19 KNOWN-SUBOPTIONS-2 19 UNKNOWN-SUBOPTIONS-RCVD-1 19 UNKNOWN-SUBOPTIONS-RCVD-2 19 VM-BIOS-UUID 22 VM-LOCATION-UUID 22 VM-NAME 22 VMOTION-ABORT 21 VMOTION-BEGIN 21 VMOTION-COMPLETE 21 VMOTION-GOAHEAD 21 VMOTION-NOTNOW 21 VMOTION-PEER 21 VMOTION-PEER-OK 21 VM-VC-UUID 22 VMware telnet code 17 VMware telnet extension 12 VMWARE-TELNET-EXT 18 WILL-PROXY 20 WONT-PROXY 20 COM-PORT-OPTION (telnet) 14 concentrator 7 configuring a network serial port 11 connection behavior 11 direction 11

G
GET-VM-BIOS-UUID 22 GET-VM-LOCATION-UUID 22 GET-VM-NAME 22 GET-VM-VC-UUID 22

H
host IP address 7

I
IAC (interpret as command) 17 IP address host 7 virtual machine 8

K
KNOWN-SUBOPTIONS-1 19 KNOWN-SUBOPTIONS-2 19

M
method, configuration 11

N
negotiation, VMware telnet session 12

O
option backing (configuration) 11 subnegotiation (telnet) 18

VMware, Inc.

23

Using a Proxy with vSphere Virtual Serial Ports

P
proxy 7, 9 connection behavior 11 third party 7 URI 11 virtual appliance 8

V
virtual appliance 8 virtual machine identification 22 IP address 8 serial port client 9 serial port server 8, 9 virtual serial port concentrator 7 VirtualDeviceConfigSpec data object 11 VirtualDeviceConnectInfo data object 11 VirtualDeviceURIBackingInfo data object 11 VirtualDeviceURIBackingOption data object 11 VirtualMachineConfigOption data object 11 VirtualMachineConfigSpec data object 11 VirtualSerialPort data object 11 VM-BIOS-UUID 22 VM-LOCATION-UUID 22 VM-NAME 22 vMotion 8 persistent serial port connections 13 VMOTION-ABORT 21 VMOTION-BEGIN 21 VMOTION-COMPLETE 21 VMOTION-GOAHEAD 21 VMOTION-NOTNOW 21 VMOTION-PEER 21 VM-VC-UUID 22 VMware telnet extension command code 17 extension commands 12 session negotiation 12 VMWARE-TELNET-EXT 18

Q
QueryConfigOption method 11

R
ReconfigVM_Task method 11 RFC 2217 8, 20 3986 9 role of the virtual serial port proxy 8

S
secret (VMOTION-GOAHEAD) 21 security 8 sequence (VMOTION-BEGIN) 21 server direction 11 serviceURI 9 backing info 11 DO-PROXY 20 session negotiation 12 syntax,command 17

T
technical support resources 5 telnet COM-PORT-OPTION 14 connections for vMotion 13 extension 7, 12 option subnegotiation 18 session 13 session negotiation 12 third party proxy 7

W
WILL-PROXY 20 WONT-PROXY 20

U
UNKNOWN-SUBOPTIONS-RCVD-1 19 UNKNOWN-SUBOPTIONS-RCVD-2 19 URI backing option 9 proxy 9, 11 service 9, 11

24

VMware, Inc.