[GitHub/exynos8895/android_kernel_samsung_universal8895.git] / Documentation / networking / ipvlan.txt


                            IPVLAN Driver HOWTO

Initial Release:
	Mahesh Bandewar <maheshb AT google.com>

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 conjuntion 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 <master-dev> <slave-dev> type ipvlan mode { l2 | L3 }

	e.g. ip link add link ipvl0 eth0 type ipvlan mode l2


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 upto 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.


5. 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 promiscous 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
Commit	Line	Data
2ad7bf36 MB	1
	2	IPVLAN Driver HOWTO
	3
	4	Initial Release:
	5	Mahesh Bandewar <maheshb AT google.com>
	6
	7	1. Introduction:
	8	This is conceptually very similar to the macvlan driver with one major
	9	exception of using L3 for mux-ing /demux-ing among slaves. This property makes
	10	the master device share the L2 with it's slave devices. I have developed this
	11	driver in conjuntion with network namespaces and not sure if there is use case
	12	outside of it.
	13
	14
	15	2. Building and Installation:
	16	In order to build the driver, please select the config item CONFIG_IPVLAN.
	17	The driver can be built into the kernel (CONFIG_IPVLAN=y) or as a module
	18	(CONFIG_IPVLAN=m).
	19
	20
	21	3. Configuration:
	22	There are no module parameters for this driver and it can be configured
	23	using IProute2/ip utility.
	24
	25	ip link add link <master-dev> <slave-dev> type ipvlan mode { l2 \| L3 }
	26
	27	e.g. ip link add link ipvl0 eth0 type ipvlan mode l2
	28
	29
	30	4. Operating modes:
	31	IPvlan has two modes of operation - L2 and L3. For a given master device,
	32	you can select one of these two modes and all slaves on that master will
	33	operate in the same (selected) mode. The RX mode is almost identical except
	34	that in L3 mode the slaves wont receive any multicast / broadcast traffic.
	35	L3 mode is more restrictive since routing is controlled from the other (mostly)
	36	default namespace.
	37
	38	4.1 L2 mode:
	39	In this mode TX processing happens on the stack instance attached to the
	40	slave device and packets are switched and queued to the master device to send
	41	out. In this mode the slaves will RX/TX multicast and broadcast (if applicable)
	42	as well.
	43
	44	4.2 L3 mode:
	45	In this mode TX processing upto L3 happens on the stack instance attached
	46	to the slave device and packets are switched to the stack instance of the
	47	master device for the L2 processing and routing from that instance will be
	48	used before packets are queued on the outbound device. In this mode the slaves
	49	will not receive nor can send multicast / broadcast traffic.
	50
	51
	52	5. What to choose (macvlan vs. ipvlan)?
	53	These two devices are very similar in many regards and the specific use
	54	case could very well define which device to choose. if one of the following
	55	situations defines your use case then you can choose to use ipvlan -
	56	(a) The Linux host that is connected to the external switch / router has
	57	policy configured that allows only one mac per port.
	58	(b) No of virtual devices created on a master exceed the mac capacity and
	59	puts the NIC in promiscous mode and degraded performance is a concern.
	60	(c) If the slave device is to be put into the hostile / untrusted network
	61	namespace where L2 on the slave could be changed / misused.
	62
	63
	64	6. Example configuration:
65
66	+=============================================================+
67	\| Host: host1 \|
68	\| \|
69	\| +----------------------+ +----------------------+ \|
70	\| \| NS:ns0 \| \| NS:ns1 \| \|
71	\| \| \| \| \| \|
72	\| \| \| \| \| \|
73	\| \| ipvl0 \| \| ipvl1 \| \|
74	\| +----------#-----------+ +-----------#----------+ \|
75	\| # # \|
76	\| ################################ \|
77	\| # eth0 \|
78	+==============================#==============================+
79
80
81	(a) Create two network namespaces - ns0, ns1
82	ip netns add ns0
83	ip netns add ns1
84
85	(b) Create two ipvlan slaves on eth0 (master device)
86	ip link add link eth0 ipvl0 type ipvlan mode l2
87	ip link add link eth0 ipvl1 type ipvlan mode l2
88
89	(c) Assign slaves to the respective network namespaces
90	ip link set dev ipvl0 netns ns0
91	ip link set dev ipvl1 netns ns1
92
93	(d) Now switch to the namespace (ns0 or ns1) to configure the slave devices
94	- For ns0
95	(1) ip netns exec ns0 bash
96	(2) ip link set dev ipvl0 up
97	(3) ip link set dev lo up
98	(4) ip -4 addr add 127.0.0.1 dev lo
99	(5) ip -4 addr add $IPADDR dev ipvl0
100	(6) ip -4 route add default via $ROUTER dev ipvl0
101	- For ns1
102	(1) ip netns exec ns1 bash
103	(2) ip link set dev ipvl1 up
104	(3) ip link set dev lo up
105	(4) ip -4 addr add 127.0.0.1 dev lo
106	(5) ip -4 addr add $IPADDR dev ipvl1
107	(6) ip -4 route add default via $ROUTER dev ipvl1