Bug 240685 - netgraph/ng_vlan_rotate: IEEE 802.1ad VLAN manipulation netgraph node type (new type)
Summary: netgraph/ng_vlan_rotate: IEEE 802.1ad VLAN manipulation netgraph node type (n...
Status: New
Alias: None
Product: Base System
Classification: Unclassified
Component: kern (show other bugs)
Version: 12.0-STABLE
Hardware: Any Any
: --- Affects Only Me
Assignee: freebsd-net mailing list
URL:
Keywords: patch
Depends on:
Blocks:
 
Reported: 2019-09-19 13:00 UTC by lutz
Modified: 2019-10-18 13:52 UTC (History)
2 users (show)

See Also:


Attachments
Patch for netgraph/ng_vlan_rotate module (29.01 KB, patch)
2019-09-19 13:00 UTC, lutz
no flags Details | Diff
Updated patch for share/man/man4/ng_vlan_rotate.4 (7.99 KB, patch)
2019-09-23 09:34 UTC, lutz
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description lutz 2019-09-19 13:00:25 UTC
Created attachment 207625 [details]
Patch for netgraph/ng_vlan_rotate module

I need to deal with carrier ethernet solutions which stack a couple of VLANs in transport. In order to deal with the packets, the VLAN stack needs to be manipulated.

This new netgragh node will handle such issues.
Comment 1 lutz 2019-09-19 13:02:29 UTC
For the sake of reasoning I'll provide the formatted man page as a comment:

NG_VLAN_ROTATE(4)      FreeBSD Kernel Interfaces Manual      NG_VLAN_ROTATE(4)

NAME
     ng_vlan_rotate - IEEE 802.1ad VLAN manipulation netgraph node type

SYNOPSIS
     #include <sys/types.h>
     #include <netgraph.h>
     #include <netgraph/ng_vlan_rotate.h>

DESCRIPTION
     The vlan_rotate node type manipulates the order of VLAN tags of frames
     tagged according to the IEEE 802.1ad (an extension of IEEE 802.1Q)
     standard between different hooks.

     Each node has four special hooks, original, ordered, excessive, and
     incomplete.

     A frame tagged with an arbitrary number of ETHERTYPE_VLAN,
     ETHERTYPE_QINQ, and 0x9100 tags received on the original hook will be
     rearranged to a new order of those tags and is sent out the "ordered"
     hook.  After successful processing the histogram counter for the observed
     stack size increments.

     If it contains fewer VLANs in the stack, than the configured min limit,
     the frame is send out to the incomplete hook and the incomplete counter
     increments.

     If it contains more VLANs in the stack, than the configured max limit,
     the frame is send out to the excessive hook and the excessive counter
     increments.

     If any destination hook is not connected, the frame is dropped and the
     drops counter increments.

     For Ethernet frames received on the ordered hook, the transformation is
     reversed and is passed to the original hook. Please note, that this
     process is identical to the one described above, besides the
     ordered/original hooks and the transformation are swapped.

     An Ethernet frame received on incomplede or excessive hook is forwarded
     to the original hook without any modification.

     This node supports only one operation at the moment: Rotation of the
     VLANs in the stack. Setting the configuration parameter rot to a positive
     value, the stack will roll up by this amount. Negative values will roll
     down. A typical scenario is setting the value to 1 in order to bring the
     innermost VLAN tag to the outmost level.  Rotation includes the VLAN id
     and the ethertype, but the QOS paramenters pcp and cfi stay in place.
     Typical QOS handling refers to the outmost setting, so this scheme keeps
     QOS intact.

HOOKS
     This node type supports the following hooks:

     original    Typically this hook would be connected to a ng_ether(4) node,
                 using the lower hook connected to a carrier network.

     ordered     Typically this hook would be connected to a ng_vlan(4) type
                 node using the downstream hook in order to seperate services.

     excessive   see below.

     incomplete  Typically those hooks would be attached to an ng_eiface(4)
                 type node using the ether hook for anomaly monitoring
                 purposes.

CONTROL MESSAGES
     This node type supports the generic control messages, plus the following:

     NGM_VLANROTATE_GET_CONF (getconf)
          Read the current configuration.

     NGM_VLANROTATE_SET_CONF (setconf)
          Set the current configuration.

     NGM_VLANROTATE_GET_STAT (getstat)
          Read the current statistics.

     NGM_VLANROTATE_CLR_STAT (clrstat)
          Zeroize the statistics.

     NGM_VLANROTATE_GETCLR_STAT (getclrstat)
          Read the current statistics and zeroize it in one step.

EXAMPLES
     The first example demonstrates how to rotate double or triple tagged
     frames so, that the innermost C-VLAN can be used as service
     discriminator. The single or double tagged frames (C-VLAN removed) are
     send out the an interface pointing to different infrastucture.

     #!/bin/sh

     BNG_IF=ixl3
     VOIP_IF=bge2

     ngctl -f- <<EOF
     mkpeer ${BNG_IF}: vlan_rotate lower original
     name ${BNG_IF}:lower rotate
     msg rotate: setconf { min=2 max=3 rot=1 }
     mkpeer rotate: vlan ordered downstream
     name rotate:ordered services
     connect services: ${VOIP_IF} voip lower
     msg services: addfilter { vlan=123 hook="voip" }
     EOF

     Let's inject the following sample frame on the BNG_IF interface:

     00:00:00:00:01:01 > 00:01:02:03:04:05,
      ethertype 802.1Q-9100 (0x9100), length 110: vlan 2, p 1,
      ethertype 802.1Q-QinQ, vlan 101, p 0,
      ethertype 802.1Q, vlan 123, p 7,
      ethertype IPv4, (tos 0x0, ttl 64, id 15994, offset 0, flags [none],
       proto ICMP (1), length 84) 192.168.140.101 > 192.168.140.1:
       ICMP echo request, id 40234, seq 0, length 64

     The frame ejected on the ordered hook will look like this:

     00:00:00:00:01:01 > 00:01:02:03:04:05,
      ethertype 802.1Q (0x8100), length 110: vlan 123, p 1,
      ethertype 802.1Q-9100, vlan 2, p 0,
      ethertype 802.1Q-QinQ, vlan 101, p 7,
      ethertype IPv4, (tos 0x0, ttl 64, id 15994, offset 0, flags [none],
       proto ICMP (1), length 84) 192.168.140.101 > 192.168.140.1:
       ICMP echo request, id 40234, seq 0, length 64

     Hence the frame pushed out to the VOIP_IF will have this form:

     00:00:00:00:01:01 > 00:01:02:03:04:05,
      ethertype 802.1Q-9100, vlan 2, p 0,
      ethertype 802.1Q-QinQ, vlan 101, p 7,
      ethertype IPv4, (tos 0x0, ttl 64, id 15994, offset 0, flags [none],
       proto ICMP (1), length 84) 192.168.140.101 > 192.168.140.1:
       ICMP echo request, id 40234, seq 0, length 64


     The second example distinguish between double tagged and single tagged
     frames. Frames with more VLAN tags are dropped.

     #!/bin/sh

     IN_IF=bge1

     ngctl -f- <<EOF
     mkpeer ${IN_IF}: vlan_rotate lower original
     name ${IN_IF}:lower separate
     msg separate: setconf { min=1 max=1 rot=0 }
     mkpeer separate: eiface incomplete ether
     name separate:incomplete untagged
     mkpeer separate: eiface ordered ether
     name separate:ordered tagged
     EOF

     Setting the rot parameter to zero (or omitting it) does not change the
     order of the tags within the frame.


SHUTDOWN
     This node shuts down upon receipt of a NGM_SHUTDOWN control message, or
     when all hooks have been disconnected.

SEE ALSO
     netgraph(4), ng_eiface(4), ng_ether(4), ng_vlan(4), ngctl(8)

HISTORY
     The ng_vlan_rotate node type appeared in FreeBSD 12.1-PRERELEASE.

AUTHORS
     Lutz Donnerhacke <lutz@donnerhacke.de>
Comment 2 Eugene Grosbein freebsd_committer 2019-09-22 08:31:45 UTC
Can you provide some practical use case for the node?

And pass manual page through spell checker, please.
Comment 3 lutz 2019-09-23 08:56:45 UTC
This node is part of an A10-NSP development. See https://www.bundesnetzagentur.de/SharedDocs/Downloads/DE/Sachgebiete/Telekommunikation/Unternehmen_Institutionen/Breitband/NGA_NGN/NGA-Forum/aktuelledokumente/L2_BSA_II_TechSpezifikation_V10.pdf?__blob=publicationFile&v=2

Carrier networks tend to stack three or more tags for internal purposes and therefore hiding the service tags deep inside of the stack. When decomposing such an access network frame, the processing order is typically reversed: First distinguish by service, than by other means.
Comment 4 lutz 2019-09-23 09:34:08 UTC
Created attachment 207732 [details]
Updated patch for share/man/man4/ng_vlan_rotate.4

I'm sorry for my errors in the man page.
This is an updated version.
Comment 5 lutz 2019-10-18 13:51:56 UTC
Comment on attachment 207625 [details]
Patch for netgraph/ng_vlan_rotate module

Overcome by https://reviews.freebsd.org/D22076
Comment 6 lutz 2019-10-18 13:52:21 UTC
Comment on attachment 207732 [details]
Updated patch for share/man/man4/ng_vlan_rotate.4

Overcome by https://reviews.freebsd.org/D22076