share/man/man4/ng_vlan_rotate.4

   1 .\"-
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" Copyright (c) 2019-2021 IKS Service GmbH
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" Author: Lutz Donnerhacke <lutz@donnerhacke.de>
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd January 26, 2021
  32 .Dt NG_VLAN_ROTATE 4
  33 .Os
  34 .Sh NAME
  35 .Nm ng_vlan_rotate
  36 .Nd IEEE 802.1ad VLAN manipulation netgraph node type
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In netgraph.h
  40 .In netgraph/ng_vlan_rotate.h
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 node type manipulates the order of VLAN tags of frames tagged
  45 according to the IEEE 802.1ad (an extension of IEEE 802.1Q) standard
  46 between different hooks.
  47 .Pp
  48 Each node has four special hooks,
  49 .Va original ,
  50 .Va ordered ,
  51 .Va excessive ,
  52 and
  53 .Va incomplete .
  54 .Pp
  55 A frame tagged with an arbitrary number of
  56 .Dv ETHERTYPE_VLAN ,
  57 .Dv ETHERTYPE_QINQ ,
  58 and
  59 .Dv 0x9100
  60 tags received on the
  61 .Va original
  62 hook will be rearranged to a new order of those tags and is sent out
  63 the
  64 .Dq ordered
  65 hook.
  66 After successful processing the
  67 .Va histogram
  68 counter for the observed stack size increments.
  69 .Pp
  70 If it contains fewer VLANs in the stack than the configured
  71 .Va min
  72 limit, the frame is sent out to the
  73 .Va incomplete
  74 hook and the
  75 .Va incomplete
  76 counter increments.
  77 .Pp
  78 If there are more VLANs in the stack than the configured
  79 .Va max
  80 limit, the frame is sent out to the
  81 .Va excessive
  82 hook and the
  83 .Va excessive
  84 counter increments.
  85 .Pp
  86 If the destination hook is not connected, the frame is dropped and the
  87 .Va drops
  88 counter increments.
  89 .Pp
  90 For Ethernet frames received on the
  91 .Va ordered
  92 hook, the transformation is reversed and is passed to the
  93 .Va original
  94 hook.
  95 Please note that this process is identical to the one described
  96 above, besides the ordered/original hooks are swapped and the
  97 transformation is reversed.
  98 .Pp
  99 An Ethernet frame received on the
 100 .Va incomplete
 101 or
 102 .Va excessive
 103 hook is forwarded to the
 104 .Va original
 105 hook without any modification.
 106 .Pp
 107 This node supports only one operation at the moment: Rotation of the
 108 VLANs in the stack.
 109 Setting the configuration parameter
 110 .Va rot
 111 to a positive value, the stack will roll up by this amount.
 112 Negative values will roll down.
 113 A typical scenario is setting the value to 1 in order to bring the
 114 innermost VLAN tag to the outmost level.
 115 Rotation includes the VLAN id, the ether type, and the QOS parameters
 116 pcp and cfi.
 117 Typical QOS handling refers to the outmost setting, so be careful to
 118 keep your QOS intact.
 119 .Sh HOOKS
 120 This node type supports the following hooks:
 121 .Bl -tag -width incomplete
 122 .It Va original
 123 Typically this hook would be connected to a
 124 .Xr ng_ether 4
 125 node, using the
 126 .Va lower
 127 hook connected to a carrier network.
 128 .It Va ordered
 129 Typically this hook would be connected to a
 130 .Xr ng_vlan 4
 131 type node using the
 132 .Va downstream
 133 hook in order to separate services.
 134 .It Va excessive
 135 see below.
 136 .It Va incomplete
 137 Typically those hooks would be attached to a
 138 .Xr ng_eiface 4
 139 type node using the
 140 .Va ether
 141 hook for anomaly monitoring purposes.
 142 .El
 143 .Sh CONTROL MESSAGES
 144 This node type supports the generic control messages, plus the following:
 145 .Bl -tag -width foo
 146 .It Dv NGM_VLANROTATE_GET_CONF Pq Ic getconf
 147 Read the current configuration.
 148 .It Dv NGM_VLANROTATE_SET_CONF Pq Ic setconf
 149 Set the current configuration.
 150 .It Dv NGM_VLANROTATE_GET_STAT Pq Ic getstat
 151 Read the current statistics.
 152 .It Dv NGM_VLANROTATE_CLR_STAT Pq Ic clrstat
 153 Zeroize the statistics.
 154 .It Dv NGM_VLANROTATE_GETCLR_STAT Pq Ic getclrstat
 155 Read the current statistics and zeroize it in one step.
 156 .El
 157 .Sh EXAMPLES
 158 The first example demonstrates how to rotate double or triple tagged
 159 frames so that the innermost C-VLAN can be used as service
 160 discriminator.
 161 The single or double tagged frames (C-VLAN removed) are sent out to an
 162 interface pointing to different infrastucture.
 163 .Bd -literal
 164 #!/bin/sh
 165
 166 BNG_IF=ixl3
 167 VOIP_IF=bge2
 168
 169 ngctl -f- <<EOF
 170 mkpeer ${BNG_IF}: vlan_rotate lower original
 171 name ${BNG_IF}:lower rotate
 172 msg rotate: setconf { min=2 max=3 rot=1 }
 173 mkpeer rotate: vlan ordered downstream
 174 name rotate:ordered services
 175 connect services: ${VOIP_IF} voip lower
 176 msg services: addfilter { vlan=123 hook="voip" }
 177 EOF
 178 .Ed
 179 .Pp
 180 Now inject the following sample frame on the
 181 .Dv BNG_IF
 182 interface:
 183 .Bd -literal
 184 00:00:00:00:01:01 > 00:01:02:03:04:05,
 185  ethertype 802.1Q-9100 (0x9100), length 110: vlan 2, p 1,
 186  ethertype 802.1Q-QinQ, vlan 101, p 0,
 187  ethertype 802.1Q, vlan 123, p 7,
 188  ethertype IPv4, (tos 0x0, ttl 64, id 15994, offset 0, flags [none],
 189   proto ICMP (1), length 84) 192.168.140.101 > 192.168.140.1:
 190   ICMP echo request, id 40234, seq 0, length 64
 191 .Ed
 192 .Pp
 193 The frame ejected on the
 194 .Va ordered
 195 hook will look like this:
 196 .Bd -literal
 197 00:00:00:00:01:01 > 00:01:02:03:04:05,
 198  ethertype 802.1Q (0x8100), length 110: vlan 123, p 7,
 199  ethertype 802.1Q-9100, vlan 2, p 1,
 200  ethertype 802.1Q-QinQ, vlan 101, p 0,
 201  ethertype IPv4, (tos 0x0, ttl 64, id 15994, offset 0, flags [none],
 202   proto ICMP (1), length 84) 192.168.140.101 > 192.168.140.1:
 203   ICMP echo request, id 40234, seq 0, length 64
 204 .Ed
 205 .Pp
 206 Hence, the frame pushed out to the
 207 .Dv VOIP_IF
 208 will have this form:
 209 .Bd -literal
 210 00:00:00:00:01:01 > 00:01:02:03:04:05,
 211  ethertype 802.1Q-9100, vlan 2, p 1,
 212  ethertype 802.1Q-QinQ, vlan 101, p 0,
 213  ethertype IPv4, (tos 0x0, ttl 64, id 15994, offset 0, flags [none],
 214   proto ICMP (1), length 84) 192.168.140.101 > 192.168.140.1:
 215   ICMP echo request, id 40234, seq 0, length 64
 216 .Ed
 217 .Pp
 218 The second example distinguishes between double tagged and single
 219 tagged frames.
 220 .Bd -literal
 221 #!/bin/sh
 222
 223 IN_IF=bge1
 224
 225 ngctl -f- <<EOF
 226 mkpeer ${IN_IF}: vlan_rotate lower original
 227 name ${IN_IF}:lower separate
 228 msg separate: setconf { min=1 max=1 rot=0 }
 229 mkpeer separate: eiface incomplete ether
 230 name separate:incomplete untagged
 231 mkpeer separate: eiface ordered ether
 232 name separate:ordered tagged
 233 EOF
 234 .Ed
 235 .Pp
 236 Setting the
 237 .Va rot
 238 parameter to zero (or omitting it) does not change
 239 the order of the tags within the frame.
 240 Frames with more VLAN tags are dropped.
 241 .Sh SHUTDOWN
 242 This node shuts down upon receipt of a
 243 .Dv NGM_SHUTDOWN
 244 control message, or when all hooks have been disconnected.
 245 .Sh SEE ALSO
 246 .Xr netgraph 4 ,
 247 .Xr ng_eiface 4 ,
 248 .Xr ng_ether 4 ,
 249 .Xr ng_vlan 4 ,
 250 .Xr ngctl 8
 251 .Sh AUTHORS
 252 .An Lutz Donnerhacke Aq Mt lutz@donnerhacke.de