virt-df/virt-df.pod

   1 =head1 NAME
   2
   3 virt-df - 'df'-like utility for virtualization stats
   4
   5 =head1 SUMMARY
   6
   7 virt-df [-options]
   8
   9 =head1 DESCRIPTION
  10
  11 virt-df is a L<df(1)>-like utility for showing the actual disk usage
  12 of guests.  Many command line options are the same as for ordinary
  13 I<df>.
  14
  15 It uses libvirt so it is capable of showing stats across a variety of
  16 different virtualization systems.
  17
  18 There are some shortcomings to the whole approach of reading disk
  19 state from outside the guest.  Please read SHORTCOMINGS section below
  20 for more details.
  21
  22 =head1 OPTIONS
  23
  24 =over 4
  25
  26 =item B<-a>, B<--all>
  27
  28 Show all domains.  The default is show only running (active) domains.
  29
  30 =item B<-c uri>, B<--connect uri>
  31
  32 Connect to libvirt URI.  The default is to connect to the default
  33 libvirt URI, normally Xen.
  34
  35 =item  B<--debug>
  36
  37 Emit debugging information on stderr.  Please supply this if you
  38 report a bug.
  39
  40 =item B<-h>, B<--human-readable>
  41
  42 Display human-readable sizes (eg. 10GiB).
  43
  44 =item B<-i>, B<--inodes>
  45
  46 Display inode information.
  47
  48 =item B<--help>
  49
  50 Display usage summary.
  51
  52 =item B<-t diskimage>
  53
  54 Test mode.  Instead of checking libvirt for domain information, this
  55 runs virt-df directly on the disk image (or device) supplied.  You may
  56 specify the B<-t> option multiple times.
  57
  58 =item B<--version>
  59
  60 Display version and exit.
  61
  62 =back
  63
  64 =head1 SHORTCOMINGS
  65
  66 virt-df spies on the guest's disk image to try to work out how much
  67 disk space it is actually using.  There are some shortcomings to this,
  68 described here.
  69
  70 (1) It does not work over remote connections.  The storage API does
  71 not support peeking into remote disks, and libvirt has rejected a
  72 request to add this support.
  73
  74 (2) It only understands a limited set of partition types.  Assuming
  75 that the files and partitions that we get back from libvirt / Xen
  76 correspond to block devices in the guests, we can go some way towards
  77 manually parsing those partitions to find out what they contain.  We
  78 can read the MBR, LVM, superblocks and so on.  However that's a lot of
  79 parsing work, and currently there is no library which understands a
  80 wide range of partition schemes and filesystem types (not even
  81 libparted which doesn't support LVM yet).  The Linux kernel does
  82 support that, but there's not really any good way to access that work.
  83
  84 The current implementation uses a hand-coded parser which understands
  85 some simple formats (MBR, LVM2, ext2/3).  In future we should use
  86 something like libparted.
  87
  88 (3) The statistics you get are delayed.  The real state of, for
  89 example, an ext2 filesystem is only stored in the memory of the
  90 guest's kernel.  The ext2 superblock contains some meta-information
  91 about blocks used and free, but this superblock is not up to date.  In
  92 fact the guest kernel may not update it even on a 'sync', not until
  93 the filesystem is unmounted.  Some operations do appear to write the
  94 superblock, for example L<fsync(2)> [that is my reading of the ext2/3
  95 source code at least].
  96
  97 =head1 SECURITY
  98
  99 The current code tries hard to be secure against malicious guests, for
 100 example guests which set up malicious disk partitions.
 101
 102 =head1 SEE ALSO
 103
 104 L<df(1)>,
 105 L<virsh(1)>,
 106 L<xm(1)>,
 107 L<http://www.libvirt.org/ocaml/>,
 108 L<http://www.libvirt.org/>,
 109 L<http://et.redhat.com/~rjones/>,
 110 L<http://caml.inria.fr/>
 111
 112 =head1 AUTHORS
 113
 114 Richard W.M. Jones <rjones @ redhat . com>
 115
 116 =head1 COPYRIGHT
 117
 118 (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones
 119 http://libvirt.org/
 120
 121 This program is free software; you can redistribute it and/or modify
 122 it under the terms of the GNU General Public License as published by
 123 the Free Software Foundation; either version 2 of the License, or
 124 (at your option) any later version.
 125
 126 This program is distributed in the hope that it will be useful,
 127 but WITHOUT ANY WARRANTY; without even the implied warranty of
 128 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 129 GNU General Public License for more details.
 130
 131 You should have received a copy of the GNU General Public License
 132 along with this program; if not, write to the Free Software
 133 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 134
 135 =head1 REPORTING BUGS
 136
 137 Bugs can be viewed on the Red Hat Bugzilla page:
 138 L<https://bugzilla.redhat.com/>.
 139
 140 If you find a bug in virt-df, please follow these steps to report it:
 141
 142 =over 4
 143
 144 =item 1. Check for existing bug reports
 145
 146 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
 147 Someone may already have reported the same bug, and they may even
 148 have fixed it.
 149
 150 =item 2. Capture debug and error messages
 151
 152 Run
 153
 154  virt-df --debug > virt-df.log 2>&1
 155
 156 and keep I<virt-df.log>.  It contains error messages which you should
 157 submit with your bug report.
 158
 159 =item 3. Get version of virt-df and version of libvirt.
 160
 161 Run
 162
 163  virt-df --version
 164
 165 =item 4. Submit a bug report.
 166
 167 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
 168 Please describe the problem in as much detail as possible.
 169
 170 Remember to include the version numbers (step 3) and the debug
 171 messages file (step 2).
 172
 173 =item 5. Assign the bug to rjones @ redhat.com
 174
 175 Assign or reassign the bug to B<rjones @ redhat.com> (without the
 176 spaces).  You can also send me an email with the bug number if you
 177 want a faster response.
 178
 179 =back
 180
 181 =end