virt-mem.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 OPTIONS
  15     -a, --all
  16         Show all domains. The default is show only running (active) domains.
  17
  18     -c uri, --connect uri
  19         Connect to libvirt URI. The default is to connect to the default
  20         libvirt URI, normally Xen.
  21
  22     --csv
  23         Print the results in CSV format, suitable for importing into a
  24         spreadsheet or database.
  25
  26         This option is only supported if virt-df was built with CSV support.
  27
  28     --debug
  29         Emit debugging information on stderr. Please supply this if you
  30         report a bug.
  31
  32     -h, --human-readable
  33         Display human-readable sizes (eg. "10GiB" instead of large numbers).
  34
  35     -i, --inodes
  36         Display inode information.
  37
  38         This option only works for Unix-like filesystems.
  39
  40     --help
  41         Display usage summary.
  42
  43     -t diskimage
  44         Test mode. Instead of checking libvirt for domain information, this
  45         runs virt-df directly on the disk image (or device) supplied. You
  46         may specify the -t option multiple times.
  47
  48     --version
  49         Display version and exit.
  50
  51 EXAMPLE
  52      # virt-df
  53      Filesystem                1K-blocks    Used Available Type
  54      f9x32kvm:hda1                190740   24817    165923 Linux ext2/3
  55      f9x32kvm:VolGroup/LogVol00  6568348 3401656   3166692 Linux ext2/3
  56      f9x32kvm:VolGroup/LogVol01  1015808                   Linux swap
  57
  58 SHORTCOMINGS
  59     virt-df spies on the guest's disk image to try to work out how much disk
  60     space it is actually using. There are some shortcomings to this,
  61     described here.
  62
  63     (1) It only understands a limited set of partition types. Assuming that
  64     the files and partitions that we get back from libvirt / Xen correspond
  65     to block devices in the guests, we can go some way towards manually
  66     parsing those partitions to find out what they contain. We can read the
  67     MBR, LVM, superblocks and so on. However that's a lot of parsing work,
  68     and currently there is no library which understands a wide range of
  69     partition schemes and filesystem types (not even libparted which doesn't
  70     support LVM yet). The Linux kernel does support that, but there's not
  71     really any good way to access that work.
  72
  73     The current implementation uses a hand-coded parser which understands
  74     some formats (MBR, LVM2, ext2/3, DOS FAT, Windows NTFS, Linux swap and
  75     Linux suspend partitions).
  76
  77     (2) The statistics you get are delayed. The real state of, for example,
  78     an ext2 filesystem is only stored in the memory of the guest's kernel.
  79     The ext2 superblock contains some meta-information about blocks used and
  80     free, but this superblock is not up to date. In fact the guest kernel
  81     may not update it even on a 'sync', not until the filesystem is
  82     unmounted. Some operations do appear to write the superblock, for
  83     example fsync(2) [that is my reading of the ext2/3 source code at
  84     least].
  85
  86 SECURITY
  87     The current code tries hard to be secure against malicious guests, for
  88     example guests which set up malicious disk partitions.
  89
  90 SEE ALSO
  91     df(1), virsh(1), xm(1), <http://www.libvirt.org/ocaml/>,
  92     <http://www.libvirt.org/>, <http://et.redhat.com/~rjones/>,
  93     <http://caml.inria.fr/>
  94
  95 AUTHORS
  96     Richard W.M. Jones <rjones @ redhat . com>
  97
  98 COPYRIGHT
  99     (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones
 100     http://libvirt.org/
 101
 102     This program is free software; you can redistribute it and/or modify it
 103     under the terms of the GNU General Public License as published by the
 104     Free Software Foundation; either version 2 of the License, or (at your
 105     option) any later version.
 106
 107     This program is distributed in the hope that it will be useful, but
 108     WITHOUT ANY WARRANTY; without even the implied warranty of
 109     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 110     Public License for more details.
 111
 112     You should have received a copy of the GNU General Public License along
 113     with this program; if not, write to the Free Software Foundation, Inc.,
 114     675 Mass Ave, Cambridge, MA 02139, USA.
 115
 116 REPORTING BUGS
 117     Bugs can be viewed on the Red Hat Bugzilla page:
 118     <https://bugzilla.redhat.com/>.
 119
 120     If you find a bug in virt-df, please follow these steps to report it:
 121
 122     1. Check for existing bug reports
 123         Go to <https://bugzilla.redhat.com/> and search for similar bugs.
 124         Someone may already have reported the same bug, and they may even
 125         have fixed it.
 126
 127     2. Capture debug and error messages
 128         Run
 129
 130          virt-df --debug > virt-df.log 2>&1
 131
 132         and keep *virt-df.log*. It contains error messages which you should
 133         submit with your bug report.
 134
 135     3. Get version of virt-df and version of libvirt.
 136         Run
 137
 138          virt-df --version
 139
 140     4. Submit a bug report.
 141         Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
 142         describe the problem in as much detail as possible.
 143
 144         Remember to include the version numbers (step 3) and the debug
 145         messages file (step 2).
 146
 147     5. Assign the bug to rjones @ redhat.com
 148         Assign or reassign the bug to rjones @ redhat.com (without the
 149         spaces). You can also send me an email with the bug number if you
 150         want a faster response.
 151