usr.sbin/valectl/valectl.8

   1 .\" Copyright (c) 2016 Michio Honda.
   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 26, 2019
  28 .Dt VALECTL 8
  29 .Os
  30 .Sh NAME
  31 .Nm valectl
  32 .Nd manage VALE switches provided by netmap
  33 .Sh SYNOPSIS
  34 .Bk -words
  35 .Bl -tag -width "valectl"
  36 .It Nm
  37 .Op Fl g Ar valeSSS:PPP
  38 .Op Fl a Ar valeSSS:interface
  39 .Op Fl h Ar valeSSS:interface
  40 .Op Fl d Ar valeSSS:interface
  41 .Op Fl n Ar interface
  42 .Op Fl r Ar interface
  43 .Op Fl l Ar valeSSS:PPP
  44 .Op Fl l
  45 .Op Fl p Ar valeSSS:PPP
  46 .Op Fl P Ar valeSSS:PPP
  47 .Op Fl C Ar spec
  48 .Op Fl m Ar memid
  49 .El
  50 .Ek
  51 .Sh DESCRIPTION
  52 .Nm
  53 manages and inspects
  54 .Xr vale 4
  55 switches, for instance attaching and detaching interfaces, creating
  56 and deleting persistent VALE ports, or listing the existing switches
  57 and their ports.
  58 In the following,
  59 .Ar valeSSS
  60 is the name of a VALE switch, while
  61 .Ar valeSSS:PPP
  62 is the name of a VALE port of
  63 .Ar valeSSS .
  64 .Pp
  65 When issued without options it lists all the existing switch ports together
  66 with their internal bridge number and port number.
  67 .Bl -tag -width Ds
  68 .It Fl g Ar valeSSS:PPP
  69 Print the number of receive rings of
  70 .Ar valeSSS:PPP .
  71 .It Fl a Ar valeSSS:interface
  72 Attach
  73 .Ar interface
  74 (which must be an existing network interface) to
  75 .Ar valeSSS
  76 and detach it from the host stack.
  77 .It Fl h Ar valeSSS:interface
  78 Attach
  79 .Ar interface
  80 (which must be an existing network interface) to
  81 .Ar valeSSS
  82 while keeping it attached to the host stack.
  83 More precisely, packets coming from
  84 the host stack and directed to the interface will go through the switch, where
  85 they can still reach the interface if the switch rules allow it.
  86 Conversely, packets coming from the interface will go through the switch and,
  87 if appropriate, will reach the host stack.
  88 .It Fl d Ar valeSSS:interface
  89 Detach
  90 .Ar interface
  91 from
  92 .Ar valeSSS .
  93 .It Fl n Ar interface
  94 Create a new persistent VALE port with name
  95 .Ar interface .
  96 The name must be different from any other network interface
  97 already present in the system.
  98 .It Fl d Ar interface
  99 Destroy the persistent VALE port with name
 100 .Ar inteface .
 101 .It Fl l Ar valeSSS:PPP
 102 Show the internal bridge number and port number of the given switch port.
 103 .It Fl p Ar valeSSS:PPP
 104 Enable polling mode for
 105 .Ar valeSSS:PPP .
 106 In polling mode, a dedicated kernel thread is spawned to handle packets
 107 received from
 108 .Ar valeSSS:PPP
 109 and push them into the switch.
 110 The kernel thread busy waits on the switch port rather than relying on
 111 interrupts or notifications.
 112 Polling mode can only be used on physical NICs attached to a VALE switch.
 113 .It Fl P Ar valeSSS:PPP
 114 Disable polling mode for
 115 .Ar valeSSS:PPP .
 116 .It Fl C Ar x | Ar x,y | Ar x,y,z | Ar x,y,z,w
 117 When used in conjunction with
 118 .Fl n
 119 it supplies the number of tx and rx rings and slots.
 120 The full format with four numbers gives, in order, number of tx slots, number
 121 of rx slots, number of tx rings and number of rx rings.
 122 The form with three numbers uses
 123 .Ar z
 124 for both the number of tx and the number of rx rings.
 125 The forms with less than two numbers use the default values for the number
 126 of rings.
 127 The form with two numbers supplies the numbers of tx and rx slots.
 128 The form with only one number uses
 129 .Ar x
 130 for both the number of tx and the number of rx slots.
 131 .Pp
 132 When used in conjunction with
 133 .Fl p
 134 only the first three forms are used.
 135 The first number may be either 0 or 1.
 136 If 0, then all interface rings will be polled by a single thread, running
 137 on the core id given by the second number (the third number, if present,
 138 must be 1).
 139 If the first number is 1, then the ring identified by the second number will
 140 be polled by the core with the same id.
 141 If a third number is given, then this is repeated for as many consecutive
 142 rings and cores.
 143 .It Fl m Ar memid
 144 Used in conjunction with
 145 .Fl n
 146 supplies the netmap memory region identifier to use together with the newly
 147 created persistent VALE port.
 148 These ports use a private memory region by default.
 149 Using this option you can let them share memory with other ports.
 150 Pass 1 as
 151 .Ar memid
 152 to use the global memory region already shared by all
 153 harware netmap ports.
 154 .El
 155 .Sh SEE ALSO
 156 .Xr netmap 4 ,
 157 .Xr vale 4
 158 .Sh AUTHORS
 159 .An -nosplit
 160 .Nm
 161 was written by
 162 .An Michio Honda
 163 at NetApp.