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=1] [debug=1] 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=1
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|FILE
68 Export "DEVICE" or "FILE" (from inside the disk image or guest)
69 over NBD.
70 Device names are the usual libguestfs names like /dev/sda1 (meaning
72 the first partition of the first disk), or /dev/VG/LV (a logical
73 volume), or RAID arrays etc. The device name should not be
74 confused with host devices.
75 Filenames are similarly those located inside the guest or disk
77 image, and always start with a "/" character (even for Windows
78 guests).
79 Exports are writable by default. Use the -r option to make them
81 read-only. Exporting read-write a live disk image or virtual
82 machine will probably cause disk corruption.
83 format=FORMAT
85 This can be used to specify the format of the disk. Use it before
86 the "disk=DISK" argument. It works like the --format option of
87 guestfish(1).
88 mount=inspect
90 Use guest inspection to mount disks. This is like "guestfish -i".
91 mount=DEV
93 mount=DEV:MOUNTPOINT
94 Mount "DEV" from inside the guest on "MOUNTPOINT" (defaults to /).
95 This is like "guestfish -m".
96 trace=1
98 Enable tracing of libguestfs calls. Note you'll probably also have
99 to use the nbdkit(1) option -v in order to see the messages.
100
102 Exporting a partition or logical volume inside a disk image
103 disk.img is a host file that contains partitions or LVM logical
104 volumes. Use the "disk=disk.img" option to add the disk. Because you
105 don't want to access filesystem contents, "mount=..." is not needed.
106 nbdkit guestfs disk=disk.img export=/dev/sda1
108 nbdkit guestfs disk=disk.img export=/dev/VG/LV
110 Use virt-filesystems(1) to find out what devices, partitions, LVs,
112 filesystems etc a disk image contains.
113 Exporting a partition or logical volume inside guest
115 Guest is the name (in libvirt) of a guest. Since the guest might be
116 live, we use the -r option to open the guest read-only. Because you
117 don't want to access filesystem contents, "mount=..." is not needed.
118 nbdkit -r guestfs domain=Guest export=/dev/sda1
120 nbdkit -r guestfs domain=Guest export=/dev/VG/LV
122 Exporting a file inside a disk image
124 disk.img is a partitioned disk image with one filesystem that contains
125 a file that we want to export. Use the "disk=disk.img" option to add
126 the disk, and "mount=/dev/sda1" to specify the filesystem in the disk
127 image. Use "export=/image" to specify the name of the file in that
128 filesystem that we want to export.
129 nbdkit guestfs disk=disk.img mount=/dev/sda1 export=/image
131 Exporting a file inside a virtual machine disk image
133 windows.img is the disk from a Windows virtual machine. Use the
134 "disk=windows.img" option to add the disk, and "mount=inspect" to auto-
135 mount the filesystem(s) in the disk image. Use
136 "export=/Users/rich/AppData/image" to specify the name of the file from
137 the guest that we want to export.
138 nbdkit guestfs disk=windows.img mount=inspect \
140 export=/Users/rich/AppData/image
141
143 To debug this plugin, use the following options:
144 nbdkit -f -v guestfs debug=1 trace=1 [...]
146 This enables libguestfs debugging and tracing (see guestfs-faq(1)). It
148 also ensures that the messages are displayed by nbdkit (because of -f
149 and -v).
150
152 nbdkit(1), nbdkit-plugin(3), guestfish(1), guestfs(3),
153 virt-filesystems(1), http://libguestfs.org.
154
156 Richard W.M. Jones
157
159 Copyright (C) 2013 Red Hat Inc.
160
162 Redistribution and use in source and binary forms, with or without
163 modification, are permitted provided that the following conditions are
164 met:
165 · Redistributions of source code must retain the above copyright
167 notice, this list of conditions and the following disclaimer.
168 · Redistributions in binary form must reproduce the above copyright
170 notice, this list of conditions and the following disclaimer in the
171 documentation and/or other materials provided with the
172 distribution.
173 · Neither the name of Red Hat nor the names of its contributors may
175 be used to endorse or promote products derived from this software
176 without specific prior written permission.
177 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
179 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
180 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
181 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
182 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
183 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
184 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
185 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
186 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
187 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
188 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
189nbdkit-1.12.3 2019-05-22 nbdkit-guestfs-plugin(1)