share/man/man4/vale.4

   1 .\" Copyright (c) 2012-2013 Luigi Rizzo, 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 .\" This document is derived in part from the enet man page (enet.4)
  26 .\" distributed with 4.3BSD Unix.
  27 .\"
  28 .\" $FreeBSD: head/share/man/man4/vale.4 228017 2011-11-27 06:55:57Z gjb $
  29 .\"
  30 .Dd July 27, 2012
  31 .Dt VALE 4
  32 .Os
  33 .Sh NAME
  34 .Nm vale
  35 .Nd a very fast Virtual Local Ethernet using the netmap API
  36 .Sh SYNOPSIS
  37 .Cd device netmap
  38 .Sh DESCRIPTION
  39 .Nm
  40 is a feature of the
  41 .Nm netmap
  42 module that implements multiple Virtual switches that can
  43 be used to interconnect netmap clients, including traffic
  44 sources and sinks, packet forwarders, userspace firewalls,
  45 and so on.
  46 .Pp
  47 .Nm
  48 is implemented completely in software, and is extremely fast.
  49 On a modern machine it can move almost 20 Million packets per
  50 second (Mpps) per core with small frames, and about 70 Gbit/s
  51 with 1500 byte frames.
  52 .Pp
  53 .Sh OPERATION
  54 .Nm
  55 dynamically creates switches and ports as client connect
  56 to it using the
  57 .Xr netmap 4
  58 API.
  59 .Pp
  60 .Nm
  61 ports are named
  62 .Pa vale[bdg:][port]
  63 where
  64 .Pa vale
  65 is the prefix indicating a VALE switch rather than a standard interface,
  66 .Pa bdg
  67 indicates a specific switch (the colon is a separator),
  68 and
  69 .Pa port
  70 indicates a port within the switch.
  71 Bridge and ports names are arbitrary strings, the only
  72 constraint being that the full name must fit within 16
  73 characters.
  74 .Pp
  75 .Nm
  76 ports can be physical network interfaces that support
  77 .Xr netmap 4
  78 API
  79 by specifying the interface name for
  80 .Pa [port].
  81 See
  82 .Nm OPERATION
  83 section in
  84 .Xr netmap 4
  85 for details of the naming rule.
  86 .Pp
  87 Physical interfaces are attached using
  88 .Pa NIOCGREGIF
  89 command of
  90 .Pa ioctl(),
  91 and
  92 .Pa NETMAP_BDG_ATTACH
  93 at
  94 .Em nr_cmd
  95 field in
  96 .Em struct nmreq .
  97 The corresponding host stack can also be attached to the bridge, specifying
  98 .Pa NETMAP_BDG_HOST
  99 in
 100 .Em nr_arg1 .
 101 To detach the interface from the bridge,
 102 .Pa NETMAP_BDG_DETACH
 103 is used instead of NETMAP_BDG_ATTACH.
 104 The host stack is also detached from the bridge at the same
 105 time if it has been attached.
 106 .Pp
 107 Physical interfaces are treated as system configuration;
 108 they are kept being attached even after the configuring process dies,
 109 and detached by any process.
 110 .Pp
 111 Once a physical interface is attached, this interface is no longer
 112 available to be directly accessed by netmap clients (user processes) or to be
 113 attached by another bridge.
 114 On the other hand, when any netmap client holds the physical interface,
 115 this interface cannot be attached to a bridge.
 116 .Pp
 117 .Pa NETMAP_BDG_LIST
 118 subcommand in nr_cmd of
 119 .Em struct nmreq
 120 is used to obtain bridge and port
 121 information.  There are two modes of how it works;
 122 If any
 123 .Em nr_name
 124 starting from non '\\0' is provided,
 125 .Pa ioctl()
 126 returning
 127 indicates the position of
 128 the named interface.
 129 This position is represented by an index of the bridge and the port, and
 130 put in
 131 .Em nr_arg1
 132 and
 133 .Em nr_arg2
 134 fields, respectively.  If the named interface does not exist,
 135 .Pa ioctl()
 136 returns
 137 .Pa EINVAL .
 138 .Pp
 139 If
 140 .Em nr_name
 141 starting from '\\0' is provided,
 142 .Pa ioctl()
 143 returning indicates the
 144 first existing interface on and after the position specified in
 145 .Em nr_arg1
 146 and
 147 .Em nr_arg2.
 148 If the caller specified a port index greater than the highest
 149 index of the ports, it is recognized as port index 0 of the
 150 next bridge
 151 (
 152 .Em nr_arg1
 153 + 1,
 154 .Em nr_arg2
 155 = 0).
 156 .Pa ioctl()
 157 returns
 158 .Pa EINVAL
 159 if the given position is higher than that of
 160 any existing interface.
 161 On successful return of
 162 .Pa ioctl() ,
 163 the interface name is also stored in
 164 .Em nr_name .
 165 .Pa NETMAP_BDG_LIST
 166 is always used with
 167 .Pa NIOCGINFO
 168 command of
 169 .Pa ioctl()
 170 .Pp
 171 Below is an example of printing all the existing ports walking through
 172 all the bridges.
 173
 174 .Bd -literal -compact
 175 struct nmreq nmr;
 176 int fd = open("/dev/netmap", O_RDWR);
 177
 178 bzero(&nmr, sizeof(nmr));
 179 nmr.nr_version = NETMAP_API;
 180 nmr.nr_cmd = NETMAP_BDG_LIST;
 181 nmr.nr_arg1 = nmr.nr_arg2 = 0; /* start from bridge:0 port:0 */
 182 for (; !ioctl(fd, NIOCGINFO, &nmr); nmr.nr_arg2++) {
 183         D("bridge:%d port:%d %s", nmr.nr_arg1, nmr.nr_arg2,
 184             nmr.nr_name);
 185         nmr.nr_name[0] = '\\0';
 186 }
 187 .Ed
 188 .Pp
 189 See
 190 .Xr netmap 4
 191 for details on the API.
 192 .Ss LIMITS
 193 .Nm
 194 currently supports up to 8 switches, 254 ports per switch,
 195 1024 buffers per port. These hard limits will be
 196 changed to sysctl variables in future releases.
 197 .Pp
 198 Attaching the host stack to the bridge imposes significant performance
 199 degradation when many packets are forwarded to the host stack by either
 200 unicast or broadcast.
 201 This is because every single packet going to the host stack causes mbuf
 202 allocation in the same thread context as one forwarding packets.
 203 .Pp
 204 .Sh SYSCTL VARIABLES
 205 .Nm
 206 uses the following sysctl variables to control operation:
 207 .Bl -tag -width 12
 208 .It dev.netmap.bridge
 209 The maximum number of packets processed internally
 210 in each iteration.
 211 Defaults to 1024, use lower values to trade latency
 212 with throughput.
 213 .Pp
 214 .It dev.netmap.verbose
 215 Set to non-zero values to enable in-kernel diagnostics.
 216 .El
 217 .Pp
 218 .Sh EXAMPLES
 219 Create one switch, with a traffic generator connected to one
 220 port, and a netmap-enabled tcpdump instance on another port:
 221 .Bd -literal -offset indent
 222 tcpdump -ni vale-a:1 &
 223 pkt-gen  -i vale-a:0 -f tx &
 224 .Ed
 225 .Pp
 226 Create two switches,
 227 each connected to two qemu machines on different ports.
 228 .Bd -literal -offset indent
 229 qemu -net nic -net netmap,ifname=vale-1:a ... &
 230 qemu -net nic -net netmap,ifname=vale-1:b ... &
 231 qemu -net nic -net netmap,ifname=vale-2:c ... &
 232 qemu -net nic -net netmap,ifname=vale-2:d ... &
 233 .Ed
 234 .Sh SEE ALSO
 235 .Xr netmap 4
 236 .Pp
 237 .Xr http://info.iet.unipi.it/~luigi/vale/
 238 .Pp
 239 Luigi Rizzo, Giuseppe Lettieri: VALE, a switched ethernet for virtual machines,
 240 June 2012, http://info.iet.unipi.it/~luigi/vale/
 241 .Sh AUTHORS
 242 .An -nosplit
 243 The
 244 .Nm
 245 switch  has been designed and implemented in 2012 by
 246 .An Luigi Rizzo
 247 and
 248 .An Giuseppe Lettieri
 249 at the Universita` di Pisa.
 250 .Pp
 251 .Nm
 252 has been funded by the European Commission within FP7 Projects
 253 CHANGE (257422) and OPENLAB (287581).