tools/tools/netmap/lb.8

   1 .\" Copyright (c) 2017 Corelight, Inc. and Universita` di Pisa
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd October 28, 2018
  28 .Dt LB 8
  29 .Os
  30 .Sh NAME
  31 .Nm lb
  32 .Nd netmap-based load balancer
  33 .Sh SYNOPSIS
  34 .Bk -words
  35 .Bl -tag -width "lb"
  36 .It Nm
  37 .Op Fl i Ar port
  38 .Op Fl p Ar pipe-group
  39 .Op Fl B Ar extra-buffers
  40 .Op Fl b Ar batch-size
  41 .Op Fl w Ar wait-link
  42 .El
  43 .Ek
  44 .Sh DESCRIPTION
  45 .Nm
  46 reads packets from an input netmap port and sends them to a number of netmap pipes,
  47 trying to balance the packets received by each pipe.
  48 Packets belonging to the
  49 same connection will always be sent to the same pipe.
  50 .Pp
  51 Command line options are listed below.
  52 .Bl -tag -width Ds
  53 .It Fl i Ar port
  54 Name of a netmap port.
  55 It must be supplied exactly once to identify
  56 the input port.
  57 Any netmap port type (e.g., physical interface, VALE switch, pipe,
  58 monitor port) can be used.
  59 .It Fl p Ar name Ns Cm \&: Ns Ar number | number
  60 Add a new pipe group of the given number of pipes.
  61 The pipe group will receive all the packets read from the input port, balanced
  62 among the available pipes.
  63 The receiving ends of the pipes
  64 will be called
  65 .Dq Ar name Ns Em }0
  66 to
  67 .Dq Ar name No Ns Em } Ns Aq Ar number No - 1 .
  68 The name is optional and defaults to
  69 the name of the input port (stripped down of any netmap operator).
  70 If the name is omitted, also the colon can be omitted.
  71 .Pp
  72 This option can be supplied multiple times to define a sequence of pipe groups,
  73 each group receiving all the packets in turn.
  74 .Pp
  75 If no
  76 .Fl p
  77 option is given, a single group of two pipes with default name is assumed.
  78 .Pp
  79 It is allowed to use the same name for several groups.
  80 The pipe numbering in each
  81 group will start from were the previous identically-named group had left.
  82 .It Fl B Ar extra-buffers
  83 Try to reserve the given number of extra buffers.
  84 Extra buffers are shared among
  85 all pipes in all groups and work as an extension of the pipe rings.
  86 If a pipe ring is full for whatever reason,
  87 .Nm
  88 tries to use extra buffers before dropping any packets directed to that pipe.
  89 .Pp
  90 If all extra buffers are busy, some are stolen from the pipe with the longest
  91 backlog.
  92 This gives preference to newer packets over old ones, and prevents a
  93 stalled pipe to deplete the pool of extra buffers.
  94 .It Fl b Ar batch-size
  95 Maximum number of packets processed between two read operations from the input port.
  96 Higher values of batch-size improve performance by amortizing read operations,
  97 but increase the risk of filling up the port internal queues.
  98 .It Fl w Ar wait-link
  99 indicates the number of seconds to wait before transmitting.
 100 It defaults to 2, and may be useful when talking to physical
 101 ports to let link negotiation complete before starting transmission.
 102 .El
 103 .Sh LIMITATIONS
 104 The group chaining assumes that the applications on the receiving end of the
 105 pipes are read-only: they must not modify the buffers or the pipe ring slots
 106 in any way.
 107 .Pp
 108 The group naming is currently implemented by creating a persistent VALE port
 109 with the given name.
 110 If
 111 .Nm
 112 does not exit cleanly the ports will not be removed.
 113 Please use
 114 .Xr vale-ctl 4
 115 to remove any stale persistent VALE port.
 116 .Sh SEE ALSO
 117 .Xr netmap 4 ,
 118 .Xr bridge 8 ,
 119 .Xr pkt-gen 8
 120 .Pp
 121 .Pa http://info.iet.unipi.it/~luigi/netmap/
 122 .Sh AUTHORS
 123 .An -nosplit
 124 .Nm
 125 has been written by
 126 .An Seth Hall
 127 at Corelight, USA.
 128 The facilities related to extra buffers and pipe groups have been added by
 129 .An Giuseppe Lettieri
 130 at University of Pisa, Italy, under contract by Corelight, USA.