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