X-Git-Url: http://git.annexia.org/?p=virt-mem.git;a=blobdiff_plain;f=virt-mem.pod;fp=virt-mem.pod;h=f5dc3c34443d03230718ec234e47a6b31c30a518;hp=0000000000000000000000000000000000000000;hb=9414deeb6210c5f2c5219c6e99eb329b4bb1be26;hpb=ae6f6e8b848a3a49e36a4461715e292d3fc5955d;ds=sidebyside diff --git a/virt-mem.pod b/virt-mem.pod new file mode 100644 index 0000000..f5dc3c3 --- /dev/null +++ b/virt-mem.pod @@ -0,0 +1,188 @@ +=head1 NAME + +virt-df - 'df'-like utility for virtualization stats + +=head1 SUMMARY + +virt-df [-options] + +=head1 DESCRIPTION + +virt-df is a L-like utility for showing the actual disk usage +of guests. Many command line options are the same as for ordinary +I. + +It uses libvirt so it is capable of showing stats across a variety of +different virtualization systems. + +=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<--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. + +=item B<--debug> + +Emit debugging information on stderr. Please supply this if you +report a bug. + +=item B<-h>, B<--human-readable> + +Display human-readable sizes (eg. "10GiB" instead of large numbers). + +=item B<-i>, B<--inodes> + +Display inode information. + +This option only works for Unix-like filesystems. + +=item B<--help> + +Display usage summary. + +=item B<-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 B<-t> option multiple times. + +=item B<--version> + +Display version and exit. + +=back + +=head1 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 + +=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 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 L [that is my reading of the ext2/3 +source code at least]. + +=head1 SECURITY + +The current code tries hard to be secure against malicious guests, for +example guests which set up malicious disk partitions. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L + +=head1 AUTHORS + +Richard W.M. Jones + +=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. + +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 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 --debug > virt-df.log 2>&1 + +and keep I. 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 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 (without the +spaces). You can also send me an email with the bug number if you +want a faster response. + +=back