Documentation/networking/ipvlan.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===================
   4 IPVLAN Driver HOWTO
   5 ===================
   6
   7 Initial Release:
   8         Mahesh Bandewar <maheshb AT google.com>
   9
  10 1. Introduction:
  11 ================
  12 This is conceptually very similar to the macvlan driver with one major
  13 exception of using L3 for mux-ing /demux-ing among slaves. This property makes
  14 the master device share the L2 with its slave devices. I have developed this
  15 driver in conjunction with network namespaces and not sure if there is use case
  16 outside of it.
  17
  18
  19 2. Building and Installation:
  20 =============================
  21
  22 In order to build the driver, please select the config item CONFIG_IPVLAN.
  23 The driver can be built into the kernel (CONFIG_IPVLAN=y) or as a module
  24 (CONFIG_IPVLAN=m).
  25
  26
  27 3. Configuration:
  28 =================
  29
  30 There are no module parameters for this driver and it can be configured
  31 using 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
  39 e.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
  58 4. Operating modes:
  59 ===================
  60
  61 IPvlan has two modes of operation - L2 and L3. For a given master device,
  62 you can select one of these two modes and all slaves on that master will
  63 operate in the same (selected) mode. The RX mode is almost identical except
  64 that in L3 mode the slaves won't receive any multicast / broadcast traffic.
  65 L3 mode is more restrictive since routing is controlled from the other (mostly)
  66 default namespace.
  67
  68 4.1 L2 mode:
  69 ------------
  70
  71 In this mode TX processing happens on the stack instance attached to the
  72 slave device and packets are switched and queued to the master device to send
  73 out. In this mode the slaves will RX/TX multicast and broadcast (if applicable)
  74 as well.
  75
  76 4.2 L3 mode:
  77 ------------
  78
  79 In this mode TX processing up to L3 happens on the stack instance attached
  80 to the slave device and packets are switched to the stack instance of the
  81 master device for the L2 processing and routing from that instance will be
  82 used before packets are queued on the outbound device. In this mode the slaves
  83 will not receive nor can send multicast / broadcast traffic.
  84
  85 4.3 L3S mode:
  86 -------------
  87
  88 This is very similar to the L3 mode except that iptables (conn-tracking)
  89 works in this mode and hence it is L3-symmetric (L3s). This will have slightly less
  90 performance but that shouldn't matter since you are choosing this mode over plain-L3
  91 mode to make conn-tracking work.
  92
  93 5. Mode flags:
  94 ==============
  95
  96 At this time following mode flags are available
  97
  98 5.1 bridge:
  99 -----------
 100 This is the default option. To configure the IPvlan port in this mode,
 101 user can choose to either add this option on the command-line or don't specify
 102 anything. This is the traditional mode where slaves can cross-talk among
 103 themselves apart from talking through the master device.
 104
 105 5.2 private:
 106 ------------
 107 If this option is added to the command-line, the port is set in private
 108 mode. i.e. port won't allow cross communication between slaves.
 109
 110 5.3 vepa:
 111 ---------
 112 If this is added to the command-line, the port is set in VEPA mode.
 113 i.e. port will offload switching functionality to the external entity as
 114 described in 802.1Qbg
 115 Note: VEPA mode in IPvlan has limitations. IPvlan uses the mac-address of the
 116 master-device, so the packets which are emitted in this mode for the adjacent
 117 neighbor will have source and destination mac same. This will make the switch /
 118 router send the redirect message.
 119
 120 6. What to choose (macvlan vs. ipvlan)?
 121 =======================================
 122
 123 These two devices are very similar in many regards and the specific use
 124 case could very well define which device to choose. if one of the following
 125 situations 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
 136 6. 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