path: root/virt-df/virt-df.1

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "VIRT-DF 1"
.TH VIRT-DF 1 "2008-03-04" "ocaml-libvirt-0.4.0.3" "Virtualization Support"
.SH "NAME"
virt\-df \- 'df'\-like utility for virtualization stats
.SH "SUMMARY"
.IX Header "SUMMARY"
virt-df [\-options]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
virt-df is a \fIdf\fR\|(1)\-like utility for showing the actual disk usage
of guests.  Many command line options are the same as for ordinary
\&\fIdf\fR.
.PP
It uses libvirt so it is capable of showing stats across a variety of
different virtualization systems.
.PP
There are some shortcomings to the whole approach of reading disk
state from outside the guest.  Please read \s-1SHORTCOMINGS\s0 section below
for more details.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-a\fR, \fB\-\-all\fR" 4
.IX Item "-a, --all"
Show all domains.  The default is show only running (active) domains.
.IP "\fB\-c uri\fR, \fB\-\-connect uri\fR" 4
.IX Item "-c uri, --connect uri"
Connect to libvirt \s-1URI\s0.  The default is to connect to the default
libvirt \s-1URI\s0, normally Xen.
.IP "\fB\-h\fR, \fB\-\-human\-readable\fR" 4
.IX Item "-h, --human-readable"
Display human-readable sizes (eg. 10GiB).
.IP "\fB\-i\fR, \fB\-\-inodes\fR" 4
.IX Item "-i, --inodes"
Display inode information.
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Display usage summary.
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
Display version and exit.
.SH "SHORTCOMINGS"
.IX Header "SHORTCOMINGS"
virt-df spies on the guest's disk image to try to work out how much
disk space it is actually using.  There are some shortcomings to this,
described here.
.PP
(1) It does not work over remote connections.  The storage \s-1API\s0 does
not support peeking into remote disks, and libvirt has rejected a
request to add this support.
.PP
(2) It only understands a limited set of partition types.  Assuming
that the files and partitions that we get back from libvirt / Xen
correspond to block devices in the guests, we can go some way towards
manually parsing those partitions to find out what they contain.  We
can read the \s-1MBR\s0, \s-1LVM\s0, superblocks and so on.  However that's a lot of
parsing work, and currently there is no library which understands a
wide range of partition schemes and filesystem types (not even
libparted which doesn't support \s-1LVM\s0 yet).  The Linux kernel does
support that, but there's not really any good way to access that work.
.PP
The current implementation uses a hand-coded parser which understands
some simple formats (\s-1MBR\s0, \s-1LVM2\s0, ext2/3).  In future we should use
something like libparted.
.PP
(3) The statistics you get are delayed.  The real state of, for
example, an ext2 filesystem is only stored in the memory of the
guest's kernel.  The ext2 superblock contains some meta-information
about blocks used and free, but this superblock is not up to date.  In
fact the guest kernel may not update it even on a 'sync', not until
the filesystem is unmounted.  Some operations do appear to write the
superblock, for example \fIfsync\fR\|(2) [that is my reading of the ext2/3
source code at least].
.SH "SECURITY"
.IX Header "SECURITY"
The current code is probably not secure against malicious guests.  In
particular a malicious guest can set up a disk in such a way that disk
structures with loops can cause virt-df to spin forever.  We are
preparing a parsing library which can fix these sorts of problems.
.PP
In the meantime, do not run virt-df on untrusted guests.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIdf\fR\|(1),
\&\fIvirsh\fR\|(1),
\&\fIxm\fR\|(1),
<http://www.libvirt.org/ocaml/>,
<http://www.libvirt.org/>,
<http://et.redhat.com/~rjones/>,
<http://caml.inria.fr/>
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones <rjones @ redhat . com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
(C) Copyright 2007\-2008 Red Hat Inc., Richard W.M. Jones
http://libvirt.org/
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0.
.SH "REPORTING BUGS"
.IX Header "REPORTING BUGS"
Bugs can be viewed on the Red Hat Bugzilla page:
<https://bugzilla.redhat.com/>.
.PP
If you find a bug in virt\-df, please follow these steps to report it:
.IP "1. Check for existing bug reports" 4
.IX Item "1. Check for existing bug reports"
Go to <https://bugzilla.redhat.com/> and search for similar bugs.
Someone may already have reported the same bug, and they may even
have fixed it.
.IP "2. Capture debug and error messages" 4
.IX Item "2. Capture debug and error messages"
Run
.Sp
.Vb 1
\& virt-df > virt-df.log 2>&1
.Ve
.Sp
and keep \fIvirt\-df.log\fR.  It contains error messages which you should
submit with your bug report.
.IP "3. Get version of virt-df and version of libvirt." 4
.IX Item "3. Get version of virt-df and version of libvirt."
Run
.Sp
.Vb 1
\& virt-df --version
.Ve
.IP "4. Submit a bug report." 4
.IX Item "4. Submit a bug report."
Go to <https://bugzilla.redhat.com/> and enter a new bug.
Please describe the problem in as much detail as possible.
.Sp
Remember to include the version numbers (step 3) and the debug
messages file (step 2).
.IP "5. Assign the bug to rjones @ redhat.com" 4
.IX Item "5. Assign the bug to rjones @ redhat.com"
Assign or reassign the bug to \fBrjones @ redhat.com\fR (without the
spaces).  You can also send me an email with the bug number if you
want a faster response.