diff options
author | Richard W.M. Jones <rjones@redhat.com> | 2008-03-04 13:43:04 +0000 |
---|---|---|
committer | Richard W.M. Jones <rjones@redhat.com> | 2008-03-04 13:43:04 +0000 |
commit | ca6baf8fcb2e3ecc917c8ec1e11c1ddbec29afcb (patch) | |
tree | fa5cfce08b8937b9d5a2f30f8a2e1c3c13ad20cb /virt-df/virt-df.1 | |
parent | f1212f9779e92bedf31b7eccb5be495f2c384971 (diff) | |
download | virt-top-ca6baf8fcb2e3ecc917c8ec1e11c1ddbec29afcb.tar.gz virt-top-ca6baf8fcb2e3ecc917c8ec1e11c1ddbec29afcb.tar.xz virt-top-ca6baf8fcb2e3ecc917c8ec1e11c1ddbec29afcb.zip |
"Finish off" this program, add manpage.
Diffstat (limited to 'virt-df/virt-df.1')
-rw-r--r-- | virt-df/virt-df.1 | 280 |
1 files changed, 280 insertions, 0 deletions
diff --git a/virt-df/virt-df.1 b/virt-df/virt-df.1 new file mode 100644 index 0000000..ff7e92d --- /dev/null +++ b/virt-df/virt-df.1 @@ -0,0 +1,280 @@ +.\" 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. |