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.