{"id":18512831,"url":"https://github.com/vmware/virtual-disks","last_synced_at":"2025-04-09T06:32:23.381Z","repository":{"id":45316260,"uuid":"336107298","full_name":"vmware/virtual-disks","owner":"vmware","description":"Go Library for Virtual Disk Development Kit","archived":false,"fork":false,"pushed_at":"2023-03-17T10:34:20.000Z","size":25,"stargazers_count":18,"open_issues_count":7,"forks_count":25,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-24T00:08:27.637Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vmware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-04T23:11:58.000Z","updated_at":"2025-01-08T03:39:08.000Z","dependencies_parsed_at":"2024-06-18T18:57:26.928Z","dependency_job_id":null,"html_url":"https://github.com/vmware/virtual-disks","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware%2Fvirtual-disks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware%2Fvirtual-disks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware%2Fvirtual-disks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware%2Fvirtual-disks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vmware","download_url":"https://codeload.github.com/vmware/virtual-disks/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247992608,"owners_count":21029926,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T15:35:37.519Z","updated_at":"2025-04-09T06:32:22.960Z","avatar_url":"https://github.com/vmware.png","language":"Go","readme":"# virtual-disks\n\nGo Library for Virtual Disk Development Kit (a.k.a. virtual-disks) is a Golang \nwrapper to access the VMware Virtual Disk Development Kit API (VDDK), which \nis a SDK to help developers create applications that access storage on virtual \nmachines. Virtual-disks provide two level apis to user:\n\n* Low level api, which expose all VDDK apis directly in Golang.\n* High level api, which provide some common used functionalities to user, such as IO read and write.\n\nUser can choose to either use main functionality via high level api, or use low level api to implement his own function combination.\n\n# Dependency\nVirtual-disks needs the Virtual Disk Development Kit (VDDK) to connect with \nvSphere.\nThe VDDK can be downloaded from here: https://code.vmware.com/web/sdk/7.0/vddk.  Virtual-disks requires the 7.0.0 VDDK release.\nAfter installing, please untar into the /usr/local/ directory:\n\n```\n\u003e cd /usr/local\n\n\u003e sudo tar xzf \u003cpath to VMware-vix-disklib-*version*.x86_64.tar.gz\u003e.\n```\n\nVDDK is free to use for personal and internal use.  Redistribution requires a no-fee license, please contact VMware to \nobtain the license.\n\nRequired Linux library packages are listed below:\n\nUbuntu:\n* libc6\n* libssl1.0.2\n* libssl1.0.0\n* libssl-dev\n* libcurl3\n* libexpat1-dev\n* libffi6\n* libgcc1\n* libglib2.0-0\n* libsqlite3-0\n* libstdc++6\n* libxml2\n* zlib1g\n\nCentos:\n* openssl-libs\n* libcurl\n* expat-devel\n* libffi \n* libgcc \n* glib2 \n* sqlite\n* libstdc++\n* libxml2\n* zlib\n\n# Use cases\nVirtual-disks provides access to virtual disks, enabling a range of use cases for application vendors including:\n* Back up a particular volume, or all volumes, associated with a virtual machine.\n* Get IO Reader and Writer for a vmbk file.\n* Connect a backup proxy to vSphere and back up all virtual machines on a storage cluster.\n* Manipulate virtual disks to defragment, expand, convert, rename, or shrink the file system image.\n* Attach child disk chain to parent disk chain.\n\n# Low level API\n## Set up\n### Init\n```$xslt\n/**\n * Initialize the library. Must be called at the \n * beginning of program. Should be called only once \n * per process. Should call Exit at the end of program\n * for clean up.\n */\nfunc Init(majorVersion uint32, minorVersion uint32, dir string) VddkError {}\n```\n### PrepareForAccess\n```$xslt\n/**\n * Notify a host to refrain from relocating a virtual machine.\n * Every PrepareForAccess call should have a matching EndAccess\n * call.\n */\nfunc PrepareForAccess(appGlobal ConnectParams) VddkError {}\n```\n### Connect\n```$xslt\n/**\n * Connect the library to local/remote server. \n * Always call Disconnect before end of \n * program, which invalidates any open file handles.\n * VixDiskLib_PrepareForAccess should be called \n * before each Connect.\n */\nfunc Connect(appGlobal ConnectParams) (VixDiskLibConnection, VddkError) {} \n```\n### ConnectEx\n```$xslt\n/**\n * Create a transport context to access disks \n * belonging to a particular snapshot of a \n * particular virtual machine. Using this transport \n * context enables callers to open virtual disks \n * using the most efficient data access protocol \n * available for managed virtual machines, for \n * improved I/O performance. If you use this call \n * instead of Connect(), additional input parameters\n * transportmode and snapshotref should be given.\n */\nfunc ConnectEx(appGlobal ConnectParams) (VixDiskLibConnection, VddkError) {}\n```\n## Disk operation\n### Create a local or remote disk\n```$xslt\n/**\n * Locally creates a new virtual disk, after being \n * connected to the host. In createParams, you must \n * specify the disk type, adapter, hardware version, \n * and capacity as a number of sectors. This \n * function supports hosted disk. For managed disk, \n * first create a hosted type virtual disk, then use \n * Clone() to convert the virtual disk to managed \n * disk.\n */\nfunc Create(connection VixDiskLibConnection, path string, createParams VixDiskLibCreateParams, progressCallbackData string) VddkError {}\n```\n### Open a local or remote disk\nAfter the library connects to a workstation or server, Open opens a virtual disk. With SAN or HotAdd transport, opening a remote disk for writing requires a pre-existing snapshot. Use different open flags to modify the open instruction:\n* VIXDISKLIB_FLAG_OPEN_UNBUFFERED – Disable host disk caching.\n* VIXDISKLIB_FLAG_OPEN_SINGLE_LINK – Open the current link, not the entire chain (hosted disk only).\n* VIXDISKLIB_FLAG_OPEN_READ_ONLY – Open the virtual disk read-only.\n* VIXDISKLIB_FLAG_OPEN_COMPRESSION_ZLIB – Open for NBDSSL transport, zlib compression.\n* VIXDISKLIB_FLAG_OPEN_COMPRESSION_FASTLZ – Open for NBDSSL transport, fastlz compression.\n* VIXDISKLIB_FLAG_OPEN_COMPRESSION_SKIPZ – Open for NBDSSL transport, skipz compression.\n\nShould have a matching VixDiskLib_Close.\n```$xslt\n/**\n * Opens a virtual disk.\n */\nfunc Open(conn VixDiskLibConnection, params ConnectParams) (VixDiskLibHandle, VddkError) {}\n```\n### Read and Write disk IO\n```$xslt\n/**\n * This function reads a range of sectors from an open virtual disk.\n */\nfunc Read(diskHandle VixDiskLibHandle, startSector uint64, numSectors uint64, buf []byte) VddkError {}\n```\n```$xslt\n/**\n * This function writes to an open virtual disk.\n */\nfunc Write(diskHandle VixDiskLibHandle, startSector uint64, numSectors uint64, buf []byte) VddkError {}\n```\n### Metadata handling\n```$xslt\n/**\n * Read Metadata key from disk.\n */\nfunc ReadMetadata(diskHandle VixDiskLibHandle, key string, buf []byte, bufLen uint, requiredLen uint) VddkError {}\n```\n```$xslt\n/**\n * Get metadata table from disk.\n */\nfunc GetMetadataKeys(diskHandle VixDiskLibHandle, buf []byte, bufLen uint, requireLen uint) VddkError {}\n```\n```$xslt\n/**\n * Write metadata table to disk.\n */\nfunc WriteMetadata(diskHandle VixDiskLibHandle, key string, val string) VddkError {}\n```\n### Block allocation\n```$xslt\n/**\n * Determine allocated blocks.\n */\nfunc QueryAllocatedBlocks(diskHandle VixDiskLibHandle, startSector VixDiskLibSectorType, numSectors VixDiskLibSectorType, chunkSize VixDiskLibSectorType) ([]VixDiskLibBlock, VddkError) {}\n```\n## Shut down\nAll virtual disk api applications should call these functions at the end of program.\n### Disconnect\n```$xslt\n/**\n * Destroy the connection. Match to Connect.\n */\nfunc Disconnect(connection VixDiskLibConnection) VddkError {}\n```\n### EndAccess\n```$xslt\n/**\n * Notifies the host that a virtual machine’s disk have been closed, so operations that \n * rely on the virtual disks to be closed, such as vMotion, can now be allowed. Internally\n * this function re-enables the vSphere API method RelocateVM_Task.\n */\nfunc EndAccess(appGlobal ConnectParams) VddkError {}\n```\n### Exit\n```$xslt\n/** \n * Releases all resources held by VixDiskLib.\n */\nfunc Exit() {}\n```\n# High level API and data structure\n## API\n### Open\n```$xslt\n/**\n * Will handle the set up operations for a disk, \n * including prepare for access, connect, open. If \n * failure happens in the set up stage, will roll \n * back to initial state. Return a DiskReaderWriter \n * which allows read or write operations to the \n * disk.\n */\nfunc Open(globalParams disklib.ConnectParams, logger logrus.FieldLogger) \n                  (DiskReaderWriter, disklib.VddkError) {}\n```\n### Read\n```$xslt\n/**\n * Read reads up to len(p) bytes into p. It returns \n * the number of bytes read (0 \u003c= n \u003c= len(p)) and \n * any error encountered.\n */\nfunc (this DiskReaderWriter) Read(p []byte) (n int, err error) {}\n```\n### ReadAt\n```$xslt\n/** \n * Read from given offset.\n */\nfunc (this DiskReaderWriter) ReadAt(p []byte, off int64) (n int, err error) {}\n```\n### Write\n```$xslt\n/**\n * Write writes len(p) bytes from p to the \n * underlying data stream. It returns the number of \n * bytes written from p (0 \u003c= n \u003c= len(p)).\n */\nfunc (this DiskReaderWriter) Write(p []byte) (n int, err error) {}\n```\n### WriteAt\n```$xslt\n/**\n * Write from given offset.\n */\nfunc (this DiskConnectHandle) WriteAt(p []byte, off int64) (n int, err error) {}\n```\n### Block allocation\n```$xslt\n/**\n * Determine allocated blocks.\n */\nfunc (this DiskReaderWriter) QueryAllocatedBlocks(startSector disklib.VixDiskLibSectorType, numSectors disklib.VixDiskLibSectorType, chunkSize disklib.VixDiskLibSectorType) ([]disklib.VixDiskLibBlock, disklib.VddkError) {}\n```\n### Close\n```$xslt\n/**\n * Clear up all the resources held. Should be called in the end.\n */\nfunc (this DiskReaderWriter) Close() error {} \n```\n## Data structure\n### DiskReaderWriter\n```$xslt\ntype DiskReaderWriter struct {\n\treaderAt io.ReaderAt\n\twriterAt io.WriterAt\n\tcloser   io.Closer\n\toffset  *int64\n\tmutex    sync.Mutex                                                                \n\tlogger   logrus.FieldLogger\n}\n```\n\n# Contributing\n\nThe Go Library for Virtual Disk Development Kit project team welcomes \ncontributions from the community. If you wish to contribute code and you \nhave not signed our contributor license agreement (CLA), our bot will update \nthe issue when you open a Pull Request. For any questions about the CLA \nprocess, please refer to our [FAQ](https://cla.vmware.com/faq).\n\nFor additional info on contributing, please see CONTRIBUTING.md\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmware%2Fvirtual-disks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvmware%2Fvirtual-disks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmware%2Fvirtual-disks/lists"}