virt-df/virt-df.pod

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