1nbdkit-vddk-plugin(1) nbdkit nbdkit-vddk-plugin(1)
2
6 nbdkit-vddk-plugin - VMware VDDK plugin for nbdkit
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]
14 [snapshot=MOREF] [transports=MODE:MODE:...]
15 nbdkit vddk --dump-plugin
16
18 "nbdkit-vddk-plugin" is an nbdkit(1) plugin that serves files from
19 local VMware VMDK files, VMware ESXi servers, VMware VCenter servers,
20 and other sources. It requires VMware's proprietary VDDK library that
21 you must download yourself separately.
22 The plugin can serve read-only (if the -r option is used) or
24 read/write.
25
27 If the VDDK library (libvixDiskLib.so.6) is located on a non-standard
28 path, you may need to set "LD_LIBRARY_PATH" or modify /etc/ld.so.conf
29 before this plugin will work. In addition you may want to set the
30 "libdir" parameter so that the VDDK library can load plugins like
31 Advanced Transport.
32 For 64 bit platforms pass the lib64 subdirectory:
34 export LD_LIBRARY_PATH=/path/to/vmware-vix-disklib-distrib/lib64
36 For 32 bit platforms pass the lib32 subdirectory:
38 export LD_LIBRARY_PATH=/path/to/vmware-vix-disklib-distrib/lib32
40 Then pass the VDDK distribution directory as "libdir" along with other
42 parameters as required:
43 nbdkit vddk \
45 libdir=/path/to/vmware-vix-disklib-distrib \
46 file=file.vmdk
47 VDDK itself looks in a few default locations for the optional
49 configuration file, usually including /etc/vmware/config and
50 $HOME/.vmware/config, but you can override this using the "config"
51 parameter.
52
54 config=FILENAME
55 Optional. The name of the VDDK configuration file.
56 cookie=COOKIE
58 Optional. Cookie from existing authenticated session on the host.
59 file=FILENAME
61 Required. Set the name of the VMDK file to serve.
62 For local files you must supply an absolute path.
64 For remote files this is usually a path on the VMware server with
66 the format "[datastore] path/to/file.vmdk". You can find the path
67 using virsh(1). For ESXi:
68 virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
70 For vCenter:
72 virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
74 dumpxml guestname
75 If a VM has multiple disks, nbdkit can only serve one at a time.
77 To serve more than one you must run multiple copies of nbdkit.
78 (See "NOTES" below).
79 libdir=PATHNAME
81 Optional. This sets the path of the VMware VDDK distribution.
82 VDDK uses this to load its own plugins, if this path is unspecified
84 or wrong then VDDK will work with reduced functionality.
85 If the parameter is not given, then a hard-coded path determined at
87 compile time is used, see "DUMP-PLUGIN OUTPUT" below.
88 nfchostport=PORT
90 Optional. Port used to establish an NFC connection to ESXi.
91 Defaults to 902.
92 (Only supported in VDDK ≥ 5.5.5 and ≥ 6.0.1)
94 password=PASSWORD
96 Optional (required for remote connections). Set the password to
97 use when connecting to the remote server.
98 Note that passing this on the command line is not secure on shared
100 machines.
101 password=-
103 Optional (required for remote connections). Ask for the password
104 (interactively) when nbdkit starts up.
105 password=+FILENAME
107 Optional (required for remote connections). Read the password from
108 the named file. This is the most secure method to supply a
109 password, as long as you set the permissions on the file
110 appropriately.
111 port=PORT
113 Optional. The port on the VCenter/ESXi host. Defaults to 443.
114 server=HOSTNAME
116 Optional (required for remote connections). The hostname or IP
117 address of VCenter or ESXi host.
118 snapshot=MOREF
120 Optional. The Managed Object Reference of the snapshot.
121 thumbprint=THUMBPRINT
123 Optional. The SSL (SHA1) thumbprint for validating the SSL
124 certificate.
125 The format is
127 "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" (20
128 hex digit pairs).
129 To extract this, log in to the ESXi hypervisor shell and run this
131 command:
132 # openssl x509 -in /etc/vmware/ssl/rui.crt -fingerprint -sha1 -noout
134 For VMware vCenter servers the thumbprint is printed on the text
136 console of the server or is available by logging in to the server
137 and using this command:
138 # openssl x509 -in /etc/vmware-vpx/ssl/rui.crt -fingerprint -sha1 -noout
140 transports=MODE:MODE:...
142 Optional. List of one or more transport modes to use. Possible
143 values include ‘nbd’, ‘nbdssl’, ‘san’, ‘hotadd’, ‘file’ (there may
144 be others). If not given, VDDK will try to choose the best
145 transport mode.
146 user=USERNAME
148 Optional (required for remote connections). The username to
149 connect to the remote server as.
150 vm=moref=ID
152 Optional (required for remote connections). The Managed Object
153 Reference ("moref") of the virtual machine.
154 For VMware ESXi hypervisors, this is a number (eg. "vm=moref=2").
156 For VMware VCenter, this is a string beginning with "vm-") (eg.
157 "vm=moref=vm-16"). Across ESXi and vCenter the numbers are
158 different even for the same virtual machine.
159 If you have libvirt ≥ 3.7, the moref is available in the virsh(1)
161 "dumpxml" output:
162 $ virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
164 ...
165 <vmware:moref>2</vmware:moref>
166 ...
167 or:
169 $ virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
171 dumpxml guestname
172 ...
173 <vmware:moref>vm-16</vmware:moref>
174 ...
175 An alternative way to find the moref of a VM is using the
177 "moRefFinder.pl" script written by William Lam
178 (<http://www.virtuallyghetto.com/2011/11/vsphere-moref-managed-object-reference.html>
179 <https://blogs.vmware.com/vsphere/2012/02/uniquely-identifying-virtual-machines-in-vsphere-and-vcloud-part-2-technical.html>).
180 vimapiver=APIVER
182 This parameter is ignored for backwards compatibility.
183
185 Open a local VMDK file
186 nbdkit vddk file=/absolute/path/to/file.vmdk
187 Note that when opening local files the "file=" parameter must be an
189 absolute path.
190 Because VDDK needs to take a lock on this file, the file must be on a
192 writable filesystem (unless you use the -r option).
193 Open a file on a remote VMware ESXi hypervisor
195 Connect directly to a VMware ESXi hypervisor and export a particular
196 file:
197 nbdkit vddk user=root password=+/tmp/rootpw \
199 server=esxi.example.com thumbprint=xx:xx:xx:... \
200 vm=moref=2 \
201 file="[datastore1] Fedora/Fedora.vmdk"
202 "user" and "password" must be specified. Use "password=+FILENAME" to
204 provide the password securely in a file.
205 "server" is the hostname of the ESXi server. "thumbprint" is the thumb
207 print for validating the SSL certificate. How to find the thumb print
208 of a server is described in "PARAMETERS" above.
209 "vm" is the Managed Object Reference ("moref") of the virtual machine.
211 To find this using virsh(1) or the "moRefFinder.pl" script, see
212 "PARAMETERS" above. Note that it is different from the moref used by
213 vCenter, and is just a single number.
214 "file" is the actual file you want to open, usually in the form
216 "[datastore] vmname/vmname.vmdk". You can find this from the virsh(1)
217 as described in "PARAMETERS" above.
218 Open a file on a remote VMware vCenter server
220 Connect via VMware vCenter and export a particular file:
221 nbdkit vddk user=root password=vmware \
223 server=vcenter.example.com thumbprint=xx:xx:xx:... \
224 vm=moref=vm-16 \
225 file="[datastore1] Fedora/Fedora.vmdk"
226 "user" and "password" must be specified. Use "password=+FILENAME" to
228 provide the password securely in a file.
229 "server" is the hostname of the vCenter server. "thumbprint" is the
231 thumb print for validating the SSL certificate. How to find the thumb
232 print of a server is described in "PARAMETERS" above.
233 "vm" is the Managed Object Reference ("moref") of the virtual machine.
235 To find this using virsh(1) or the "moRefFinder.pl" script, see
236 "PARAMETERS" above. Note that it is different from the moref used by
237 ESXi, and always begins with the prefix "vm-".
238 "file" is the actual file you want to open, usually in the form
240 "[datastore] vmname/vmname.vmdk". You can find this from the virsh(1)
241 as described in "PARAMETERS" above.
242
244 To query more information about the plugin (and whether it is working),
245 use:
246 nbdkit vddk --dump-plugin
248 If the plugin is not present, not working or the library path is wrong
250 you will get an error.
251 If it works the output will include:
253 "vddk_default_libdir=..."
255 The compiled-in library path. Use "libdir=PATHNAME" to override
256 this at runtime.
257 "vddk_has_nfchostport=1"
259 If this is printed then the "nfchostport=PORT" parameter is
260 supported by this build.
261
263 Debugging messages can be very helpful if you have problems connecting
264 to VMware servers, or to find the list of available transport modes, or
265 to diagnose SAN problems.
266 Run nbdkit like this to see all debugging messages:
268 nbdkit -f -v vddk file=FILENAME [...]
270
272 Sector size limitation
273 The VDDK plugin can only answer read/write requests on whole 512 byte
274 sector boundaries. This is because the VDDK Read and Write APIs only
275 take sector numbers.
276 The plugin could be extended in future to support byte granularity, but
278 common NBD clients don't need it so it's not a priority.
279 Threads
281 Handling threads in the VDDK API is complex and does not map well to
282 any of the thread models offered by nbdkit (see "THREADS" in
283 nbdkit-plugin(3)). The plugin uses the nbdkit "SERIALIZE_ALL_REQUESTS"
284 model, but technically even this is not completely safe. This is a
285 subject of future work.
286 Export names
288 For VMs with multiple disks, it would be nice to map the disk names to
289 NBD export names. However nbdkit core will need to be extended to
290 support this.
291
293 nbdkit(1), nbdkit-plugin(3), virsh(1),
294 <https://www.vmware.com/support/developer/vddk/>
295
297 Richard W.M. Jones
298
300 Copyright (C) 2013-2018 Red Hat Inc.
301
303 Redistribution and use in source and binary forms, with or without
304 modification, are permitted provided that the following conditions are
305 met:
306 · Redistributions of source code must retain the above copyright
308 notice, this list of conditions and the following disclaimer.
309 · Redistributions in binary form must reproduce the above copyright
311 notice, this list of conditions and the following disclaimer in the
312 documentation and/or other materials provided with the
313 distribution.
314 · Neither the name of Red Hat nor the names of its contributors may
316 be used to endorse or promote products derived from this software
317 without specific prior written permission.
318 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
320 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
321 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
322 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
323 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
324 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
325 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
326 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
327 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
328 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
329 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
330nbdkit 2018-11-28 nbdkit-vddk-plugin(1)