[mirror_ovs.git] / utilities / ovs-dpctl-top.8.in

.de IQ
.  br
.  ns
.  IP "\\$1"
..
.TH ovs\-dpctl\-top "8" "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
.
.SH NAME
\fBovs\-dpctl\-top\fR \- Top like behavior for ovs\-dpctl dump\-flows
.
.SH SYNOPSIS
\fBovs\-dpctl\-top\fR [\-h] [\-v] [\-f FLOWFILES] [\-V] [\-s] [\-\-host HOST]
[\-a | \-\-accumulate] [\-\-accumulate\-decay ACCUMULATEDECAY] [\-d DELAY]
.
.SH DESCRIPTION
.PP
This program summarizes \fBovs\-dpctl\fR flow content by aggregating the number
of packets, total bytes and occurrence of the following fields:
.IP
\- Datapath in_port
.IP
\- Ethernet type
.IP
\- Source and destination MAC addresses
.IP
\- IP protocol
.IP
\- Source and destination IPv4 addresses
.IP
\- Source and destination IPv6 addresses
.IP
\- UDP and TCP destination port
.IP
\- Tunnel source and destination addresses
.
.SS "Output shows four values:"
.IP
\- FIELDS: the flow fields for example in_port(1).
.IP
\- COUNT: the number of lines in the dump\-flow output contain the flow field.
.IP
\- PACKETS: the total number of packets containing the flow field.
.IP
\- BYTES: the total number of bytes containing the flow field.  If units are
not present then values are in bytes.
.IP
\- AVERAGE: the average packets size (BYTES/PACKET).
.PP
.SS "Top Behavior"
.PP
While in top mode, the default behavior, the following single character commands
are supported:
.IP
a \- toggles top in accumulate and live mode.  Accumulate mode is described
below.
.IP
s \- toggles which column is used to sort content in decreasing order.  A
DESC title is placed over the column.
.IP
_ \- a space indicating to collect dump\-flow content again
.IP
h \- halt output.  Any character will restart sampling
.IP
f \- cycle through flow fields
.IP
q \- q for quit.
.PP
.SS "Accumulate Mode"
.PP
There are two supported modes: live and accumulate.  The default is live.
The parameter \fB\-\-accumulate\fR  or the 'a' character in top mode enables the
latter.  In live mode, recent dump\-flow content is presented.
Where as accumulate mode keeps track of the prior historical
information until the flow is reset not when the flow is purged.  Reset
flows are determined when the packet count for a flow has decreased from
its previous sample.  There is one caveat, eventually the system will
run out of memory if, after the accumulate\-decay period any flows that
have not been refreshed are purged.  The goal here is to free memory
of flows that are not active.  Statistics are not decremented.  Their purpose
is to reflect the overall history of the flow fields.
.PP
.SS "Debugging Errors"
.PP
Parsing errors are counted and displayed in the status line at the beginning
of the output.  Use the \fB\-\-verbose\fR option with \fB\-\-script to see
what output was not parsed, like this:
.PP
$ ovs\-dpctl dump\-flows | ovs\-dpctl\-top \fB\-\-script\fR \fB\-\-verbose\fR
.PP
Error messages will identify content that failed to parse.
.PP
.SS "Access Remote Hosts"
.PP
The \fB\-\-host\fR must follow the format user@hostname.  This script simply
calls \&'ssh user@Hostname' without checking for login credentials therefore
public keys should be installed on the system identified by hostname, such as:
.PP
$ ssh\-copy\-id user@hostname
.PP
Consult ssh\-copy\-id man pages for more details.
.PP
.SS "Expected usage"
.PP
$ ovs\-dpctl\-top
.PP
or to run as a script:
.PP
$ ovs\-dpctl dump\-flows > dump\-flows.log
.PP
$ ovs\-dpctl\-top \fB\-\-script\fR \fB\-\-flow\-file\fR dump\-flows.log
.SS "OPTIONS"
.TP
\fB\-h\fR, \fB\-\-help\fR
show this help message and exit.
.TP
\fB\-v\fR, \fB\-\-version\fR
show program's version number and exit.
.TP
\fB\-f\fR FLOWFILES, \fB\-\-flow\-file\fR FLOWFILES
file containing flows from ovs\-dpctl dump\-flow.
.TP
\fB\-V\fR, \fB\-\-verbose\fR
enable debug level verbosity.
.TP
\fB\-s\fR, \fB\-\-script\fR
Run from a script (no user interface).
.TP
\fB\-\-host\fR HOST
Specify a user@host for retrieving flows see Accessing
Remote Hosts for more information.
.TP
\fB\-a\fR, \fB\-\-accumulate\fR
Accumulate dump\-flow content.
.TP
\fB\-\-accumulate\-decay\fR ACCUMULATEDECAY
Decay old accumulated flows.  The default is 5 minutes. A value of 0 disables
decay.
.TP
\fB\-d\fR DELAY, \fB\-\-delay\fR DELAY
Delay in milliseconds to collect dump\-flow content (sample rate).
Commit	Line	Data
14b4c575 MH	1	.de IQ
	2	. br
	3	. ns
	4	. IP "\\$1"
	5	..
	6	.TH ovs\-dpctl\-top "8" "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
	7	.
	8	.SH NAME
	9	\fBovs\-dpctl\-top\fR \- Top like behavior for ovs\-dpctl dump\-flows
	10	.
	11	.SH SYNOPSIS
	12	\fBovs\-dpctl\-top\fR [\-h] [\-v] [\-f FLOWFILES] [\-V] [\-s] [\-\-host HOST]
	13	[\-a \| \-\-accumulate] [\-\-accumulate\-decay ACCUMULATEDECAY] [\-d DELAY]
	14	.
	15	.SH DESCRIPTION
	16	.PP
	17	This program summarizes \fBovs\-dpctl\fR flow content by aggregating the number
	18	of packets, total bytes and occurrence of the following fields:
	19	.IP
	20	\- Datapath in_port
	21	.IP
	22	\- Ethernet type
	23	.IP
	24	\- Source and destination MAC addresses
	25	.IP
	26	\- IP protocol
	27	.IP
	28	\- Source and destination IPv4 addresses
	29	.IP
	30	\- Source and destination IPv6 addresses
	31	.IP
	32	\- UDP and TCP destination port
	33	.IP
	34	\- Tunnel source and destination addresses
	35	.
	36	.SS "Output shows four values:"
	37	.IP
	38	\- FIELDS: the flow fields for example in_port(1).
	39	.IP
	40	\- COUNT: the number of lines in the dump\-flow output contain the flow field.
	41	.IP
	42	\- PACKETS: the total number of packets containing the flow field.
	43	.IP
	44	\- BYTES: the total number of bytes containing the flow field. If units are
	45	not present then values are in bytes.
	46	.IP
	47	\- AVERAGE: the average packets size (BYTES/PACKET).
	48	.PP
	49	.SS "Top Behavior"
	50	.PP
	51	While in top mode, the default behavior, the following single character commands
	52	are supported:
	53	.IP
	54	a \- toggles top in accumulate and live mode. Accumulate mode is described
	55	below.
	56	.IP
	57	s \- toggles which column is used to sort content in decreasing order. A
	58	DESC title is placed over the column.
	59	.IP
	60	_ \- a space indicating to collect dump\-flow content again
	61	.IP
	62	h \- halt output. Any character will restart sampling
	63	.IP
	64	f \- cycle through flow fields
65	.IP
66	q \- q for quit.
67	.PP
68	.SS "Accumulate Mode"
69	.PP
70	There are two supported modes: live and accumulate. The default is live.
71	The parameter \fB\-\-accumulate\fR or the 'a' character in top mode enables the
72	latter. In live mode, recent dump\-flow content is presented.
73	Where as accumulate mode keeps track of the prior historical
74	information until the flow is reset not when the flow is purged. Reset
75	flows are determined when the packet count for a flow has decreased from
76	its previous sample. There is one caveat, eventually the system will
77	run out of memory if, after the accumulate\-decay period any flows that
78	have not been refreshed are purged. The goal here is to free memory
79	of flows that are not active. Statistics are not decremented. Their purpose
80	is to reflect the overall history of the flow fields.
81	.PP
82	.SS "Debugging Errors"
83	.PP
84	Parsing errors are counted and displayed in the status line at the beginning
85	of the output. Use the \fB\-\-verbose\fR option with \fB\-\-script to see
86	what output was not parsed, like this:
87	.PP
88	$ ovs\-dpctl dump\-flows \| ovs\-dpctl\-top \fB\-\-script\fR \fB\-\-verbose\fR
89	.PP
90	Error messages will identify content that failed to parse.
91	.PP
92	.SS "Access Remote Hosts"
93	.PP
94	The \fB\-\-host\fR must follow the format user@hostname. This script simply
95	calls \&'ssh user@Hostname' without checking for login credentials therefore
96	public keys should be installed on the system identified by hostname, such as:
97	.PP
98	$ ssh\-copy\-id user@hostname
99	.PP
100	Consult ssh\-copy\-id man pages for more details.
101	.PP
102	.SS "Expected usage"
103	.PP
104	$ ovs\-dpctl\-top
105	.PP
106	or to run as a script:
107	.PP
108	$ ovs\-dpctl dump\-flows > dump\-flows.log
109	.PP
110	$ ovs\-dpctl\-top \fB\-\-script\fR \fB\-\-flow\-file\fR dump\-flows.log
111	.SS "OPTIONS"
112	.TP
113	\fB\-h\fR, \fB\-\-help\fR
114	show this help message and exit.
115	.TP
116	\fB\-v\fR, \fB\-\-version\fR
117	show program's version number and exit.
118	.TP
119	\fB\-f\fR FLOWFILES, \fB\-\-flow\-file\fR FLOWFILES
120	file containing flows from ovs\-dpctl dump\-flow.
121	.TP
122	\fB\-V\fR, \fB\-\-verbose\fR
123	enable debug level verbosity.
124	.TP
125	\fB\-s\fR, \fB\-\-script\fR
126	Run from a script (no user interface).
127	.TP
128	\fB\-\-host\fR HOST
129	Specify a user@host for retrieving flows see Accessing
130	Remote Hosts for more information.
131	.TP
132	\fB\-a\fR, \fB\-\-accumulate\fR
133	Accumulate dump\-flow content.
134	.TP
135	\fB\-\-accumulate\-decay\fR ACCUMULATEDECAY
136	Decay old accumulated flows. The default is 5 minutes. A value of 0 disables
137	decay.
138	.TP
139	\fB\-d\fR DELAY, \fB\-\-delay\fR DELAY
140	Delay in milliseconds to collect dump\-flow content (sample rate).