5 guestmount - Mount a guest filesystem on the host using FUSE and libguestfs
9 guestmount [--options] -a disk.img -m device [--ro] mountpoint
13 You must I<not> use C<guestmount> in read-write mode on live virtual
14 machines. If you do this, you risk disk corruption in the VM.
18 The guestmount program can be used to mount virtual machine
19 filesystems and other disk images on the host. It uses libguestfs for
20 access to the guest filesystem, and FUSE (the "filesystem in
21 userspace") to make it appear as a mountable device.
23 Along with other options, you have to give at least one device (I<-a>
24 option) and at least one mountpoint (I<-m> option). How this works is
25 better explained in the L<guestfish(1)> manual page, or you can use
26 L<virt-inspector(1)> and/or the wrapper script
27 C<guestmount-wrapper> to help you.
29 FUSE lets you mount filesystems as non-root. The mountpoint must be
30 owned by you, and the filesystem will not be visible to any other
31 users unless you make certain global configuration changes to
32 C</etc/fuse.conf>. To unmount the filesystem, use the C<fusermount -u>
37 For a typical Windows guest which has its main filesystem on the
40 guestmount -a windows.img -m /dev/sda1 --ro /mnt
42 For a typical Linux guest which has a /boot filesystem on the first
43 partition, and the root filesystem on a logical volume:
45 guestmount -a linux.img -m /dev/VG/LV -m /dev/sda1:/boot --ro /mnt
47 To get L<virt-inspector(1)> to do the hard work of detecting guest
50 guestmount $(virt-inspector --ro-fish MyGuest) /mnt
52 (or use --fish if you don't want it to be a read only mount). The
53 option is called I<--ro-fish> or I<--fish> because these parameters
54 are compatible with L<guestfish(1)>.
56 If you don't know what filesystems are contained in a guest or
57 disk image, use L<virt-list-filesystems(1)> first:
59 virt-list-filesystems MyGuest
61 If you want to trace the libguestfs calls but without excessive
62 debugging, we recommend:
64 guestmount [-a ... -m ...] --trace /mnt
66 If you want to debug the program, we recommend:
68 guestmount [-a ... -m ...] --trace --verbose /mnt
74 =item B<-a image> | B<--add image>
76 Add a block device or virtual machine image.
78 =item B<--dir-cache-timeout N>
80 Set the readdir cache timeout to I<N> seconds, the default being 60
81 seconds. The readdir cache [actually, there are several
82 semi-independent caches] is populated after a readdir(2) call with the
83 stat and extended attributes of the files in the directory, in
84 anticipation that they will be requested soon after.
86 There is also a different attribute cache implemented by FUSE
87 (see the FUSE option I<-o attr_timeout>), but the FUSE cache
88 does not anticipate future requests, only cache existing ones.
92 Display help on special FUSE options (see I<-o> below).
96 Display brief help and exit.
98 =item B<-m dev[:mnt]> | B<--mount dev[:mnt]>
100 Mount the named partition or logical volume on the given mountpoint
101 B<in the guest> (this has nothing to do with mountpoints in the host).
103 If the mountpoint is omitted, it defaults to C</>. You have to mount
106 =item B<-n> | B<--no-sync>
108 By default, we attempt to sync the guest disk when the FUSE mountpoint
109 is unmounted. If you specify this option, then we don't attempt to
110 sync the disk. See the discussion of autosync in the L<guestfs(3)>
113 =item B<-o option> | B<--option option>
115 Pass extra options to FUSE.
117 To get a list of all the extra options supported by FUSE, use the
118 command below. Note that only the FUSE I<-o> options can be passed,
119 and only some of them are a good idea.
121 guestmount --fuse-help
123 Some potentially useful FUSE options:
127 =item B<-o allow_other>
129 Allow other users to see the filesystem.
131 =item B<-o attr_timeout=N>
133 Enable attribute caching by FUSE, and set the timeout to I<N> seconds.
135 =item B<-o kernel_cache>
137 Allow the kernel to cache files (reduces the number of reads
138 that have to go through the L<guestfs(3)> API). This is generally
139 a good idea if you can afford the extra memory usage.
141 =item B<-o uid=N> B<-o gid=N>
143 Use these options to map all UIDs and GIDs inside the guest filesystem
144 to the chosen values.
148 =item B<-r> | B<--ro>
150 Add devices and mount everything read-only. Also disallow writes and
151 make the disk appear read-only to FUSE.
153 This is highly recommended if you are not going to edit the guest
154 disk. If the guest is running and this option is I<not> supplied,
155 then there is a strong risk of disk corruption in the guest. We try
156 to prevent this from happening, but it is not always possible.
160 Enable SELinux support for the guest.
164 Trace libguestfs calls (to stderr).
166 This also stops the daemon from forking into the background.
168 =item B<-v> | B<--verbose>
170 Enable verbose messages from underlying libguestfs.
172 =item B<-V> | B<--version>
174 Display the program version and exit.
181 L<virt-inspector(1)>,
186 L<http://libguestfs.org/>,
187 L<http://fuse.sf.net/>.
191 Richard W.M. Jones (C<rjones at redhat dot com>)
195 Copyright (C) 2009 Red Hat Inc.
196 L<http://libguestfs.org/>
198 This program is free software; you can redistribute it and/or modify
199 it under the terms of the GNU General Public License as published by
200 the Free Software Foundation; either version 2 of the License, or
201 (at your option) any later version.
203 This program is distributed in the hope that it will be useful,
204 but WITHOUT ANY WARRANTY; without even the implied warranty of
205 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
206 GNU General Public License for more details.
208 You should have received a copy of the GNU General Public License
209 along with this program; if not, write to the Free Software
210 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.