virt-mem.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-MEM 1"
 132 .TH VIRT-MEM 1 "2008-06-10" "virt-mem-0.2.1" "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 .SH "OPTIONS"
 147 .IX Header "OPTIONS"
 148 .IP "\fB\-a\fR, \fB\-\-all\fR" 4
 149 .IX Item "-a, --all"
 150 Show all domains.  The default is show only running (active) domains.
 151 .IP "\fB\-c uri\fR, \fB\-\-connect uri\fR" 4
 152 .IX Item "-c uri, --connect uri"
 153 Connect to libvirt \s-1URI\s0.  The default is to connect to the default
 154 libvirt \s-1URI\s0, normally Xen.
 155 .IP "\fB\-\-csv\fR" 4
 156 .IX Item "--csv"
 157 Print the results in \s-1CSV\s0 format, suitable for importing into a
 158 spreadsheet or database.
 159 .Sp
 160 This option is only supported if virt-df was built with \s-1CSV\s0 support.
 161 .IP "\fB\-\-debug\fR" 4
 162 .IX Item "--debug"
 163 Emit debugging information on stderr.  Please supply this if you
 164 report a bug.
 165 .IP "\fB\-h\fR, \fB\-\-human\-readable\fR" 4
 166 .IX Item "-h, --human-readable"
 167 Display human-readable sizes (eg. \*(L"10GiB\*(R" instead of large numbers).
 168 .IP "\fB\-i\fR, \fB\-\-inodes\fR" 4
 169 .IX Item "-i, --inodes"
 170 Display inode information.
 171 .Sp
 172 This option only works for Unix-like filesystems.
 173 .IP "\fB\-\-help\fR" 4
 174 .IX Item "--help"
 175 Display usage summary.
 176 .IP "\fB\-t diskimage\fR" 4
 177 .IX Item "-t diskimage"
 178 Test mode.  Instead of checking libvirt for domain information, this
 179 runs virt-df directly on the disk image (or device) supplied.  You may
 180 specify the \fB\-t\fR option multiple times.
 181 .IP "\fB\-\-version\fR" 4
 182 .IX Item "--version"
 183 Display version and exit.
 184 .SH "EXAMPLE"
 185 .IX Header "EXAMPLE"
 186 .Vb 5
 187 \& # virt-df
 188 \& Filesystem                1K-blocks    Used Available Type
 189 \& f9x32kvm:hda1                190740   24817    165923 Linux ext2/3
 190 \& f9x32kvm:VolGroup/LogVol00  6568348 3401656   3166692 Linux ext2/3
 191 \& f9x32kvm:VolGroup/LogVol01  1015808                   Linux swap
 192 .Ve
 193 .SH "SHORTCOMINGS"
 194 .IX Header "SHORTCOMINGS"
 195 virt-df spies on the guest's disk image to try to work out how much
 196 disk space it is actually using.  There are some shortcomings to this,
 197 described here.
 198 .PP
 199 (1) It only understands a limited set of partition types.  Assuming
 200 that the files and partitions that we get back from libvirt / Xen
 201 correspond to block devices in the guests, we can go some way towards
 202 manually parsing those partitions to find out what they contain.  We
 203 can read the \s-1MBR\s0, \s-1LVM\s0, superblocks and so on.  However that's a lot of
 204 parsing work, and currently there is no library which understands a
 205 wide range of partition schemes and filesystem types (not even
 206 libparted which doesn't support \s-1LVM\s0 yet).  The Linux kernel does
 207 support that, but there's not really any good way to access that work.
 208 .PP
 209 The current implementation uses a hand-coded parser which understands
 210 some formats (\s-1MBR\s0, \s-1LVM2\s0, ext2/3, \s-1DOS\s0 \s-1FAT\s0, Windows \s-1NTFS\s0, Linux swap and
 211 Linux suspend partitions).
 212 .PP
 213 (2) The statistics you get are delayed.  The real state of, for
 214 example, an ext2 filesystem is only stored in the memory of the
 215 guest's kernel.  The ext2 superblock contains some meta-information
 216 about blocks used and free, but this superblock is not up to date.  In
 217 fact the guest kernel may not update it even on a 'sync', not until
 218 the filesystem is unmounted.  Some operations do appear to write the
 219 superblock, for example \fIfsync\fR\|(2) [that is my reading of the ext2/3
 220 source code at least].
 221 .SH "SECURITY"
 222 .IX Header "SECURITY"
 223 The current code tries hard to be secure against malicious guests, for
 224 example guests which set up malicious disk partitions.
 225 .SH "SEE ALSO"
 226 .IX Header "SEE ALSO"
 227 \&\fIdf\fR\|(1),
 228 \&\fIvirsh\fR\|(1),
 229 \&\fIxm\fR\|(1),
 230 <http://www.libvirt.org/ocaml/>,
 231 <http://www.libvirt.org/>,
 232 <http://et.redhat.com/~rjones/>,
 233 <http://caml.inria.fr/>
 234 .SH "AUTHORS"
 235 .IX Header "AUTHORS"
 236 Richard W.M. Jones <rjones @ redhat . com>
 237 .SH "COPYRIGHT"
 238 .IX Header "COPYRIGHT"
 239 (C) Copyright 2007\-2008 Red Hat Inc., Richard W.M. Jones
 240 http://libvirt.org/
 241 .PP
 242 This program is free software; you can redistribute it and/or modify
 243 it under the terms of the \s-1GNU\s0 General Public License as published by
 244 the Free Software Foundation; either version 2 of the License, or
 245 (at your option) any later version.
 246 .PP
 247 This program is distributed in the hope that it will be useful,
 248 but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
 249 \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
 250 \&\s-1GNU\s0 General Public License for more details.
 251 .PP
 252 You should have received a copy of the \s-1GNU\s0 General Public License
 253 along with this program; if not, write to the Free Software
 254 Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0.
 255 .SH "REPORTING BUGS"
 256 .IX Header "REPORTING BUGS"
 257 Bugs can be viewed on the Red Hat Bugzilla page:
 258 <https://bugzilla.redhat.com/>.
 259 .PP
 260 If you find a bug in virt\-df, please follow these steps to report it:
 261 .IP "1. Check for existing bug reports" 4
 262 .IX Item "1. Check for existing bug reports"
 263 Go to <https://bugzilla.redhat.com/> and search for similar bugs.
 264 Someone may already have reported the same bug, and they may even
 265 have fixed it.
 266 .IP "2. Capture debug and error messages" 4
 267 .IX Item "2. Capture debug and error messages"
 268 Run
 269 .Sp
 270 .Vb 1
 271 \& virt-df --debug > virt-df.log 2>&1
 272 .Ve
 273 .Sp
 274 and keep \fIvirt\-df.log\fR.  It contains error messages which you should
 275 submit with your bug report.
 276 .IP "3. Get version of virt-df and version of libvirt." 4
 277 .IX Item "3. Get version of virt-df and version of libvirt."
 278 Run
 279 .Sp
 280 .Vb 1
 281 \& virt-df --version
 282 .Ve
 283 .IP "4. Submit a bug report." 4
 284 .IX Item "4. Submit a bug report."
 285 Go to <https://bugzilla.redhat.com/> and enter a new bug.
 286 Please describe the problem in as much detail as possible.
 287 .Sp
 288 Remember to include the version numbers (step 3) and the debug
 289 messages file (step 2).
 290 .IP "5. Assign the bug to rjones @ redhat.com" 4
 291 .IX Item "5. Assign the bug to rjones @ redhat.com"
 292 Assign or reassign the bug to \fBrjones @ redhat.com\fR (without the
 293 spaces).  You can also send me an email with the bug number if you
 294 want a faster response.