C<virt-df> is a command line tool to display free space on virtual
machine filesystems. Unlike other tools, it doesn't just display the
-amount of space allocated to a virtual machine, but can look inside
-the virtual machine to see how much space is really being used.
+size of disk allocated to a virtual machine, but can look inside disk
+images to see how much space is really being used.
-It is like the L<df(1)> command, but for virtual machines, except that
-it also works for Windows virtual machines.
+If used without any I<-a> or I<-d> arguments, C<virt-df> checks with
+libvirt to get a list of all active and inactive guests, and performs
+a C<df>-type operation on each one in turn, printing out the results.
-If used without any arguments, C<virt-df> checks with libvirt to get a
-list of all active and inactive guests, and performs a C<df>-type
-operation on each one in turn, printing out the results.
+If any I<-a> or I<-d> arguments are specified, C<virt-df> performs a
+C<df>-type operation on either the single named libvirt domain, or on
+the disk image(s) listed on the command line (which must all belong to
+a single VM). In this mode (with arguments), C<virt-df> will I<only
+work for a single guest>. If you want to run on multiple guests, then
+you have to invoke C<virt-df> multiple times.
-If used with any argument(s), C<virt-df> performs a C<df>-type
-operation on either the single named libvirt domain, or on the disk
-image(s) listed on the command line (which must all belong to a single
-VM). In this mode (with arguments), C<virt-df> will I<only work for a
-single guest>. If you want to run on multiple guests, then you have
-to invoke C<virt-df> multiple times.
+Use the I<--csv> option to get a format which can be easily parsed by
+other programs. Other options are similar to the standard L<df(1)>
+command.
-Use the C<--csv> option to get a format which can be easily parsed by
-other programs. Other options are mostly similar to standard C<df>
-options. See below for the complete list.
+=head1 EXAMPLES
+
+Show disk usage for a single libvirt guest called C<F14x64>. Make the
+output human-readable:
+
+ # virt-df -d F14x64 -h
+ Filesystem Size Used Available Use%
+ F14x64:/dev/sda1 484M 66M 393M 14%
+ F14x64:/dev/vg_f13x64/lv_root 7.4G 3.4G 4.0G 46%
+
+Show disk usage for a disk image file called C<test.img>:
+
+ $ virt-df -a test1.img
+ Filesystem 1K-blocks Used Available Use%
+ test1.img:/dev/sda1 99099 1551 92432 2%
=head1 OPTIONS
If you specify guest block devices directly (I<-a>), then libvirt is
not used at all.
+=item B<--csv>
+
+Write out the results in CSV format (comma-separated values). This
+format can be imported easily into databases and spreadsheets, but
+read L</NOTE ABOUT CSV FORMAT> below.
+
=item B<-d> guest
=item B<--domain> guest
-Add all the disks from the named libvirt guest.
+Add all the disks from the named libvirt guest. Domain UUIDs can be
+used instead of names.
=item B<--format=raw|qcow2|..>
If you have untrusted raw-format guest disk images, you should use
this option to specify the disk format. This avoids a possible
-security problem with malicious guests (CVE-2010-3851). See also
-L</add-drive-opts>.
+security problem with malicious guests (CVE-2010-3851).
=item B<-h>
You are not allowed to use I<-h> and I<--csv> at the same time.
-=item B<--inodes> | B<-i>
+=item B<-i>
+
+=item B<--inodes>
Print inodes instead of blocks.
=back
+=head1 STATVFS NUMBERS
+
+C<virt-df> (and L<df(1)>) get information by issuing a L<statvfs(3)>
+system call. You can get the same information directly, either from
+the host (using libguestfs) or inside the guest:
+
+=over 4
+
+=item From the host
+
+Run this command:
+
+ guestfish --ro -d GuestName -i statvfs /
+
+(change C</> to see stats for other filesystems).
+
+=item From inside the guest
+
+Run this command:
+
+ python -c 'import os; s = os.statvfs ("/"); print s'
+
+(change C</> to see stats for other filesystems).
+
+=back
+
=head1 NOTE ABOUT CSV FORMAT
Comma-separated values (CSV) is a deceptive format. It I<seems> like
quote or escape these characters on the command line. See the shell
manual page L<sh(1)> for details.
+=head1 EXIT STATUS
+
+This program returns 0 if successful, or non-zero if there was an
+error.
+
=head1 SEE ALSO
+L<df(1)>,
L<guestfs(3)>,
L<guestfish(1)>,
L<virt-filesystems(1)>,
-L<Sys::Virt(3)>,
L<http://libguestfs.org/>.
=head1 AUTHOR
=head1 COPYRIGHT
-Copyright (C) 2009-2010 Red Hat Inc.
+Copyright (C) 2009-2011 Red Hat Inc.
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
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.
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.