todo: Add notes on inspecting ISO images.
[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  guestmount [--options] -a disk.img -i [--ro] mountpoint
12
13  guestmount [--options] -d Guest -i [--ro] mountpoint
14
15 =head1 WARNING
16
17 You must I<not> use C<guestmount> in read-write mode on live virtual
18 machines.  If you do this, you risk disk corruption in the VM.
19
20 =head1 DESCRIPTION
21
22 The guestmount program can be used to mount virtual machine
23 filesystems and other disk images on the host.  It uses libguestfs for
24 access to the guest filesystem, and FUSE (the "filesystem in
25 userspace") to make it appear as a mountable device.
26
27 Along with other options, you have to give at least one device (I<-a>
28 option) or libvirt domain (I<-d> option), and at least one mountpoint
29 (I<-m> option) or use the I<-i> inspection option.  How this works is
30 better explained in the L<guestfish(1)> manual page, or by looking at
31 the examples below.
32
33 FUSE lets you mount filesystems as non-root.  The mountpoint must be
34 owned by you, and the filesystem will not be visible to any other
35 users unless you make certain global configuration changes to
36 C</etc/fuse.conf>.  To unmount the filesystem, use the C<fusermount -u>
37 command.
38
39 =head1 EXAMPLES
40
41 For a typical Windows guest which has its main filesystem on the
42 first partition:
43
44  guestmount -a windows.img -m /dev/sda1 --ro /mnt
45
46 For a typical Linux guest which has a /boot filesystem on the first
47 partition, and the root filesystem on a logical volume:
48
49  guestmount -a linux.img -m /dev/VG/LV -m /dev/sda1:/boot --ro /mnt
50
51 To get libguestfs to detect guest mountpoints for you:
52
53  guestmount -a guest.img -i --ro /mnt
54
55 For a libvirt guest called "Guest" you could do:
56
57  guestmount -d Guest -i --ro /mnt
58
59 If you don't know what filesystems are contained in a guest or
60 disk image, use L<virt-filesystems(1)> first:
61
62  virt-filesystems MyGuest
63
64 If you want to trace the libguestfs calls but without excessive
65 debugging information, we recommend:
66
67  guestmount [...] --trace /mnt
68
69 If you want to debug the program, we recommend:
70
71  guestmount [...] --trace --verbose /mnt
72
73 =head1 OPTIONS
74
75 =over 4
76
77 =item B<-a image> | B<--add image>
78
79 Add a block device or virtual machine image.
80
81 The format of the disk image is auto-detected.  To override this and
82 force a particular format use the I<--format=..> option.
83
84 =item B<-c URI> | B<--connect URI>
85
86 When used in conjunction with the I<-d> option, this specifies
87 the libvirt URI to use.  The default is to use the default libvirt
88 connection.
89
90 =item B<-d libvirt-domain> | B<--domain libvirt-domain>
91
92 Add disks from the named libvirt domain.  If the I<--ro> option is
93 also used, then any libvirt domain can be used.  However in write
94 mode, only libvirt domains which are shut down can be named here.
95
96 =item B<--dir-cache-timeout N>
97
98 Set the readdir cache timeout to I<N> seconds, the default being 60
99 seconds.  The readdir cache [actually, there are several
100 semi-independent caches] is populated after a readdir(2) call with the
101 stat and extended attributes of the files in the directory, in
102 anticipation that they will be requested soon after.
103
104 There is also a different attribute cache implemented by FUSE
105 (see the FUSE option I<-o attr_timeout>), but the FUSE cache
106 does not anticipate future requests, only cache existing ones.
107
108 =item B<--echo-keys>
109
110 When prompting for keys and passphrases, guestfish normally turns
111 echoing off so you cannot see what you are typing.  If you are not
112 worried about Tempest attacks and there is no one else in the room
113 you can specify this flag to see what you are typing.
114
115 =item B<--format=raw|qcow2|..> | B<--format>
116
117 The default for the I<-a> option is to auto-detect the format of the
118 disk image.  Using this forces the disk format for I<-a> options which
119 follow on the command line.  Using I<--format> with no argument
120 switches back to auto-detection for subsequent I<-a> options.
121
122 If you have untrusted raw-format guest disk images, you should use
123 this option to specify the disk format.  This avoids a possible
124 security problem with malicious guests (CVE-2010-3851).  See also
125 L<guestfs(3)/guestfs_add_drive_opts>.
126
127 =item B<--fuse-help>
128
129 Display help on special FUSE options (see I<-o> below).
130
131 =item B<--help>
132
133 Display brief help and exit.
134
135 =item B<-i> | B<--inspector>
136
137 Using L<virt-inspector(1)> code, inspect the disks looking for
138 an operating system and mount filesystems as they would be
139 mounted on the real virtual machine.
140
141 =item B<--keys-from-stdin>
142
143 Read key or passphrase parameters from stdin.  The default is
144 to try to read passphrases from the user by opening C</dev/tty>.
145
146 =item B<-m dev[:mnt]> | B<--mount dev[:mnt]>
147
148 Mount the named partition or logical volume on the given mountpoint
149 B<in the guest> (this has nothing to do with mountpoints in the host).
150
151 If the mountpoint is omitted, it defaults to C</>.  You have to mount
152 something on C</>.
153
154 =item B<-n> | B<--no-sync>
155
156 By default, we attempt to sync the guest disk when the FUSE mountpoint
157 is unmounted.  If you specify this option, then we don't attempt to
158 sync the disk.  See the discussion of autosync in the L<guestfs(3)>
159 manpage.
160
161 =item B<-o option> | B<--option option>
162
163 Pass extra options to FUSE.
164
165 To get a list of all the extra options supported by FUSE, use the
166 command below.  Note that only the FUSE I<-o> options can be passed,
167 and only some of them are a good idea.
168
169  guestmount --fuse-help
170
171 Some potentially useful FUSE options:
172
173 =over 4
174
175 =item B<-o allow_other>
176
177 Allow other users to see the filesystem.
178
179 =item B<-o attr_timeout=N>
180
181 Enable attribute caching by FUSE, and set the timeout to I<N> seconds.
182
183 =item B<-o kernel_cache>
184
185 Allow the kernel to cache files (reduces the number of reads
186 that have to go through the L<guestfs(3)> API).  This is generally
187 a good idea if you can afford the extra memory usage.
188
189 =item B<-o uid=N> B<-o gid=N>
190
191 Use these options to map all UIDs and GIDs inside the guest filesystem
192 to the chosen values.
193
194 =back
195
196 =item B<-r> | B<--ro>
197
198 Add devices and mount everything read-only.  Also disallow writes and
199 make the disk appear read-only to FUSE.
200
201 This is highly recommended if you are not going to edit the guest
202 disk.  If the guest is running and this option is I<not> supplied,
203 then there is a strong risk of disk corruption in the guest.  We try
204 to prevent this from happening, but it is not always possible.
205
206 See also L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
207
208 =item B<--selinux>
209
210 Enable SELinux support for the guest.
211
212 =item B<-v> | B<--verbose>
213
214 Enable verbose messages from underlying libguestfs.
215
216 =item B<-V> | B<--version>
217
218 Display the program version and exit.
219
220 =item B<-w> | B<--rw>
221
222 This option does nothing at the moment.
223 See L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
224
225 =item B<-x> | B<--trace>
226
227 Trace libguestfs calls and entry into each FUSE function.
228
229 This also stops the daemon from forking into the background.
230
231 =back
232
233 =head1 SEE ALSO
234
235 L<guestfish(1)>,
236 L<virt-inspector(1)>,
237 L<virt-cat(1)>,
238 L<virt-edit(1)>,
239 L<virt-tar(1)>,
240 L<guestfs(3)>,
241 L<http://libguestfs.org/>,
242 L<http://fuse.sf.net/>.
243
244 =head1 AUTHORS
245
246 Richard W.M. Jones (C<rjones at redhat dot com>)
247
248 =head1 COPYRIGHT
249
250 Copyright (C) 2009-2010 Red Hat Inc.
251 L<http://libguestfs.org/>
252
253 This program is free software; you can redistribute it and/or modify
254 it under the terms of the GNU General Public License as published by
255 the Free Software Foundation; either version 2 of the License, or
256 (at your option) any later version.
257
258 This program is distributed in the hope that it will be useful,
259 but WITHOUT ANY WARRANTY; without even the implied warranty of
260 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
261 GNU General Public License for more details.
262
263 You should have received a copy of the GNU General Public License
264 along with this program; if not, write to the Free Software
265 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.