Loading...
VMCI Sockets Programming Guide
VMware ESXi 5.5
VMware Workstation 9.x
This document supports the version of each product listed and supports all subsequent versions until the document is replaced by a new edition. To check for more recent editions of this document, see http://www.vmware.com/support/pubs.
EN-001166-00
VMCI Sockets Programming Guide
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 © 2008–2013 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents.
VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.
VMware, Inc.
3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com
2 |
VMware, Inc. |
Contents
About This Book |
5 |
|
|
|
|
|
|
|
1 About VMCI Sockets |
7 |
|
|
|
|
|
|
|
Introduction to VMCI Sockets |
7 |
|
|
|
||||
Previous VMCI Releases |
7 |
|
|
|
|
|||
How VMCI Sockets Work |
7 |
|
|
|
||||
Persistence of Sockets |
8 |
|
|
|
|
|
||
Socket Programming |
8 |
|
|
|
|
|
||
Features in Specific VMware Releases |
8 |
|
||||||
Enabling and Finding VMCI Sockets |
|
8 |
|
|||||
Location of Include File for C Programs 8 |
||||||||
Security of VMCI Sockets |
9 |
|
|
|
|
|||
Use Cases for VMCI Sockets |
9 |
|
|
|
|
|||
RabbitMQ with Stream VMCI Sockets |
9 |
|||||||
Network Storage with Datagram VMCI Sockets 10 |
||||||||
2 Porting to VMCI Sockets |
11 |
|
|
|
|
|||
Porting Existing Socket Applications |
|
11 |
|
|||||
Include a New Header File |
11 |
|
|
|
||||
Change AF_INET to VMCI Sockets 11 |
||||||||
Obtain the CID |
11 |
|
|
|
|
|
|
|
The VMCISock_GetLocalCID() Function 11 |
||||||||
Connection Oriented Stream Socket |
12 |
|||||||
Connectionless Datagram Socket |
|
12 |
|
|||||
Initializing the Address Structure |
12 |
|
||||||
Communicating Between Host and Guest |
12 |
|||||||
VMCI Sockets and Networking |
12 |
|
||||||
Setting Up a Networkless Guest |
|
12 |
|
|||||
3 Creating Stream VMCI Sockets |
13 |
|
||||||
Stream VMCI Sockets |
13 |
|
|
|
|
|
|
|
Preparing the Server for a Connection |
14 |
|||||||
Socket() Function |
14 |
|
|
|
|
|
|
|
Set and Get Socket Options |
14 |
|
|
|
||||
Bind() Function |
15 |
|
|
|
|
|
|
|
Listen() Function |
15 |
|
|
|
|
|
|
|
Accept() Function |
15 |
|
|
|
|
|
|
|
Select() Function |
15 |
|
|
|
|
|
|
|
Recv() Function |
16 |
|
|
|
|
|
|
|
Send() Function |
16 |
|
|
|
|
|
|
|
Close() Function |
16 |
|
|
|
|
|
|
|
Poll() Information |
16 |
|
|
|
|
|
|
|
Read() and Write() |
16 |
|
|
|
|
|
|
|
Getsockname() Function |
16 |
|
|
|
|
|||
Having the Client Request a Connection |
17 |
|||||||
Socket() Function |
17 |
|
|
|
|
|
|
|
Connect() Function 17 |
|
|
|
|
|
|||
Send() Function |
17 |
|
|
|
|
|
|
|
VMware, Inc. |
3 |
VMCI Sockets Programming Guide |
|
|
|
|
|
|
|
Recv() Function |
18 |
|
|
|
|
|
|
Close() Function |
|
18 |
|
|
|
|
|
Poll() Information |
18 |
|
|
|
|
||
Read() and Write() |
18 |
|
|
|
|||
4 Creating Datagram VMCI Sockets |
19 |
||||||
Datagram VMCI Sockets |
|
19 |
|
|
|
||
Preparing the Server for a Connection |
20 |
||||||
Socket() Function |
20 |
|
|
|
|
||
Socket Options |
20 |
|
|
|
|
|
|
Bind() Function |
20 |
|
|
|
|
|
|
Getsockname() Function |
21 |
|
|
||||
Recvfrom() Function |
|
21 |
|
|
|
||
Sendto() Function |
21 |
|
|
|
|
||
Close() Function |
|
21 |
|
|
|
|
|
Having the Client Request a Connection 21 |
|||||||
Socket() Function |
21 |
|
|
|
|
||
Sendto() Function |
22 |
|
|
|
|
||
Connect() and Send() |
22 |
|
|
|
|||
Recvfrom() Function |
|
22 |
|
|
|
||
Close() Function |
|
22 |
|
|
|
|
|
5 Security of the VMCI Device |
23 |
|
|||||
Interfaces for VMCI Settings |
23 |
|
|
||||
VMCI Device Always Enabled 23 |
|
||||||
VMCI and Hardware Version |
23 |
|
|||||
Authentication |
23 |
|
|
|
|
|
|
Isolation Options in VMX |
24 |
|
|
||||
Isolation of Virtual Machines |
24 |
|
|
||||
Isolation in Workstation |
24 |
|
|
||||
Isolation in ESX/ESXi |
24 |
|
|
|
|||
Trusted VMCI Sockets |
24 |
|
|
||||
Appendix: Learning More About Sockets 25 |
|||||||
About Berkeley Sockets and Winsock |
25 |
||||||
Trade Press Books |
25 |
|
|
|
|
||
Berkeley Sockets |
|
25 |
|
|
|
|
|
Microsoft Winsock |
26 |
|
|
|
|||
Short Introduction to Sockets |
26 |
|
|
||||
Socket Addresses |
26 |
|
|
|
|
||
Socket() System Call |
26 |
|
|
|
|||
Bind() System Call |
26 |
|
|
|
|||
Listen() System Call |
27 |
|
|
|
|||
Accept() System Call |
|
27 |
|
|
|
||
Connect() System Call |
27 |
|
|
||||
Socket Read and Write |
28 |
|
|
||||
Index 29
4 |
VMware, Inc. |
About This Book
The VMware® VMCI Sockets Programming Guide describes how to program virtual machine communications interface (VMCI) sockets. The VMCI sockets API facilitates fast and efficient communication between guest virtual machines and their host.
Revision History
VMware revises this guide with each release of the product or when necessary. A revised version can contain minor or major changes. Table 1 summarizes the significant changes in each version of this guide.
Table 1. Revision History
Revision Description
20130830 Manual slightly revised for the ESXi 5.5 release.
20120719 Guest to guest communication dedocumented for the ESXi 5.1 release.
20120105 Windows header file now in Program Files\Common Files\VMware\Drivers\vmci\sockets\include.
20110720 Manual revised for the Workstation 8.0 release and for the ESXi 5.0 release.
20100521 Manual revised for the Workstation 7.1 release and for ESX/ESXi 4.x releases.
20091020 Manual revised slightly for the Workstation 7.0 release.
20090515 Revised manual, including host to guest stream socket support, for the ESX/ESXi 4.0 release.
20080815 Released manual, with socket options, for VMware Workstation 6.5 and VMware Server 2.0 products.
20080620 Draft of this manual for the VMware Workstation 6.5 Beta 2 and VMware Server 2.0 RC1 releases.
Intended Audience
This manual is intended for programmers who are developing applications using VMCI sockets to create C or C++ networking applications for guest operating systems running on VMware hosts. VMCI sockets are based on TCP sockets.
This guide assumes that you are familiar with Berkeley sockets or Winsock, the Windows implementation of sockets. If you are not familiar with sockets, “Appendix: Learning More About Sockets” on page 25 provides pointers to learning resources.
Document Feedback
VMware welcomes your suggestions for improving our documentation and search tools. Send your feedback to docfeedback@vmware.com.
VMware, Inc. |
5 |
VMCI Sockets Programming Guide
VMware Technical Publications Glossary
VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions of terms as they are used in VMware technical documentation go to http://www.vmware.com/support/pubs.
# |
VMware, Inc. |
About VMCI Sockets |
1 |
|
|
|
|
This chapter includes the following topics:
“Introduction to VMCI Sockets” on page 7
“Features in Specific VMware Releases” on page 8
“Enabling and Finding VMCI Sockets” on page 8
“Use Cases for VMCI Sockets” on page 9
This guide assumes that you know about either Berkeley sockets or Winsock, the Windows implementation. If you are new to sockets, see “Appendix: Learning More About Sockets” on page 25.
Introduction to VMCI Sockets
The VMware VMCI sockets library offers an API that is similar to the Berkeley UNIX socket interface and the Windows socket interface, two industry standards. VMCI sockets support fast and efficient communication between guest virtual machines and their host.
Previous VMCI Releases
The original VMCI library was released as an experimental C language interface with Workstation 6.0. VMCI included a datagram API and a shared memory API. Both interfaces were discontinued in Workstation 6.5.
The VMCI sockets library was first released with Workstation 6.5 and Server 2.0 as a supported interface. The VMCI sockets library had more flexible algorithms, wrapped in a stream sockets API for external presentation. Stream socket support was improved for ESX/ESXi hosts when VMware vSphere™ 4 and vCenter™ Server 4 were released.
How VMCI Sockets Work
VMCI sockets are similar to other socket types. Like local UNIX sockets, VMCI sockets work on an individual physical machine, and can perform interprocess communication on the local system. With Internet sockets, communicating processes usually reside on different systems across the network. Similarly, VMCI sockets allow guest virtual machines to communicate the host on which they reside.
The VMCI sockets library supports both connection oriented stream sockets like TCP, and connectionless datagram sockets like UDP. However, with VMCI sockets, a virtual socket can have only two endpoints and unlike TCP sockets, the server cannot initiate a connection to the client.
VMCI sockets support data transfer among processes on the same system (interprocess communication). They also allow communication to processes on different systems, including ones running different versions and types of operating systems. VMCI sockets comprise a single protocol family.
Sockets require active processes, so communicating guest virtual machines must be running, not powered off.
VMCI sockets are available only at the user level. Kernel APIs are not supported.
VMware, Inc. |
7 |
VMCI Sockets Programming Guide
Persistence of Sockets
VMCI sockets lose connection after suspend and resume of a virtual machine.
In VMware vSphere with ESX/ESXi hosts and vCenter Server, VMCI sockets do not survive live migration with VMware vMotion™ from source to destination host. In VMware vSphere with ESX/ESXi hosts, VMCI stream socket connections are dropped when a virtual machine is put into fault tolerance (FT) mode. No new VMCI stream socket connections can be established while a virtual machine is in FT mode.
Socket Programming
If you have existing socket based applications, only a few code changes are required for VMCI sockets. If you do not have socket based applications, you can easily find public domain code on the Web. For example, Apache and Firefox, as shown in Figure 1 1, “ESXi host with Stream VMCI Sockets and RabbitMQ,” on page 9, use stream sockets and are open source.
Repurposing a networking program to use VMCI sockets requires minimal effort, because VMCI sockets behave like traditional Internet sockets on a given platform. However, some socket options do not make sense for communication across the VMCI device, so they are silently ignored to promote program portability.
Modification is straightforward. You include a header file, change the protocol address family, and allocate a new data structure. Otherwise VMCI sockets use the same API as Berkeley sockets or Windows sockets. See “Porting Existing Socket Applications” on page 11 for a description of the modifications needed.
Features in Specific VMware Releases
VMCI sockets communicate between the host and a guest on VMware platform products. You could also use VMCI sockets for interprocess communications on a guest. You cannot use VMCI sockets between the host and a virtual machine running on a different host.
IMPORTANT To use VMCI sockets, virtual machines must be upgraded to VMware compatibility 7 (virtual hardware version 7), which was introduced in VMware Workstation 6.5 and supported in ESX/ESXi 4.0.
As of VMware Server 2.0 RC2 and Workstation 6.5 RC releases, you can set the minimum, maximum, and default size of communicating stream buffers. See “Set and Get Socket Options” on page 14.
ESX/ESXi 4.x (vSphere 4) releases and later have complete user level support for VMCI sockets. Datagram and stream sockets are supported between host and guests on both Linux and Windows. In the Workstation 7.x releases running on Windows hosts, only datagram sockets were supported.
In the ESXi 5.0 and Workstation 8.0 releases, it was announced that the guest to guest VMCI sockets feature would be discontinued. As of the ESXi 5.1 release, only host to guest VMCI sockets are allowed.
Enabling and Finding VMCI Sockets
For host to guest communication, VMCI is enabled on virtual machines with version 7 compatibility and later.
Location of Include File for C Programs
VMware Tools or another installer places the vmci_sockets.h include file in one of the following locations:
Windows guests on Workstation 8.0 or later, and Windows hosts of Workstation 8.0 or later –
C:\Program Files\Common Files\VMware\Drivers\vmci\sockets\include
earlier Windows guests – C:\Program Files\VMware\VMware Tools\VSock SDK\include
earlier Windows hosts – C:\Program Files\VMware\VMware Workstation
Linux guests – /usr/lib/vmware-tools/include/vmci
Linux hosts – /usr/lib/vmware/include/vmci
ESX/ESXi hosts – Not installed on the system.
8 |
VMware, Inc. |
Chapter 1 About VMCI Sockets
Security of VMCI Sockets
VMCI Sockets are more secure after elimination of guest to guest communications. For an overview of VMCI security, see Chapter 5, “Security of the VMCI Device,” on page 23.
Use Cases for VMCI Sockets
VMCI sockets can help with the following solutions:
Implement network based communication for off the network virtual machines
Improve the privacy of data transmission on hosted virtual machines
Increase host guest performance of socket modified applications and databases
Implement a fast host guest file system
Provide an alternative data path for access to and management of guest virtual machines
RabbitMQ with Stream VMCI Sockets
On the ESXi host in Figure 1 1, two virtual machines contain a message queuing client that communicates with a guest proxy through amqplib. Guest proxies communicate with the host proxy over VMCI Sockets, which treat each guest connection as a separate session. The host proxy multiplexes these sessions and communicates with the RabbitMQ proxy over a single TCP/IP socket, passing encapsulated AMQP. A RabbitMQ node runs on a virtual machine. The RabbitMQ cluster is a collection of RabbitMQ nodes that are assembled for reliability and scaling. The AMQP proxy splits out multiplexed sessions of individual connections to a RabbitMQ node. All this takes place on the management network, reducing traffic on the guest network.
Figure 1-1. ESXi host with Stream VMCI Sockets and RabbitMQ
Guest network
Client |
|
Client |
|
amqplib |
|
amqplib |
|
Guest |
|
Guest |
RabbitMQ components |
proxy |
|
proxy |
Middleware components |
VM |
|
VM |
|
|
|
||
vmx |
|
vmx |
|
VMCI |
Host |
VMCI |
|
|
proxy |
|
|
ESXi |
|
|
|
Management network |
|
||
|
Encapsulated |
|
|
|
AMQP |
|
|
|
AMQP |
Node |
RabbitMQ |
|
AMQP |
||
|
proxy |
Cluster |
|
|
Node |
||
|
|
|
|
Originated in 2003, AMQP (advanced message queuing protocol) is an industry standard for passing business messages between applications and organizations. It is popular in the banking and finance industries.
VMware, Inc. |
9 |
Loading...