Debian: Use /bin/bash as the shell for regression test scripts.
[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 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 want to trace the libguestfs calls but without excessive
57 debugging, we recommend:
58
59  guestmount [-a ... -m ...] --trace /mnt
60
61 If you want to debug the program, we recommend:
62
63  guestmount [-a ... -m ...] --trace --verbose /mnt
64
65 =head1 OPTIONS
66
67 =over 4
68
69 =item B<-a image> | B<--add image>
70
71 Add a block device or virtual machine image.
72
73 =item B<--dir-cache-timeout N>
74
75 Set the readdir cache timeout to I<N> seconds, the default being 60
76 seconds.  The readdir cache [actually, there are several
77 semi-independent caches] is populated after a readdir(2) call with the
78 stat and extended attributes of the files in the directory, in
79 anticipation that they will be requested soon after.
80
81 There is also a different attribute cache implemented by FUSE
82 (see the FUSE option I<-o attr_timeout>), but the FUSE cache
83 does not anticipate future requests, only cache existing ones.
84
85 =item B<--fuse-help>
86
87 Display help on special FUSE options (see I<-o> below).
88
89 =item B<--help>
90
91 Display brief help and exit.
92
93 =item B<-m dev[:mnt]> | B<--mount dev[:mnt]>
94
95 Mount the named partition or logical volume on the given mountpoint
96 B<in the guest> (this has nothing to do with mountpoints in the host).
97
98 If the mountpoint is omitted, it defaults to C</>.  You have to mount
99 something on C</>.
100
101 =item B<-n> | B<--no-sync>
102
103 By default, we attempt to sync the guest disk when the FUSE mountpoint
104 is unmounted.  If you specify this option, then we don't attempt to
105 sync the disk.  See the discussion of autosync in the L<guestfs(3)>
106 manpage.
107
108 =item B<-o option> | B<--option option>
109
110 Pass extra options to FUSE.
111
112 To get a list of all the extra options supported by FUSE, use the
113 command below.  Note that only the FUSE I<-o> options can be passed,
114 and only some of them are a good idea.
115
116  guestmount --fuse-help
117
118 Some potentially useful FUSE options:
119
120 =over 4
121
122 =item B<-o allow_other>
123
124 Allow other users to see the filesystem.
125
126 =item B<-o attr_timeout=N>
127
128 Enable attribute caching by FUSE, and set the timeout to I<N> seconds.
129
130 =item B<-o kernel_cache>
131
132 Allow the kernel to cache files (reduces the number of reads
133 that have to go through the L<guestfs(3)> API).  This is generally
134 a good idea if you can afford the extra memory usage.
135
136 =item B<-o uid=N> B<-o gid=N>
137
138 Use these options to map all UIDs and GIDs inside the guest filesystem
139 to the chosen values.
140
141 =back
142
143 =item B<-r> | B<--ro>
144
145 Add devices and mount everything read-only.  Also disallow writes and
146 make the disk appear read-only to FUSE.
147
148 This is highly recommended if you are not going to edit the guest
149 disk.  If the guest is running and this option is I<not> supplied,
150 then there is a strong risk of disk corruption in the guest.  We try
151 to prevent this from happening, but it is not always possible.
152
153 =item B<--selinux>
154
155 Enable SELinux support for the guest.
156
157 =item B<--trace>
158
159 Trace libguestfs calls (to stderr).
160
161 This also stops the daemon from forking into the background.
162
163 =item B<-v> | B<--verbose>
164
165 Enable verbose messages from underlying libguestfs.
166
167 =item B<-V> | B<--version>
168
169 Display the program version and exit.
170
171 =back
172
173 =head1 SEE ALSO
174
175 L<guestfish(1)>,
176 L<virt-inspector(1)>,
177 L<virt-cat(1)>,
178 L<virt-edit(1)>,
179 L<virt-tar(1)>,
180 L<guestfs(3)>,
181 L<http://libguestfs.org/>,
182 L<http://fuse.sf.net/>.
183
184 =head1 AUTHORS
185
186 Richard W.M. Jones (C<rjones at redhat dot com>)
187
188 =head1 COPYRIGHT
189
190 Copyright (C) 2009 Red Hat Inc.
191 L<http://libguestfs.org/>
192
193 This program is free software; you can redistribute it and/or modify
194 it under the terms of the GNU General Public License as published by
195 the Free Software Foundation; either version 2 of the License, or
196 (at your option) any later version.
197
198 This program is distributed in the hope that it will be useful,
199 but WITHOUT ANY WARRANTY; without even the implied warranty of
200 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
201 GNU General Public License for more details.
202
203 You should have received a copy of the GNU General Public License
204 along with this program; if not, write to the Free Software
205 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.