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 or the I<--live>
  30 option.  How this works is better explained in the L<guestfish(1)>
  31 manual page, or by looking at 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 NOTES
  74
  75 =head2 Other users cannot see the filesystem by default
  76
  77 If you mount a filesystem as one user (eg. root), then other users
  78 will not be able to see it by default.  The fix is to add the FUSE
  79 C<allow_other> option when mounting:
  80
  81  sudo guestmount [...] -o allow_other /mnt
  82
  83 =head2 Enabling FUSE
  84
  85 On some distros, you may need to add yourself to a special group
  86 (eg. C<fuse>) before you can use any FUSE filesystem.  This is
  87 necessary on Debian and derivatives.
  88
  89 On other distros, no special group is required.  It is not necessary
  90 on Fedora or Red Hat Enterprise Linux.
  91
  92 =head1 OPTIONS
  93
  94 =over 4
  95
  96 =item B<-a image>
  97
  98 =item B<--add image>
  99
 100 Add a block device or virtual machine image.
 101
 102 The format of the disk image is auto-detected.  To override this and
 103 force a particular format use the I<--format=..> option.
 104
 105 =item B<-c URI>
 106
 107 =item B<--connect URI>
 108
 109 When used in conjunction with the I<-d> option, this specifies
 110 the libvirt URI to use.  The default is to use the default libvirt
 111 connection.
 112
 113 =item B<-d libvirt-domain>
 114
 115 =item B<--domain libvirt-domain>
 116
 117 Add disks from the named libvirt domain.  If the I<--ro> option is
 118 also used, then any libvirt domain can be used.  However in write
 119 mode, only libvirt domains which are shut down can be named here.
 120
 121 Domain UUIDs can be used instead of names.
 122
 123 =item B<--dir-cache-timeout N>
 124
 125 Set the readdir cache timeout to I<N> seconds, the default being 60
 126 seconds.  The readdir cache [actually, there are several
 127 semi-independent caches] is populated after a readdir(2) call with the
 128 stat and extended attributes of the files in the directory, in
 129 anticipation that they will be requested soon after.
 130
 131 There is also a different attribute cache implemented by FUSE
 132 (see the FUSE option I<-o attr_timeout>), but the FUSE cache
 133 does not anticipate future requests, only cache existing ones.
 134
 135 =item B<--echo-keys>
 136
 137 When prompting for keys and passphrases, guestfish normally turns
 138 echoing off so you cannot see what you are typing.  If you are not
 139 worried about Tempest attacks and there is no one else in the room
 140 you can specify this flag to see what you are typing.
 141
 142 =item B<--format=raw|qcow2|..>
 143
 144 =item B<--format>
 145
 146 The default for the I<-a> option is to auto-detect the format of the
 147 disk image.  Using this forces the disk format for I<-a> options which
 148 follow on the command line.  Using I<--format> with no argument
 149 switches back to auto-detection for subsequent I<-a> options.
 150
 151 If you have untrusted raw-format guest disk images, you should use
 152 this option to specify the disk format.  This avoids a possible
 153 security problem with malicious guests (CVE-2010-3851).  See also
 154 L<guestfs(3)/guestfs_add_drive_opts>.
 155
 156 =item B<--fuse-help>
 157
 158 Display help on special FUSE options (see I<-o> below).
 159
 160 =item B<--help>
 161
 162 Display brief help and exit.
 163
 164 =item B<-i>
 165
 166 =item B<--inspector>
 167
 168 Using L<virt-inspector(1)> code, inspect the disks looking for
 169 an operating system and mount filesystems as they would be
 170 mounted on the real virtual machine.
 171
 172 =item B<--keys-from-stdin>
 173
 174 Read key or passphrase parameters from stdin.  The default is
 175 to try to read passphrases from the user by opening C</dev/tty>.
 176
 177 =item B<--live>
 178
 179 Connect to a live virtual machine.
 180 (Experimental, see L<guestfs(3)/ATTACHING TO RUNNING DAEMONS>).
 181
 182 =item B<-m dev[:mountpoint[:options]]>
 183
 184 =item B<--mount dev[:mountpoint[:options]]>
 185
 186 Mount the named partition or logical volume on the given mountpoint
 187 B<in the guest> (this has nothing to do with mountpoints in the host).
 188
 189 If the mountpoint is omitted, it defaults to C</>.  You have to mount
 190 something on C</>.
 191
 192 The third (and rarely used) part of the mount parameter is the list of
 193 mount options used to mount the underlying filesystem.  If this is not
 194 given, then the mount options are either the empty string or C<ro>
 195 (the latter if the I<--ro> flag is used).  By specifying the mount
 196 options, you override this default choice.  Probably the only time you
 197 would use this is to enable ACLs and/or extended attributes if the
 198 filesystem can support them:
 199
 200  -m /dev/sda1:/:acl,user_xattr
 201
 202 =item B<-n>
 203
 204 =item B<--no-sync>
 205
 206 By default, we attempt to sync the guest disk when the FUSE mountpoint
 207 is unmounted.  If you specify this option, then we don't attempt to
 208 sync the disk.  See the discussion of autosync in the L<guestfs(3)>
 209 manpage.
 210
 211 =item B<-o option>
 212
 213 =item B<--option option>
 214
 215 Pass extra options to FUSE.
 216
 217 To get a list of all the extra options supported by FUSE, use the
 218 command below.  Note that only the FUSE I<-o> options can be passed,
 219 and only some of them are a good idea.
 220
 221  guestmount --fuse-help
 222
 223 Some potentially useful FUSE options:
 224
 225 =over 4
 226
 227 =item B<-o allow_other>
 228
 229 Allow other users to see the filesystem.
 230
 231 =item B<-o attr_timeout=N>
 232
 233 Enable attribute caching by FUSE, and set the timeout to I<N> seconds.
 234
 235 =item B<-o kernel_cache>
 236
 237 Allow the kernel to cache files (reduces the number of reads
 238 that have to go through the L<guestfs(3)> API).  This is generally
 239 a good idea if you can afford the extra memory usage.
 240
 241 =item B<-o uid=N> B<-o gid=N>
 242
 243 Use these options to map all UIDs and GIDs inside the guest filesystem
 244 to the chosen values.
 245
 246 =back
 247
 248 =item B<-r>
 249
 250 =item B<--ro>
 251
 252 Add devices and mount everything read-only.  Also disallow writes and
 253 make the disk appear read-only to FUSE.
 254
 255 This is highly recommended if you are not going to edit the guest
 256 disk.  If the guest is running and this option is I<not> supplied,
 257 then there is a strong risk of disk corruption in the guest.  We try
 258 to prevent this from happening, but it is not always possible.
 259
 260 See also L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
 261
 262 =item B<--selinux>
 263
 264 Enable SELinux support for the guest.
 265
 266 =item B<-v>
 267
 268 =item B<--verbose>
 269
 270 Enable verbose messages from underlying libguestfs.
 271
 272 =item B<-V>
 273
 274 =item B<--version>
 275
 276 Display the program version and exit.
 277
 278 =item B<-w>
 279
 280 =item B<--rw>
 281
 282 This changes the I<-a>, I<-d> and I<-m> options so that disks are
 283 added and mounts are done read-write.
 284
 285 See L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
 286
 287 =item B<-x>
 288
 289 =item B<--trace>
 290
 291 Trace libguestfs calls and entry into each FUSE function.
 292
 293 This also stops the daemon from forking into the background.
 294
 295 =back
 296
 297 =head1 FILES
 298
 299 =over 4
 300
 301 =item $HOME/.libguestfs-tools.rc
 302
 303 =item /etc/libguestfs-tools.conf
 304
 305 This configuration file controls the default read-only or read-write
 306 mode (I<--ro> or I<--rw>).
 307
 308 See L<guestfish(1)/OPENING DISKS FOR READ AND WRITE>.
 309
 310 =back
 311
 312 =head1 EXIT STATUS
 313
 314 This program returns 0 if successful, or non-zero if there was an
 315 error.
 316
 317 =head1 SEE ALSO
 318
 319 L<guestfish(1)>,
 320 L<virt-inspector(1)>,
 321 L<virt-cat(1)>,
 322 L<virt-edit(1)>,
 323 L<virt-tar(1)>,
 324 L<guestfs(3)>,
 325 L<http://libguestfs.org/>,
 326 L<http://fuse.sf.net/>.
 327
 328 =head1 AUTHORS
 329
 330 Richard W.M. Jones (C<rjones at redhat dot com>)
 331
 332 =head1 COPYRIGHT
 333
 334 Copyright (C) 2009-2010 Red Hat Inc.
 335 L<http://libguestfs.org/>
 336
 337 This program is free software; you can redistribute it and/or modify
 338 it under the terms of the GNU General Public License as published by
 339 the Free Software Foundation; either version 2 of the License, or
 340 (at your option) any later version.
 341
 342 This program is distributed in the hope that it will be useful,
 343 but WITHOUT ANY WARRANTY; without even the implied warranty of
 344 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 345 GNU General Public License for more details.
 346
 347 You should have received a copy of the GNU General Public License
 348 along with this program; if not, write to the Free Software
 349 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.