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=1] [debug=1] 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=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
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|FILE
68           Export "DEVICE" or "FILE" (from inside the disk image or guest)
69           over NBD.
70
71           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
76           Filenames are similarly those located inside the guest or disk
77           image, and always start with a "/" character (even for Windows
78           guests).
79
80           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
84       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
89       mount=inspect
90           Use guest inspection to mount disks.  This is like "guestfish -i".
91
92       mount=DEV
93       mount=DEV:MOUNTPOINT
94           Mount "DEV" from inside the guest on "MOUNTPOINT" (defaults to /).
95           This is like "guestfish -m".
96
97       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

WORKED EXAMPLES

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
107        nbdkit guestfs disk=disk.img export=/dev/sda1
108
109        nbdkit guestfs disk=disk.img export=/dev/VG/LV
110
111       Use virt-filesystems(1) to find out what devices, partitions, LVs,
112       filesystems etc a disk image contains.
113
114   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
119        nbdkit -r guestfs domain=Guest export=/dev/sda1
120
121        nbdkit -r guestfs domain=Guest export=/dev/VG/LV
122
123   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
130        nbdkit guestfs disk=disk.img mount=/dev/sda1 export=/image
131
132   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
139        nbdkit guestfs disk=windows.img mount=inspect \
140          export=/Users/rich/AppData/image
141

DEBUGGING

143       To debug this plugin, use the following options:
144
145        nbdkit -f -v guestfs debug=1 trace=1 [...]
146
147       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

SEE ALSO

152       nbdkit(1), nbdkit-plugin(3), guestfish(1), guestfs(3),
153       virt-filesystems(1), http://libguestfs.org.
154

AUTHORS

156       Richard W.M. Jones
157
159       Copyright (C) 2013 Red Hat Inc.
160

LICENSE

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
166       ·   Redistributions of source code must retain the above copyright
167           notice, this list of conditions and the following disclaimer.
168
169       ·   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
174       ·   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
178       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.
189
190
191
192nbdkit-1.12.3                     2019-05-21          nbdkit-guestfs-plugin(1)
Impressum