diff options
Diffstat (limited to 'virt-df/virt-df.txt')
| -rw-r--r-- | virt-df/virt-df.txt | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/virt-df/virt-df.txt b/virt-df/virt-df.txt new file mode 100644 index 0000000..fcddafb --- /dev/null +++ b/virt-df/virt-df.txt @@ -0,0 +1,139 @@ +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. + + There are some shortcomings to the whole approach of reading disk state + from outside the guest. Please read SHORTCOMINGS section below for more + details. + +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. + + -h, --human-readable + Display human-readable sizes (eg. 10GiB). + + -i, --inodes + Display inode information. + + --help + Display usage summary. + + --version + Display version and exit. + +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 fsync(2) [that is my reading of the ext2/3 source code at + least]. + +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. + +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 > 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. + |