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 [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

DESCRIPTION

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
24       The plugin can serve read-only (if the -r option is used) or
25       read/write.
26

LIBRARY AND CONFIG FILE LOCATIONS

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
34       For 64 bit platforms pass the lib64 subdirectory:
35
36        export LD_LIBRARY_PATH=/path/to/vmware-vix-disklib-distrib/lib64
37
38       For 32 bit platforms pass the lib32 subdirectory:
39
40        export LD_LIBRARY_PATH=/path/to/vmware-vix-disklib-distrib/lib32
41
42       Then pass the VDDK distribution directory as "libdir" along with other
43       parameters as required:
44
45        nbdkit vddk \
46            libdir=/path/to/vmware-vix-disklib-distrib \
47            file=file.vmdk
48
49       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

PARAMETERS

55       All parameters are optional except:
56
57       "file"
58           is required for opening a local VMDK file.
59
60       "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
69       See the "EXAMPLES" section below for local and remote command lines.
70
71       config=FILENAME
72           The name of the VDDK configuration file.
73
74       cookie=COOKIE
75           Cookie from existing authenticated session on the host.
76
77       file=FILENAME
78           Set the name of the VMDK file to serve.
79
80           For local files you must supply an absolute path.
81
82           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
86            virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
87
88           For vCenter:
89
90            virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
91                  dumpxml guestname
92
93           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
97       libdir=PATHNAME
98           This sets the path of the VMware VDDK distribution.
99
100           VDDK uses this to load its own plugins, if this path is unspecified
101           or wrong then VDDK will work with reduced functionality.
102
103           If the parameter is not given, then a hard-coded path determined at
104           compile time is used, see "DUMP-PLUGIN OUTPUT" below.
105
106       nfchostport=PORT
107           Port used to establish an NFC connection to ESXi.  Defaults to 902.
108
109           (Only supported in VDDK ≥ 5.5.5 and ≥ 6.0.1)
110
111       password=PASSWORD
112           Set the password to use when connecting to the remote server.
113
114           Note that passing this on the command line is not secure on shared
115           machines.
116
117       password=-
118           Ask for the password (interactively) when nbdkit starts up.
119
120       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
125       port=PORT
126           The port on the VCenter/ESXi host.  Defaults to 443.
127
128       server=HOSTNAME
129           The hostname or IP address of VCenter or ESXi host.
130
131       single-link=true
132           Open the current link, not the entire chain.  This corresponds to
133           the "VIXDISKLIB_FLAG_OPEN_SINGLE_LINK" flag.
134
135       snapshot=MOREF
136           The Managed Object Reference of the snapshot.
137
138       thumbprint=THUMBPRINT
139           The SSL (SHA1) thumbprint for validating the SSL certificate.
140
141           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
145           See "THUMBPRINTS" below for how to get this.
146
147       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
153       unbuffered=true
154           Disable host caching.  This corresponds to the
155           "VIXDISKLIB_FLAG_OPEN_UNBUFFERED" flag.
156
157       user=USERNAME
158           The username to connect to the remote server as.
159
160       vm=moref=ID
161           The Managed Object Reference ("moref") of the virtual machine.
162
163           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
168           If you have libvirt ≥ 3.7, the moref is available in the virsh(1)
169           "dumpxml" output:
170
171            $ virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
172            ...
173            <vmware:moref>2</vmware:moref>
174            ...
175
176           or:
177
178            $ 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
184           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
189       vimapiver=APIVER
190           This parameter is ignored for backwards compatibility.
191

EXAMPLES

193   Open a local VMDK file
194        nbdkit vddk file=/absolute/path/to/file.vmdk
195
196       Note that when opening local files the "file=" parameter must be an
197       absolute path.
198
199       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
202   Open a file on a remote VMware ESXi hypervisor
203       Connect directly to a VMware ESXi hypervisor and export a particular
204       file:
205
206        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
211       "user" and "password" must be specified.  Use "password=+FILENAME" to
212       provide the password securely in a file.
213
214       "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
218       "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
223       "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
227   Open a file on a remote VMware vCenter server
228       Connect via VMware vCenter and export a particular file:
229
230        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
235       "user" and "password" must be specified.  Use "password=+FILENAME" to
236       provide the password securely in a file.
237
238       "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
242       "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
247       "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

THUMBPRINTS

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
256   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
260        # openssl x509 -in /etc/vmware/ssl/rui.crt -fingerprint -sha1 -noout
261
262       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
266        # openssl x509 -in /etc/vmware-vpx/ssl/rui.crt -fingerprint -sha1 -noout
267
268   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
272        nbdkit -f -v vddk server=esxi.example.com [...] thumbprint=12
273        qemu-img info nbd:localhost:10809
274
275       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
278        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
280       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

DUMP-PLUGIN OUTPUT

284       To query more information about the plugin (and whether it is working),
285       use:
286
287        nbdkit vddk --dump-plugin
288
289       If the plugin is not present, not working or the library path is wrong
290       you will get an error.
291
292       If it works the output will include:
293
294       "vddk_default_libdir=..."
295           The compiled-in library path.  Use "libdir=PATHNAME" to override
296           this at runtime.
297
298       "vddk_has_nfchostport=1"
299           If this is printed then the "nfchostport=PORT" parameter is
300           supported by this build.
301
302       "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

DEBUGGING VDDK

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
312       Run nbdkit like this to see all debugging messages:
313
314        nbdkit -f -v vddk file=FILENAME [...]
315

NOTES

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
322       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
325   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
332   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
337   Out of memory errors
338       In the verbose log you may see errors like:
339
340        nbdkit: vddk[3]: error: [NFC ERROR] NfcFssrvrProcessErrorMsg:
341        received NFC error 5 from server: Failed to allocate the
342        requested 2097176 bytes
343
344       This seems especially common when there are multiple parallel
345       connections open to the VMware server.
346
347       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
351        <nfcsvc>
352          <path>libnfcsvc.so</path>
353          <enabled>true</enabled>
354          <maxMemory>50331648</maxMemory>
355          <maxStreamMemory>10485760</maxStreamMemory>
356        </nfcsvc>
357
358       and restarting the "hostd" service:
359
360        # /etc/init.d/hostd restart
361
362       For more information see https://bugzilla.redhat.com/1614276.
363

SUPPORTED VERSIONS OF VDDK

365       This plugin requires VDDK ≥ 5.1.1.
366
367       It has been tested with all versions up to 6.7 (but should work with
368       future versions).
369
370       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

SEE ALSO

374       nbdkit(1), nbdkit-plugin(3), virsh(1),
375       https://www.vmware.com/support/developer/vddk/
376

AUTHORS

378       Richard W.M. Jones
379
381       Copyright (C) 2013-2018 Red Hat Inc.
382

LICENSE

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
388       ·   Redistributions of source code must retain the above copyright
389           notice, this list of conditions and the following disclaimer.
390
391       ·   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
396       ·   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
400       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.
411
412
413
414nbdkit-1.12.3                     2019-05-21             nbdkit-vddk-plugin(1)
Impressum