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 42The 43.Nm 44node type manipulates the order of VLAN tags of frames tagged 45according to the IEEE 802.1ad (an extension of IEEE 802.1Q) standard 46between different hooks. 47.Pp 48Each node has four special hooks, 49.Va original , 50.Va ordered , 51.Va excessive , 52and 53.Va incomplete . 54.Pp 55A frame tagged with an arbitrary number of 56.Dv ETHERTYPE_VLAN , 57.Dv ETHERTYPE_QINQ , 58and 59.Dv 0x9100 60tags received on the 61.Va original 62hook will be rearranged to a new order of those tags and is sent out 63the 64.Dq ordered 65hook. 66After successful processing the 67.Va histogram 68counter for the observed stack size increments. 69.Pp 70If it contains fewer VLANs in the stack than the configured 71.Va min 72limit, the frame is sent out to the 73.Va incomplete 74hook and the 75.Va incomplete 76counter increments. 77.Pp 78If there are more VLANs in the stack than the configured 79.Va max 80limit, the frame is sent out to the 81.Va excessive 82hook and the 83.Va excessive 84counter increments. 85.Pp 86If the destination hook is not connected, the frame is dropped and the 87.Va drops 88counter increments. 89.Pp 90For Ethernet frames received on the 91.Va ordered 92hook, the transformation is reversed and is passed to the 93.Va original 94hook. 95Please note that this process is identical to the one described 96above, besides the ordered/original hooks are swapped and the 97transformation is reversed. 98.Pp 99An Ethernet frame received on the 100.Va incomplete 101or 102.Va excessive 103hook is forwarded to the 104.Va original 105hook without any modification. 106.Pp 107This node supports only one operation at the moment: Rotation of the 108VLANs in the stack. 109Setting the configuration parameter 110.Va rot 111to a positive value, the stack will roll up by this amount. 112Negative values will roll down. 113A typical scenario is setting the value to 1 in order to bring the 114innermost VLAN tag to the outmost level. 115Rotation includes the VLAN id, the ether type, and the QOS parameters 116pcp and cfi. 117Typical QOS handling refers to the outmost setting, so be careful to 118keep your QOS intact. 119.Sh HOOKS 120This node type supports the following hooks: 121.Bl -tag -width incomplete 122.It Va original 123Typically this hook would be connected to a 124.Xr ng_ether 4 125node, using the 126.Va lower 127hook connected to a carrier network. 128.It Va ordered 129Typically this hook would be connected to a 130.Xr ng_vlan 4 131type node using the 132.Va downstream 133hook in order to separate services. 134.It Va excessive 135see below. 136.It Va incomplete 137Typically those hooks would be attached to a 138.Xr ng_eiface 4 139type node using the 140.Va ether 141hook for anomaly monitoring purposes. 142.El 143.Sh CONTROL MESSAGES 144This 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 147Read the current configuration. 148.It Dv NGM_VLANROTATE_SET_CONF Pq Ic setconf 149Set the current configuration. 150.It Dv NGM_VLANROTATE_GET_STAT Pq Ic getstat 151Read the current statistics. 152.It Dv NGM_VLANROTATE_CLR_STAT Pq Ic clrstat 153Zeroize the statistics. 154.It Dv NGM_VLANROTATE_GETCLR_STAT Pq Ic getclrstat 155Read the current statistics and zeroize it in one step. 156.El 157.Sh EXAMPLES 158The first example demonstrates how to rotate double or triple tagged 159frames so that the innermost C-VLAN can be used as service 160discriminator. 161The single or double tagged frames (C-VLAN removed) are sent out to an 162interface pointing to different infrastucture. 163.Bd -literal 164#!/bin/sh 165 166BNG_IF=ixl3 167VOIP_IF=bge2 168 169ngctl -f- <<EOF 170mkpeer ${BNG_IF}: vlan_rotate lower original 171name ${BNG_IF}:lower rotate 172msg rotate: setconf { min=2 max=3 rot=1 } 173mkpeer rotate: vlan ordered downstream 174name rotate:ordered services 175connect services: ${VOIP_IF} voip lower 176msg services: addfilter { vlan=123 hook="voip" } 177EOF 178.Ed 179.Pp 180Now inject the following sample frame on the 181.Dv BNG_IF 182interface: 183.Bd -literal 18400: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 193The frame ejected on the 194.Va ordered 195hook will look like this: 196.Bd -literal 19700: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 206Hence, the frame pushed out to the 207.Dv VOIP_IF 208will have this form: 209.Bd -literal 21000: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 218The second example distinguishes between double tagged and single 219tagged frames. 220.Bd -literal 221#!/bin/sh 222 223IN_IF=bge1 224 225ngctl -f- <<EOF 226mkpeer ${IN_IF}: vlan_rotate lower original 227name ${IN_IF}:lower separate 228msg separate: setconf { min=1 max=1 rot=0 } 229mkpeer separate: eiface incomplete ether 230name separate:incomplete untagged 231mkpeer separate: eiface ordered ether 232name separate:ordered tagged 233EOF 234.Ed 235.Pp 236Setting the 237.Va rot 238parameter to zero (or omitting it) does not change 239the order of the tags within the frame. 240Frames with more VLAN tags are dropped. 241.Sh SHUTDOWN 242This node shuts down upon receipt of a 243.Dv NGM_SHUTDOWN 244control 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 253