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       If the plugin is not present, not working or the library path is wrong
352       you will get an error.
353
354       If it works the output will include:
355
356       "vddk_default_libdir=..."
357           The compiled-in library path.  Use "libdir=PATHNAME" to override
358           this at runtime.
359
360       "vddk_has_nfchostport=1"
361           If this is printed then the "nfchostport=PORT" parameter is
362           supported by this build.
363
364       "vddk_dll=..."
365           Prints the full path to the VDDK shared library.  Since this
366           requires a glibc extension it may not be available in all builds of
367           the plugin.
368

NOTES

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

SUPPORTED VERSIONS OF VDDK

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

DEBUG FLAGS

425       Debugging messages can be very helpful if you have problems connecting
426       to VMware servers, or to find the list of available transport modes, or
427       to diagnose SAN problems:
428
429        nbdkit -f -v vddk file=FILENAME [...]
430
431       Additional debug flags are available:
432
433       -D vddk.diskinfo=1
434           Debug disk information returned by "GetInfo".
435
436       -D vddk.extents=1
437           Debug extents returned by "QueryAllocatedBlocks".
438
439       -D vddk.datapath=0
440           Suppress debugging of datapath calls ("Read" and "Write").
441

FILES

443       $plugindir/nbdkit-vddk-plugin.so
444           The plugin.
445
446           Use "nbdkit --dump-config" to find the location of $plugindir.
447

VERSION

449       "nbdkit-vddk-plugin" first appeared in nbdkit 1.2.
450

AUTHORS

459       Richard W.M. Jones
460

COPYRIGHT

462       Copyright (C) 2013-2020 Red Hat Inc.
463

LICENSE

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