generator: Don't use real uuidgen for UUIDs.
[libguestfs.git] / fuse / guestmount.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 guestmount - Mount a guest filesystem on the host using FUSE and libguestfs
6
7 =head1 SYNOPSIS
8
9  guestmount [--options] -a disk.img -m device [--ro] mountpoint
10
11 =head1 WARNING
12
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.
15
16 =head1 DESCRIPTION
17
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.
22
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.
28
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>
33 command.
34
35 =head1 EXAMPLES
36
37 For a typical Windows guest which has its main filesystem on the
38 first partition:
39
40  guestmount -a windows.img -m /dev/sda1 --ro /mnt
41
42 For a typical Linux guest which has a /boot filesystem on the first
43 partition, and the root filesystem on a logical volume:
44
45  guestmount -a linux.img -m /dev/VG/LV -m /dev/sda1:/boot --ro /mnt
46
47 To get L<virt-inspector(1)> to do the hard work of detecting guest
48 mountpoints for you:
49
50  guestmount $(virt-inspector --ro-fish MyGuest) /mnt
51
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)>.
55
56 If you don't know what filesystems are contained in a guest or
57 disk image, use L<virt-list-filesystems(1)> first:
58
59  virt-list-filesystems MyGuest
60
61 If you want to trace the libguestfs calls but without excessive
62 debugging, we recommend:
63
64  guestmount [-a ... -m ...] --trace /mnt
65
66 If you want to debug the program, we recommend:
67
68  guestmount [-a ... -m ...] --trace --verbose /mnt
69
70 =head1 OPTIONS
71
72 =over 4
73
74 =item B<-a image> | B<--add image>
75
76 Add a block device or virtual machine image.
77
78 =item B<--dir-cache-timeout N>
79
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.
85
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.
89
90 =item B<--fuse-help>
91
92 Display help on special FUSE options (see I<-o> below).
93
94 =item B<--help>
95
96 Display brief help and exit.
97
98 =item B<-m dev[:mnt]> | B<--mount dev[:mnt]>
99
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).
102
103 If the mountpoint is omitted, it defaults to C</>.  You have to mount
104 something on C</>.
105
106 =item B<-n> | B<--no-sync>
107
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)>
111 manpage.
112
113 =item B<-o option> | B<--option option>
114
115 Pass extra options to FUSE.
116
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.
120
121  guestmount --fuse-help
122
123 Some potentially useful FUSE options:
124
125 =over 4
126
127 =item B<-o allow_other>
128
129 Allow other users to see the filesystem.
130
131 =item B<-o attr_timeout=N>
132
133 Enable attribute caching by FUSE, and set the timeout to I<N> seconds.
134
135 =item B<-o kernel_cache>
136
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.
140
141 =item B<-o uid=N> B<-o gid=N>
142
143 Use these options to map all UIDs and GIDs inside the guest filesystem
144 to the chosen values.
145
146 =back
147
148 =item B<-r> | B<--ro>
149
150 Add devices and mount everything read-only.  Also disallow writes and
151 make the disk appear read-only to FUSE.
152
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.
157
158 =item B<--selinux>
159
160 Enable SELinux support for the guest.
161
162 =item B<--trace>
163
164 Trace libguestfs calls (to stderr).
165
166 This also stops the daemon from forking into the background.
167
168 =item B<-v> | B<--verbose>
169
170 Enable verbose messages from underlying libguestfs.
171
172 =item B<-V> | B<--version>
173
174 Display the program version and exit.
175
176 =back
177
178 =head1 SEE ALSO
179
180 L<guestfish(1)>,
181 L<virt-inspector(1)>,
182 L<virt-cat(1)>,
183 L<virt-edit(1)>,
184 L<virt-tar(1)>,
185 L<guestfs(3)>,
186 L<http://libguestfs.org/>,
187 L<http://fuse.sf.net/>.
188
189 =head1 AUTHORS
190
191 Richard W.M. Jones (C<rjones at redhat dot com>)
192
193 =head1 COPYRIGHT
194
195 Copyright (C) 2009 Red Hat Inc.
196 L<http://libguestfs.org/>
197
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.
202
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.
207
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.