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.Dd October 26, 2019 26.Dt LB 8 27.Os 28.Sh NAME 29.Nm lb 30.Nd netmap-based load balancer 31.Sh SYNOPSIS 32.Bk -words 33.Bl -tag -width "lb" 34.It Nm 35.Op Fl i Ar port 36.Op Fl p Ar pipe-group 37.Op Fl B Ar extra-buffers 38.Op Fl b Ar batch-size 39.Op Fl w Ar wait-link 40.El 41.Ek 42.Sh DESCRIPTION 43.Nm 44reads packets from an input netmap port and sends them to a number of netmap pipes, 45trying to balance the packets received by each pipe. 46Packets belonging to the 47same connection will always be sent to the same pipe. 48.Pp 49Command line options are listed below. 50.Bl -tag -width Ds 51.It Fl i Ar port 52Name of a netmap port. 53It must be supplied exactly once to identify 54the input port. 55Any netmap port type (e.g., physical interface, VALE switch, pipe, 56monitor port) can be used. 57.It Fl p Ar name Ns Cm \&: Ns Ar number | number 58Add a new pipe group of the given number of pipes. 59The pipe group will receive all the packets read from the input port, balanced 60among the available pipes. 61The receiving ends of the pipes 62will be called 63.Dq Ar name Ns Em }0 64to 65.Dq Ar name No Ns Em } Ns Aq Ar number No - 1 . 66The name is optional and defaults to 67the name of the input port (stripped down of any netmap operator). 68If the name is omitted, also the colon can be omitted. 69.Pp 70This option can be supplied multiple times to define a sequence of pipe groups, 71each group receiving all the packets in turn. 72.Pp 73If no 74.Fl p 75option is given, a single group of two pipes with default name is assumed. 76.Pp 77It is allowed to use the same name for several groups. 78The pipe numbering in each 79group will start from were the previous identically-named group had left. 80.It Fl B Ar extra-buffers 81Try to reserve the given number of extra buffers. 82Extra buffers are shared among 83all pipes in all groups and work as an extension of the pipe rings. 84If a pipe ring is full for whatever reason, 85.Nm 86tries to use extra buffers before dropping any packets directed to that pipe. 87.Pp 88If all extra buffers are busy, some are stolen from the pipe with the longest 89backlog. 90This gives preference to newer packets over old ones, and prevents a 91stalled pipe to deplete the pool of extra buffers. 92.It Fl b Ar batch-size 93Maximum number of packets processed between two read operations from the input port. 94Higher values of batch-size improve performance by amortizing read operations, 95but increase the risk of filling up the port internal queues. 96.It Fl w Ar wait-link 97indicates the number of seconds to wait before transmitting. 98It defaults to 2, and may be useful when talking to physical 99ports to let link negotiation complete before starting transmission. 100.El 101.Sh LIMITATIONS 102The group chaining assumes that the applications on the receiving end of the 103pipes are read-only: they must not modify the buffers or the pipe ring slots 104in any way. 105.Pp 106The group naming is currently implemented by creating a persistent VALE port 107with the given name. 108If 109.Nm 110does not exit cleanly the ports will not be removed. 111Please use 112.Xr valectl 8 113to remove any stale persistent VALE port. 114.Sh SEE ALSO 115.Xr netmap 4 , 116.Xr bridge 8 , 117.Xr pkt-gen 8 118.Pp 119.Pa http://info.iet.unipi.it/~luigi/netmap/ 120.Sh AUTHORS 121.An -nosplit 122.Nm 123has been written by 124.An Seth Hall 125at Corelight, USA. 126The facilities related to extra buffers and pipe groups have been added by 127.An Giuseppe Lettieri 128at University of Pisa, Italy, under contract by Corelight, USA. 129