Attachment 207732 Details for Bug 240685 – Updated patch for share/man/man4/ng_vlan_rotate.4

[patch] Updated patch for share/man/man4/ng_vlan_rotate.4

file_240685.txt (text/plain), 7.99 KB, created by Lutz Donnerhacke on 2019-09-23 09:34:08 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Lutz Donnerhacke

Created: 2019-09-23 09:34:08 UTC

Size: 7.99 KB

patch

obsolete

>--- share/man/man4/ng_vlan_rotate.4     (nonexistent)
>+++ share/man/man4/ng_vlan_rotate.4     (working copy)
>@@ -0,0 +1,253 @@
>+.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
>+.\"
>+.\" Copyright (c) 2019 IKS Service GmbH
>+.\" All rights reserved.
>+.\"
>+.\" Redistribution and use in source and binary forms, with or without
>+.\" modification, are permitted provided that the following conditions
>+.\" are met:
>+.\" 1. Redistributions of source code must retain the above copyright
>+.\"    notice, this list of conditions and the following disclaimer.
>+.\" 2. Redistributions in binary form must reproduce the above copyright
>+.\"    notice, this list of conditions and the following disclaimer in the
>+.\"    documentation and/or other materials provided with the distribution.
>+.\"
>+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
>+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
>+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
>+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
>+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
>+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
>+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
>+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
>+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
>+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
>+.\" SUCH DAMAGE.
>+.\"
>+.\" Author: Lutz Donnerhacke <lutz@donnerhacke.de>
>+.\"
>+.\" $FreeBSD$
>+.\"
>+.Dd September 19, 2019
>+.Dt NG_VLAN_ROTATE 4
>+.Os
>+.Sh NAME
>+.Nm ng_vlan_rotate
>+.Nd IEEE 802.1ad VLAN manipulation netgraph node type
>+.Sh SYNOPSIS
>+.In sys/types.h
>+.In netgraph.h
>+.In netgraph/ng_vlan_rotate.h
>+.Sh DESCRIPTION
>+The
>+.Nm 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.
>+.Pp
>+Each node has four special hooks,
>+.Va original ,
>+.Va ordered ,
>+.Va excessive ,
>+and
>+.Va incomplete .
>+.Pp
>+A frame tagged with an arbitrary number of
>+.Dv ETHERTYPE_VLAN ,
>+.Dv ETHERTYPE_QINQ ,
>+and
>+.Dv 0x9100
>+tags received on the
>+.Va original
>+hook will be rearranged to a new order of those tags and
>+is sent out the
>+.Dq ordered
>+hook.
>+After successful processing the
>+.Va histogram
>+counter for the observed stack size increments.
>+.Pp
>+If it contains fewer VLANs in the stack, than the configured
>+.Va min
>+limit, the frame is sent out to the
>+.Va incomplete
>+hook and the
>+.Va incomplete
>+counter increments.
>+.Pp
>+If it contains more VLANs in the stack, than the configured
>+.Va max
>+limit, the frame is sent out to the
>+.Va excessive
>+hook and the
>+.Va excessive
>+counter increments.
>+.Pp
>+If the destination hook is not connected, the frame is dropped and the
>+.Va drops
>+counter increments.
>+.Pp
>+For Ethernet frames received on the
>+.Va ordered
>+hook, the transformation is reversed and is passed to the
>+.Va original
>+hook. Please note, that this process is identical to the one described
>+above, besides the ordered/original hooks are swapped and the
>+transformation is reversed.
>+.Pp
>+An Ethernet frame received on
>+.Va incomplete
>+or
>+.Va excessive
>+hook is forwarded to the
>+.Va original
>+hook without any modification.
>+.Pp
>+This node supports only one operation at the moment: Rotation of the
>+VLANs in the stack. Setting the configuration parameter
>+.Va 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 ether type, but the QOS
>+parameters pcp and cfi stay in place. Typical QOS handling refers to
>+the outmost setting, so this scheme keeps QOS intact.
>+.Sh HOOKS
>+This node type supports the following hooks:
>+.Bl -tag -width incomplete
>+.It Va original
>+Typically this hook would be connected to a
>+.Xr ng_ether 4
>+node, using the
>+.Va lower
>+hook connected to a carrier network.
>+.It Va ordered
>+Typically this hook would be connected to a
>+.Xr ng_vlan 4
>+type node using the
>+.Va downstream
>+hook in order to separate services.
>+.It Va excessive
>+see below.
>+.It Va incomplete
>+Typically those hooks would be attached to a
>+.Xr ng_eiface 4
>+type node using the
>+.Va ether
>+hook for anomaly monitoring purposes.
>+.El
>+.Sh CONTROL MESSAGES
>+This node type supports the generic control messages, plus the following:
>+.Bl -tag -width foo
>+.It Dv NGM_VLANROTATE_GET_CONF Pq Ic getconf
>+Read the current configuration.
>+.It Dv NGM_VLANROTATE_SET_CONF Pq Ic setconf
>+Set the current configuration.
>+.It Dv NGM_VLANROTATE_GET_STAT Pq Ic getstat
>+Read the current statistics.
>+.It Dv NGM_VLANROTATE_CLR_STAT Pq Ic clrstat
>+Zeroize the statistics.
>+.It Dv NGM_VLANROTATE_GETCLR_STAT Pq Ic getclrstat
>+Read the current statistics and zeroize it in one step.
>+.El
>+.Sh 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 sent out to an interface pointing to different
>+infrastucture.
>+.Bd -literal
>+#!/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
>+.Ed
>+
>+Let's inject the following sample frame on the
>+.Dv BNG_IF
>+interface:
>+.Bd -literal
>+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
>+.Ed
>+
>+The frame ejected on the
>+.Va ordered
>+hook will look like this:
>+.Bd -literal
>+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
>+.Ed
>+
>+Hence, the frame pushed out to the
>+.Dv VOIP_IF
>+will have this form:
>+.Bd -literal
>+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
>+.Ed
>+
>+.Pp
>+The second example distinguish between double tagged and single tagged
>+frames. Frames with more VLAN tags are dropped.
>+.Bd -literal
>+#!/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
>+.Ed
>+
>+Setting the
>+.Va rot
>+parameter to zero (or omitting it) does not change
>+the order of the tags within the frame.
>+
>+.Sh SHUTDOWN
>+This node shuts down upon receipt of a
>+.Dv NGM_SHUTDOWN
>+control message, or when all hooks have been disconnected.
>+.Sh SEE ALSO
>+.Xr netgraph 4 ,
>+.Xr ng_eiface 4 ,
>+.Xr ng_ether 4 ,
>+.Xr ng_vlan 4 ,
>+.Xr ngctl 8
>+.Sh HISTORY
>+The
>+.Nm
>+node type appeared in
>+.Fx 12.1-PRERELEASE .
>+.Sh AUTHORS
>+.An Lutz Donnerhacke Aq Mt lutz@donnerhacke.de

Actions: View | Diff

Attachments on bug 240685: 207625 | 207732