1nbdkit-vddk-plugin(1) NBDKIT nbdkit-vddk-plugin(1)
2
6 nbdkit-vddk-plugin - nbdkit VMware VDDK plugin
7
9 nbdkit vddk file=FILENAME [config=FILENAME] [libdir=LIBRARY]
10 [vm=moref=ID] [server=HOSTNAME] [user=USERNAME]
11 [password=PASSWORD | password=- | password=+FILENAME]
12 [cookie=COOKIE] [thumbprint=THUMBPRINT]
13 [port=PORT] [nfchostport=PORT] [single-link=true]
14 [snapshot=MOREF] [transports=MODE:MODE:...]
15 [unbuffered=true]
16 nbdkit vddk --dump-plugin
17
19 "nbdkit-vddk-plugin" is an nbdkit(1) plugin that serves files from
20 local VMware VMDK files, VMware ESXi servers, VMware VCenter servers,
21 and other sources. It requires VMware's proprietary VDDK library that
22 you must download yourself separately.
23 The plugin can serve read-only (if the -r option is used) or
25 read/write.
26
28 If the VDDK library (libvixDiskLib.so.N) is located on a non-standard
29 path, you may need to set "LD_LIBRARY_PATH" or modify /etc/ld.so.conf
30 before this plugin will work. In addition you may want to set the
31 "libdir" parameter so that the VDDK library can load plugins like
32 Advanced Transport.
33 For 64 bit platforms pass the lib64 subdirectory:
35 export LD_LIBRARY_PATH=/path/to/vmware-vix-disklib-distrib/lib64
37 For 32 bit platforms pass the lib32 subdirectory:
39 export LD_LIBRARY_PATH=/path/to/vmware-vix-disklib-distrib/lib32
41 Then pass the VDDK distribution directory as "libdir" along with other
43 parameters as required:
44 nbdkit vddk \
46 libdir=/path/to/vmware-vix-disklib-distrib \
47 file=file.vmdk
48 VDDK itself looks in a few default locations for the optional
50 configuration file, usually including /etc/vmware/config and
51 $HOME/.vmware/config, but you can override this using the "config"
52 parameter.
53
55 All parameters are optional except:
56 "file"
58 is required for opening a local VMDK file.
59 "server"
61 "thumbprint"
62 "user"
63 "password"
64 "vm"
65 "file"
66 When making a remote connection you must supply all 6 of these
67 parameters.
68 See the "EXAMPLES" section below for local and remote command lines.
70 config=FILENAME
72 The name of the VDDK configuration file.
73 cookie=COOKIE
75 Cookie from existing authenticated session on the host.
76 file=FILENAME
78 Set the name of the VMDK file to serve.
79 For local files you must supply an absolute path.
81 For remote files this is usually a path on the VMware server with
83 the format "[datastore] path/to/file.vmdk". You can find the path
84 using virsh(1). For ESXi:
85 virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
87 For vCenter:
89 virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
91 dumpxml guestname
92 If a VM has multiple disks, nbdkit can only serve one at a time.
94 To serve more than one you must run multiple copies of nbdkit.
95 (See "NOTES" below).
96 libdir=PATHNAME
98 This sets the path of the VMware VDDK distribution.
99 VDDK uses this to load its own plugins, if this path is unspecified
101 or wrong then VDDK will work with reduced functionality.
102 If the parameter is not given, then a hard-coded path determined at
104 compile time is used, see "DUMP-PLUGIN OUTPUT" below.
105 nfchostport=PORT
107 Port used to establish an NFC connection to ESXi. Defaults to 902.
108 (Only supported in VDDK ≥ 5.5.5 and ≥ 6.0.1)
110 password=PASSWORD
112 Set the password to use when connecting to the remote server.
113 Note that passing this on the command line is not secure on shared
115 machines.
116 password=-
118 Ask for the password (interactively) when nbdkit starts up.
119 password=+FILENAME
121 Read the password from the named file. This is the most secure
122 method to supply a password, as long as you set the permissions on
123 the file appropriately.
124 port=PORT
126 The port on the VCenter/ESXi host. Defaults to 443.
127 server=HOSTNAME
129 The hostname or IP address of VCenter or ESXi host.
130 single-link=true
132 Open the current link, not the entire chain. This corresponds to
133 the "VIXDISKLIB_FLAG_OPEN_SINGLE_LINK" flag.
134 snapshot=MOREF
136 The Managed Object Reference of the snapshot.
137 thumbprint=THUMBPRINT
139 The SSL (SHA1) thumbprint for validating the SSL certificate.
140 The format is
142 "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" (20
143 hex digit pairs).
144 See "THUMBPRINTS" below for how to get this.
146 transports=MODE:MODE:...
148 List of one or more transport modes to use. Possible values
149 include ‘nbd’, ‘nbdssl’, ‘san’, ‘hotadd’, ‘file’ (there may be
150 others). If not given, VDDK will try to choose the best transport
151 mode.
152 unbuffered=true
154 Disable host caching. This corresponds to the
155 "VIXDISKLIB_FLAG_OPEN_UNBUFFERED" flag.
156 user=USERNAME
158 The username to connect to the remote server as.
159 vm=moref=ID
161 The Managed Object Reference ("moref") of the virtual machine.
162 For VMware ESXi hypervisors, this is a number (eg. "vm=moref=2").
164 For VMware VCenter, this is a string beginning with "vm-") (eg.
165 "vm=moref=vm-16"). Across ESXi and vCenter the numbers are
166 different even for the same virtual machine.
167 If you have libvirt ≥ 3.7, the moref is available in the virsh(1)
169 "dumpxml" output:
170 $ virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
172 ...
173 <vmware:moref>2</vmware:moref>
174 ...
175 or:
177 $ virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
179 dumpxml guestname
180 ...
181 <vmware:moref>vm-16</vmware:moref>
182 ...
183 An alternative way to find the moref of a VM is using the
185 "moRefFinder.pl" script written by William Lam
186 (http://www.virtuallyghetto.com/2011/11/vsphere-moref-managed-object-reference.html
187 https://blogs.vmware.com/vsphere/2012/02/uniquely-identifying-virtual-machines-in-vsphere-and-vcloud-part-2-technical.html).
188 vimapiver=APIVER
190 This parameter is ignored for backwards compatibility.
191
193 Open a local VMDK file
194 nbdkit vddk file=/absolute/path/to/file.vmdk
195 Note that when opening local files the "file=" parameter must be an
197 absolute path.
198 Because VDDK needs to take a lock on this file, the file must be on a
200 writable filesystem (unless you use the -r option).
201 Open a file on a remote VMware ESXi hypervisor
203 Connect directly to a VMware ESXi hypervisor and export a particular
204 file:
205 nbdkit vddk user=root password=+/tmp/rootpw \
207 server=esxi.example.com thumbprint=xx:xx:xx:... \
208 vm=moref=2 \
209 file="[datastore1] Fedora/Fedora.vmdk"
210 "user" and "password" must be specified. Use "password=+FILENAME" to
212 provide the password securely in a file.
213 "server" is the hostname of the ESXi server. "thumbprint" is the thumb
215 print for validating the SSL certificate. How to find the thumb print
216 of a server is described in "THUMBPRINTS" below.
217 "vm" is the Managed Object Reference ("moref") of the virtual machine.
219 To find this using virsh(1) or the "moRefFinder.pl" script, see
220 "PARAMETERS" above. Note that it is different from the moref used by
221 vCenter, and is just a single number.
222 "file" is the actual file you want to open, usually in the form
224 "[datastore] vmname/vmname.vmdk". You can find this from virsh(1) as
225 described in "PARAMETERS" above.
226 Open a file on a remote VMware vCenter server
228 Connect via VMware vCenter and export a particular file:
229 nbdkit vddk user=root password=vmware \
231 server=vcenter.example.com thumbprint=xx:xx:xx:... \
232 vm=moref=vm-16 \
233 file="[datastore1] Fedora/Fedora.vmdk"
234 "user" and "password" must be specified. Use "password=+FILENAME" to
236 provide the password securely in a file.
237 "server" is the hostname of the vCenter server. "thumbprint" is the
239 thumb print for validating the SSL certificate. How to find the thumb
240 print of a server is described in "THUMBPRINTS" below.
241 "vm" is the Managed Object Reference ("moref") of the virtual machine.
243 To find this using virsh(1) or the "moRefFinder.pl" script, see
244 "PARAMETERS" above. Note that it is different from the moref used by
245 ESXi, and always begins with the prefix "vm-".
246 "file" is the actual file you want to open, usually in the form
248 "[datastore] vmname/vmname.vmdk". You can find this from virsh(1) as
249 described in "PARAMETERS" above.
250
252 The thumbprint is a 20 byte string containing the SSL (SHA1)
253 fingerprint of the remote VMware server and it is required when making
254 a remote connection. There are two ways to obtain this.
255 Extracting thumbprint from ESXi or vCenter server
257 To extract the thumbprint, log in to the ESXi hypervisor shell and run
258 this command:
259 # openssl x509 -in /etc/vmware/ssl/rui.crt -fingerprint -sha1 -noout
261 For VMware vCenter servers the thumbprint is printed on the text
263 console of the server or is available by logging in to the server and
264 using this command:
265 # openssl x509 -in /etc/vmware-vpx/ssl/rui.crt -fingerprint -sha1 -noout
267 Trick: Get VDDK to tell you the thumbprint
269 Another (easier) way to get the thumbprint of a server is to connect to
270 the server using a bogus thumbprint with debugging enabled:
271 nbdkit -f -v vddk server=esxi.example.com [...] thumbprint=12
273 qemu-img info nbd:localhost:10809
274 The nbdkit process will try to connect (and fail because the thumbprint
276 is wrong). However in the debug output will be a message such as this:
277 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
279 This gives you the server’s real thumbprint. Of course this method is
281 not secure since it allows a Man-in-the-Middle (MITM) attack.
282
284 To query more information about the plugin (and whether it is working),
285 use:
286 nbdkit vddk --dump-plugin
288 If the plugin is not present, not working or the library path is wrong
290 you will get an error.
291 If it works the output will include:
293 "vddk_default_libdir=..."
295 The compiled-in library path. Use "libdir=PATHNAME" to override
296 this at runtime.
297 "vddk_has_nfchostport=1"
299 If this is printed then the "nfchostport=PORT" parameter is
300 supported by this build.
301 "vddk_dll=..."
303 Prints the full path to the VDDK shared library. Since this
304 requires a glibc extension it may not be available in all builds of
305 the plugin.
306
308 Debugging messages can be very helpful if you have problems connecting
309 to VMware servers, or to find the list of available transport modes, or
310 to diagnose SAN problems.
311 Run nbdkit like this to see all debugging messages:
313 nbdkit -f -v vddk file=FILENAME [...]
315
317 Sector size limitation
318 The VDDK plugin can only answer read/write requests on whole 512 byte
319 sector boundaries. This is because the VDDK Read and Write APIs only
320 take sector numbers.
321 The plugin could be extended in future to support byte granularity, but
323 common NBD clients don't need it so it's not a priority.
324 Threads
326 Handling threads in the VDDK API is complex and does not map well to
327 any of the thread models offered by nbdkit (see "THREADS" in
328 nbdkit-plugin(3)). The plugin uses the nbdkit "SERIALIZE_ALL_REQUESTS"
329 model, but technically even this is not completely safe. This is a
330 subject of future work.
331 Export names
333 For VMs with multiple disks, it would be nice to map the disk names to
334 NBD export names. However nbdkit core will need to be extended to
335 support this.
336 Out of memory errors
338 In the verbose log you may see errors like:
339 nbdkit: vddk[3]: error: [NFC ERROR] NfcFssrvrProcessErrorMsg:
341 received NFC error 5 from server: Failed to allocate the
342 requested 2097176 bytes
343 This seems especially common when there are multiple parallel
345 connections open to the VMware server.
346 These can be caused by resource limits set on the VMware server. You
348 can increase the limit for the NFC service by editing
349 /etc/vmware/hostd/config.xml and adjusting the "<maxMemory>" setting:
350 <nfcsvc>
352 <path>libnfcsvc.so</path>
353 <enabled>true</enabled>
354 <maxMemory>50331648</maxMemory>
355 <maxStreamMemory>10485760</maxStreamMemory>
356 </nfcsvc>
357 and restarting the "hostd" service:
359 # /etc/init.d/hostd restart
361 For more information see https://bugzilla.redhat.com/1614276.
363
365 This plugin requires VDDK ≥ 5.1.1.
366 It has been tested with all versions up to 6.7 (but should work with
368 future versions).
369 VDDK ≥ 6.0 should be used if possible. This is the first version which
371 added Flush support which is crucial for data integrity when writing.
372
374 nbdkit(1), nbdkit-plugin(3), virsh(1),
375 https://www.vmware.com/support/developer/vddk/
376
378 Richard W.M. Jones
379
381 Copyright (C) 2013-2018 Red Hat Inc.
382
384 Redistribution and use in source and binary forms, with or without
385 modification, are permitted provided that the following conditions are
386 met:
387 · Redistributions of source code must retain the above copyright
389 notice, this list of conditions and the following disclaimer.
390 · Redistributions in binary form must reproduce the above copyright
392 notice, this list of conditions and the following disclaimer in the
393 documentation and/or other materials provided with the
394 distribution.
395 · Neither the name of Red Hat nor the names of its contributors may
397 be used to endorse or promote products derived from this software
398 without specific prior written permission.
399 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
401 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
402 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
403 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
404 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
405 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
406 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
407 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
408 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
409 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
410 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
411nbdkit-1.12.3 2019-05-22 nbdkit-vddk-plugin(1)