3 virt-df - 'df'-like utility for virtualization stats
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
15 It uses libvirt so it is capable of showing stats across a variety of
16 different virtualization systems.
18 There are some shortcomings to the whole approach of reading disk
19 state from outside the guest. Please read SHORTCOMINGS section below
28 Show all domains. The default is show only running (active) domains.
30 =item B<-c uri>, B<--connect uri>
32 Connect to libvirt URI. The default is to connect to the default
33 libvirt URI, normally Xen.
35 =item B<-h>, B<--human-readable>
37 Display human-readable sizes (eg. 10GiB).
39 =item B<-i>, B<--inodes>
41 Display inode information.
45 Display usage summary.
49 Display version and exit.
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,
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.
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.
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.
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].
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.
93 In the meantime, do not run virt-df on untrusted guests.
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/>
107 Richard W.M. Jones <rjones @ redhat . com>
111 (C) Copyright 2007-2008 Red Hat Inc., Richard W.M. Jones
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.
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.
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.
128 =head1 REPORTING BUGS
130 Bugs can be viewed on the Red Hat Bugzilla page:
131 L<https://bugzilla.redhat.com/>.
133 If you find a bug in virt-df, please follow these steps to report it:
137 =item 1. Check for existing bug reports
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
143 =item 2. Capture debug and error messages
147 virt-df > virt-df.log 2>&1
149 and keep I<virt-df.log>. It contains error messages which you should
150 submit with your bug report.
152 =item 3. Get version of virt-df and version of libvirt.
158 =item 4. Submit a bug report.
160 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
161 Please describe the problem in as much detail as possible.
163 Remember to include the version numbers (step 3) and the debug
164 messages file (step 2).
166 =item 5. Assign the bug to rjones @ redhat.com
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.