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