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                    [config=FILENAME] [cookie=COOKIE] [libdir=LIBRARY]
11                    [nfchostport=PORT] [single-link=true]
12                    [password=PASSWORD | password=- | password=+FILENAME
13                    | password=-FD]
14                    [port=PORT] [server=HOSTNAME] [snapshot=MOREF]
15                    [thumbprint=THUMBPRINT] [transports=MODE:MODE:...]
16                    [unbuffered=true] [user=USERNAME] [vm=moref=ID]
17        nbdkit vddk --dump-plugin
18

DESCRIPTION

20       "nbdkit-vddk-plugin" is an nbdkit(1) plugin that serves files from
21       local VMware VMDK files, VMware ESXi servers, VMware VCenter servers,
22       and other sources.  It requires VMware's proprietary VDDK library that
23       you must download yourself separately.
24
25       The plugin can serve read-only (if the -r option is used) or
26       read/write.
27

EXAMPLES

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

PARAMETERS

86       All parameters are optional except:
87
88       "file"
89           is required for opening a local VMDK file.
90
91       "file"
92       "server"
93       "thumbprint"
94       "user"
95       "password"
96       "vm"
97           When making a remote connection you must supply all of these
98           parameters.
99
100       config=FILENAME
101           The name of the VDDK configuration file.
102
103       cookie=COOKIE
104           Cookie from existing authenticated session on the host.
105
106       file=FILENAME
107       file=[datastore] vmname/vmname.vmdk
108           Set the name of the VMDK file to serve.
109
110           For local files you must supply an absolute path.  For remote files
111           see "FILE PARAMETER" section below.
112
113           If a VM has multiple disks, nbdkit can only serve one at a time.
114           To serve more than one you must run multiple copies of nbdkit.
115           (See "NOTES" below).
116
117           "file=" is a magic config key and may be omitted in most cases.
118           See "Magic parameters" in nbdkit(1).
119
120       libdir=PATHNAME
121           This sets the path of the VMware VDDK distribution.
122
123           VDDK uses this to load its own plugins, if this path is unspecified
124           or wrong then VDDK will work with reduced functionality.
125
126           If the parameter is not given, then a hard-coded path determined at
127           compile time is used, see "DUMP-PLUGIN OUTPUT" below.
128
129       nfchostport=PORT
130           Port used to establish an NFC connection to ESXi.  Defaults to 902.
131
132           (Only supported in VDDK ≥ 5.5.5 and ≥ 6.0.1)
133
134       password=PASSWORD
135           Set the password to use when connecting to the remote server.
136
137           Note that passing this on the command line is not secure on shared
138           machines.
139
140       password=-
141           Ask for the password (interactively) when nbdkit starts up.
142
143       password=+FILENAME
144           Read the password from the named file.  This is a secure method to
145           supply a password, as long as you set the permissions on the file
146           appropriately.
147
148       password=-FD
149           Read the password from file descriptor number "FD", inherited from
150           the parent process when nbdkit starts up.  This is also a secure
151           method to supply a password.
152
153       port=PORT
154           The port on the VCenter/ESXi host.  Defaults to 443.
155
156       server=HOSTNAME
157           The hostname or IP address of VCenter or ESXi host.
158
159       single-link=true
160           Open the current link, not the entire chain.  This corresponds to
161           the "VIXDISKLIB_FLAG_OPEN_SINGLE_LINK" flag.
162
163       snapshot=MOREF
164           The Managed Object Reference of the snapshot.  See "MANAGED OBJECT
165           REFERENCE" below.
166
167       thumbprint=THUMBPRINT
168           The SSL (SHA1) thumbprint for validating the SSL certificate.
169
170           The format is
171           "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" (20
172           hex digit pairs).
173
174           See "THUMBPRINTS" below for how to get this.
175
176       transports=MODE:MODE:...
177           List of one or more transport modes to use.  Possible values
178           include ‘nbd’, ‘nbdssl’, ‘san’, ‘hotadd’, ‘file’ (there may be
179           others).  If not given, VDDK will try to choose the best transport
180           mode.
181
182       unbuffered=true
183           Disable host caching.  This corresponds to the
184           "VIXDISKLIB_FLAG_OPEN_UNBUFFERED" flag.
185
186       user=USERNAME
187           The username to connect to the remote server as.
188
189       vm=moref=ID
190           The Managed Object Reference ("moref") of the virtual machine.  See
191           "MANAGED OBJECT REFERENCE" below.
192
193       vimapiver=APIVER
194           This parameter is ignored for backwards compatibility.
195

LIBRARY AND CONFIG FILE LOCATIONS

197       The VDDK library should not be placed on a system library path such as
198       /usr/lib.  The reason for this is that the VDDK library is shipped with
199       recompiled libraries like libcrypto.so and libstdc++.so that can
200       conflict with system libraries.
201
202       You have two choices:
203
204       ·   Place VDDK in the default libdir which is compiled into this
205           plugin, for example:
206
207            $ nbdkit vddk --dump-plugin | grep ^vddk_default_libdir
208            vddk_default_libdir=/usr/lib64/vmware-vix-disklib
209
210       ·   But the most common way is to set the "libdir" parameter to point
211           to vmware-vix-disklib-distrib/ (which you can unpack anywhere you
212           like), and this plugin will find the VDDK library from there.  For
213           example:
214
215            nbdkit vddk \
216                libdir=/path/to/vmware-vix-disklib-distrib \
217                file=file.vmdk
218
219       VDDK itself looks in a few default locations for the optional
220       configuration file, usually including /etc/vmware/config and
221       $HOME/.vmware/config, but you can override this using the "config"
222       parameter.
223
224   No need to set "LD_LIBRARY_PATH"
225       In nbdkit ≤ 1.16 you had to set the environment variable
226       "LD_LIBRARY_PATH" when using this plugin.  In nbdkit ≥ 1.18 this is not
227       recommended.
228

FILE PARAMETER

230       The "file" parameter can either be a local file, in which case it must
231       be the absolute path.  Or it can refer to a remote file on the VMware
232       server in the format "[datastore] vmname/vmname.vmdk".
233
234       For remote files you can find the path using virsh(1).  For ESXi:
235
236        virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
237
238       For vCenter:
239
240        virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
241              dumpxml guestname
242

THUMBPRINTS

244       The thumbprint is a 20 byte string containing the SSL (SHA1)
245       fingerprint of the remote VMware server and it is required when making
246       a remote connection.  There are two ways to obtain this.
247
248   Extracting thumbprint from ESXi or vCenter server
249       To extract the thumbprint, log in to the ESXi hypervisor shell and run
250       this command:
251
252        # openssl x509 -in /etc/vmware/ssl/rui.crt -fingerprint -sha1 -noout
253
254       For VMware vCenter servers the thumbprint is printed on the text
255       console of the server or is available by logging in to the server and
256       using this command:
257
258        # openssl x509 -in /etc/vmware-vpx/ssl/rui.crt -fingerprint -sha1 -noout
259
260   Trick: Get VDDK to tell you the thumbprint
261       Another (easier) way to get the thumbprint of a server is to connect to
262       the server using a bogus thumbprint with debugging enabled:
263
264        nbdkit -f -v vddk server=esxi.example.com [...] thumbprint=12
265        qemu-img info nbd:localhost:10809
266
267       The nbdkit process will try to connect (and fail because the thumbprint
268       is wrong).  However in the debug output will be a message such as this:
269
270        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
271
272       This gives you the server’s real thumbprint.  Of course this method is
273       not secure since it allows a Man-in-the-Middle (MITM) attack.
274

MANAGED OBJECT REFERENCE

276       Some parameters require you to pass in the Managed Object Reference
277       ("moref") of an object on the VMware server.
278
279       For VMware ESXi hypervisors, the "vm" moref is a number (eg.
280       "vm=moref=2").  For VMware VCenter it is a string beginning with "vm-")
281       (eg. "vm=moref=vm-16").  Across ESXi and vCenter the numbers are
282       different even for the same virtual machine.
283
284       If you have libvirt ≥ 3.7, the moref is available in the virsh(1)
285       "dumpxml" output:
286
287        $ virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
288        ...
289        <vmware:moref>2</vmware:moref>
290        ...
291
292       or:
293
294        $ virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
295              dumpxml guestname
296        ...
297        <vmware:moref>vm-16</vmware:moref>
298        ...
299
300       An alternative way to find the moref of a VM is using the
301       "moRefFinder.pl" script written by William Lam
302       (http://www.virtuallyghetto.com/2011/11/vsphere-moref-managed-object-reference.html
303       https://blogs.vmware.com/vsphere/2012/02/uniquely-identifying-virtual-machines-in-vsphere-and-vcloud-part-2-technical.html).
304

DUMP-PLUGIN OUTPUT

306       To query more information about the plugin (and whether it is working),
307       use:
308
309        nbdkit vddk --dump-plugin
310
311       If the plugin is not present, not working or the library path is wrong
312       you will get an error.
313
314       If it works the output will include:
315
316       "vddk_default_libdir=..."
317           The compiled-in library path.  Use "libdir=PATHNAME" to override
318           this at runtime.
319
320       "vddk_has_nfchostport=1"
321           If this is printed then the "nfchostport=PORT" parameter is
322           supported by this build.
323
324       "vddk_dll=..."
325           Prints the full path to the VDDK shared library.  Since this
326           requires a glibc extension it may not be available in all builds of
327           the plugin.
328

NOTES

330   Sector size limitation
331       The VDDK plugin can only answer read/write requests on whole 512 byte
332       sector boundaries.  This is because the VDDK Read and Write APIs only
333       take sector numbers.  If your client needs finer granularity, you can
334       use nbdkit-blocksize-filter(3) with the setting "minblock=512".
335
336   Threads
337       Handling threads in the VDDK API is complex and does not map well to
338       any of the thread models offered by nbdkit (see "THREADS" in
339       nbdkit-plugin(3)).  The plugin uses the nbdkit "SERIALIZE_ALL_REQUESTS"
340       model, but technically even this is not completely safe.  This is a
341       subject of future work.
342
343   Out of memory errors
344       In the verbose log you may see errors like:
345
346        nbdkit: vddk[3]: error: [NFC ERROR] NfcFssrvrProcessErrorMsg:
347        received NFC error 5 from server: Failed to allocate the
348        requested 2097176 bytes
349
350       This seems especially common when there are multiple parallel
351       connections open to the VMware server.
352
353       These can be caused by resource limits set on the VMware server.  You
354       can increase the limit for the NFC service by editing
355       /etc/vmware/hostd/config.xml and adjusting the "<maxMemory>" setting:
356
357        <nfcsvc>
358          <path>libnfcsvc.so</path>
359          <enabled>true</enabled>
360          <maxMemory>50331648</maxMemory>
361          <maxStreamMemory>10485760</maxStreamMemory>
362        </nfcsvc>
363
364       and restarting the "hostd" service:
365
366        # /etc/init.d/hostd restart
367
368       For more information see https://bugzilla.redhat.com/1614276.
369

SUPPORTED VERSIONS OF VDDK

371       This plugin requires VDDK ≥ 5.1.1.
372
373       It has been tested with all versions up to 6.7 (but should work with
374       future versions).
375
376       VDDK ≥ 6.0 should be used if possible.  This is the first version which
377       added Flush support which is crucial for data integrity when writing.
378

DEBUG FLAGS

380       Debugging messages can be very helpful if you have problems connecting
381       to VMware servers, or to find the list of available transport modes, or
382       to diagnose SAN problems:
383
384        nbdkit -f -v vddk file=FILENAME [...]
385
386       Additional debug flags are available:
387
388       -D vddk.diskinfo=1
389           Debug disk information returned by "GetInfo".
390
391       -D vddk.extents=1
392           Debug extents returned by "QueryAllocatedBlocks".
393
394       -D vddk.datapath=0
395           Suppress debugging of datapath calls ("Read" and "Write").
396

FILES

398       $plugindir/nbdkit-vddk-plugin.so
399           The plugin.
400
401           Use "nbdkit --dump-config" to find the location of $plugindir.
402

VERSION

404       "nbdkit-vddk-plugin" first appeared in nbdkit 1.2.
405

AUTHORS

412       Richard W.M. Jones
413

COPYRIGHT

415       Copyright (C) 2013-2020 Red Hat Inc.
416

LICENSE

418       Redistribution and use in source and binary forms, with or without
419       modification, are permitted provided that the following conditions are
420       met:
421
422       ·   Redistributions of source code must retain the above copyright
423           notice, this list of conditions and the following disclaimer.
424
425       ·   Redistributions in binary form must reproduce the above copyright
426           notice, this list of conditions and the following disclaimer in the
427           documentation and/or other materials provided with the
428           distribution.
429
430       ·   Neither the name of Red Hat nor the names of its contributors may
431           be used to endorse or promote products derived from this software
432           without specific prior written permission.
433
434       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
435       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
436       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
437       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
438       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
439       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
440       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
441       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
442       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
443       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
444       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
445
446
447
448nbdkit-1.18.4                     2020-04-16             nbdkit-vddk-plugin(1)