Virtual Disk Development Kit Programming Guide

Update 1 VMware vSphere 6.7 Virtual Disk Development Kit 6.7.1 Virtual Disk Development Kit Programming Guide

You can find the most up-to-date technical documentation on the VMware website at: https://docs.vmware.com/ If you have comments about this documentation, submit your feedback to [email protected]

VMware, Inc. 3401 Hillview Ave. Palo Alto, CA 94304 www.vmware.com

VMware, Inc. 2 Contents

About This Book 9

1 Introduction to the Virtual Disk API 11 About the Virtual Disk API 11 VDDK Components 12 Virtual Disk Library 12 Disk Mount Library 12 Virtual Disk Utilities 12 Backup and Restore on vSphere 12 Backup Design for vCloud Director 13 Use Cases for the Virtual Disk Library 13 Developing for VMware Platform Products 13 Managed Disk and Hosted Disk 14 Advanced Transports 15 VDDK and VADP Compared 15 Platform Product Compatibility 15 Redistributing VDDK Components 15

2 Installing the Development Kit 16 Prerequisites 16 Development Systems 16 Programming Environments 16 VMware Platform Products 17 Storage Device Support 17 Installing the VDDK Package 17 Repackaging VDDK Libraries 18 How to Find VADP Components 19

3 Virtual Disk Interfaces 20 VMDK File Location 20 Virtual Disk Types 20 Persistence Disk Modes 21 VMDK File Naming 21 Thin Provisioned Disk 22 Internationalization and Localization 22 Virtual Disk Internal Format 23 Grain Directories and Grain Tables 23

VMware, Inc. 3 Virtual Disk Development Kit Programming Guide

Data Structures in Virtual Disk API 23 Credentials and Privileges for VMDK Access 24 Adapter Types 25 Virtual Disk Transport Methods 25 Local File Access 26 SAN Transport 26 HotAdd Transport 27 NBDSSL Transport 28

4 Virtual Disk API Functions 32 Virtual Disk Library Functions 32 Alphabetic Table of Functions 33 Start Up 34 Initialize the Library 34 Connect to a Workstation or Server 35 VMX Specification 35 Disk Operations 36 Create a New Hosted Disk 36 Open a Local or Remote Disk 36 Read Sectors From a Disk 37 Write Sectors To a Disk 37 Close a Local or Remote Disk 38 Get Information About a Disk 38 Free Memory from Get Information 38 Metadata Handling 38 Read Metadata Key from Disk 38 Get Metadata Table from Disk 38 Write Metadata Table to Disk 39 Check and Repair Sparse Disk Metadata 39 Disk Chaining and Redo Logs 39 Create Child from Parent Disk 40 Attach Child to Parent Disk 40 Opening in a Chain 42 Redo Logs and Linked Clone Backup 42 Cloning a Virtual Disk 42 Compute Space Needed for Clone 43 Clone a Disk by Copying Data 43 Error Handling 43 Return Error Description Text 43 Free Error Description Text 43 Administrative Disk Operations 44 Rename an Existing Disk 44

VMware, Inc. 4 Virtual Disk Development Kit Programming Guide

Grow an Existing Local Disk 44 Defragment an Existing Disk 44 Shrink an Existing Local Disk 44 Unlink Extents to Remove Disk 45 Shut Down 45 Disconnect from Server 45 Clean Up and Exit 45 Advanced Transport APIs 45 Initialize Virtual Disk API 45 Phone Home Support 48 Location of Log Files 48 List Available Transport Methods 49 Connect to VMware vSphere 49 Get Selected Transport Method 50 Prepare For Access and End Access 51 SAN Mode on Linux Uses Direct Mode 52 Clean Up After Disconnect 52 Ordering of Function Calls in Sequence 52 Updating Applications for Advanced Transport 52 Algorithm for vSphere Backup 53 Backup and Recovery Example 54 Multithreading Considerations 55 Multiple Threads and VixDiskLib 55 Capabilities of Library Calls 56 Support for Managed Disk 56 Support for Hosted Disk 56

5 Virtual Disk API Sample Code 57 Compiling the Sample Program 57 Visual C++ on Windows 57 C++ on Linux Systems 58 Library Files Required 58 Usage Message 59 Walk-Through of Sample Program 60 Include Files 60 Definitions and Structures 60 Dynamic Loading 61 Wrapper Classes 61 Command Functions 61 SSL Certificate