[Openvpn-devel,v3,8/9] VLAN: add documentation to manpage

Message ID 20191109095836.11190-1-a@unstable.cc
State Accepted
Headers show
Series None | expand

Commit Message

Antonio Quartulli Nov. 8, 2019, 10:58 p.m. UTC
This patch adds documentation for all the VLAN related knobs.

Signed-off-by: Fabian Knittel <fabian.knittel@lettink.de>
Signed-off-by: Antonio Quartulli <a@unstable.cc>
---

Changes from v1:
- slight rewording of some sentences, as suggested by Arne

Changes from v2:
- slight rewording of some sentences, as suggested by Gert

 doc/openvpn.8 | 100 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 99 insertions(+), 1 deletion(-)

Comments

Gert Doering Nov. 9, 2019, 12:24 a.m. UTC | #1
Acked-by: Gert Doering <gert@greenie.muc.de>

Documentation is good :-) and it matches observed behaviour, so that's
even better.  Can the wording be improved?  Surely, always, but this
is a continuous process by letting "untainted" people read the docs
and come up with questions that we find obvious...

Your patch has been applied to the master branch.

commit 0328003b0e987de0b7b91c3e53c84604188d9421
Author: Antonio Quartulli
Date:   Sat Nov 9 10:58:36 2019 +0100

     VLAN: add documentation to manpage

     Signed-off-by: Fabian Knittel <fabian.knittel@lettink.de>
     Signed-off-by: Antonio Quartulli <a@unstable.cc>
     Acked-by: Gert Doering <gert@greenie.muc.de>
     Message-Id: <20191109095836.11190-1-a@unstable.cc>
     URL: https://www.mail-archive.com/search?l=mid&q=20191109095836.11190-1-a@unstable.cc
     Signed-off-by: Gert Doering <gert@greenie.muc.de>


--
kind regards,

Gert Doering

Patch

diff --git a/doc/openvpn.8 b/doc/openvpn.8
index 11daa92a..f58a3ccc 100644
--- a/doc/openvpn.8
+++ b/doc/openvpn.8
@@ -3440,7 +3440,8 @@  without needing to restart the server.
 
 The following
 options are legal in a client\-specific context:
-.B \-\-push, \-\-push\-reset, \-\-push\-remove, \-\-iroute, \-\-ifconfig\-push,
+.B \-\-push, \-\-push\-reset, \-\-push\-remove, \-\-iroute,
+.B \-\-ifconfig\-push, \-\-vlan\-pvid
 and
 .B \-\-config.
 .\"*********************************************************
@@ -3908,6 +3909,103 @@  connection is torn down.
 
 Not implemented on Windows.
 .\"*********************************************************
+.TP
+.B \-\-vlan\-tagging
+Server-only option. Turns the OpenVPN server instance into a switch that
+understands VLAN\-tagging, based on IEEE 802.1Q.
+
+The server TAP device and each of the connecting clients is seen as a port of the
+switch. All client ports are in untagged mode and the server TAP device is
+VLAN-tagged, untagged or accepts both, depending on the
+.B \-\-vlan\-accept setting.
+
+Ethernet frames with a prepended 802.1Q tag are called "tagged". If the VLAN
+Identifier (VID) field in such a tag is non-zero, the frame is called
+"VLAN\-tagged". If the VID is zero, but the Priority Control Point (PCP) field
+is non\-zero, the frame is called "prio\-tagged". If there is no 802.1Q tag, the
+frame is "untagged".
+
+Using the
+.B \-\-vlan\-pvid v
+option once per client (see \-\-client\-config\-dir), each port can be associated
+with a certain VID. Packets
+can only be forwarded between ports having the same VID. Therefore, clients
+with differing VIDs are completely separated from one\-another, even if
+.B \-\-client\-to\-client
+is activated.
+
+The packet filtering takes place in the OpenVPN server. Clients should not
+have any VLAN tagging configuration applied.
+
+The
+.B \-\-vlan\-tagging
+option is off by default. While turned off, OpenVPN
+accepts any Ethernet frame and does not perform any special processing
+for VLAN\-tagged packets.
+
+The option can only be activated in
+.B \-\-dev tap mode.
+
+.\"*********************************************************
+.TP
+.B \-\-vlan\-accept all | tagged | untagged
+Configure the VLAN tagging policy for the server TAP device. The following modes
+are available:
+
+.B tagged
+\-\- Admit only VLAN\-tagged frames.
+Only VLAN\-tagged packets are accepted, while untagged or priority\-tagged
+packets are dropped when entering the server TAP device.
+
+.br
+.B untagged
+\-\- Admit only untagged and prio\-tagged frames.
+.br
+VLAN\-tagged packets are not accepted, while untagged or priority\-tagged
+packets entering the server TAP device are tagged with the value configured
+for the global
+.B \-\-vlan\-pvid
+setting.
+.br
+.B all
+(default) \-\- Admit all frames.
+.br
+All packets are admitted and then treated like untagged or tagged mode
+respectively.
+
+(Note: Some vendors refer to switch ports running in
+.B tagged
+mode as "trunk ports" and switch ports running in
+.B untagged
+mode as "access ports".)
+
+Packets forwarded from clients to the server are VLAN\-tagged
+with the originating client's PVID, unless the VID matches the
+global \-\-vlan\-pvid, in which case the tag is removed.
+
+If no PVID is configured for a given client (see \-\-vlan\-pvid) packets
+are tagged with 1 by default.
+.\"*********************************************************
+.TP
+.B \-\-vlan\-pvid v
+Specifies which VLAN identifier a "port" is associated with. Only valid when
+\fB\-\-vlan\-tagging\fR is speficied.
+
+In the client context, the setting specifies which VLAN ID a client is
+associated with. In the global context, the VLAN ID of the server TAP device is set.
+The latter only makes sense for
+.B \-\-vlan\-accept untagged
+and
+.B \-\-vlan\-accept all
+modes.
+
+Valid values for
+.B v
+go from 1 through to 4094. The global value defaults to 1. If no \-\-vlan\-pvid
+is specified in the client context, the global value is inherited.
+
+In some switch implementations, the PVID is also referred to as "Native VLAN".
+.\"*********************************************************
 .SS Client Mode
 Use client mode when connecting to an OpenVPN server
 which has