utilities/ovs-dpctl-top.8.in

   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).