Documentation/networking/ipvlan.txt

   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 conjunction 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 up to 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 promiscuous 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