From 1dc2a785954bf4e562d0c85bea435ee56f705db5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 28 Apr 2020 00:01:51 +0200 Subject: docs: networking: convert ipvlan.txt to ReST - add SPDX header; - adjust titles and chapters, adding proper markups; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/index.rst | 1 + Documentation/networking/ipvlan.rst | 189 ++++++++++++++++++++++++++++++++++++ Documentation/networking/ipvlan.txt | 146 ---------------------------- 3 files changed, 190 insertions(+), 146 deletions(-) create mode 100644 Documentation/networking/ipvlan.rst delete mode 100644 Documentation/networking/ipvlan.txt diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 709675464e51..54dee1575b54 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -71,6 +71,7 @@ Contents: ipsec ip-sysctl ipv6 + ipvlan .. only:: subproject and html diff --git a/Documentation/networking/ipvlan.rst b/Documentation/networking/ipvlan.rst new file mode 100644 index 000000000000..694adcba36b0 --- /dev/null +++ b/Documentation/networking/ipvlan.rst @@ -0,0 +1,189 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================== +IPVLAN Driver HOWTO +=================== + +Initial Release: + Mahesh Bandewar + +1. Introduction: +================ +This is conceptually very similar to the macvlan driver with one major +exception of using L3 for mux-ing /demux-ing among slaves. This property makes +the master device share the L2 with it's slave devices. I have developed this +driver in conjunction with network namespaces and not sure if there is use case +outside of it. + + +2. Building and Installation: +============================= + +In order to build the driver, please select the config item CONFIG_IPVLAN. +The driver can be built into the kernel (CONFIG_IPVLAN=y) or as a module +(CONFIG_IPVLAN=m). + + +3. Configuration: +================= + +There are no module parameters for this driver and it can be configured +using IProute2/ip utility. +:: + + ip link add link name type ipvlan [ mode MODE ] [ FLAGS ] + where + MODE: l3 (default) | l3s | l2 + FLAGS: bridge (default) | private | vepa + +e.g. + + (a) Following will create IPvlan link with eth0 as master in + L3 bridge mode:: + + bash# ip link add link eth0 name ipvl0 type ipvlan + (b) This command will create IPvlan link in L2 bridge mode:: + + bash# ip link add link eth0 name ipvl0 type ipvlan mode l2 bridge + + (c) This command will create an IPvlan device in L2 private mode:: + + bash# ip link add link eth0 name ipvlan type ipvlan mode l2 private + + (d) This command will create an IPvlan device in L2 vepa mode:: + + bash# ip link add link eth0 name ipvlan type ipvlan mode l2 vepa + + +4. Operating modes: +=================== + +IPvlan has two modes of operation - L2 and L3. For a given master device, +you can select one of these two modes and all slaves on that master will +operate in the same (selected) mode. The RX mode is almost identical except +that in L3 mode the slaves wont receive any multicast / broadcast traffic. +L3 mode is more restrictive since routing is controlled from the other (mostly) +default namespace. + +4.1 L2 mode: +------------ + +In this mode TX processing happens on the stack instance attached to the +slave device and packets are switched and queued to the master device to send +out. In this mode the slaves will RX/TX multicast and broadcast (if applicable) +as well. + +4.2 L3 mode: +------------ + +In this mode TX processing up to L3 happens on the stack instance attached +to the slave device and packets are switched to the stack instance of the +master device for the L2 processing and routing from that instance will be +used before packets are queued on the outbound device. In this mode the slaves +will not receive nor can send multicast / broadcast traffic. + +4.3 L3S mode: +------------- + +This is very similar to the L3 mode except that iptables (conn-tracking) +works in this mode and hence it is L3-symmetric (L3s). This will have slightly less +performance but that shouldn't matter since you are choosing this mode over plain-L3 +mode to make conn-tracking work. + +5. Mode flags: +============== + +At this time following mode flags are available + +5.1 bridge: +----------- +This is the default option. To configure the IPvlan port in this mode, +user can choose to either add this option on the command-line or don't specify +anything. This is the traditional mode where slaves can cross-talk among +themselves apart from talking through the master device. + +5.2 private: +------------ +If this option is added to the command-line, the port is set in private +mode. i.e. port won't allow cross communication between slaves. + +5.3 vepa: +--------- +If this is added to the command-line, the port is set in VEPA mode. +i.e. port will offload switching functionality to the external entity as +described in 802.1Qbg +Note: VEPA mode in IPvlan has limitations. IPvlan uses the mac-address of the +master-device, so the packets which are emitted in this mode for the adjacent +neighbor will have source and destination mac same. This will make the switch / +router send the redirect message. + +6. What to choose (macvlan vs. ipvlan)? +======================================= + +These two devices are very similar in many regards and the specific use +case could very well define which device to choose. if one of the following +situations defines your use case then you can choose to use ipvlan: + + +(a) The Linux host that is connected to the external switch / router has + policy configured that allows only one mac per port. +(b) No of virtual devices created on a master exceed the mac capacity and + puts the NIC in promiscuous mode and degraded performance is a concern. +(c) If the slave device is to be put into the hostile / untrusted network + namespace where L2 on the slave could be changed / misused. + + +6. Example configuration: +========================= + +:: + + +=============================================================+ + | Host: host1 | + | | + | +----------------------+ +----------------------+ | + | | NS:ns0 | | NS:ns1 | | + | | | | | | + | | | | | | + | | ipvl0 | | ipvl1 | | + | +----------#-----------+ +-----------#----------+ | + | # # | + | ################################ | + | # eth0 | + +==============================#==============================+ + + +(a) Create two network namespaces - ns0, ns1:: + + ip netns add ns0 + ip netns add ns1 + +(b) Create two ipvlan slaves on eth0 (master device):: + + ip link add link eth0 ipvl0 type ipvlan mode l2 + ip link add link eth0 ipvl1 type ipvlan mode l2 + +(c) Assign slaves to the respective network namespaces:: + + ip link set dev ipvl0 netns ns0 + ip link set dev ipvl1 netns ns1 + +(d) Now switch to the namespace (ns0 or ns1) to configure the slave devices + + - For ns0:: + + (1) ip netns exec ns0 bash + (2) ip link set dev ipvl0 up + (3) ip link set dev lo up + (4) ip -4 addr add 127.0.0.1 dev lo + (5) ip -4 addr add $IPADDR dev ipvl0 + (6) ip -4 route add default via $ROUTER dev ipvl0 + + - For ns1:: + + (1) ip netns exec ns1 bash + (2) ip link set dev ipvl1 up + (3) ip link set dev lo up + (4) ip -4 addr add 127.0.0.1 dev lo + (5) ip -4 addr add $IPADDR dev ipvl1 + (6) ip -4 route add default via $ROUTER dev ipvl1 diff --git a/Documentation/networking/ipvlan.txt b/Documentation/networking/ipvlan.txt deleted file mode 100644 index 27a38e50c287..000000000000 --- a/Documentation/networking/ipvlan.txt +++ /dev/null @@ -1,146 +0,0 @@ - - IPVLAN Driver HOWTO - -Initial Release: - Mahesh Bandewar - -1. Introduction: - This is conceptually very similar to the macvlan driver with one major -exception of using L3 for mux-ing /demux-ing among slaves. This property makes -the master device share the L2 with it's slave devices. I have developed this -driver in conjunction with network namespaces and not sure if there is use case -outside of it. - - -2. Building and Installation: - In order to build the driver, please select the config item CONFIG_IPVLAN. -The driver can be built into the kernel (CONFIG_IPVLAN=y) or as a module -(CONFIG_IPVLAN=m). - - -3. Configuration: - There are no module parameters for this driver and it can be configured -using IProute2/ip utility. - - ip link add link name type ipvlan [ mode MODE ] [ FLAGS ] - where - MODE: l3 (default) | l3s | l2 - FLAGS: bridge (default) | private | vepa - - e.g. - (a) Following will create IPvlan link with eth0 as master in - L3 bridge mode - bash# ip link add link eth0 name ipvl0 type ipvlan - (b) This command will create IPvlan link in L2 bridge mode. - bash# ip link add link eth0 name ipvl0 type ipvlan mode l2 bridge - (c) This command will create an IPvlan device in L2 private mode. - bash# ip link add link eth0 name ipvlan type ipvlan mode l2 private - (d) This command will create an IPvlan device in L2 vepa mode. - bash# ip link add link eth0 name ipvlan type ipvlan mode l2 vepa - - -4. Operating modes: - IPvlan has two modes of operation - L2 and L3. For a given master device, -you can select one of these two modes and all slaves on that master will -operate in the same (selected) mode. The RX mode is almost identical except -that in L3 mode the slaves wont receive any multicast / broadcast traffic. -L3 mode is more restrictive since routing is controlled from the other (mostly) -default namespace. - -4.1 L2 mode: - In this mode TX processing happens on the stack instance attached to the -slave device and packets are switched and queued to the master device to send -out. In this mode the slaves will RX/TX multicast and broadcast (if applicable) -as well. - -4.2 L3 mode: - In this mode TX processing up to L3 happens on the stack instance attached -to the slave device and packets are switched to the stack instance of the -master device for the L2 processing and routing from that instance will be -used before packets are queued on the outbound device. In this mode the slaves -will not receive nor can send multicast / broadcast traffic. - -4.3 L3S mode: - This is very similar to the L3 mode except that iptables (conn-tracking) -works in this mode and hence it is L3-symmetric (L3s). This will have slightly less -performance but that shouldn't matter since you are choosing this mode over plain-L3 -mode to make conn-tracking work. - -5. Mode flags: - At this time following mode flags are available - -5.1 bridge: - This is the default option. To configure the IPvlan port in this mode, -user can choose to either add this option on the command-line or don't specify -anything. This is the traditional mode where slaves can cross-talk among -themselves apart from talking through the master device. - -5.2 private: - If this option is added to the command-line, the port is set in private -mode. i.e. port won't allow cross communication between slaves. - -5.3 vepa: - If this is added to the command-line, the port is set in VEPA mode. -i.e. port will offload switching functionality to the external entity as -described in 802.1Qbg -Note: VEPA mode in IPvlan has limitations. IPvlan uses the mac-address of the -master-device, so the packets which are emitted in this mode for the adjacent -neighbor will have source and destination mac same. This will make the switch / -router send the redirect message. - -6. What to choose (macvlan vs. ipvlan)? - These two devices are very similar in many regards and the specific use -case could very well define which device to choose. if one of the following -situations defines your use case then you can choose to use ipvlan - - (a) The Linux host that is connected to the external switch / router has -policy configured that allows only one mac per port. - (b) No of virtual devices created on a master exceed the mac capacity and -puts the NIC in promiscuous mode and degraded performance is a concern. - (c) If the slave device is to be put into the hostile / untrusted network -namespace where L2 on the slave could be changed / misused. - - -6. Example configuration: - - +=============================================================+ - | Host: host1 | - | | - | +----------------------+ +----------------------+ | - | | NS:ns0 | | NS:ns1 | | - | | | | | | - | | | | | | - | | ipvl0 | | ipvl1 | | - | +----------#-----------+ +-----------#----------+ | - | # # | - | ################################ | - | # eth0 | - +==============================#==============================+ - - - (a) Create two network namespaces - ns0, ns1 - ip netns add ns0 - ip netns add ns1 - - (b) Create two ipvlan slaves on eth0 (master device) - ip link add link eth0 ipvl0 type ipvlan mode l2 - ip link add link eth0 ipvl1 type ipvlan mode l2 - - (c) Assign slaves to the respective network namespaces - ip link set dev ipvl0 netns ns0 - ip link set dev ipvl1 netns ns1 - - (d) Now switch to the namespace (ns0 or ns1) to configure the slave devices - - For ns0 - (1) ip netns exec ns0 bash - (2) ip link set dev ipvl0 up - (3) ip link set dev lo up - (4) ip -4 addr add 127.0.0.1 dev lo - (5) ip -4 addr add $IPADDR dev ipvl0 - (6) ip -4 route add default via $ROUTER dev ipvl0 - - For ns1 - (1) ip netns exec ns1 bash - (2) ip link set dev ipvl1 up - (3) ip link set dev lo up - (4) ip -4 addr add 127.0.0.1 dev lo - (5) ip -4 addr add $IPADDR dev ipvl1 - (6) ip -4 route add default via $ROUTER dev ipvl1 -- cgit