1nbdkit-guestfs-plugin(1) NBDKIT nbdkit-guestfs-plugin(1)
2
6 nbdkit-guestfs-plugin - nbdkit libguestfs plugin
7
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
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
20 Export the first partition inside a disk image called "disk.img", and
21 allow writes:
22 nbdkit guestfs disk=disk.img export=/dev/sda1
24 Export a disk image which is located inside a libvirt guest called
26 "Guest", read-only (-r option):
27 nbdkit -r guestfs domain=Guest mount=inspect export=/images/disk.img
29
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 The parameters control:
36 • 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 • 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 • 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 • Use the -r option to export read-only. The default is read-write.
50
52 connect=URI
53 This optional parameter specifies the libvirt connection URI. This
54 is only used with the "domain" parameter.
55 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 disk=DISK
61 Add the named disk image. You may specify this option multiple
62 times.
63 domain=DOMAIN
65 Add the disk(s) from the libvirt guest called "DOMAIN".
66 export=DEVICE
68 export=FILE
69 Export "DEVICE" or "FILE" (from inside the disk image or guest)
70 over NBD.
71 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 Filenames are similarly those located inside the guest or disk
78 image, and always start with a "/" character (even for Windows
79 guests).
80 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 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 mount=inspect
91 Use guest inspection to mount disks. This is like "guestfish -i".
92 mount=DEV
94 mount=DEV:MOUNTPOINT
95 Mount "DEV" from inside the guest on "MOUNTPOINT" (defaults to /).
96 This is like "guestfish -m".
97 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
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 nbdkit guestfs disk=disk.img export=/dev/sda1
109 nbdkit guestfs disk=disk.img export=/dev/VG/LV
111 Use virt-filesystems(1) to find out what devices, partitions, LVs,
113 filesystems etc a disk image contains.
114 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 nbdkit -r guestfs domain=Guest export=/dev/sda1
121 nbdkit -r guestfs domain=Guest export=/dev/VG/LV
123 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 nbdkit guestfs disk=disk.img mount=/dev/sda1 export=/image
132 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 nbdkit guestfs disk=windows.img mount=inspect \
141 export=/Users/rich/AppData/image
142
144 To debug this plugin, use the following options:
145 nbdkit -f -v guestfs debug=on trace=on [...]
147 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
153 $plugindir/nbdkit-guestfs-plugin.so
154 The plugin.
155 Use "nbdkit --dump-config" to find the location of $plugindir.
157
159 "nbdkit-guestfs-plugin" first appeared in nbdkit 1.2.
160
162 nbdkit(1), nbdkit-plugin(3), guestfish(1), guestfs(3),
163 virt-filesystems(1), http://libguestfs.org.
164
166 Richard W.M. Jones
167
169 Copyright (C) 2013 Red Hat Inc.
170
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 • Redistributions of source code must retain the above copyright
177 notice, this list of conditions and the following disclaimer.
178 • 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 • 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 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.
199nbdkit-1.28.2 2021-11-09 nbdkit-guestfs-plugin(1)