0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===================
0004 IPVLAN Driver HOWTO
0005 ===================
0006
0007 Initial Release:
0008 Mahesh Bandewar <maheshb AT google.com>
0009
0010 1. Introduction:
0011 ================
0012 This is conceptually very similar to the macvlan driver with one major
0013 exception of using L3 for mux-ing /demux-ing among slaves. This property makes
0014 the master device share the L2 with its slave devices. I have developed this
0015 driver in conjunction with network namespaces and not sure if there is use case
0016 outside of it.
0017
0018
0019 2. Building and Installation:
0020 =============================
0021
0022 In order to build the driver, please select the config item CONFIG_IPVLAN.
0023 The driver can be built into the kernel (CONFIG_IPVLAN=y) or as a module
0024 (CONFIG_IPVLAN=m).
0025
0026
0027 3. Configuration:
0028 =================
0029
0030 There are no module parameters for this driver and it can be configured
0031 using IProute2/ip utility.
0032 ::
0033
0034 ip link add link <master> name <slave> type ipvlan [ mode MODE ] [ FLAGS ]
0035 where
0036 MODE: l3 (default) | l3s | l2
0037 FLAGS: bridge (default) | private | vepa
0038
0039 e.g.
0040
0041 (a) Following will create IPvlan link with eth0 as master in
0042 L3 bridge mode::
0043
0044 bash# ip link add link eth0 name ipvl0 type ipvlan
0045 (b) This command will create IPvlan link in L2 bridge mode::
0046
0047 bash# ip link add link eth0 name ipvl0 type ipvlan mode l2 bridge
0048
0049 (c) This command will create an IPvlan device in L2 private mode::
0050
0051 bash# ip link add link eth0 name ipvlan type ipvlan mode l2 private
0052
0053 (d) This command will create an IPvlan device in L2 vepa mode::
0054
0055 bash# ip link add link eth0 name ipvlan type ipvlan mode l2 vepa
0056
0057
0058 4. Operating modes:
0059 ===================
0060
0061 IPvlan has two modes of operation - L2 and L3. For a given master device,
0062 you can select one of these two modes and all slaves on that master will
0063 operate in the same (selected) mode. The RX mode is almost identical except
0064 that in L3 mode the slaves wont receive any multicast / broadcast traffic.
0065 L3 mode is more restrictive since routing is controlled from the other (mostly)
0066 default namespace.
0067
0068 4.1 L2 mode:
0069 ------------
0070
0071 In this mode TX processing happens on the stack instance attached to the
0072 slave device and packets are switched and queued to the master device to send
0073 out. In this mode the slaves will RX/TX multicast and broadcast (if applicable)
0074 as well.
0075
0076 4.2 L3 mode:
0077 ------------
0078
0079 In this mode TX processing up to L3 happens on the stack instance attached
0080 to the slave device and packets are switched to the stack instance of the
0081 master device for the L2 processing and routing from that instance will be
0082 used before packets are queued on the outbound device. In this mode the slaves
0083 will not receive nor can send multicast / broadcast traffic.
0084
0085 4.3 L3S mode:
0086 -------------
0087
0088 This is very similar to the L3 mode except that iptables (conn-tracking)
0089 works in this mode and hence it is L3-symmetric (L3s). This will have slightly less
0090 performance but that shouldn't matter since you are choosing this mode over plain-L3
0091 mode to make conn-tracking work.
0092
0093 5. Mode flags:
0094 ==============
0095
0096 At this time following mode flags are available
0097
0098 5.1 bridge:
0099 -----------
0100 This is the default option. To configure the IPvlan port in this mode,
0101 user can choose to either add this option on the command-line or don't specify
0102 anything. This is the traditional mode where slaves can cross-talk among
0103 themselves apart from talking through the master device.
0104
0105 5.2 private:
0106 ------------
0107 If this option is added to the command-line, the port is set in private
0108 mode. i.e. port won't allow cross communication between slaves.
0109
0110 5.3 vepa:
0111 ---------
0112 If this is added to the command-line, the port is set in VEPA mode.
0113 i.e. port will offload switching functionality to the external entity as
0114 described in 802.1Qbg
0115 Note: VEPA mode in IPvlan has limitations. IPvlan uses the mac-address of the
0116 master-device, so the packets which are emitted in this mode for the adjacent
0117 neighbor will have source and destination mac same. This will make the switch /
0118 router send the redirect message.
0119
0120 6. What to choose (macvlan vs. ipvlan)?
0121 =======================================
0122
0123 These two devices are very similar in many regards and the specific use
0124 case could very well define which device to choose. if one of the following
0125 situations defines your use case then you can choose to use ipvlan:
0126
0127
0128 (a) The Linux host that is connected to the external switch / router has
0129 policy configured that allows only one mac per port.
0130 (b) No of virtual devices created on a master exceed the mac capacity and
0131 puts the NIC in promiscuous mode and degraded performance is a concern.
0132 (c) If the slave device is to be put into the hostile / untrusted network
0133 namespace where L2 on the slave could be changed / misused.
0134
0135
0136 6. Example configuration:
0137 =========================
0138
0139 ::
0140
0141 +=============================================================+
0142 | Host: host1 |
0143 | |
0144 | +----------------------+ +----------------------+ |
0145 | | NS:ns0 | | NS:ns1 | |
0146 | | | | | |
0147 | | | | | |
0148 | | ipvl0 | | ipvl1 | |
0149 | +----------#-----------+ +-----------#----------+ |
0150 | # # |
0151 | ################################ |
0152 | # eth0 |
0153 +==============================#==============================+
0154
0155
0156 (a) Create two network namespaces - ns0, ns1::
0157
0158 ip netns add ns0
0159 ip netns add ns1
0160
0161 (b) Create two ipvlan slaves on eth0 (master device)::
0162
0163 ip link add link eth0 ipvl0 type ipvlan mode l2
0164 ip link add link eth0 ipvl1 type ipvlan mode l2
0165
0166 (c) Assign slaves to the respective network namespaces::
0167
0168 ip link set dev ipvl0 netns ns0
0169 ip link set dev ipvl1 netns ns1
0170
0171 (d) Now switch to the namespace (ns0 or ns1) to configure the slave devices
0172
0173 - For ns0::
0174
0175 (1) ip netns exec ns0 bash
0176 (2) ip link set dev ipvl0 up
0177 (3) ip link set dev lo up
0178 (4) ip -4 addr add 127.0.0.1 dev lo
0179 (5) ip -4 addr add $IPADDR dev ipvl0
0180 (6) ip -4 route add default via $ROUTER dev ipvl0
0181
0182 - For ns1::
0183
0184 (1) ip netns exec ns1 bash
0185 (2) ip link set dev ipvl1 up
0186 (3) ip link set dev lo up
0187 (4) ip -4 addr add 127.0.0.1 dev lo
0188 (5) ip -4 addr add $IPADDR dev ipvl1
0189 (6) ip -4 route add default via $ROUTER dev ipvl1
