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<--csv>
  36
  37 Print the results in CSV format, suitable for importing into a
  38 spreadsheet or database.
  39
  40 This option is only supported if virt-df was built with CSV support.
  41
  42 =item B<--debug>
  43
  44 Emit debugging information on stderr.  Please supply this if you
  45 report a bug.
  46
  47 =item B<-h>, B<--human-readable>
  48
  49 Display human-readable sizes (eg. 10GiB).
  50
  51 =item B<-i>, B<--inodes>
  52
  53 Display inode information.
  54
  55 =item B<--help>
  56
  57 Display usage summary.
  58
  59 =item B<-t diskimage>
  60
  61 Test mode.  Instead of checking libvirt for domain information, this
  62 runs virt-df directly on the disk image (or device) supplied.  You may
  63 specify the B<-t> option multiple times.
  64
  65 =item B<--version>
  66
  67 Display version and exit.
  68
  69 =back
  70
  71 =head1 SHORTCOMINGS
  72
  73 virt-df spies on the guest's disk image to try to work out how much
  74 disk space it is actually using.  There are some shortcomings to this,
  75 described here.
  76
  77 (1) It does not work over remote connections.  The storage API does
  78 not support peeking into remote disks, and libvirt has rejected a
  79 request to add this support.
  80
  81 (2) It only understands a limited set of partition types.  Assuming
  82 that the files and partitions that we get back from libvirt / Xen
  83 correspond to block devices in the guests, we can go some way towards
  84 manually parsing those partitions to find out what they contain.  We
  85 can read the MBR, LVM, superblocks and so on.  However that's a lot of
  86 parsing work, and currently there is no library which understands a
  87 wide range of partition schemes and filesystem types (not even
  88 libparted which doesn't support LVM yet).  The Linux kernel does
  89 support that, but there's not really any good way to access that work.
  90
  91 The current implementation uses a hand-coded parser which understands
  92 some simple formats (MBR, LVM2, ext2/3).  In future we should use
  93 something like libparted.
  94
  95 (3) The statistics you get are delayed.  The real state of, for
  96 example, an ext2 filesystem is only stored in the memory of the
  97 guest's kernel.  The ext2 superblock contains some meta-information
  98 about blocks used and free, but this superblock is not up to date.  In
  99 fact the guest kernel may not update it even on a 'sync', not until
 100 the filesystem is unmounted.  Some operations do appear to write the
 101 superblock, for example L<fsync(2)> [that is my reading of the ext2/3
 102 source code at least].
 103
 104 =head1 SECURITY
 105
 106 The current code tries hard to be secure against malicious guests, for
 107 example guests which set up malicious disk partitions.
 108
 109 =head1 SEE ALSO
 110
 111 L<df(1)>,
 112 L<virsh(1)>,
 113 L<xm(1)>,
 114 L<http://www.libvirt.org/ocaml/>,
 115 L<http://www.libvirt.org/>,
 116 L<http://et.redhat.com/~rjones/>,
 117 L<http://caml.inria.fr/>
 118
 119 =head1 AUTHORS
 120
 121 Richard W.M. Jones <rjones @ redhat . com>
 122
 123 =head1 COPYRIGHT
 124
 125 (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones
 126 http://libvirt.org/
 127
 128 This program is free software; you can redistribute it and/or modify
 129 it under the terms of the GNU General Public License as published by
 130 the Free Software Foundation; either version 2 of the License, or
 131 (at your option) any later version.
 132
 133 This program is distributed in the hope that it will be useful,
 134 but WITHOUT ANY WARRANTY; without even the implied warranty of
 135 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 136 GNU General Public License for more details.
 137
 138 You should have received a copy of the GNU General Public License
 139 along with this program; if not, write to the Free Software
 140 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 141
 142 =head1 REPORTING BUGS
 143
 144 Bugs can be viewed on the Red Hat Bugzilla page:
 145 L<https://bugzilla.redhat.com/>.
 146
 147 If you find a bug in virt-df, please follow these steps to report it:
 148
 149 =over 4
 150
 151 =item 1. Check for existing bug reports
 152
 153 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
 154 Someone may already have reported the same bug, and they may even
 155 have fixed it.
 156
 157 =item 2. Capture debug and error messages
 158
 159 Run
 160
 161  virt-df --debug > virt-df.log 2>&1
 162
 163 and keep I<virt-df.log>.  It contains error messages which you should
 164 submit with your bug report.
 165
 166 =item 3. Get version of virt-df and version of libvirt.
 167
 168 Run
 169
 170  virt-df --version
 171
 172 =item 4. Submit a bug report.
 173
 174 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
 175 Please describe the problem in as much detail as possible.
 176
 177 Remember to include the version numbers (step 3) and the debug
 178 messages file (step 2).
 179
 180 =item 5. Assign the bug to rjones @ redhat.com
 181
 182 Assign or reassign the bug to B<rjones @ redhat.com> (without the
 183 spaces).  You can also send me an email with the bug number if you
 184 want a faster response.
 185
 186 =back