X-Git-Url: http://git.annexia.org/?p=virt-top.git;a=blobdiff_plain;f=virt-top%2Fvirt-top.1;fp=virt-top%2Fvirt-top.1;h=0000000000000000000000000000000000000000;hp=55a7877609a8491c113f2ee3d92eea242d197605;hb=32a6888f045f64a3fb3423e21897977f9a839bf9;hpb=5fa5553c047155cf99fca9940cecdbc64c93acaf diff --git a/virt-top/virt-top.1 b/virt-top/virt-top.1 deleted file mode 100755 index 55a7877..0000000 --- a/virt-top/virt-top.1 +++ /dev/null @@ -1,546 +0,0 @@ -.\" 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 - -.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), -, -, -, - -.SH "AUTHORS" -.IX Header "AUTHORS" -Richard W.M. Jones -.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: -. -.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 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 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.