guestfs-browser.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 guestfs-browser - Guest filesystem browser
   6
   7 =head1 SYNOPSIS
   8
   9  guestfs-browser [--options]
  10
  11  guestfs-browser [--options] -d domname
  12
  13  guestfs-browser [--options] -a disk.img [-a disk.img [...]]
  14
  15 =head1 DESCRIPTION
  16
  17 The guest filesystem browser is a graphical program for browsing
  18 virtual machine filesystems and disk images interactively.
  19
  20 If you need to make scripted changes or browse disk images from the
  21 command line, we suggest you look at L<guestfish(1)> or
  22 L<virt-rescue(1)> instead.  If you want to mount a disk image or
  23 virtual machine disk on the host, use L<guestmount(1)>.
  24
  25 To start guestfs-browser with an empty window, use:
  26
  27  guestfs-browser
  28
  29 To start guestfs-browser pointing to a disk image file called
  30 C<disk.img>, use:
  31
  32  guestfs-browser -a disk.img
  33
  34 To start guestfs-browser pointing to a libvirt domain called C<guest>,
  35 use:
  36
  37  guestfs-browser [-c libvirtURI] -d guest
  38
  39 Note that this only works for local libvirt guests (at least the
  40 browser must be able to read the disks locally).
  41
  42 The program does not need to be run as root, unless root is required
  43 in order to access the disk images.  Currently guestfs-browser only
  44 accesses the disk image read only.  It is therefore safe to use
  45 guestfs-browser on live virtual machines, but you may see strange or
  46 inconsistent results.
  47
  48 =head1 OPTIONS
  49
  50 =over 4
  51
  52 =item B<-a>
  53
  54 =item B<--add>
  55
  56 Add I<file> which should be a disk image.  You can supply multiple
  57 disk images by repeating this option.
  58
  59 The format of the disk image is auto-detected.  To override this and
  60 force a particular format use the I<--format=..> option.
  61
  62 =item B<-c> URI
  63
  64 =item B<--connect> URI
  65
  66 If using libvirt, connect to the given I<URI>.  If omitted, then we
  67 connect to the default libvirt hypervisor.
  68
  69 If you specify guest block devices directly (I<-a>), then libvirt is
  70 not used at all.
  71
  72 =item B<-d> guest
  73
  74 =item B<--domain> guest
  75
  76 Add all the disks from the named libvirt guest.
  77
  78 =item B<--format raw|qcow2|..>
  79
  80 =item B<--format "">
  81
  82 The default for the I<-a> option is to auto-detect the format of the
  83 disk image.  Using this forces the disk format for I<-a> options which
  84 follow on the command line.  Using I<--format> with no argument
  85 switches back to auto-detection for subsequent I<-a> options.
  86
  87 For example:
  88
  89  guestfs-browser --format raw -a disk.img
  90
  91 forces raw format (no auto-detection) for C<disk.img>.
  92
  93  guestfs-browser --format raw -a disk.img --format "" -a another.img
  94
  95 forces raw format (no auto-detection) for C<disk.img> and reverts to
  96 auto-detection for C<another.img>.
  97
  98 If you have untrusted raw-format guest disk images, you should use
  99 this option to specify the disk format.  This avoids a possible
 100 security problem with malicious guests (CVE-2010-3851).
 101
 102 =item B<-v>
 103
 104 =item B<--verbose>
 105
 106 Enable verbose messages for debugging.
 107
 108 =item B<-V>
 109
 110 =item B<--version>
 111
 112 Display version number and exit.
 113
 114 =item B<-x>
 115
 116 Enable tracing of libguestfs API calls.
 117
 118 =back
 119
 120 =head1 SEE ALSO
 121
 122 L<guestfs(3)>,
 123 L<guestfish(1)>,
 124 L<virt-cat(1)>,
 125 L<virt-edit(1)>,
 126 L<virt-rescue(1)>,
 127 L<http://people.redhat.com/~rjones/guestfs-browser/>,
 128 L<http://libguestfs.org/>.
 129
 130 =head1 AUTHOR
 131
 132 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 133
 134 =head1 COPYRIGHT
 135
 136 Copyright (C) 2010 Red Hat Inc.
 137
 138 This program is free software; you can redistribute it and/or modify
 139 it under the terms of the GNU General Public License as published by
 140 the Free Software Foundation; either version 2 of the License, or
 141 (at your option) any later version.
 142
 143 This program is distributed in the hope that it will be useful,
 144 but WITHOUT ANY WARRANTY; without even the implied warranty of
 145 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 146 GNU General Public License for more details.
 147
 148 You should have received a copy of the GNU General Public License
 149 along with this program; if not, write to the Free Software
 150 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.