This document discusses how to exchange status messages between a guest virtual machine and the host system using GuestRPC. GuestRPC provides a private communication channel between the guest and host through a shared memory interface. It allows writing and reading the virtual machine configuration file and log files. The document outlines several use cases for status reporting and application configuration. It then describes how GuestRPC works and several methods for using it, including the VMware Guest API, VMware Tools commands, and a new open source Fling GuestRPC library.

1. How to Exchange Status Message Between Guest
and Host Using RPC
Max Daneri, VMware
William Lam, VMware
TEX5109

2. 22
Disclaimer
 This presentation may contain product features that are currently
under development.
 This overview of new technology represents no commitment from
VMware to deliver these features in any generally available
product.
 Features are subject to change, and must not be included in
contracts, purchase orders, or sales agreements of any kind.
 Technical feasibility and market demand will affect final delivery.
 Pricing and packaging for any new technologies or features
discussed or presented have not been determined.

3. 33
Agenda
• Introduction
• Dilemma / Motivation
• What is GuestRPC
• Use Cases
• How GuestRPC works
• How to use GuestRPC to exchange message Guest-Host
• How to get guest message from vSphere SDK
• How to use vSphere SDK to exchange message Host-Guest
• Summary

4. 44
Introduction
William Lam
Staff Product Integration Architect, VMware R&D
Blog: www.virtuallyghetto.com
Twitter: @lamw
Max Daneri
Senior Consultant CIM Emea
Web: http://www.vmts.net
Twitter @m_daneri

5. 55
Dilemma
vApp network
vApp
External Network (set up by system admin)
External Organization Network (set up by system admin)
Organization
Internal Organization network (set up by system admin)
vApp network
(set up by org admin/vApp author, internal to vApp)
External Organization Network
vApp network
1 2 3
4
56
7
8
I’ve to monitor this
How can I do ?

6. 66
Motivation
VMware vSphere
How do I retrieve info from
Hypervisor from within Guest OS?
Blog:http://www.virtuallyghetto.com/2011/01/how-to-extract-
host-information-from.html

7. 77
Guest RPC
 It is private communication channel between the guest and host
 It works like a bidirectional communication protocol over a shared
memory between host and guest
 Write and read the Virtual Machine configuration running file (write from
VM is limited to some specific parameters)
 Write message on Virtual Machine log file

8. 88
Use Cases
 Reporting
• Virtual Machine status
(disk space, network connectivity, connections failures, etc.)
• VM applications state
(services or daemons running state, number of database transactions, etc.)
 Application configuration
• A well know application using this is VMware Horizon View

9. 99
How Does GuestRPC Work?
It’s a very low level “communication” method, in practice the communication is
done by accessing a special I/O port, specific to VMware virtual machines
5658h, and setting a specific command parameter
The following Assembly code invokes “Backdoor” functions:

10. 1010
How to Use GuestRPC
There are currently three methods to use Guest RPC:
 VMware Guest API (Supported)
 Native VMware Tools command line
 Fling Guest RPC .NET and Java library

11. 1111
VMware Supported Guest API

12. 1212
VMware Supported Guest API
 These are the only officially supported API
 HA Application Monitoring API
• The vSphere High Availability (HA) feature for ESXi hosts in a cluster provides
protection for a guest OS and applications running in a virtual machine by
restarting the virtual machine if a guest OS or application failure occurs.
 Guest API
• The vSphere Guest API provides functions, that allow
management agents and other software to collect data about the state and pe
rformance of a VMware virtual machine.
The Guest API provides fast access to resource management information, with
out the need for authentication
More info on http://pubs.vmware.com/vsphere-
51/topic/com.vmware.ICbase/PDF/vsp51_guest_HAappmon_sdk.pdf

13. 1313
Guest RPC Using VMware Tools

14. 1414
Guest RPC Using VMware Tools
VMware Tools has a native support for Guest RPC
vmtoolsd –cmd <Guest RPC Command>
You can find it on :
 UNIX/Linux - /usr/bin/vmtoolsd
 Windows - C:Program FilesVMwareVMware Toolsvmtoolsd.exe

15. 1515
Guest RPC Commands

16. 1616
Guest RPC Commands 1/2
To work with VMX file (running configuration copy)
 INFO-SET guestinfo.<varname> <value>
Set a new temporary VM configuration parameter called guestinfo.varname to a
specific value
Note:
• Any temporary parameter has to start with guestinfo.
• These values remain on memory until the next VM power cycle
 INFO-GET <varname>
Retrieves any persistent or temporary value inside VM running configuration file
To write a log
 PLOG <message>
Write a log message on Virtual machine log file (vmware.log)

17. 1717
Guest RPC Commands 2/2
HA Application monitoring command
 GuestAppMonitor.Cmd.Enable
Enable HA application monitoring
 GuestAppMonitor.Cmd.Disable
Requests the virtual machine infrastructure to stop monitoring the calling program.
 GuestAppMonitor.Cmd.IsEnabled
Returns the current recorded state of application monitoring.
 GuestAppMonitor.Cmd.MarkActive
Sends a request to mark the program as active. This function is also known as the
heartbeat because your program must call it at least once every 30 seconds while
your application monitoring is enabled, or the virtual machine infrastructure will
determine that the monitoring has failed.
 GuestAppMonitor.Cmd.GetAppStatus
Returns the current status recorded by the virtual machine infrastructure
as ‘Green’, ‘Red’, or ‘Gray’.
• Green. Virtual machine infrastructure acknowledges that the application is being monitored.
• Red. Virtual machine infrastructure does not think the application is being monitored. The HA
monitoring agent will initialize an asynchronous reset on the virtual machine if the status is Red.
• Gray. App monitor is disabled

18. 1818
Fling Guest RPC Library

19. 1919
Fling Guest RPC Library
A new library that make any RPC command easy to use
OS Support :
 Windows 32bit/64bit (Java and .NET)
 Any Linux 32bit/64bit (Java and Mono)
Available on VMware labs with source code soon

20. 2020
Fling Guest RPC Library 1/2
 GuestInfo functions
• void SetGuestInfo(string key, string value )
Set a new temporary VM configuration parameter called guestinfo.key to a
specific value
• string GetGuestInfo(string key )
Retrieves any persistent or temporary value inside VM running
configuration file
 Various functions
• VMLog(string log)
Write a log message on Virtual machine log file (vmware.log)
• Boolean VMCheckVirtual()
Check if it is running on a virtual machine
• String CmdRpc(String command)
Exec a generic command

21. 2121
Fling Guest RPC Library 2/2
Application monitor functions
 GuestAppMonitorEnable()
Enable HA application monitoring
 Boolean GuestAppMonitorDisable()
Requests the virtual machine infrastructure to stop monitoring the calling
program.
 Boolean GuestAppMonitorIsEnabled()
Returns the current recorded state of application monitoring.
 void GuestAppMonitorMarkActive()
Sends a request to mark the program as active.
 string GuestAppMonitorGetAppStatus()
Returns the current status recorded by the virtual machine infrastructure as
‘Green’, ‘Red’, or ‘Gray’.

22. 2222
How to use “GuestInfo”
Note: Guestinfo.<*> is a VMX runtime property only, and
disappear after any VM power cycle

23. 2323
How to Use “GuestInfo”
From a vSphere Web Service API point of view Guestinfo.<*> values can
be collected visiting the content of
VirtualMachine.config.extraConfig (Type:OptionValue[ ])
Data Object – OptionValue

24. 2424
PowerShell 1/2
Param (
[parameter(Mandatory=$true)] $VCenter,
[parameter(Mandatory=$true)] $VM
)
$format = @{Expression= {$_.Key} ;
Label="Key";width=25}, `
@{Expression= {$_.Value};
Label="Value";width=15}
Connect-VIServer $VCenter
(get-vm -Name $VM|get-view) | where {
$_.key.contains("guestinfo.vmworld") }
| Format-Table -Property $format | Out-String
Sample PowerShell script

25. 2525
PowerShell 2/2
Results
--------------------------------------------------
Key Value
--- -----
guestinfo.vmworld.sda1 OK
guestinfo.vmworld.Defa... OK
guestinfo.vmworld.Micr... FAILS

26. 2626
What Else Can We Do With This Data?

27. 2727
vSphere Web Client Extension
Simple vSphere Web Client project showing how to use
Guest RPC

28. 2828
Another Project Using GuestRPC
• VAM (Virtual Application Monitor)
• Modular and expandable open source networks and
applications monitor
• Available on https://labs.vmware.com Release date: TBD

29. 2929
vSphere Client Plugin – VAM demo

30. 3030
Summary
 GuestRPC is a powerful method to exchange information between
an ESXi host and its virtual machines
 Accessible through API or CLI
 Easy to use GuestRPC Library (Fling)
 Best for last, everything can be done without use of a
network connection

31. 3131
TAP Membership Renewal – Great Benefits
• TAP Access membership includes:
New TAP Access NFR Bundle
• Access to NDA Roadmap sessions at VMworld, PEX and Onsite/Online
• VMware Solution Exchange (VSX) and Partner Locator listings
• VMware Ready logo (ISVs)
• Partner University and other resources in Partner Central
• TAP Elite includes all of the above plus:
• 5X the number of licenses in the NFR Bundle
• Unlimited product technical support
• 5 instances of SDK Support
• Services Software Solutions Bundle
• Annual Fees
• TAP Access - $750
• TAP Elite - $7,500
• Send email to tapalliance@vmware.com

32. 3232
TAP Resources
 TAP
• TAP support: 1-866-524-4966
• Email: tapalliance@vmware.com
• Partner Central: http://www.vmware.com/partners/partners.html
 TAP Team
• Kristen Edwards – Sr. Alliance Program Manager
• Sheela Toor – Marketing Communication Manager
• Michael Thompson – Alliance Web Application Manager
• Audra Bowcutt –
• Ted Dunn –
• Dalene Bishop – Partner Enablement Manager, TAP
 VMware Solution Exchange
• Marketplace support –
vsxalliance@vmware.com
• Partner Marketplace @ VMware
booth pod TAP1

33. THANK YOU

35. How to Exchange Status Message Between Guest
and Host Using RPC
Max Daneri, VMware
William Lam, VMware
TEX5109