--- /dev/null
+NAME
+ virt-df - 'df'-like utility for virtualization stats
+
+SUMMARY
+ virt-df [-options]
+
+DESCRIPTION
+ virt-df is a df(1)-like utility for showing the actual disk usage of
+ guests. Many command line options are the same as for ordinary *df*.
+
+ It uses libvirt so it is capable of showing stats across a variety of
+ different virtualization systems.
+
+OPTIONS
+ -a, --all
+ Show all domains. The default is show only running (active) domains.
+
+ -c uri, --connect uri
+ Connect to libvirt URI. The default is to connect to the default
+ libvirt URI, normally Xen.
+
+ --csv
+ Print the results in CSV format, suitable for importing into a
+ spreadsheet or database.
+
+ This option is only supported if virt-df was built with CSV support.
+
+ --debug
+ Emit debugging information on stderr. Please supply this if you
+ report a bug.
+
+ -h, --human-readable
+ Display human-readable sizes (eg. "10GiB" instead of large numbers).
+
+ -i, --inodes
+ Display inode information.
+
+ This option only works for Unix-like filesystems.
+
+ --help
+ Display usage summary.
+
+ -t diskimage
+ Test mode. Instead of checking libvirt for domain information, this
+ runs virt-df directly on the disk image (or device) supplied. You
+ may specify the -t option multiple times.
+
+ --version
+ Display version and exit.
+
+EXAMPLE
+ # virt-df
+ Filesystem 1K-blocks Used Available Type
+ f9x32kvm:hda1 190740 24817 165923 Linux ext2/3
+ f9x32kvm:VolGroup/LogVol00 6568348 3401656 3166692 Linux ext2/3
+ f9x32kvm:VolGroup/LogVol01 1015808 Linux swap
+
+SHORTCOMINGS
+ virt-df spies on the guest's disk image to try to work out how much disk
+ space it is actually using. There are some shortcomings to this,
+ described here.
+
+ (1) It only understands a limited set of partition types. Assuming that
+ the files and partitions that we get back from libvirt / Xen correspond
+ to block devices in the guests, we can go some way towards manually
+ parsing those partitions to find out what they contain. We can read the
+ MBR, LVM, superblocks and so on. However that's a lot of parsing work,
+ and currently there is no library which understands a wide range of
+ partition schemes and filesystem types (not even libparted which doesn't
+ support LVM yet). The Linux kernel does support that, but there's not
+ really any good way to access that work.
+
+ The current implementation uses a hand-coded parser which understands
+ some formats (MBR, LVM2, ext2/3, DOS FAT, Windows NTFS, Linux swap and
+ Linux suspend partitions).
+
+ (2) The statistics you get are delayed. The real state of, for example,
+ an ext2 filesystem is only stored in the memory of the guest's kernel.
+ The ext2 superblock contains some meta-information about blocks used and
+ free, but this superblock is not up to date. In fact the guest kernel
+ may not update it even on a 'sync', not until the filesystem is
+ unmounted. Some operations do appear to write the superblock, for
+ example fsync(2) [that is my reading of the ext2/3 source code at
+ least].
+
+SECURITY
+ The current code tries hard to be secure against malicious guests, for
+ example guests which set up malicious disk partitions.
+
+SEE ALSO
+ df(1), virsh(1), xm(1), <http://www.libvirt.org/ocaml/>,
+ <http://www.libvirt.org/>, <http://et.redhat.com/~rjones/>,
+ <http://caml.inria.fr/>
+
+AUTHORS
+ Richard W.M. Jones <rjones @ redhat . com>
+
+COPYRIGHT
+ (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones
+ http://libvirt.org/
+
+ This program is free software; you can redistribute it and/or modify it
+ under the terms of the GNU General Public License as published by the
+ Free Software Foundation; either version 2 of the License, or (at your
+ option) any later version.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+ Public License for more details.
+
+ You should have received a copy of the GNU General Public License along
+ with this program; if not, write to the Free Software Foundation, Inc.,
+ 675 Mass Ave, Cambridge, MA 02139, USA.
+
+REPORTING BUGS
+ Bugs can be viewed on the Red Hat Bugzilla page:
+ <https://bugzilla.redhat.com/>.
+
+ If you find a bug in virt-df, please follow these steps to report it:
+
+ 1. Check for existing bug reports
+ Go to <https://bugzilla.redhat.com/> and search for similar bugs.
+ Someone may already have reported the same bug, and they may even
+ have fixed it.
+
+ 2. Capture debug and error messages
+ Run
+
+ virt-df --debug > virt-df.log 2>&1
+
+ and keep *virt-df.log*. It contains error messages which you should
+ submit with your bug report.
+
+ 3. Get version of virt-df and version of libvirt.
+ Run
+
+ virt-df --version
+
+ 4. Submit a bug report.
+ Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
+ describe the problem in as much detail as possible.
+
+ Remember to include the version numbers (step 3) and the debug
+ messages file (step 2).
+
+ 5. Assign the bug to rjones @ redhat.com
+ Assign or reassign the bug to rjones @ redhat.com (without the
+ spaces). You can also send me an email with the bug number if you
+ want a faster response.
+