+++ /dev/null
-.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
-.\"
-.\" Standard preamble:
-.\" ========================================================================
-.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. \*(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-
-.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\}
-.\"
-.\" Escape single quotes in literal strings from groff's Unicode transform.
-.ie \n(.g .ds Aq \(aq
-.el .ds Aq '
-.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
-.\" entries marked with X<> in POD. Of course, you'll have to process the
-.\" output yourself in some meaningful fashion.
-.ie \nF \{\
-. de IX
-. tm Index:\\$1\t\\n%\t"\\$2"
-..
-. nr % 0
-. rr F
-.\}
-.el \{\
-. de IX
-..
-.\}
-.\"
-.\" 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-TOP 1"
-.TH VIRT-TOP 1 "2011-02-02" "virt-top-1.0.5" "Virtualization Support"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.if n .ad l
-.nh
-.SH "NAME"
-virt\-top \- 'top'\-like utility for virtualization stats
-.SH "SUMMARY"
-.IX Header "SUMMARY"
-virt-top [\-options]
-.SH "DESCRIPTION"
-.IX Header "DESCRIPTION"
-virt-top is a \fItop\fR\|(1)\-like utility for showing stats of virtualized
-domains. Many keys and command line options are the same as for
-ordinary \fItop\fR.
-.PP
-It uses libvirt so it is capable of showing stats across a variety of
-different virtualization systems.
-.SH "OPTIONS"
-.IX Header "OPTIONS"
-.IP "\fB\-1\fR" 4
-.IX Item "-1"
-Display physical CPUs by default (instead of domains).
-When virt-top is running, use the \fI1\fR key to toggle
-between physical CPUs and domains display.
-.IP "\fB\-2\fR" 4
-.IX Item "-2"
-Display network interfaces by default (instead of domains).
-When virt-top is running, use the \fI2\fR key to toggle
-between network interfaces and domains display.
-.IP "\fB\-3\fR" 4
-.IX Item "-3"
-Display block devices (virtual disks) by default (instead of domains).
-When virt-top is running, use the \fI3\fR key to toggle
-between block devices and domains display.
-.IP "\fB\-b\fR" 4
-.IX Item "-b"
-Batch mode. In this mode keypresses are ignored.
-.IP "\fB\-c uri\fR or \fB\-\-connect uri\fR" 4
-.IX Item "-c uri or --connect uri"
-Connect to \s-1URI\s0 given. The default is to connect to the Xen
-hypervisor.
-.Sp
-To connect to \s-1QEMU/KVM\s0 you would normally do \fI\-c qemu:///system\fR
-.Sp
-To connect to libvirtd on a remote machine you would normally do
-\&\fI\-c xen://host/\fR
-.Sp
-Full details on connection URIs is available at
-<http://libvirt.org/uri.html>
-.IP "\fB\-d delay\fR" 4
-.IX Item "-d delay"
-Set the delay between screen updates in seconds.
-The default is 3.0 seconds. You can change this
-while virt-top is running by pressing either \fIs\fR or \fId\fR key.
-.IP "\fB\-n iterations\fR" 4
-.IX Item "-n iterations"
-Set the number of iterations to run. The default
-is to run continuously.
-.IP "\fB\-o sort\fR" 4
-.IX Item "-o sort"
-Set the sort order to one of:
-\&\fBcpu\fR (sort by \f(CW%CPU\fR used),
-\&\fBmem\fR (sort by total memory),
-\&\fBtime\fR (sort by total time),
-\&\fBid\fR (sort by domain \s-1ID\s0),
-\&\fBname\fR (sort by domain name),
-\&\fBnetrx\fR (sort by network received bytes),
-\&\fBnettx\fR (sort by network transmitted bytes),
-\&\fBblockrdrq\fR (sort by block device [disk] read requests),
-\&\fBblockwrrq\fR (sort by block device [disk] write requests).
-.Sp
-While virt-top is running you can change the sort
-order using keys \fIP\fR (cpu), \fIM\fR (memory),
-\&\fIT\fR (total time), \fIN\fR (domain \s-1ID\s0),
-\&\fIF\fR (interactively select the sort field).
-.IP "\fB\-s\fR" 4
-.IX Item "-s"
-Secure mode. Currently this does nothing.
-.IP "\fB\-\-hist\-cpu secs\fR" 4
-.IX Item "--hist-cpu secs"
-Set the time in seconds between updates of the historical
-\&\f(CW%CPU\fR at the top right of the display.
-.IP "\fB\-\-csv file.csv\fR" 4
-.IX Item "--csv file.csv"
-Write the statistics to file \fIfile.csv\fR. First a header is written
-showing the statistics being recorded in each column, then one line is
-written for each screen update. The \s-1CSV\s0 file can be loaded directly
-by most spreadsheet programs.
-.Sp
-Currently the statistics which this records vary between releases of
-virt-top (but the column headers will stay the same, so you can use
-those to process the \s-1CSV\s0 file).
-.Sp
-Not every version of virt-top supports \s-1CSV\s0 output \- it depends how the
-program was compiled (see \fI\s-1README\s0\fR file in the source distribution
-for details).
-.Sp
-To save space you can compress your \s-1CSV\s0 files (if your shell supports
-this feature, eg. \fIbash\fR):
-.Sp
-.Vb 1
-\& virt\-top \-\-csv >(gzip \-9 > output.csv.gz)
-.Ve
-.Sp
-You can use a similar trick to split the \s-1CSV\s0 file up. In this example
-the \s-1CSV\s0 file is split every 1000 lines into files called
-\&\fIoutput.csv.00\fR, \fIoutput.csv.01\fR etc.
-.Sp
-.Vb 1
-\& virt\-top \-\-csv >(split \-d \-l 1000 \- output.csv.)
-.Ve
-.IP "\fB\-\-no\-csv\-cpu\fR" 4
-.IX Item "--no-csv-cpu"
-Disable domain \s-1CPU\s0 stats in \s-1CSV\s0 output.
-.IP "\fB\-\-no\-csv\-block\fR" 4
-.IX Item "--no-csv-block"
-Disable domain block device stats in \s-1CSV\s0 output.
-.IP "\fB\-\-no\-csv\-net\fR" 4
-.IX Item "--no-csv-net"
-Disable domain network interface stats in \s-1CSV\s0 output.
-.IP "\fB\-\-debug filename\fR" 4
-.IX Item "--debug filename"
-Send debug and error messages to \fIfilename\fR.
-To send error messages to syslog you can do:
-.Sp
-.Vb 1
-\& virt\-top \-\-debug >(logger \-t virt\-top)
-.Ve
-.Sp
-See also \s-1REPORTING\s0 \s-1BUGS\s0 below.
-.IP "\fB\-\-init\-file filename\fR" 4
-.IX Item "--init-file filename"
-Read \fIfilename\fR as the init file instead of the default which is
-\&\fI\f(CI$HOME\fI/.virt\-toprc\fR. See also \s-1INIT\s0 \s-1FILE\s0 below.
-.IP "\fB\-\-no\-init\-file\fR" 4
-.IX Item "--no-init-file"
-Do not read any init file.
-.IP "\fB\-\-script\fR" 4
-.IX Item "--script"
-Script mode. There will be no user interface. This is most useful
-when used together with the \fI\-\-csv\fR and \fI\-n\fR options.
-.IP "\fB\-\-stream\fR" 4
-.IX Item "--stream"
-Stream mode. All output is sent to stdout. This can be used from
-shell scripts etc. There is no user interface.
-.IP "\fB\-\-block\-in\-bytes\fR" 4
-.IX Item "--block-in-bytes"
-Show I/O statistics in Bytes. Default is shown in the number of Requests.
-.IP "\fB\-\-end\-time time\fR" 4
-.IX Item "--end-time time"
-The program will exit at the \fItime\fR given.
-.Sp
-The time may be given in one of the following formats:
-.RS 4
-.IP "\fIYYYY-MM-DD \s-1HH:MM:SS\s0\fR" 4
-.IX Item "YYYY-MM-DD HH:MM:SS"
-End time is the date and time given.
-.IP "\fI\s-1HH:MM:SS\s0\fR" 4
-.IX Item "HH:MM:SS"
-End time is the time given, today.
-.IP "\fI+HH:MM:SS\fR" 4
-.IX Item "+HH:MM:SS"
-End time is \s-1HH\s0 hours, \s-1MM\s0 minutes, \s-1SS\s0 seconds in the future (counted
-from the moment that program starts).
-.IP "\fI+secs\fR" 4
-.IX Item "+secs"
-End time is \fIsecs\fR seconds in the future.
-.RE
-.RS 4
-.Sp
-For example to run the program for 3 minutes you could do:
-.Sp
-.Vb 1
-\& virt\-top \-\-end\-time +00:03:00
-.Ve
-.Sp
-or:
-.Sp
-.Vb 1
-\& virt\-top \-\-end\-time +180
-.Ve
-.Sp
-Not every version of virt-top supports this option \- it depends how the
-program was compiled (see \fI\s-1README\s0\fR file in the source distribution
-for details).
-.RE
-.IP "\fB\-\-help\fR" 4
-.IX Item "--help"
-Display usage summary.
-.IP "\fB\-\-version\fR" 4
-.IX Item "--version"
-Display version number and exit.
-.SH "KEYS"
-.IX Header "KEYS"
-Note that keys are case sensitive. For example use upper-case \fIP\fR
-(shift P) to sort by \f(CW%CPU\fR. \fI^\fR before a key means a Ctrl key, so
-\&\fI^L\fR is Ctrl L.
-.IP "\fIspace\fR or \fI^L\fR" 4
-.IX Item "space or ^L"
-Updates the display.
-.IP "\fIq\fR" 4
-.IX Item "q"
-Quits the program.
-.IP "\fIh\fR" 4
-.IX Item "h"
-Displays help.
-.IP "\fIs\fR or \fId\fR" 4
-.IX Item "s or d"
-Change the delay between screen updates.
-.IP "\fIB\fR" 4
-.IX Item "B"
-Toggle Block I/O statistics so they are shown in either bytes or requests.
-.IP "\fI0\fR (number 0)" 4
-.IX Item "0 (number 0)"
-Show the normal list of domains display.
-.IP "\fI1\fR (number 1)" 4
-.IX Item "1 (number 1)"
-Toggle into showing physical CPUs. If pressed
-again toggles back to showing domains (the normal
-display).
-.IP "\fI2\fR" 4
-.IX Item "2"
-Toggle into showing network interfaces. If pressed
-again toggles back to showing domains.
-.IP "\fI3\fR" 4
-.IX Item "3"
-Toggle into showing block devices (virtual disks). If pressed again
-toggles back to showing domains.
-.IP "\fIP\fR" 4
-.IX Item "P"
-Sort by \f(CW%CPU\fR.
-.IP "\fIM\fR" 4
-.IX Item "M"
-Sort by total memory. Note that this shows the total memory
-allocated to the guest, not the memory being used.
-.IP "\fIT\fR" 4
-.IX Item "T"
-Sort by total time.
-.IP "\fIN\fR" 4
-.IX Item "N"
-Sort by domain \s-1ID\s0.
-.IP "\fIF\fR" 4
-.IX Item "F"
-Select the sort field interactively (there are other
-sort fields you can choose using this key).
-.IP "\fIW\fR" 4
-.IX Item "W"
-This creates or overwrites the init file with the current settings.
-.Sp
-This key is disabled if \fI\-\-no\-init\-file\fR was specified on the
-command line or if \fIoverwrite-init-file false\fR is given in
-the init file.
-.SH "INIT FILE"
-.IX Header "INIT FILE"
-When virt-top starts up, it reads initial settings from the
-file \fI.virt\-toprc\fR in the user's home directory.
-.PP
-The name of this file may be overridden using the \fI\-\-init\-file
-filename\fR command line option or may be disabled entirely using
-\&\fI\-\-no\-init\-file\fR.
-.PP
-The init file has a simple format. Blank lines and comments
-beginning with \fI#\fR are ignored. Everything else is a set of
-\&\fIkey value\fR pairs, described below.
-.IP "\fBdisplay\fR \fItask|pcpu|block|net\fR" 4
-.IX Item "display task|pcpu|block|net"
-Sets the major display mode to one of \fItask\fR (tasks, the
-default), \fIpcpu\fR (physical CPUs), \fIblock\fR (block devices),
-or \fInet\fR (network interfaces).
-.IP "\fBdelay\fR \fIsecs\fR" 4
-.IX Item "delay secs"
-Sets the delay between display updates in seconds.
-.IP "\fBhist-cpu\fR \fIsecs\fR" 4
-.IX Item "hist-cpu secs"
-Sets the historical \s-1CPU\s0 delay in seconds.
-.IP "\fBiterations\fR \fIn\fR" 4
-.IX Item "iterations n"
-Sets the number of iterations to run before we exit. Setting
-this to \fI\-1\fR means to run continuously.
-.IP "\fBsort\fR \fIcpu|mem|time|id|name|...\fR" 4
-.IX Item "sort cpu|mem|time|id|name|..."
-Sets the sort order. The option names are the same as for
-the command line \fI\-o\fR option.
-.IP "\fBconnect\fR \fIuri\fR" 4
-.IX Item "connect uri"
-Sets the default connection \s-1URI\s0.
-.IP "\fBdebug\fR \fIfilename\fR" 4
-.IX Item "debug filename"
-Sets the default filename to use for debug and error messages.
-.IP "\fBcsv\fR \fIfilename\fR" 4
-.IX Item "csv filename"
-Enables \s-1CSV\s0 output to the named file.
-.IP "\fBcsv-cpu\fR \fItrue|false\fR" 4
-.IX Item "csv-cpu true|false"
-Enable or disable domain \s-1CPU\s0 stats in \s-1CSV\s0 output.
-.IP "\fBcsv-block\fR \fItrue|false\fR" 4
-.IX Item "csv-block true|false"
-Enable or disable domain block device stats in \s-1CSV\s0 output.
-.IP "\fBcsv-net\fR \fItrue|false\fR" 4
-.IX Item "csv-net true|false"
-Enable or disable domain network interface stats in \s-1CSV\s0 output.
-.IP "\fBbatch\fR \fItrue|false\fR" 4
-.IX Item "batch true|false"
-Sets batch mode.
-.IP "\fBsecure\fR \fItrue|false\fR" 4
-.IX Item "secure true|false"
-Sets secure mode.
-.IP "\fBscript\fR \fItrue|false\fR" 4
-.IX Item "script true|false"
-Sets script mode.
-.IP "\fBstream\fR \fItrue|false\fR" 4
-.IX Item "stream true|false"
-Sets stream mode.
-.IP "\fBblock-in-bytes\fR \fItrue|false\fR" 4
-.IX Item "block-in-bytes true|false"
-Show block device statistics in bytes.
-.IP "\fBend-time\fR \fItime\fR" 4
-.IX Item "end-time time"
-Set the time at which the program exits. See above for the
-time formats supported.
-.IP "\fBoverwrite-init-file\fR \fIfalse\fR" 4
-.IX Item "overwrite-init-file false"
-If set to \fIfalse\fR then the \fIW\fR key will not overwrite the
-init file.
-.PP
-Note that in the current implementation, options specified in
-the init file override options specified on the command line.
-This is a bug and this behaviour may change in the future.
-.SH "NOTES"
-.IX Header "NOTES"
-.SS "Block I/O statistics"
-.IX Subsection "Block I/O statistics"
-This I/O value is the amount of I/O since the previous iteration
-of virt-top. To calculate speed of I/O, you should divide
-the number by delay secs.
-.SS "\s-1NETWORK\s0 \s-1RX\s0 \s-1BYTES\s0 \s-1AND\s0 \s-1PACKETS\s0"
-.IX Subsection "NETWORK RX BYTES AND PACKETS"
-Libvirt/virt\-top has no way to know that a packet transmitted to a
-guest was received (eg. if the guest is not listening). In the
-network \s-1RX\s0 stats, virt-top reports the packets transmitted to the
-guest, on the basis that the guest might receive them.
-.PP
-In particular this includes broadcast packets. Because of the way
-that Linux bridges work, if the guest is connected to a bridge, it
-will probably see a steady \*(L"background noise\*(R" of \s-1RX\s0 packets even when
-the network interface is idle or down. These are caused by \s-1STP\s0
-packets generated by the bridge.
-.SH "SEE ALSO"
-.IX Header "SEE ALSO"
-\&\fItop\fR\|(1),
-\&\fIvirsh\fR\|(1),
-<http://www.libvirt.org/ocaml/>,
-<http://www.libvirt.org/>,
-<http://people.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\-2011 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-top, 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\-top \-\-debug virt\-top.log
-.Ve
-.Sp
-and keep \fIvirt\-top.log\fR. It contains error messages which you
-should submit with your bug report.
-.IP "3. Get version of virt-top and version of libvirt." 4
-.IX Item "3. Get version of virt-top and version of libvirt."
-Use:
-.Sp
-.Vb 1
-\& virt\-top \-\-version
-.Ve
-.Sp
-If you can get the precise version of libvirt you are using
-then that too is helpful.
-.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.
git.annexia.org / virt-top.git / blobdiff