X-Git-Url: http://git.annexia.org/?p=virt-top.git;a=blobdiff_plain;f=virt-top%2Fvirt-top.1;h=2665e27b970bae6c19bb3b100df177116e233f8d;hp=7e9c5d41d3bf1f4ccb08f223e6eb2393df8a3434;hb=1f3c5a55e0dbbab20fcd23cd81689e0f6ca72669;hpb=a8b837d5018c488a130fcbea425904817a862210 diff --git a/virt-top/virt-top.1 b/virt-top/virt-top.1 old mode 100644 new mode 100755 index 7e9c5d4..2665e27 --- a/virt-top/virt-top.1 +++ b/virt-top/virt-top.1 @@ -1,15 +1,7 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) .\" .\" 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 @@ -25,11 +17,11 @@ .. .\" 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 +.\" 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- @@ -48,22 +40,25 @@ . 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 (.Sh), items (.Ip), and index +.\" 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. -.if \nF \{\ +.ie \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 +.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. @@ -129,7 +124,11 @@ .\" ======================================================================== .\" .IX Title "VIRT-TOP 1" -.TH VIRT-TOP 1 "2007-08-30" "ocaml-libvirt-0.3.2.6" "Virtualization Support" +.TH VIRT-TOP 1 "2011-01-06" "virt-top-1.0.4" "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" @@ -167,6 +166,14 @@ Batch mode. In this mode keypresses are ignored. .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. @@ -180,7 +187,7 @@ is to run continuously. .IX Item "-o sort" Set the sort order to one of: \&\fBcpu\fR (sort by \f(CW%CPU\fR used), -\&\fBmem\fR (sort by memory 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), @@ -214,19 +221,95 @@ those to process the \s-1CSV\s0 file). 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) +\& 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\-\-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 @@ -265,7 +348,8 @@ toggles back to showing domains. Sort by \f(CW%CPU\fR. .IP "\fIM\fR" 4 .IX Item "M" -Sort by memory. +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. @@ -276,24 +360,132 @@ Sort by domain \s-1ID\s0. .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 "\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 "\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), -\&\fIxm\fR\|(1), -\&\fIxentop\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: +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. @@ -304,16 +496,21 @@ have fixed it. Run .Sp .Vb 1 -\& virt-top --debug virt-top.log +\& 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." -In virt\-top, press the \fIh\fR (help) key, and write down the version of -virt-top and the version of libvirt. They are shown in the first -line. +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.