nbdkit-vddk-plugin(1)

1nbdkit-vddk-plugin(1)               NBDKIT               nbdkit-vddk-plugin(1)
2
3
4

NAME

6       nbdkit-vddk-plugin - nbdkit VMware VDDK plugin
7

SYNOPSIS

9        nbdkit vddk [file=]FILENAME
10                    [compression=none|zlib|fastlz|skipz]
11                    [config=FILENAME] [cookie=COOKIE] [libdir=LIBRARY]
12                    [nfchostport=PORT] [single-link=true]
13                    [password=PASSWORD | password=- | password=+FILENAME |
14                     password=-FD]
15                    [port=PORT] [server=HOSTNAME] [snapshot=MOREF]
16                    [thumbprint=THUMBPRINT] [transports=MODE:MODE:...]
17                    [unbuffered=true] [user=USERNAME] [vm=moref=ID]
18        nbdkit vddk --dump-plugin
19

DESCRIPTION

21       "nbdkit-vddk-plugin" is an nbdkit(1) plugin that serves disks from
22       local VMware VMDK files, VMware ESXi servers, VMware VCenter servers,
23       and other sources.
24
25       It requires VMware's proprietary VDDK library that you must download
26       yourself (see "LIBRARY LOCATION" below).
27

EXAMPLES

29   Open a local VMDK file
30        nbdkit vddk /absolute/path/to/file.vmdk
31
32       When opening local files the filename must be an absolute path.
33
34       Because VDDK needs to lock the file, the file must be on a writable
35       filesystem.  You can avoid this by opening the file read-only (the -r
36       option):
37
38        nbdkit -r vddk /absolute/path/to/file.vmdk
39
40   Open a file on a remote VMware ESXi hypervisor
41       Connect directly to a VMware ESXi hypervisor and export a particular
42       file:
43
44        nbdkit vddk user=root password=+/tmp/rootpw \
45                    server=esxi.example.com thumbprint=xx:xx:xx:... \
46                    vm=moref=2 \
47                    "[datastore1] Fedora/Fedora.vmdk"
48
49       "user" and "password" must be specified.  Use "password=+FILENAME" to
50       provide the password securely in a file.
51
52       "server" is the hostname of the ESXi server.
53
54       "thumbprint" is the thumb print for validating the SSL certificate.
55       How to find the thumb print of a server is described in "THUMBPRINTS"
56       below.
57
58       "vm" is the Managed Object Reference ("moref") of the virtual machine.
59       See "MANAGED OBJECT REFERENCE" below.
60
61       The file parameter is the file you want to open, usually in the form
62       "[datastore] vmname/vmname.vmdk".  See "FILE PARAMETER" below.
63
64   Open a file on a remote VMware vCenter server
65       Connect via VMware vCenter and export a particular file:
66
67        nbdkit vddk user=root password=vmware \
68                    server=vcenter.example.com thumbprint=xx:xx:xx:... \
69                    vm=moref=vm-16 \
70                    "[datastore1] Fedora/Fedora.vmdk"
71
72       "user" and "password" must be specified.  Use "password=+FILENAME" to
73       provide the password securely in a file.
74
75       "server" is the hostname of the vCenter server.
76
77       "thumbprint" is the thumb print for validating the SSL certificate.
78       How to find the thumb print of a server is described in "THUMBPRINTS"
79       below.
80
81       "vm" is the Managed Object Reference ("moref") of the virtual machine.
82       See "MANAGED OBJECT REFERENCE" below.
83
84       The file parameter is the file you want to open, usually in the form
85       "[datastore] vmname/vmname.vmdk".  See "FILE PARAMETER" below.
86

PARAMETERS

88       For opening a local VMDK file, the "file" parameter is required and
89       must be an absolute path.
90
91       For opening a remote connection, "file", "server", "thumbprint",
92       "user", "password" and "vm" are required.
93
94       All other parameters are optional.
95
96       compression=none
97       compression=zlib
98       compression=fastlz
99       compression=skipz
100           (nbdkit ≥ 1.24, vSphere ≥ 6.5)
101
102           Select the compression type used over the network between VDDK and
103           the VMware server.  The default is "none".  See VMware document
104           “Best Practices for NBD Transport”.
105
106       config=FILENAME
107           The name of the VDDK configuration file.
108
109           The config file controls rarely adjusted VDDK settings like log
110           level, caching and timeouts.  See the VDDK documentation for a full
111           list of settings.
112
113           VDDK itself looks in a few default locations for the configuration
114           file, usually including /etc/vmware/config and
115           $HOME/.vmware/config.  Using "config" overrides these defaults.
116
117       cookie=COOKIE
118           (vSphere ≥ 6.7)
119
120           Cookie from existing authenticated session on the host.
121
122           This changes the authentication type from "VIXDISKLIB_CRED_UID" to
123           "VIXDISKLIB_CRED_SESSIONID" which can improve performance.  The
124           cookie can be found by connecting to a VCenter Server over HTTPS
125           and retrieving the "vmware_soap_session" cookie.
126
127       [file=]FILENAME
128       [file=][datastore] vmname/vmname.vmdk
129           Set the name of the VMDK file to serve.
130
131           For local files you must supply an absolute path.  For remote files
132           see "FILE PARAMETER" section below.
133
134           If a VM has multiple disks, nbdkit can only serve one at a time.
135           To serve more than one you must run multiple copies of nbdkit.
136           (See "NOTES" below).
137
138           "file=" is a magic config key and may be omitted in most cases.
139           See "Magic parameters" in nbdkit(1).
140
141       libdir=PATHNAME
142           This sets the path of the VMware VDDK distribution.
143
144           VDDK uses this to load its own plugins, if this path is unspecified
145           or wrong then VDDK will work with reduced functionality.  See
146           "LIBRARY LOCATION" below.
147
148       nfchostport=PORT
149           Port used to establish an NFC connection to ESXi.  Defaults to 902.
150
151       password=PASSWORD
152           Set the password to use when connecting to the remote server.
153
154           Note that passing this on the command line is not secure on shared
155           machines.
156
157       password=-
158           Ask for the password (interactively) when nbdkit starts up.
159
160       password=+FILENAME
161           Read the password from the named file.  This is a secure method to
162           supply a password, as long as you set the permissions on the file
163           appropriately.
164
165       password=-FD
166           Read the password from file descriptor number "FD", inherited from
167           the parent process when nbdkit starts up.  This is also a secure
168           method to supply a password.
169
170       port=PORT
171           The port on the VCenter/ESXi host.  Defaults to 443.
172
173       server=HOSTNAME
174           The hostname or IP address of VCenter or ESXi host.
175
176       single-link=true
177           (nbdkit ≥ 1.12)
178
179           Open the current link, not the entire chain.  This corresponds to
180           the "VIXDISKLIB_FLAG_OPEN_SINGLE_LINK" flag.
181
182       snapshot=MOREF
183           The Managed Object Reference of the snapshot.  See "MANAGED OBJECT
184           REFERENCE" below.
185
186       thumbprint=THUMBPRINT
187           The SSL (SHA1) thumbprint for validating the SSL certificate.
188
189           The format is
190           "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" (20
191           hex digit pairs).
192
193           See "THUMBPRINTS" below for how to get this.
194
195       transports=MODE:MODE:...
196           List of one or more transport modes to use.  Possible values
197           include ‘nbd’, ‘nbdssl’, ‘san’, ‘hotadd’, ‘file’ (there may be
198           others).  If not given, VDDK will try to choose the best transport
199           mode.
200
201       unbuffered=true
202           (nbdkit ≥ 1.12)
203
204           Disable host caching.  This corresponds to the
205           "VIXDISKLIB_FLAG_OPEN_UNBUFFERED" flag.
206
207       user=USERNAME
208           The username to connect to the remote server as.
209
210       vm=moref=ID
211           The Managed Object Reference ("moref") of the virtual machine.  See
212           "MANAGED OBJECT REFERENCE" below.
213
214       vimapiver=APIVER
215           This parameter is ignored for backwards compatibility.
216

LIBRARY LOCATION

218       The VDDK library should not be placed on a system library path such as
219       /usr/lib.  The reason is that the VDDK library ships with recompiled
220       libraries like libcrypto.so and libstdc++.so that conflict with system
221       libraries.
222
223       You have two choices:
224
225       •   Place VDDK in the default libdir which is compiled into this
226           plugin, for example:
227
228            $ nbdkit vddk --dump-plugin | grep ^vddk_default_libdir
229            vddk_default_libdir=/usr/lib64/vmware-vix-disklib
230
231       •   But the best advice is to unpack the VDDK tarball anywhere you like
232           and set the "libdir=/path/to/vmware-vix-disklib-distrib".  For
233           example:
234
235            nbdkit vddk \
236                   libdir=/opt/vmware-vix-disklib-distrib \
237                   /path/to/file.vmdk
238
239   No need to set "LD_LIBRARY_PATH"
240       In nbdkit ≤ 1.16 you had to set the environment variable
241       "LD_LIBRARY_PATH" when using this plugin.  In nbdkit ≥ 1.18 this is not
242       recommended.
243

FILE PARAMETER

245       The "file" parameter can either be a local file, in which case it must
246       be the absolute path.  Or it can refer to a remote file on the VMware
247       server in the format "[datastore] vmname/vmname.vmdk".
248
249   Finding the remote filename
250       For remote files you can find the path using virsh(1).  For ESXi:
251
252        $ virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
253        ...
254         <disk type='file' device='disk'>
255           <source file='[datastore] vmname/vmname.vmdk'/>
256        ...
257
258       For vCenter the command is the same but the URI starts with "vpx://":
259
260        $ virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
261                dumpxml guestname
262
263       See also: https://libvirt.org/drvesx.html
264
265   Optional file= prefix
266       The "file=" part is optional, so these commands are equivalent:
267
268        nbdkit vddk file=/path/to/file.vmdk
269        nbdkit vddk /path/to/file.vmdk
270

THUMBPRINTS

272       The thumbprint is a 20 byte string containing the SSL (SHA1)
273       fingerprint of the remote VMware server and it is required when making
274       a remote connection.  There are several ways to obtain this.
275
276   Using a web browser
277       Visit "https://SERVER-NAME/folder" and log in.  Click the lock icon
278       next to the URL bar and navigate to the SHA-1 fingerprint of the site’s
279       certificate.  This 20 hex digit pair string can be directly copied to
280       the "thumbprint=" parameter.
281
282   Using openssl remotely
283       The following command will print the thumbprint of a VMware server
284       called "SERVER-NAME":
285
286        $ openssl s_client -connect SERVER-NAME:443 </dev/null |
287          openssl x509 -in /dev/stdin -fingerprint -sha1 -noout
288
289   By logging in to the ESXi or vCenter server
290       Log in to the ESXi hypervisor shell and run this command:
291
292        # openssl x509 -in /etc/vmware/ssl/rui.crt -fingerprint -sha1 -noout
293
294       For VMware vCenter servers the thumbprint is printed on the text
295       console of the server or is available by logging in to the server and
296       using this command:
297
298        # openssl x509 -in /etc/vmware-vpx/ssl/rui.crt -fingerprint -sha1 -noout
299
300   Trick: Get VDDK to tell you the thumbprint
301       Another way to get the thumbprint of a server is to connect to the
302       server using a bogus thumbprint with debugging enabled:
303
304        nbdkit -U - -fv vddk server=esxi.example.com [...] thumbprint=12 \
305               --run 'qemu-img info "$uri"'
306
307       The nbdkit process will try to connect (and fail because the thumbprint
308       is wrong).  However in the debug output will be a message such as this:
309
310        nbdkit: debug: VixDiskLibVim: Failed to verify SSL certificate: actual thumbprint=B2:31:BD:DE:9F:DB:9D:E0:78:EF:30:42:8A:41:B0:28:92:93:C8:DD expected=12
311
312       This gives you the server’s real thumbprint.  Of course this method is
313       not secure since it allows a Man-in-the-Middle (MITM) attack.
314

MANAGED OBJECT REFERENCE

316       Some use cases require you to pass in the Managed Object Reference
317       ("moref") of an object on the VMware server.
318
319       For VMware ESXi hypervisors, the "vm" moref is a number (eg.
320       "vm=moref=2").  For VMware VCenter it is a string beginning with "vm-")
321       (eg. "vm=moref=vm-16").  Across ESXi and vCenter the numbers are
322       different even for the same virtual machine.
323
324       If you have libvirt ≥ 3.7, the moref is available in the virsh(1)
325       "dumpxml" output:
326
327        $ virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
328        ...
329        <vmware:moref>2</vmware:moref>
330        ...
331
332       or:
333
334        $ virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
335              dumpxml guestname
336        ...
337        <vmware:moref>vm-16</vmware:moref>
338        ...
339
340       An alternative way to find the moref of a VM is using the
341       "moRefFinder.pl" script written by William Lam
342       (http://www.virtuallyghetto.com/2011/11/vsphere-moref-managed-object-reference.html
343       https://blogs.vmware.com/vsphere/2012/02/uniquely-identifying-virtual-machines-in-vsphere-and-vcloud-part-2-technical.html).
344

DUMP-PLUGIN OUTPUT

346       To query more information about the plugin (and whether it is working),
347       use:
348
349        nbdkit vddk --dump-plugin
350
351       or:
352
353        nbdkit vddk --dump-plugin libdir=/opt/vmware-vix-disklib-distrib
354
355       (see "LIBRARY LOCATION" above).
356
357       If the plugin is not present or not working you will get an error.
358
359       If it works the output will include:
360
361       "vddk_default_libdir=..."
362           The compiled-in library path.  Use "libdir=PATHNAME" to override
363           this at runtime.
364
365       "vddk_has_nfchostport=1"
366           If this is printed then the "nfchostport=PORT" parameter is
367           supported by this build.
368
369       "vddk_dll=..."
370           Prints the full path to the VDDK shared library.  Since this
371           requires a glibc extension it may not be available in all builds of
372           the plugin.
373

NOTES

375   Sector size limitation
376       The VDDK plugin can only answer read/write requests on whole 512 byte
377       sector boundaries.  This is because the VDDK Read and Write APIs only
378       take sector numbers.  If your client needs finer granularity, you can
379       use nbdkit-blocksize-filter(1) with the setting "minblock=512".
380
381   Threads
382       Handling threads in the VDDK API is complex and does not map well to
383       any of the thread models offered by nbdkit (see "THREADS" in
384       nbdkit-plugin(3)).  The plugin uses the nbdkit "SERIALIZE_REQUESTS"
385       model, but technically even this is not completely safe.  This is a
386       subject of future work.
387
388   Out of memory errors
389       In the verbose log you may see errors like:
390
391        nbdkit: vddk[3]: error: [NFC ERROR] NfcFssrvrProcessErrorMsg:
392        received NFC error 5 from server: Failed to allocate the
393        requested 2097176 bytes
394
395       This seems especially common when there are multiple parallel
396       connections open to the VMware server.
397
398       These can be caused by resource limits set on the VMware server.  You
399       can increase the limit for the NFC service by editing
400       /etc/vmware/hostd/config.xml and adjusting the "<maxMemory>" setting:
401
402        <nfcsvc>
403          <path>libnfcsvc.so</path>
404          <enabled>true</enabled>
405          <maxMemory>50331648</maxMemory>
406          <maxStreamMemory>10485760</maxStreamMemory>
407        </nfcsvc>
408
409       and restarting the "hostd" service:
410
411        # /etc/init.d/hostd restart
412
413       For more information see https://bugzilla.redhat.com/1614276.
414

SUPPORTED VERSIONS OF VDDK

416       This plugin requires VDDK ≥ 5.5.5, which in turn means that it is only
417       supported on x64-64 platforms.
418
419       It has been tested with all versions up to 7.0.3 (but should work with
420       future versions).
421
422       VDDK ≥ 6.0 should be used if possible.  This is the first version which
423       added Flush support which is crucial for data integrity when writing.
424
425       VDDK 6.7 was the first version that supported the
426       "VixDiskLib_QueryAllocatedBlocks" API, required to provide extent
427       information over NBD.
428

DEBUG FLAGS

430       Debugging messages can be very helpful if you have problems connecting
431       to VMware servers, or to find the list of available transport modes, or
432       to diagnose SAN problems:
433
434        nbdkit -f -v vddk file=FILENAME [...]
435
436       Additional debug flags are available:
437
438       -D vddk.diskinfo=1
439           Debug disk information returned by "GetInfo".
440
441       -D vddk.extents=1
442           Debug extents returned by "QueryAllocatedBlocks".
443
444       -D vddk.datapath=0
445           Suppress debugging of datapath calls ("Read" and "Write").
446
447       -D vddk.stats=1
448           When the plugin exits print some statistics about the amount of
449           time spent waiting on each VDDK call.
450

FILES

452       $plugindir/nbdkit-vddk-plugin.so
453           The plugin.
454
455           Use "nbdkit --dump-config" to find the location of $plugindir.
456

VERSION

458       "nbdkit-vddk-plugin" first appeared in nbdkit 1.2.
459

AUTHORS

468       Richard W.M. Jones
469

COPYRIGHT

471       Copyright (C) 2013-2020 Red Hat Inc.
472

LICENSE

474       Redistribution and use in source and binary forms, with or without
475       modification, are permitted provided that the following conditions are
476       met:
477
478       •   Redistributions of source code must retain the above copyright
479           notice, this list of conditions and the following disclaimer.
480
481       •   Redistributions in binary form must reproduce the above copyright
482           notice, this list of conditions and the following disclaimer in the
483           documentation and/or other materials provided with the
484           distribution.
485
486       •   Neither the name of Red Hat nor the names of its contributors may
487           be used to endorse or promote products derived from this software
488           without specific prior written permission.
489
490       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
491       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
492       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
493       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
494       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
495       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
496       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
497       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
498       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
499       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
500       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
501
502
503
504nbdkit-1.28.2                     2021-11-09             nbdkit-vddk-plugin(1)