1 files changed, 174 insertions, 0 deletions
diff --git a/virt-df/virt-df.pod b/virt-df/virt-df.pod
new file mode 100644
index 0000000..84b1d97
--- /dev/null
+++ b/virt-df/virt-df.pod
@@ -0,0 +1,174 @@
+=head1 NAME
+
+virt-df - 'df'-like utility for virtualization stats
+
+=head1 SUMMARY
+
+virt-df [-options]
+
+=head1 DESCRIPTION
+
+virt-df is a L<df(1)>-like utility for showing the actual disk usage
+of guests.  Many command line options are the same as for ordinary
+I<df>.
+
+It uses libvirt so it is capable of showing stats across a variety of
+different virtualization systems.
+
+There are some shortcomings to the whole approach of reading disk
+state from outside the guest.  Please read SHORTCOMINGS section below
+for more details.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-a>, B<--all>
+
+Show all domains.  The default is show only running (active) domains.
+
+=item B<-c uri>, B<--connect uri>
+
+Connect to libvirt URI.  The default is to connect to the default
+libvirt URI, normally Xen.
+
+=item B<-h>, B<--human-readable>
+
+Display human-readable sizes (eg. 10GiB).
+
+=item B<-i>, B<--inodes>
+
+Display inode information.
+
+=item B<--help>
+
+Display usage summary.
+
+=item B<--version>
+
+Display version and exit.
+
+=back
+
+=head1 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 does not work over remote connections.  The storage API does
+not support peeking into remote disks, and libvirt has rejected a
+request to add this support.
+
+(2) 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 simple formats (MBR, LVM2, ext2/3).  In future we should use
+something like libparted.
+
+(3) 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 L<fsync(2)> [that is my reading of the ext2/3
+source code at least].
+
+=head1 SECURITY
+
+The current code is probably not secure against malicious guests.  In
+particular a malicious guest can set up a disk in such a way that disk
+structures with loops can cause virt-df to spin forever.  We are
+preparing a parsing library which can fix these sorts of problems.
+
+In the meantime, do not run virt-df on untrusted guests.
+
+=head1 SEE ALSO
+
+L<df(1)>,
+L<virsh(1)>,
+L<xm(1)>,
+L<http://www.libvirt.org/ocaml/>,
+L<http://www.libvirt.org/>,
+L<http://et.redhat.com/~rjones/>,
+L<http://caml.inria.fr/>
+
+=head1 AUTHORS
+
+Richard W.M. Jones <rjones @ redhat . com>
+
+=head1 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.
+
+=head1 REPORTING BUGS
+
+Bugs can be viewed on the Red Hat Bugzilla page:
+L<https://bugzilla.redhat.com/>.
+
+If you find a bug in virt-df, please follow these steps to report it:
+
+=over 4
+
+=item 1. Check for existing bug reports
+
+Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
+Someone may already have reported the same bug, and they may even
+have fixed it.
+
+=item 2. Capture debug and error messages
+
+Run
+
+ virt-df > virt-df.log 2>&1
+
+and keep I<virt-df.log>.  It contains error messages which you should
+submit with your bug report.
+
+=item 3. Get version of virt-df and version of libvirt.
+
+Run
+
+ virt-df --version
+
+=item 4. Submit a bug report.
+
+Go to L<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).
+
+=item 5. Assign the bug to rjones @ redhat.com
+
+Assign or reassign the bug to B<rjones @ redhat.com> (without the
+spaces).  You can also send me an email with the bug number if you
+want a faster response.
+
+=back
+
+=end