1.. SPDX-License-Identifier: GPL-2.0
2
3===================
4IPVLAN Driver HOWTO
5===================
6
7Initial Release:
8	Mahesh Bandewar <maheshb AT google.com>
9
101. Introduction:
11================
12This is conceptually very similar to the macvlan driver with one major
13exception of using L3 for mux-ing /demux-ing among slaves. This property makes
14the master device share the L2 with it's slave devices. I have developed this
15driver in conjunction with network namespaces and not sure if there is use case
16outside of it.
17
18
192. Building and Installation:
20=============================
21
22In order to build the driver, please select the config item CONFIG_IPVLAN.
23The driver can be built into the kernel (CONFIG_IPVLAN=y) or as a module
24(CONFIG_IPVLAN=m).
25
26
273. Configuration:
28=================
29
30There are no module parameters for this driver and it can be configured
31using IProute2/ip utility.
32::
33
34    ip link add link <master> name <slave> type ipvlan [ mode MODE ] [ FLAGS ]
35       where
36	 MODE: l3 (default) | l3s | l2
37	 FLAGS: bridge (default) | private | vepa
38
39e.g.
40
41    (a) Following will create IPvlan link with eth0 as master in
42	L3 bridge mode::
43
44	  bash# ip link add link eth0 name ipvl0 type ipvlan
45    (b) This command will create IPvlan link in L2 bridge mode::
46
47	  bash# ip link add link eth0 name ipvl0 type ipvlan mode l2 bridge
48
49    (c) This command will create an IPvlan device in L2 private mode::
50
51	  bash# ip link add link eth0 name ipvlan type ipvlan mode l2 private
52
53    (d) This command will create an IPvlan device in L2 vepa mode::
54
55	  bash# ip link add link eth0 name ipvlan type ipvlan mode l2 vepa
56
57
584. Operating modes:
59===================
60
61IPvlan has two modes of operation - L2 and L3. For a given master device,
62you can select one of these two modes and all slaves on that master will
63operate in the same (selected) mode. The RX mode is almost identical except
64that in L3 mode the slaves wont receive any multicast / broadcast traffic.
65L3 mode is more restrictive since routing is controlled from the other (mostly)
66default namespace.
67
684.1 L2 mode:
69------------
70
71In this mode TX processing happens on the stack instance attached to the
72slave device and packets are switched and queued to the master device to send
73out. In this mode the slaves will RX/TX multicast and broadcast (if applicable)
74as well.
75
764.2 L3 mode:
77------------
78
79In this mode TX processing up to L3 happens on the stack instance attached
80to the slave device and packets are switched to the stack instance of the
81master device for the L2 processing and routing from that instance will be
82used before packets are queued on the outbound device. In this mode the slaves
83will not receive nor can send multicast / broadcast traffic.
84
854.3 L3S mode:
86-------------
87
88This is very similar to the L3 mode except that iptables (conn-tracking)
89works in this mode and hence it is L3-symmetric (L3s). This will have slightly less
90performance but that shouldn't matter since you are choosing this mode over plain-L3
91mode to make conn-tracking work.
92
935. Mode flags:
94==============
95
96At this time following mode flags are available
97
985.1 bridge:
99-----------
100This is the default option. To configure the IPvlan port in this mode,
101user can choose to either add this option on the command-line or don't specify
102anything. This is the traditional mode where slaves can cross-talk among
103themselves apart from talking through the master device.
104
1055.2 private:
106------------
107If this option is added to the command-line, the port is set in private
108mode. i.e. port won't allow cross communication between slaves.
109
1105.3 vepa:
111---------
112If this is added to the command-line, the port is set in VEPA mode.
113i.e. port will offload switching functionality to the external entity as
114described in 802.1Qbg
115Note: VEPA mode in IPvlan has limitations. IPvlan uses the mac-address of the
116master-device, so the packets which are emitted in this mode for the adjacent
117neighbor will have source and destination mac same. This will make the switch /
118router send the redirect message.
119
1206. What to choose (macvlan vs. ipvlan)?
121=======================================
122
123These two devices are very similar in many regards and the specific use
124case could very well define which device to choose. if one of the following
125situations defines your use case then you can choose to use ipvlan:
126
127
128(a) The Linux host that is connected to the external switch / router has
129    policy configured that allows only one mac per port.
130(b) No of virtual devices created on a master exceed the mac capacity and
131    puts the NIC in promiscuous mode and degraded performance is a concern.
132(c) If the slave device is to be put into the hostile / untrusted network
133    namespace where L2 on the slave could be changed / misused.
134
135
1366. Example configuration:
137=========================
138
139::
140
141  +=============================================================+
142  |  Host: host1                                                |
143  |                                                             |
144  |   +----------------------+      +----------------------+    |
145  |   |   NS:ns0             |      |  NS:ns1              |    |
146  |   |                      |      |                      |    |
147  |   |                      |      |                      |    |
148  |   |        ipvl0         |      |         ipvl1        |    |
149  |   +----------#-----------+      +-----------#----------+    |
150  |              #                              #               |
151  |              ################################               |
152  |                              # eth0                         |
153  +==============================#==============================+
154
155
156(a) Create two network namespaces - ns0, ns1::
157
158	ip netns add ns0
159	ip netns add ns1
160
161(b) Create two ipvlan slaves on eth0 (master device)::
162
163	ip link add link eth0 ipvl0 type ipvlan mode l2
164	ip link add link eth0 ipvl1 type ipvlan mode l2
165
166(c) Assign slaves to the respective network namespaces::
167
168	ip link set dev ipvl0 netns ns0
169	ip link set dev ipvl1 netns ns1
170
171(d) Now switch to the namespace (ns0 or ns1) to configure the slave devices
172
173	- For ns0::
174
175		(1) ip netns exec ns0 bash
176		(2) ip link set dev ipvl0 up
177		(3) ip link set dev lo up
178		(4) ip -4 addr add 127.0.0.1 dev lo
179		(5) ip -4 addr add $IPADDR dev ipvl0
180		(6) ip -4 route add default via $ROUTER dev ipvl0
181
182	- For ns1::
183
184		(1) ip netns exec ns1 bash
185		(2) ip link set dev ipvl1 up
186		(3) ip link set dev lo up
187		(4) ip -4 addr add 127.0.0.1 dev lo
188		(5) ip -4 addr add $IPADDR dev ipvl1
189		(6) ip -4 route add default via $ROUTER dev ipvl1
190