virt-df/virt-df.txt

   1 NAME
   2     virt-df - 'df'-like utility for virtualization stats
   3
   4 SUMMARY
   5     virt-df [-options]
   6
   7 DESCRIPTION
   8     virt-df is a df(1)-like utility for showing the actual disk usage of
   9     guests. Many command line options are the same as for ordinary *df*.
  10
  11     It uses libvirt so it is capable of showing stats across a variety of
  12     different virtualization systems.
  13
  14     There are some shortcomings to the whole approach of reading disk state
  15     from outside the guest. Please read SHORTCOMINGS section below for more
  16     details.
  17
  18 OPTIONS
  19     -a, --all
  20         Show all domains. The default is show only running (active) domains.
  21
  22     -c uri, --connect uri
  23         Connect to libvirt URI. The default is to connect to the default
  24         libvirt URI, normally Xen.
  25
  26     -h, --human-readable
  27         Display human-readable sizes (eg. 10GiB).
  28
  29     -i, --inodes
  30         Display inode information.
  31
  32     --help
  33         Display usage summary.
  34
  35     --version
  36         Display version and exit.
  37
  38 SHORTCOMINGS
  39     virt-df spies on the guest's disk image to try to work out how much disk
  40     space it is actually using. There are some shortcomings to this,
  41     described here.
  42
  43     (1) It does not work over remote connections. The storage API does not
  44     support peeking into remote disks, and libvirt has rejected a request to
  45     add this support.
  46
  47     (2) It only understands a limited set of partition types. Assuming that
  48     the files and partitions that we get back from libvirt / Xen correspond
  49     to block devices in the guests, we can go some way towards manually
  50     parsing those partitions to find out what they contain. We can read the
  51     MBR, LVM, superblocks and so on. However that's a lot of parsing work,
  52     and currently there is no library which understands a wide range of
  53     partition schemes and filesystem types (not even libparted which doesn't
  54     support LVM yet). The Linux kernel does support that, but there's not
  55     really any good way to access that work.
  56
  57     The current implementation uses a hand-coded parser which understands
  58     some simple formats (MBR, LVM2, ext2/3). In future we should use
  59     something like libparted.
  60
  61     (3) The statistics you get are delayed. The real state of, for example,
  62     an ext2 filesystem is only stored in the memory of the guest's kernel.
  63     The ext2 superblock contains some meta-information about blocks used and
  64     free, but this superblock is not up to date. In fact the guest kernel
  65     may not update it even on a 'sync', not until the filesystem is
  66     unmounted. Some operations do appear to write the superblock, for
  67     example fsync(2) [that is my reading of the ext2/3 source code at
  68     least].
  69
  70 SECURITY
  71     The current code is probably not secure against malicious guests. In
  72     particular a malicious guest can set up a disk in such a way that disk
  73     structures with loops can cause virt-df to spin forever. We are
  74     preparing a parsing library which can fix these sorts of problems.
  75
  76     In the meantime, do not run virt-df on untrusted guests.
  77
  78 SEE ALSO
  79     df(1), virsh(1), xm(1), <http://www.libvirt.org/ocaml/>,
  80     <http://www.libvirt.org/>, <http://et.redhat.com/~rjones/>,
  81     <http://caml.inria.fr/>
  82
  83 AUTHORS
  84     Richard W.M. Jones <rjones @ redhat . com>
  85
  86 COPYRIGHT
  87     (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones
  88     http://libvirt.org/
  89
  90     This program is free software; you can redistribute it and/or modify it
  91     under the terms of the GNU General Public License as published by the
  92     Free Software Foundation; either version 2 of the License, or (at your
  93     option) any later version.
  94
  95     This program is distributed in the hope that it will be useful, but
  96     WITHOUT ANY WARRANTY; without even the implied warranty of
  97     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
  98     Public License for more details.
  99
 100     You should have received a copy of the GNU General Public License along
 101     with this program; if not, write to the Free Software Foundation, Inc.,
 102     675 Mass Ave, Cambridge, MA 02139, USA.
 103
 104 REPORTING BUGS
 105     Bugs can be viewed on the Red Hat Bugzilla page:
 106     <https://bugzilla.redhat.com/>.
 107
 108     If you find a bug in virt-df, please follow these steps to report it:
 109
 110     1. Check for existing bug reports
 111         Go to <https://bugzilla.redhat.com/> and search for similar bugs.
 112         Someone may already have reported the same bug, and they may even
 113         have fixed it.
 114
 115     2. Capture debug and error messages
 116         Run
 117
 118          virt-df > virt-df.log 2>&1
 119
 120         and keep *virt-df.log*. It contains error messages which you should
 121         submit with your bug report.
 122
 123     3. Get version of virt-df and version of libvirt.
 124         Run
 125
 126          virt-df --version
 127
 128     4. Submit a bug report.
 129         Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
 130         describe the problem in as much detail as possible.
 131
 132         Remember to include the version numbers (step 3) and the debug
 133         messages file (step 2).
 134
 135     5. Assign the bug to rjones @ redhat.com
 136         Assign or reassign the bug to rjones @ redhat.com (without the
 137         spaces). You can also send me an email with the bug number if you
 138         want a faster response.
 139