Initial, non-working FAT32 support.
[virt-df.git] / virt-df / virt-df.1
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  | will give a
29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
32 .tr \(*W-|\(bv\*(Tr
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 .    de IX
57 .    tm Index:\\$1\t\\n%\t"\\$2"
58 ..
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "VIRT-DF 1"
132 .TH VIRT-DF 1 "2008-04-17" "virt-df-2.0.0" "Virtualization Support"
133 .SH "NAME"
134 virt\-df \- 'df'\-like utility for virtualization stats
135 .SH "SUMMARY"
136 .IX Header "SUMMARY"
137 virt-df [\-options]
138 .SH "DESCRIPTION"
139 .IX Header "DESCRIPTION"
140 virt-df is a \fIdf\fR\|(1)\-like utility for showing the actual disk usage
141 of guests.  Many command line options are the same as for ordinary
142 \&\fIdf\fR.
143 .PP
144 It uses libvirt so it is capable of showing stats across a variety of
145 different virtualization systems.
146 .PP
147 There are some shortcomings to the whole approach of reading disk
148 state from outside the guest.  Please read \s-1SHORTCOMINGS\s0 section below
149 for more details.
150 .SH "OPTIONS"
151 .IX Header "OPTIONS"
152 .IP "\fB\-a\fR, \fB\-\-all\fR" 4
153 .IX Item "-a, --all"
154 Show all domains.  The default is show only running (active) domains.
155 .IP "\fB\-c uri\fR, \fB\-\-connect uri\fR" 4
156 .IX Item "-c uri, --connect uri"
157 Connect to libvirt \s-1URI\s0.  The default is to connect to the default
158 libvirt \s-1URI\s0, normally Xen.
159 .IP "\fB\-\-csv\fR" 4
160 .IX Item "--csv"
161 Print the results in \s-1CSV\s0 format, suitable for importing into a
162 spreadsheet or database.
163 .Sp
164 This option is only supported if virt-df was built with \s-1CSV\s0 support.
165 .IP "\fB\-\-debug\fR" 4
166 .IX Item "--debug"
167 Emit debugging information on stderr.  Please supply this if you
168 report a bug.
169 .IP "\fB\-h\fR, \fB\-\-human\-readable\fR" 4
170 .IX Item "-h, --human-readable"
171 Display human-readable sizes (eg. 10GiB).
172 .IP "\fB\-i\fR, \fB\-\-inodes\fR" 4
173 .IX Item "-i, --inodes"
174 Display inode information.
175 .IP "\fB\-\-help\fR" 4
176 .IX Item "--help"
177 Display usage summary.
178 .IP "\fB\-t diskimage\fR" 4
179 .IX Item "-t diskimage"
180 Test mode.  Instead of checking libvirt for domain information, this
181 runs virt-df directly on the disk image (or device) supplied.  You may
182 specify the \fB\-t\fR option multiple times.
183 .IP "\fB\-\-version\fR" 4
184 .IX Item "--version"
185 Display version and exit.
186 .SH "SHORTCOMINGS"
187 .IX Header "SHORTCOMINGS"
188 virt-df spies on the guest's disk image to try to work out how much
189 disk space it is actually using.  There are some shortcomings to this,
190 described here.
191 .PP
192 (1) It does not work over remote connections.  The storage \s-1API\s0 does
193 not support peeking into remote disks, and libvirt has rejected a
194 request to add this support.
195 .PP
196 (2) It only understands a limited set of partition types.  Assuming
197 that the files and partitions that we get back from libvirt / Xen
198 correspond to block devices in the guests, we can go some way towards
199 manually parsing those partitions to find out what they contain.  We
200 can read the \s-1MBR\s0, \s-1LVM\s0, superblocks and so on.  However that's a lot of
201 parsing work, and currently there is no library which understands a
202 wide range of partition schemes and filesystem types (not even
203 libparted which doesn't support \s-1LVM\s0 yet).  The Linux kernel does
204 support that, but there's not really any good way to access that work.
205 .PP
206 The current implementation uses a hand-coded parser which understands
207 some simple formats (\s-1MBR\s0, \s-1LVM2\s0, ext2/3).  In future we should use
208 something like libparted.
209 .PP
210 (3) The statistics you get are delayed.  The real state of, for
211 example, an ext2 filesystem is only stored in the memory of the
212 guest's kernel.  The ext2 superblock contains some meta-information
213 about blocks used and free, but this superblock is not up to date.  In
214 fact the guest kernel may not update it even on a 'sync', not until
215 the filesystem is unmounted.  Some operations do appear to write the
216 superblock, for example \fIfsync\fR\|(2) [that is my reading of the ext2/3
217 source code at least].
218 .SH "SECURITY"
219 .IX Header "SECURITY"
220 The current code tries hard to be secure against malicious guests, for
221 example guests which set up malicious disk partitions.
222 .SH "SEE ALSO"
223 .IX Header "SEE ALSO"
224 \&\fIdf\fR\|(1),
225 \&\fIvirsh\fR\|(1),
226 \&\fIxm\fR\|(1),
227 <http://www.libvirt.org/ocaml/>,
228 <http://www.libvirt.org/>,
229 <http://et.redhat.com/~rjones/>,
230 <http://caml.inria.fr/>
231 .SH "AUTHORS"
232 .IX Header "AUTHORS"
233 Richard W.M. Jones <rjones @ redhat . com>
234 .SH "COPYRIGHT"
235 .IX Header "COPYRIGHT"
236 (C) Copyright 2007\-2008 Red Hat Inc., Richard W.M. Jones
237 http://libvirt.org/
238 .PP
239 This program is free software; you can redistribute it and/or modify
240 it under the terms of the \s-1GNU\s0 General Public License as published by
241 the Free Software Foundation; either version 2 of the License, or
242 (at your option) any later version.
243 .PP
244 This program is distributed in the hope that it will be useful,
245 but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
246 \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
247 \&\s-1GNU\s0 General Public License for more details.
248 .PP
249 You should have received a copy of the \s-1GNU\s0 General Public License
250 along with this program; if not, write to the Free Software
251 Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0.
252 .SH "REPORTING BUGS"
253 .IX Header "REPORTING BUGS"
254 Bugs can be viewed on the Red Hat Bugzilla page:
255 <https://bugzilla.redhat.com/>.
256 .PP
257 If you find a bug in virt\-df, please follow these steps to report it:
258 .IP "1. Check for existing bug reports" 4
259 .IX Item "1. Check for existing bug reports"
260 Go to <https://bugzilla.redhat.com/> and search for similar bugs.
261 Someone may already have reported the same bug, and they may even
262 have fixed it.
263 .IP "2. Capture debug and error messages" 4
264 .IX Item "2. Capture debug and error messages"
265 Run
266 .Sp
267 .Vb 1
268 \& virt-df --debug > virt-df.log 2>&1
269 .Ve
270 .Sp
271 and keep \fIvirt\-df.log\fR.  It contains error messages which you should
272 submit with your bug report.
273 .IP "3. Get version of virt-df and version of libvirt." 4
274 .IX Item "3. Get version of virt-df and version of libvirt."
275 Run
276 .Sp
277 .Vb 1
278 \& virt-df --version
279 .Ve
280 .IP "4. Submit a bug report." 4
281 .IX Item "4. Submit a bug report."
282 Go to <https://bugzilla.redhat.com/> and enter a new bug.
283 Please describe the problem in as much detail as possible.
284 .Sp
285 Remember to include the version numbers (step 3) and the debug
286 messages file (step 2).
287 .IP "5. Assign the bug to rjones @ redhat.com" 4
288 .IX Item "5. Assign the bug to rjones @ redhat.com"
289 Assign or reassign the bug to \fBrjones @ redhat.com\fR (without the
290 spaces).  You can also send me an email with the bug number if you
291 want a faster response.