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