1nbdkit-vddk-plugin(1) NBDKIT nbdkit-vddk-plugin(1)
2
6 nbdkit-vddk-plugin - nbdkit VMware VDDK plugin
7
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
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 The plugin can serve read-only (if the -r option is used) or
26 read/write.
27
29 Open a local VMDK file
30 nbdkit vddk file=/absolute/path/to/file.vmdk
31 Note that when opening local files the "file=" parameter must be an
33 absolute path.
34 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 Open a file on a remote VMware ESXi hypervisor
39 Connect directly to a VMware ESXi hypervisor and export a particular
40 file:
41 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 "user" and "password" must be specified. Use "password=+FILENAME" to
48 provide the password securely in a file.
49 "server" is the hostname of the ESXi server.
51 "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 "vm" is the Managed Object Reference ("moref") of the virtual machine.
57 See "MANAGED OBJECT REFERENCE" below.
58 "file" is the file you want to open, usually in the form
60 "[datastore] vmname/vmname.vmdk". See "FILE PARAMETER" below.
61 Open a file on a remote VMware vCenter server
63 Connect via VMware vCenter and export a particular file:
64 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 "user" and "password" must be specified. Use "password=+FILENAME" to
71 provide the password securely in a file.
72 "server" is the hostname of the vCenter server.
74 "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 "vm" is the Managed Object Reference ("moref") of the virtual machine.
80 See "MANAGED OBJECT REFERENCE" below.
81 "file" is the file you want to open, usually in the form
83 "[datastore] vmname/vmname.vmdk". See "FILE PARAMETER" below.
84
86 All parameters are optional except:
87 "file"
89 is required for opening a local VMDK file.
90 "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 config=FILENAME
101 The name of the VDDK configuration file.
102 cookie=COOKIE
104 Cookie from existing authenticated session on the host.
105 file=FILENAME
107 file=[datastore] vmname/vmname.vmdk
108 Set the name of the VMDK file to serve.
109 For local files you must supply an absolute path. For remote files
111 see "FILE PARAMETER" section below.
112 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 libdir=PATHNAME
118 This sets the path of the VMware VDDK distribution.
119 VDDK uses this to load its own plugins, if this path is unspecified
121 or wrong then VDDK will work with reduced functionality.
122 If the parameter is not given, then a hard-coded path determined at
124 compile time is used, see "DUMP-PLUGIN OUTPUT" below.
125 nfchostport=PORT
127 Port used to establish an NFC connection to ESXi. Defaults to 902.
128 (Only supported in VDDK ≥ 5.5.5 and ≥ 6.0.1)
130 password=PASSWORD
132 Set the password to use when connecting to the remote server.
133 Note that passing this on the command line is not secure on shared
135 machines.
136 password=-
138 Ask for the password (interactively) when nbdkit starts up.
139 password=+FILENAME
141 Read the password from the named file. This is a secure method to
142 supply a password, as long as you set the permissions on the file
143 appropriately.
144 password=-FD
146 Read the password from file descriptor number "FD", inherited from
147 the parent process when nbdkit starts up. This is also a secure
148 method to supply a password.
149 port=PORT
151 The port on the VCenter/ESXi host. Defaults to 443.
152 server=HOSTNAME
154 The hostname or IP address of VCenter or ESXi host.
155 single-link=true
157 Open the current link, not the entire chain. This corresponds to
158 the "VIXDISKLIB_FLAG_OPEN_SINGLE_LINK" flag.
159 snapshot=MOREF
161 The Managed Object Reference of the snapshot. See "MANAGED OBJECT
162 REFERENCE" below.
163 thumbprint=THUMBPRINT
165 The SSL (SHA1) thumbprint for validating the SSL certificate.
166 The format is
168 "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" (20
169 hex digit pairs).
170 See "THUMBPRINTS" below for how to get this.
172 transports=MODE:MODE:...
174 List of one or more transport modes to use. Possible values
175 include ‘nbd’, ‘nbdssl’, ‘san’, ‘hotadd’, ‘file’ (there may be
176 others). If not given, VDDK will try to choose the best transport
177 mode.
178 unbuffered=true
180 Disable host caching. This corresponds to the
181 "VIXDISKLIB_FLAG_OPEN_UNBUFFERED" flag.
182 user=USERNAME
184 The username to connect to the remote server as.
185 vm=moref=ID
187 The Managed Object Reference ("moref") of the virtual machine. See
188 "MANAGED OBJECT REFERENCE" below.
189 vimapiver=APIVER
191 This parameter is ignored for backwards compatibility.
192
194 If the VDDK library (libvixDiskLib.so.N) is located on a non-standard
195 path, you may need to set "LD_LIBRARY_PATH" or modify /etc/ld.so.conf
196 before this plugin will work. In addition you may want to set the
197 "libdir" parameter so that the VDDK library can load plugins like
198 Advanced Transport.
199 Usually the VDDK distribution directory should be passed as the
201 "libdir" parameter and set "LD_LIBRARY_PATH" to the lib64 subdirectory:
202 LD_LIBRARY_PATH=/path/to/vmware-vix-disklib-distrib/lib64 \
204 nbdkit vddk \
205 libdir=/path/to/vmware-vix-disklib-distrib \
206 file=file.vmdk
207 VDDK itself looks in a few default locations for the optional
209 configuration file, usually including /etc/vmware/config and
210 $HOME/.vmware/config, but you can override this using the "config"
211 parameter.
212
214 The "file" parameter can either be a local file, in which case it must
215 be the absolute path. Or it can refer to a remote file on the VMware
216 server in the format "[datastore] vmname/vmname.vmdk".
217 For remote files you can find the path using virsh(1). For ESXi:
219 virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
221 For vCenter:
223 virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
225 dumpxml guestname
226
228 The thumbprint is a 20 byte string containing the SSL (SHA1)
229 fingerprint of the remote VMware server and it is required when making
230 a remote connection. There are two ways to obtain this.
231 Extracting thumbprint from ESXi or vCenter server
233 To extract the thumbprint, log in to the ESXi hypervisor shell and run
234 this command:
235 # openssl x509 -in /etc/vmware/ssl/rui.crt -fingerprint -sha1 -noout
237 For VMware vCenter servers the thumbprint is printed on the text
239 console of the server or is available by logging in to the server and
240 using this command:
241 # openssl x509 -in /etc/vmware-vpx/ssl/rui.crt -fingerprint -sha1 -noout
243 Trick: Get VDDK to tell you the thumbprint
245 Another (easier) way to get the thumbprint of a server is to connect to
246 the server using a bogus thumbprint with debugging enabled:
247 nbdkit -f -v vddk server=esxi.example.com [...] thumbprint=12
249 qemu-img info nbd:localhost:10809
250 The nbdkit process will try to connect (and fail because the thumbprint
252 is wrong). However in the debug output will be a message such as this:
253 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
255 This gives you the server’s real thumbprint. Of course this method is
257 not secure since it allows a Man-in-the-Middle (MITM) attack.
258
260 Some parameters require you to pass in the Managed Object Reference
261 ("moref") of an object on the VMware server.
262 For VMware ESXi hypervisors, the "vm" moref is a number (eg.
264 "vm=moref=2"). For VMware VCenter it is a string beginning with "vm-")
265 (eg. "vm=moref=vm-16"). Across ESXi and vCenter the numbers are
266 different even for the same virtual machine.
267 If you have libvirt ≥ 3.7, the moref is available in the virsh(1)
269 "dumpxml" output:
270 $ virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
272 ...
273 <vmware:moref>2</vmware:moref>
274 ...
275 or:
277 $ virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
279 dumpxml guestname
280 ...
281 <vmware:moref>vm-16</vmware:moref>
282 ...
283 An alternative way to find the moref of a VM is using the
285 "moRefFinder.pl" script written by William Lam
286 (http://www.virtuallyghetto.com/2011/11/vsphere-moref-managed-object-reference.html
287 https://blogs.vmware.com/vsphere/2012/02/uniquely-identifying-virtual-machines-in-vsphere-and-vcloud-part-2-technical.html).
288
290 To query more information about the plugin (and whether it is working),
291 use:
292 nbdkit vddk --dump-plugin
294 If the plugin is not present, not working or the library path is wrong
296 you will get an error.
297 If it works the output will include:
299 "vddk_default_libdir=..."
301 The compiled-in library path. Use "libdir=PATHNAME" to override
302 this at runtime.
303 "vddk_has_nfchostport=1"
305 If this is printed then the "nfchostport=PORT" parameter is
306 supported by this build.
307 "vddk_dll=..."
309 Prints the full path to the VDDK shared library. Since this
310 requires a glibc extension it may not be available in all builds of
311 the plugin.
312
314 Debugging messages can be very helpful if you have problems connecting
315 to VMware servers, or to find the list of available transport modes, or
316 to diagnose SAN problems.
317 Run nbdkit like this to see all debugging messages:
319 nbdkit -f -v vddk file=FILENAME [...]
321
323 Sector size limitation
324 The VDDK plugin can only answer read/write requests on whole 512 byte
325 sector boundaries. This is because the VDDK Read and Write APIs only
326 take sector numbers.
327 The plugin could be extended in future to support byte granularity, but
329 common NBD clients don't need it so it's not a priority.
330 Threads
332 Handling threads in the VDDK API is complex and does not map well to
333 any of the thread models offered by nbdkit (see "THREADS" in
334 nbdkit-plugin(3)). The plugin uses the nbdkit "SERIALIZE_ALL_REQUESTS"
335 model, but technically even this is not completely safe. This is a
336 subject of future work.
337 Export names
339 For VMs with multiple disks, it would be nice to map the disk names to
340 NBD export names. However nbdkit core will need to be extended to
341 support this.
342 Out of memory errors
344 In the verbose log you may see errors like:
345 nbdkit: vddk[3]: error: [NFC ERROR] NfcFssrvrProcessErrorMsg:
347 received NFC error 5 from server: Failed to allocate the
348 requested 2097176 bytes
349 This seems especially common when there are multiple parallel
351 connections open to the VMware server.
352 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 <nfcsvc>
358 <path>libnfcsvc.so</path>
359 <enabled>true</enabled>
360 <maxMemory>50331648</maxMemory>
361 <maxStreamMemory>10485760</maxStreamMemory>
362 </nfcsvc>
363 and restarting the "hostd" service:
365 # /etc/init.d/hostd restart
367 For more information see https://bugzilla.redhat.com/1614276.
369
371 This plugin requires VDDK ≥ 5.1.1.
372 It has been tested with all versions up to 6.7 (but should work with
374 future versions).
375 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
380 $plugindir/nbdkit-vddk-plugin.so
381 The plugin.
382 Use "nbdkit --dump-config" to find the location of $plugindir.
384
386 "nbdkit-vddk-plugin" first appeared in nbdkit 1.2.
387
389 nbdkit(1), nbdkit-plugin(3), nbdkit-readahead-filter(1),
390 nbdkit-retry-filter(1), virsh(1),
391 https://www.vmware.com/support/developer/vddk/
392
394 Richard W.M. Jones
395
397 Copyright (C) 2013-2019 Red Hat Inc.
398
400 Redistribution and use in source and binary forms, with or without
401 modification, are permitted provided that the following conditions are
402 met:
403 · Redistributions of source code must retain the above copyright
405 notice, this list of conditions and the following disclaimer.
406 · Redistributions in binary form must reproduce the above copyright
408 notice, this list of conditions and the following disclaimer in the
409 documentation and/or other materials provided with the
410 distribution.
411 · Neither the name of Red Hat nor the names of its contributors may
413 be used to endorse or promote products derived from this software
414 without specific prior written permission.
415 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
417 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
418 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
419 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
420 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
421 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
422 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
423 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
424 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
425 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
426 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
427nbdkit-1.16.1 2019-12-03 nbdkit-vddk-plugin(1)