Runlist parsing, now working.
[virt-df.git] / 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