1nbdkit-guestfs-plugin(1)            NBDKIT            nbdkit-guestfs-plugin(1)
2
3
4

NAME

6       nbdkit-guestfs-plugin - nbdkit libguestfs plugin
7

SYNOPSIS

9        nbdkit [-r] guestfs
10          [disk=DISK] [domain=DOMAIN] [format=FORMAT] [connect=URI]
11          [mount=inspect|MOUNT] [trace=on] [debug=on] export=DEVICE|FILE
12

WARNING

14       Using nbdkit-guestfs-plugin in read-write mode on live virtual machines
15       can be dangerous, potentially causing disk corruption.  Use the -r
16       (read-only) option to use this plugin safely if the disk image or
17       virtual machine might be live.
18

EXAMPLES

20       Export the first partition inside a disk image called "disk.img", and
21       allow writes:
22
23        nbdkit guestfs disk=disk.img export=/dev/sda1
24
25       Export a disk image which is located inside a libvirt guest called
26       "Guest", read-only (-r option):
27
28        nbdkit -r guestfs domain=Guest mount=inspect export=/images/disk.img
29

DESCRIPTION

31       "nbdkit-guestfs-plugin" is an nbdkit(1) plugin that lets you access the
32       contents of disk images over NBD.  There are many weird and wonderful
33       uses for this, and this man page only covers the simpler ones.
34
35       The parameters control:
36
37       •   Which disk(s) are added to libguestfs.  Specifically "disk=DISK"
38           and "domain=DOMAIN" add a single disk or all the disks from a
39           particular libvirt guest.
40
41       •   What, if any, filesystems inside the disk image / guest have to be
42           mounted.  Use "mount=inspect" to do this automatically (like
43           guestfish(1) -i option), else mount individual filesystems.
44
45       •   What device or file from inside the disk image or guest you want to
46           export over NBD.  Use "export=DEVICE|FILE" to specify the thing
47           that you want to export.
48
49       •   Use the -r option to export read-only.  The default is read-write.
50

PARAMETERS

52       connect=URI
53           This optional parameter specifies the libvirt connection URI.  This
54           is only used with the "domain" parameter.
55
56       debug=on
57           Enable full debugging of libguestfs.  Note you'll probably also
58           have to use the nbdkit(1) option -v in order to see the messages.
59
60       disk=DISK
61           Add the named disk image.  You may specify this option multiple
62           times.
63
64       domain=DOMAIN
65           Add the disk(s) from the libvirt guest called "DOMAIN".
66
67       export=DEVICE
68       export=FILE
69           Export "DEVICE" or "FILE" (from inside the disk image or guest)
70           over NBD.
71
72           Device names are the usual libguestfs names like /dev/sda1 (meaning
73           the first partition of the first disk), or /dev/VG/LV (a logical
74           volume), or RAID arrays etc.  The device name should not be
75           confused with host devices.
76
77           Filenames are similarly those located inside the guest or disk
78           image, and always start with a "/" character (even for Windows
79           guests).
80
81           Exports are writable by default.  Use the -r option to make them
82           read-only.  Exporting read-write a live disk image or virtual
83           machine will probably cause disk corruption.
84
85       format=FORMAT
86           This can be used to specify the format of the disk.  Use it before
87           the "disk=DISK" argument.  It works like the --format option of
88           guestfish(1).
89
90       mount=inspect
91           Use guest inspection to mount disks.  This is like "guestfish -i".
92
93       mount=DEV
94       mount=DEV:MOUNTPOINT
95           Mount "DEV" from inside the guest on "MOUNTPOINT" (defaults to /).
96           This is like "guestfish -m".
97
98       trace=on
99           Enable tracing of libguestfs calls.  Note you'll probably also have
100           to use the nbdkit(1) option -v in order to see the messages.
101

WORKED EXAMPLES

103   Exporting a partition or logical volume inside a disk image
104       disk.img is a host file that contains partitions or LVM logical
105       volumes.  Use the "disk=disk.img" option to add the disk.  Because you
106       don't want to access filesystem contents, "mount=..." is not needed.
107
108        nbdkit guestfs disk=disk.img export=/dev/sda1
109
110        nbdkit guestfs disk=disk.img export=/dev/VG/LV
111
112       Use virt-filesystems(1) to find out what devices, partitions, LVs,
113       filesystems etc a disk image contains.
114
115   Exporting a partition or logical volume inside guest
116       Guest is the name (in libvirt) of a guest.  Since the guest might be
117       live, we use the -r option to open the guest read-only.  Because you
118       don't want to access filesystem contents, "mount=..." is not needed.
119
120        nbdkit -r guestfs domain=Guest export=/dev/sda1
121
122        nbdkit -r guestfs domain=Guest export=/dev/VG/LV
123
124   Exporting a file inside a disk image
125       disk.img is a partitioned disk image with one filesystem that contains
126       a file that we want to export.  Use the "disk=disk.img" option to add
127       the disk, and "mount=/dev/sda1" to specify the filesystem in the disk
128       image.  Use "export=/image" to specify the name of the file in that
129       filesystem that we want to export.
130
131        nbdkit guestfs disk=disk.img mount=/dev/sda1 export=/image
132
133   Exporting a file inside a virtual machine disk image
134       windows.img is the disk from a Windows virtual machine.  Use the
135       "disk=windows.img" option to add the disk, and "mount=inspect" to auto-
136       mount the filesystem(s) in the disk image.  Use
137       "export=/Users/rich/AppData/image" to specify the name of the file from
138       the guest that we want to export.
139
140        nbdkit guestfs disk=windows.img mount=inspect \
141          export=/Users/rich/AppData/image
142

DEBUGGING

144       To debug this plugin, use the following options:
145
146        nbdkit -f -v guestfs debug=on trace=on [...]
147
148       This enables libguestfs debugging and tracing (see guestfs-faq(1)).  It
149       also ensures that the messages are displayed by nbdkit (because of -f
150       and -v).
151

FILES

153       $plugindir/nbdkit-guestfs-plugin.so
154           The plugin.
155
156           Use "nbdkit --dump-config" to find the location of $plugindir.
157

VERSION

159       "nbdkit-guestfs-plugin" first appeared in nbdkit 1.2.
160

SEE ALSO

162       nbdkit(1), nbdkit-plugin(3), guestfish(1), guestfs(3),
163       virt-filesystems(1), http://libguestfs.org.
164

AUTHORS

166       Richard W.M. Jones
167
169       Copyright (C) 2013 Red Hat Inc.
170

LICENSE

172       Redistribution and use in source and binary forms, with or without
173       modification, are permitted provided that the following conditions are
174       met:
175
176       •   Redistributions of source code must retain the above copyright
177           notice, this list of conditions and the following disclaimer.
178
179       •   Redistributions in binary form must reproduce the above copyright
180           notice, this list of conditions and the following disclaimer in the
181           documentation and/or other materials provided with the
182           distribution.
183
184       •   Neither the name of Red Hat nor the names of its contributors may
185           be used to endorse or promote products derived from this software
186           without specific prior written permission.
187
188       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
189       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
190       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
191       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
192       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
193       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
194       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
195       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
196       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
197       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
198       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
199
200
201
202nbdkit-1.28.2                     2021-11-09          nbdkit-guestfs-plugin(1)
Impressum