.\" Automatically generated by Podwrapper::Man 1.10.3 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-vddk-plugin 1"
.TH nbdkit-vddk-plugin 1 "2019-01-26" "nbdkit-1.10.3" "NBDKIT"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nbdkit\-vddk\-plugin \- nbdkit VMware VDDK plugin
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\& nbdkit vddk file=FILENAME [config=FILENAME] [libdir=LIBRARY]
\&             [vm=moref=ID] [server=HOSTNAME] [user=USERNAME]
\&             [password=PASSWORD | password=\- | password=+FILENAME]
\&             [cookie=COOKIE] [thumbprint=THUMBPRINT]
\&             [port=PORT] [nfchostport=PORT]
\&             [snapshot=MOREF] [transports=MODE:MODE:...]
\& nbdkit vddk \-\-dump\-plugin
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-vddk\-plugin\*(C'\fR is an \fBnbdkit\fR\|(1) plugin that serves files from
local VMware \s-1VMDK\s0 files, VMware ESXi servers, VMware VCenter servers,
and other sources.  It requires VMware's proprietary \s-1VDDK\s0 library that
you must download yourself separately.
.PP
The plugin can serve read-only (if the \fI\-r\fR option is used) or
read/write.
.SH "LIBRARY AND CONFIG FILE LOCATIONS"
.IX Header "LIBRARY AND CONFIG FILE LOCATIONS"
If the \s-1VDDK\s0 library (\fIlibvixDiskLib.so.6\fR) is located on a
non-standard path, you may need to set \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR or modify
\&\fI/etc/ld.so.conf\fR before this plugin will work.  In addition you may
want to set the \f(CW\*(C`libdir\*(C'\fR parameter so that the \s-1VDDK\s0 library can load
plugins like Advanced Transport.
.PP
For 64 bit platforms pass the \fIlib64\fR subdirectory:
.PP
.Vb 1
\& export LD_LIBRARY_PATH=/path/to/vmware\-vix\-disklib\-distrib/lib64
.Ve
.PP
For 32 bit platforms pass the \fIlib32\fR subdirectory:
.PP
.Vb 1
\& export LD_LIBRARY_PATH=/path/to/vmware\-vix\-disklib\-distrib/lib32
.Ve
.PP
Then pass the \s-1VDDK\s0 distribution directory as \f(CW\*(C`libdir\*(C'\fR along with
other parameters as required:
.PP
.Vb 3
\& nbdkit vddk \e
\&     libdir=/path/to/vmware\-vix\-disklib\-distrib \e
\&     file=file.vmdk
.Ve
.PP
\&\s-1VDDK\s0 itself looks in a few default locations for the optional
configuration file, usually including \fI/etc/vmware/config\fR and
\&\fI\f(CI$HOME\fI/.vmware/config\fR, but you can override this using the \f(CW\*(C`config\*(C'\fR
parameter.
.SH "PARAMETERS"
.IX Header "PARAMETERS"
.IP "\fBconfig=\fR\s-1FILENAME\s0" 4
.IX Item "config=FILENAME"
Optional.  The name of the \s-1VDDK\s0 configuration file.
.IP "\fBcookie=\fR\s-1COOKIE\s0" 4
.IX Item "cookie=COOKIE"
Optional.  Cookie from existing authenticated session on the host.
.IP "\fBfile=\fR\s-1FILENAME\s0" 4
.IX Item "file=FILENAME"
Required.  Set the name of the \s-1VMDK\s0 file to serve.
.Sp
For local files you \fBmust\fR supply an absolute path.
.Sp
For remote files this is usually a path on the VMware server with the
format \f(CW"[datastore] path/to/file.vmdk"\fR.  You can find the path
using \fBvirsh\fR\|(1).  For ESXi:
.Sp
.Vb 1
\& virsh \-c \*(Aqesx://esxi.example.com?no_verify=1\*(Aq dumpxml guestname
.Ve
.Sp
For vCenter:
.Sp
.Vb 2
\& virsh \-c \*(Aqvpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1\*(Aq \e
\&       dumpxml guestname
.Ve
.Sp
If a \s-1VM\s0 has multiple disks, nbdkit can only serve one at a time.  To
serve more than one you must run multiple copies of nbdkit.  (See
\&\*(L"\s-1NOTES\*(R"\s0 below).
.IP "\fBlibdir=\fR\s-1PATHNAME\s0" 4
.IX Item "libdir=PATHNAME"
Optional.  This sets the path of the VMware \s-1VDDK\s0 distribution.
.Sp
\&\s-1VDDK\s0 uses this to load its own plugins, if this path is unspecified or
wrong then \s-1VDDK\s0 will work with reduced functionality.
.Sp
If the parameter is not given, then a hard-coded path determined at
compile time is used, see \*(L"DUMP-PLUGIN \s-1OUTPUT\*(R"\s0 below.
.IP "\fBnfchostport=\fR\s-1PORT\s0" 4
.IX Item "nfchostport=PORT"
Optional.  Port used to establish an \s-1NFC\s0 connection to ESXi.  Defaults
to 902.
.Sp
(Only supported in \s-1VDDK\s0 ≥ 5.5.5 and ≥ 6.0.1)
.IP "\fBpassword=\fR\s-1PASSWORD\s0" 4
.IX Item "password=PASSWORD"
Optional (required for remote connections).  Set the password to use
when connecting to the remote server.
.Sp
Note that passing this on the command line is not secure on shared
machines.
.IP "\fBpassword=\-\fR" 4
.IX Item "password=-"
Optional (required for remote connections).  Ask for the password
(interactively) when nbdkit starts up.
.IP "\fBpassword=+\fR\s-1FILENAME\s0" 4
.IX Item "password=+FILENAME"
Optional (required for remote connections).  Read the password from
the named file.  This is the most secure method to supply a password,
as long as you set the permissions on the file appropriately.
.IP "\fBport=\fR\s-1PORT\s0" 4
.IX Item "port=PORT"
Optional.  The port on the VCenter/ESXi host.  Defaults to 443.
.IP "\fBserver=\fR\s-1HOSTNAME\s0" 4
.IX Item "server=HOSTNAME"
Optional (required for remote connections).  The hostname or \s-1IP\s0
address of VCenter or ESXi host.
.IP "\fBsnapshot=\fR\s-1MOREF\s0" 4
.IX Item "snapshot=MOREF"
Optional.  The Managed Object Reference of the snapshot.
.IP "\fBthumbprint=\fR\s-1THUMBPRINT\s0" 4
.IX Item "thumbprint=THUMBPRINT"
Optional.  The \s-1SSL\s0 (\s-1SHA1\s0) thumbprint for validating the \s-1SSL\s0
certificate.
.Sp
The format is
\&\f(CW\*(C`xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx\*(C'\fR
(20 hex digit pairs).
.Sp
To extract this, log in to the ESXi hypervisor shell and run this
command:
.Sp
.Vb 1
\& # openssl x509 \-in /etc/vmware/ssl/rui.crt \-fingerprint \-sha1 \-noout
.Ve
.Sp
For VMware vCenter servers the thumbprint is printed on the text
console of the server or is available by logging in to the server and
using this command:
.Sp
.Vb 1
\& # openssl x509 \-in /etc/vmware\-vpx/ssl/rui.crt \-fingerprint \-sha1 \-noout
.Ve
.IP "\fBtransports=\fR\s-1MODE\s0\fB:\fR\s-1MODE\s0\fB:\fR..." 4
.IX Item "transports=MODE:MODE:..."
Optional.  List of one or more transport modes to use.  Possible
values include ‘nbd’, ‘nbdssl’, ‘san’, ‘hotadd’, ‘file’ (there may be
others).  If not given, \s-1VDDK\s0 will try to choose the best transport
mode.
.IP "\fBuser=\fR\s-1USERNAME\s0" 4
.IX Item "user=USERNAME"
Optional (required for remote connections).  The username to connect
to the remote server as.
.IP "\fBvm=moref=\fR\s-1ID\s0" 4
.IX Item "vm=moref=ID"
Optional (required for remote connections).  The Managed Object
Reference (\*(L"moref\*(R") of the virtual machine.
.Sp
For VMware ESXi hypervisors, this is a number (eg. \f(CW\*(C`vm=moref=2\*(C'\fR).
For VMware VCenter, this is a string beginning with \f(CW"vm\-"\fR)
(eg. \f(CW\*(C`vm=moref=vm\-16\*(C'\fR).  Across ESXi and vCenter the numbers are
different even for the same virtual machine.
.Sp
If you have libvirt ≥ 3.7, the moref is available in the
\&\fBvirsh\fR\|(1) \f(CW\*(C`dumpxml\*(C'\fR output:
.Sp
.Vb 4
\& $ virsh \-c \*(Aqesx://esxi.example.com?no_verify=1\*(Aq dumpxml guestname
\& ...
\& <vmware:moref>2</vmware:moref>
\& ...
.Ve
.Sp
or:
.Sp
.Vb 5
\& $ virsh \-c \*(Aqvpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1\*(Aq \e
\&       dumpxml guestname
\& ...
\& <vmware:moref>vm\-16</vmware:moref>
\& ...
.Ve
.Sp
An alternative way to find the moref of a \s-1VM\s0 is using the
\&\f(CW\*(C`moRefFinder.pl\*(C'\fR script written by William Lam
(http://www.virtuallyghetto.com/2011/11/vsphere\-moref\-managed\-object\-reference.html
https://blogs.vmware.com/vsphere/2012/02/uniquely\-identifying\-virtual\-machines\-in\-vsphere\-and\-vcloud\-part\-2\-technical.html).
.IP "\fBvimapiver=\fR\s-1APIVER\s0" 4
.IX Item "vimapiver=APIVER"
This parameter is ignored for backwards compatibility.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Open a local \s-1VMDK\s0 file"
.IX Subsection "Open a local VMDK file"
.Vb 1
\& nbdkit vddk file=/absolute/path/to/file.vmdk
.Ve
.PP
Note that when opening local files the \f(CW\*(C`file=\*(C'\fR parameter \fBmust\fR be
an absolute path.
.PP
Because \s-1VDDK\s0 needs to take a lock on this file, the file must be on a
writable filesystem (unless you use the \fI\-r\fR option).
.SS "Open a file on a remote VMware ESXi hypervisor"
.IX Subsection "Open a file on a remote VMware ESXi hypervisor"
Connect directly to a VMware ESXi hypervisor and export a particular
file:
.PP
.Vb 4
\& nbdkit vddk user=root password=+/tmp/rootpw \e
\&             server=esxi.example.com thumbprint=xx:xx:xx:... \e
\&             vm=moref=2 \e
\&             file="[datastore1] Fedora/Fedora.vmdk"
.Ve
.PP
\&\f(CW\*(C`user\*(C'\fR and \f(CW\*(C`password\*(C'\fR must be specified.  Use \f(CW\*(C`password=+FILENAME\*(C'\fR
to provide the password securely in a file.
.PP
\&\f(CW\*(C`server\*(C'\fR is the hostname of the ESXi server.  \f(CW\*(C`thumbprint\*(C'\fR is the
thumb print for validating the \s-1SSL\s0 certificate.  How to find the thumb
print of a server is described in \*(L"\s-1PARAMETERS\*(R"\s0 above.
.PP
\&\f(CW\*(C`vm\*(C'\fR is the Managed Object Reference (\*(L"moref\*(R") of the virtual
machine.  To find this using \fBvirsh\fR\|(1) or the \f(CW\*(C`moRefFinder.pl\*(C'\fR
script, see \*(L"\s-1PARAMETERS\*(R"\s0 above.  Note that it is different from the
moref used by vCenter, and is just a single number.
.PP
\&\f(CW\*(C`file\*(C'\fR is the actual file you want to open, usually in the form
\&\f(CW"[datastore] vmname/vmname.vmdk"\fR.  You can find this from
\&\fBvirsh\fR\|(1) as described in \*(L"\s-1PARAMETERS\*(R"\s0 above.
.SS "Open a file on a remote VMware vCenter server"
.IX Subsection "Open a file on a remote VMware vCenter server"
Connect via VMware vCenter and export a particular file:
.PP
.Vb 4
\& nbdkit vddk user=root password=vmware \e
\&             server=vcenter.example.com thumbprint=xx:xx:xx:... \e
\&             vm=moref=vm\-16 \e
\&             file="[datastore1] Fedora/Fedora.vmdk"
.Ve
.PP
\&\f(CW\*(C`user\*(C'\fR and \f(CW\*(C`password\*(C'\fR must be specified.  Use \f(CW\*(C`password=+FILENAME\*(C'\fR
to provide the password securely in a file.
.PP
\&\f(CW\*(C`server\*(C'\fR is the hostname of the vCenter server.  \f(CW\*(C`thumbprint\*(C'\fR is the
thumb print for validating the \s-1SSL\s0 certificate.  How to find the thumb
print of a server is described in \*(L"\s-1PARAMETERS\*(R"\s0 above.
.PP
\&\f(CW\*(C`vm\*(C'\fR is the Managed Object Reference (\*(L"moref\*(R") of the virtual
machine.  To find this using \fBvirsh\fR\|(1) or the \f(CW\*(C`moRefFinder.pl\*(C'\fR
script, see \*(L"\s-1PARAMETERS\*(R"\s0 above.  Note that it is different from the
moref used by ESXi, and always begins with the prefix \f(CW"vm\-"\fR.
.PP
\&\f(CW\*(C`file\*(C'\fR is the actual file you want to open, usually in the form
\&\f(CW"[datastore] vmname/vmname.vmdk"\fR.  You can find this from
\&\fBvirsh\fR\|(1) as described in \*(L"\s-1PARAMETERS\*(R"\s0 above.
.SH "DUMP-PLUGIN OUTPUT"
.IX Header "DUMP-PLUGIN OUTPUT"
To query more information about the plugin (and whether it is
working), use:
.PP
.Vb 1
\& nbdkit vddk \-\-dump\-plugin
.Ve
.PP
If the plugin is not present, not working or the library path is wrong
you will get an error.
.PP
If it works the output will include:
.ie n .IP """vddk_default_libdir=...""" 4
.el .IP "\f(CWvddk_default_libdir=...\fR" 4
.IX Item "vddk_default_libdir=..."
The compiled-in library path.  Use \f(CW\*(C`libdir=PATHNAME\*(C'\fR to override this
at runtime.
.ie n .IP """vddk_has_nfchostport=1""" 4
.el .IP "\f(CWvddk_has_nfchostport=1\fR" 4
.IX Item "vddk_has_nfchostport=1"
If this is printed then the \f(CW\*(C`nfchostport=PORT\*(C'\fR parameter is supported
by this build.
.ie n .IP """vddk_dll=...""" 4
.el .IP "\f(CWvddk_dll=...\fR" 4
.IX Item "vddk_dll=..."
Prints the full path to the \s-1VDDK\s0 shared library.  Since this requires
a glibc extension it may not be available in all builds of the plugin.
.SH "DEBUGGING VDDK"
.IX Header "DEBUGGING VDDK"
Debugging messages can be very helpful if you have problems connecting
to VMware servers, or to find the list of available transport modes,
or to diagnose \s-1SAN\s0 problems.
.PP
Run nbdkit like this to see all debugging messages:
.PP
.Vb 1
\& nbdkit \-f \-v vddk file=FILENAME [...]
.Ve
.SH "NOTES"
.IX Header "NOTES"
.SS "Sector size limitation"
.IX Subsection "Sector size limitation"
The \s-1VDDK\s0 plugin can only answer read/write requests on whole 512 byte
sector boundaries.  This is because the \s-1VDDK\s0 Read and Write APIs only
take sector numbers.
.PP
The plugin could be extended in future to support byte granularity,
but common \s-1NBD\s0 clients don't need it so it's not a priority.
.SS "Threads"
.IX Subsection "Threads"
Handling threads in the \s-1VDDK API\s0 is complex and does not map well to
any of the thread models offered by nbdkit (see
\&\*(L"\s-1THREADS\*(R"\s0 in \fBnbdkit\-plugin\fR\|(3)).  The plugin uses the nbdkit
\&\f(CW\*(C`SERIALIZE_ALL_REQUESTS\*(C'\fR model, but technically even this is not
completely safe.  This is a subject of future work.
.SS "Export names"
.IX Subsection "Export names"
For VMs with multiple disks, it would be nice to map the disk names to
\&\s-1NBD\s0 export names.  However nbdkit core will need to be extended to
support this.
.SS "Out of memory errors"
.IX Subsection "Out of memory errors"
In the verbose log you may see errors like:
.PP
.Vb 3
\& nbdkit: vddk[3]: error: [NFC ERROR] NfcFssrvrProcessErrorMsg:
\& received NFC error 5 from server: Failed to allocate the
\& requested 2097176 bytes
.Ve
.PP
This seems especially common when there are multiple parallel
connections open to the VMware server.
.PP
These can be caused by resource limits set on the VMware server.  You
can increase the limit for the \s-1NFC\s0 service by editing
\&\fI/etc/vmware/hostd/config.xml\fR and adjusting the
\&\f(CW\*(C`<maxMemory>\*(C'\fR setting:
.PP
.Vb 6
\& <nfcsvc>
\&   <path>libnfcsvc.so</path>
\&   <enabled>true</enabled>
\&   <maxMemory>50331648</maxMemory>
\&   <maxStreamMemory>10485760</maxStreamMemory>
\& </nfcsvc>
.Ve
.PP
and restarting the \f(CW\*(C`hostd\*(C'\fR service:
.PP
.Vb 1
\& # /etc/init.d/hostd restart
.Ve
.PP
For more information see https://bugzilla.redhat.com/1614276.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-plugin\fR\|(3),
\&\fBvirsh\fR\|(1),
https://www.vmware.com/support/developer/vddk/
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2013\-2018 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP "\(bu" 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP "\(bu" 4
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
.IP "\(bu" 4
Neither the name of Red Hat nor the names of its contributors may be
used to endorse or promote products derived from this software without
specific prior written permission.
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0