Documentation/networking/vrf.txt

   1 Virtual Routing and Forwarding (VRF)
   2 ====================================
   3 The VRF device combined with ip rules provides the ability to create virtual
   4 routing and forwarding domains (aka VRFs, VRF-lite to be specific) in the
   5 Linux network stack. One use case is the multi-tenancy problem where each
   6 tenant has their own unique routing tables and in the very least need
   7 different default gateways.
   8
   9 Processes can be "VRF aware" by binding a socket to the VRF device. Packets
  10 through the socket then use the routing table associated with the VRF
  11 device. An important feature of the VRF device implementation is that it
  12 impacts only Layer 3 and above so L2 tools (e.g., LLDP) are not affected
  13 (ie., they do not need to be run in each VRF). The design also allows
  14 the use of higher priority ip rules (Policy Based Routing, PBR) to take
  15 precedence over the VRF device rules directing specific traffic as desired.
  16
  17 In addition, VRF devices allow VRFs to be nested within namespaces. For
  18 example network namespaces provide separation of network interfaces at the
  19 device layer, VLANs on the interfaces within a namespace provide L2 separation
  20 and then VRF devices provide L3 separation.
  21
  22 Design
  23 ------
  24 A VRF device is created with an associated route table. Network interfaces
  25 are then enslaved to a VRF device:
  26
  27          +-----------------------------+
  28          |           vrf-blue          |  ===> route table 10
  29          +-----------------------------+
  30             |        |            |
  31          +------+ +------+     +-------------+
  32          | eth1 | | eth2 | ... |    bond1    |
  33          +------+ +------+     +-------------+
  34                                   |       |
  35                               +------+ +------+
  36                               | eth8 | | eth9 |
  37                               +------+ +------+
  38
  39 Packets received on an enslaved device and are switched to the VRF device
  40 in the IPv4 and IPv6 processing stacks giving the impression that packets
  41 flow through the VRF device. Similarly on egress routing rules are used to
  42 send packets to the VRF device driver before getting sent out the actual
  43 interface. This allows tcpdump on a VRF device to capture all packets into
  44 and out of the VRF as a whole.[1] Similarly, netfilter[2] and tc rules can be
  45 applied using the VRF device to specify rules that apply to the VRF domain
  46 as a whole.
  47
  48 [1] Packets in the forwarded state do not flow through the device, so those
  49     packets are not seen by tcpdump. Will revisit this limitation in a
  50     future release.
  51
  52 [2] Iptables on ingress supports PREROUTING with skb->dev set to the real
  53     ingress device and both INPUT and PREROUTING rules with skb->dev set to
  54     the VRF device. For egress POSTROUTING and OUTPUT rules can be written
  55     using either the VRF device or real egress device.
  56
  57 Setup
  58 -----
  59 1. VRF device is created with an association to a FIB table.
  60    e.g, ip link add vrf-blue type vrf table 10
  61         ip link set dev vrf-blue up
  62
  63 2. An l3mdev FIB rule directs lookups to the table associated with the device.
  64    A single l3mdev rule is sufficient for all VRFs. The VRF device adds the
  65    l3mdev rule for IPv4 and IPv6 when the first device is created with a
  66    default preference of 1000. Users may delete the rule if desired and add
  67    with a different priority or install per-VRF rules.
  68
  69    Prior to the v4.8 kernel iif and oif rules are needed for each VRF device:
  70        ip ru add oif vrf-blue table 10
  71        ip ru add iif vrf-blue table 10
  72
  73 3. Set the default route for the table (and hence default route for the VRF).
  74        ip route add table 10 unreachable default metric 4278198272
  75
  76    This high metric value ensures that the default unreachable route can
  77    be overridden by a routing protocol suite.  FRRouting interprets
  78    kernel metrics as a combined admin distance (upper byte) and priority
  79    (lower 3 bytes).  Thus the above metric translates to [255/8192].
  80
  81 4. Enslave L3 interfaces to a VRF device.
  82        ip link set dev eth1 master vrf-blue
  83
  84    Local and connected routes for enslaved devices are automatically moved to
  85    the table associated with VRF device. Any additional routes depending on
  86    the enslaved device are dropped and will need to be reinserted to the VRF
  87    FIB table following the enslavement.
  88
  89    The IPv6 sysctl option keep_addr_on_down can be enabled to keep IPv6 global
  90    addresses as VRF enslavement changes.
  91        sysctl -w net.ipv6.conf.all.keep_addr_on_down=1
  92
  93 5. Additional VRF routes are added to associated table.
  94        ip route add table 10 ...
  95
  96
  97 Applications
  98 ------------
  99 Applications that are to work within a VRF need to bind their socket to the
 100 VRF device:
 101
 102     setsockopt(sd, SOL_SOCKET, SO_BINDTODEVICE, dev, strlen(dev)+1);
 103
 104 or to specify the output device using cmsg and IP_PKTINFO.
 105
 106 By default the scope of the port bindings for unbound sockets is
 107 limited to the default VRF. That is, it will not be matched by packets
 108 arriving on interfaces enslaved to an l3mdev and processes may bind to
 109 the same port if they bind to an l3mdev.
 110
 111 TCP & UDP services running in the default VRF context (ie., not bound
 112 to any VRF device) can work across all VRF domains by enabling the
 113 tcp_l3mdev_accept and udp_l3mdev_accept sysctl options:
 114     sysctl -w net.ipv4.tcp_l3mdev_accept=1
 115     sysctl -w net.ipv4.udp_l3mdev_accept=1
 116
 117 netfilter rules on the VRF device can be used to limit access to services
 118 running in the default VRF context as well.
 119
 120 ################################################################################
 121
 122 Using iproute2 for VRFs
 123 =======================
 124 iproute2 supports the vrf keyword as of v4.7. For backwards compatibility this
 125 section lists both commands where appropriate -- with the vrf keyword and the
 126 older form without it.
 127
 128 1. Create a VRF
 129
 130    To instantiate a VRF device and associate it with a table:
 131        $ ip link add dev NAME type vrf table ID
 132
 133    As of v4.8 the kernel supports the l3mdev FIB rule where a single rule
 134    covers all VRFs. The l3mdev rule is created for IPv4 and IPv6 on first
 135    device create.
 136
 137 2. List VRFs
 138
 139    To list VRFs that have been created:
 140        $ ip [-d] link show type vrf
 141          NOTE: The -d option is needed to show the table id
 142
 143    For example:
 144    $ ip -d link show type vrf
 145    11: mgmt: <NOARP,MASTER,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000
 146        link/ether 72:b3:ba:91:e2:24 brd ff:ff:ff:ff:ff:ff promiscuity 0
 147        vrf table 1 addrgenmode eui64
 148    12: red: <NOARP,MASTER,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000
 149        link/ether b6:6f:6e:f6:da:73 brd ff:ff:ff:ff:ff:ff promiscuity 0
 150        vrf table 10 addrgenmode eui64
 151    13: blue: <NOARP,MASTER,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000
 152        link/ether 36:62:e8:7d:bb:8c brd ff:ff:ff:ff:ff:ff promiscuity 0
 153        vrf table 66 addrgenmode eui64
 154    14: green: <NOARP,MASTER,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000
 155        link/ether e6:28:b8:63:70:bb brd ff:ff:ff:ff:ff:ff promiscuity 0
 156        vrf table 81 addrgenmode eui64
 157
 158
 159    Or in brief output:
 160
 161    $ ip -br link show type vrf
 162    mgmt         UP             72:b3:ba:91:e2:24 <NOARP,MASTER,UP,LOWER_UP>
 163    red          UP             b6:6f:6e:f6:da:73 <NOARP,MASTER,UP,LOWER_UP>
 164    blue         UP             36:62:e8:7d:bb:8c <NOARP,MASTER,UP,LOWER_UP>
 165    green        UP             e6:28:b8:63:70:bb <NOARP,MASTER,UP,LOWER_UP>
 166
 167
 168 3. Assign a Network Interface to a VRF
 169
 170    Network interfaces are assigned to a VRF by enslaving the netdevice to a
 171    VRF device:
 172        $ ip link set dev NAME master NAME
 173
 174    On enslavement connected and local routes are automatically moved to the
 175    table associated with the VRF device.
 176
 177    For example:
 178    $ ip link set dev eth0 master mgmt
 179
 180
 181 4. Show Devices Assigned to a VRF
 182
 183    To show devices that have been assigned to a specific VRF add the master
 184    option to the ip command:
 185        $ ip link show vrf NAME
 186        $ ip link show master NAME
 187
 188    For example:
 189    $ ip link show vrf red
 190    3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master red state UP mode DEFAULT group default qlen 1000
 191        link/ether 02:00:00:00:02:02 brd ff:ff:ff:ff:ff:ff
 192    4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master red state UP mode DEFAULT group default qlen 1000
 193        link/ether 02:00:00:00:02:03 brd ff:ff:ff:ff:ff:ff
 194    7: eth5: <BROADCAST,MULTICAST> mtu 1500 qdisc noop master red state DOWN mode DEFAULT group default qlen 1000
 195        link/ether 02:00:00:00:02:06 brd ff:ff:ff:ff:ff:ff
 196
 197
 198    Or using the brief output:
 199    $ ip -br link show vrf red
 200    eth1             UP             02:00:00:00:02:02 <BROADCAST,MULTICAST,UP,LOWER_UP>
 201    eth2             UP             02:00:00:00:02:03 <BROADCAST,MULTICAST,UP,LOWER_UP>
 202    eth5             DOWN           02:00:00:00:02:06 <BROADCAST,MULTICAST>
 203
 204
 205 5. Show Neighbor Entries for a VRF
 206
 207    To list neighbor entries associated with devices enslaved to a VRF device
 208    add the master option to the ip command:
 209        $ ip [-6] neigh show vrf NAME
 210        $ ip [-6] neigh show master NAME
 211
 212    For example:
 213    $  ip neigh show vrf red
 214    10.2.1.254 dev eth1 lladdr a6:d9:c7:4f:06:23 REACHABLE
 215    10.2.2.254 dev eth2 lladdr 5e:54:01:6a:ee:80 REACHABLE
 216
 217    $ ip -6 neigh show vrf red
 218    2002:1::64 dev eth1 lladdr a6:d9:c7:4f:06:23 REACHABLE
 219
 220
 221 6. Show Addresses for a VRF
 222
 223    To show addresses for interfaces associated with a VRF add the master
 224    option to the ip command:
 225        $ ip addr show vrf NAME
 226        $ ip addr show master NAME
 227
 228    For example:
 229    $ ip addr show vrf red
 230    3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master red state UP group default qlen 1000
 231        link/ether 02:00:00:00:02:02 brd ff:ff:ff:ff:ff:ff
 232        inet 10.2.1.2/24 brd 10.2.1.255 scope global eth1
 233           valid_lft forever preferred_lft forever
 234        inet6 2002:1::2/120 scope global
 235           valid_lft forever preferred_lft forever
 236        inet6 fe80::ff:fe00:202/64 scope link
 237           valid_lft forever preferred_lft forever
 238    4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master red state UP group default qlen 1000
 239        link/ether 02:00:00:00:02:03 brd ff:ff:ff:ff:ff:ff
 240        inet 10.2.2.2/24 brd 10.2.2.255 scope global eth2
 241           valid_lft forever preferred_lft forever
 242        inet6 2002:2::2/120 scope global
 243           valid_lft forever preferred_lft forever
 244        inet6 fe80::ff:fe00:203/64 scope link
 245           valid_lft forever preferred_lft forever
 246    7: eth5: <BROADCAST,MULTICAST> mtu 1500 qdisc noop master red state DOWN group default qlen 1000
 247        link/ether 02:00:00:00:02:06 brd ff:ff:ff:ff:ff:ff
 248
 249    Or in brief format:
 250    $ ip -br addr show vrf red
 251    eth1             UP             10.2.1.2/24 2002:1::2/120 fe80::ff:fe00:202/64
 252    eth2             UP             10.2.2.2/24 2002:2::2/120 fe80::ff:fe00:203/64
 253    eth5             DOWN
 254
 255
 256 7. Show Routes for a VRF
 257
 258    To show routes for a VRF use the ip command to display the table associated
 259    with the VRF device:
 260        $ ip [-6] route show vrf NAME
 261        $ ip [-6] route show table ID
 262
 263    For example:
 264    $ ip route show vrf red
 265    unreachable default  metric 4278198272
 266    broadcast 10.2.1.0 dev eth1  proto kernel  scope link  src 10.2.1.2
 267    10.2.1.0/24 dev eth1  proto kernel  scope link  src 10.2.1.2
 268    local 10.2.1.2 dev eth1  proto kernel  scope host  src 10.2.1.2
 269    broadcast 10.2.1.255 dev eth1  proto kernel  scope link  src 10.2.1.2
 270    broadcast 10.2.2.0 dev eth2  proto kernel  scope link  src 10.2.2.2
 271    10.2.2.0/24 dev eth2  proto kernel  scope link  src 10.2.2.2
 272    local 10.2.2.2 dev eth2  proto kernel  scope host  src 10.2.2.2
 273    broadcast 10.2.2.255 dev eth2  proto kernel  scope link  src 10.2.2.2
 274
 275    $ ip -6 route show vrf red
 276    local 2002:1:: dev lo  proto none  metric 0  pref medium
 277    local 2002:1::2 dev lo  proto none  metric 0  pref medium
 278    2002:1::/120 dev eth1  proto kernel  metric 256  pref medium
 279    local 2002:2:: dev lo  proto none  metric 0  pref medium
 280    local 2002:2::2 dev lo  proto none  metric 0  pref medium
 281    2002:2::/120 dev eth2  proto kernel  metric 256  pref medium
 282    local fe80:: dev lo  proto none  metric 0  pref medium
 283    local fe80:: dev lo  proto none  metric 0  pref medium
 284    local fe80::ff:fe00:202 dev lo  proto none  metric 0  pref medium
 285    local fe80::ff:fe00:203 dev lo  proto none  metric 0  pref medium
 286    fe80::/64 dev eth1  proto kernel  metric 256  pref medium
 287    fe80::/64 dev eth2  proto kernel  metric 256  pref medium
 288    ff00::/8 dev red  metric 256  pref medium
 289    ff00::/8 dev eth1  metric 256  pref medium
 290    ff00::/8 dev eth2  metric 256  pref medium
 291    unreachable default dev lo  metric 4278198272  error -101 pref medium
 292
 293 8. Route Lookup for a VRF
 294
 295    A test route lookup can be done for a VRF:
 296        $ ip [-6] route get vrf NAME ADDRESS
 297        $ ip [-6] route get oif NAME ADDRESS
 298
 299    For example:
 300    $ ip route get 10.2.1.40 vrf red
 301    10.2.1.40 dev eth1  table red  src 10.2.1.2
 302        cache
 303
 304    $ ip -6 route get 2002:1::32 vrf red
 305    2002:1::32 from :: dev eth1  table red  proto kernel  src 2002:1::2  metric 256  pref medium
 306
 307
 308 9. Removing Network Interface from a VRF
 309
 310    Network interfaces are removed from a VRF by breaking the enslavement to
 311    the VRF device:
 312        $ ip link set dev NAME nomaster
 313
 314    Connected routes are moved back to the default table and local entries are
 315    moved to the local table.
 316
 317    For example:
 318    $ ip link set dev eth0 nomaster
 319
 320 --------------------------------------------------------------------------------
 321
 322 Commands used in this example:
 323
 324 cat >> /etc/iproute2/rt_tables.d/vrf.conf <<EOF
 325 1  mgmt
 326 10 red
 327 66 blue
 328 81 green
 329 EOF
 330
 331 function vrf_create
 332 {
 333     VRF=$1
 334     TBID=$2
 335
 336     # create VRF device
 337     ip link add ${VRF} type vrf table ${TBID}
 338
 339     if [ "${VRF}" != "mgmt" ]; then
 340         ip route add table ${TBID} unreachable default metric 4278198272
 341     fi
 342     ip link set dev ${VRF} up
 343 }
 344
 345 vrf_create mgmt 1
 346 ip link set dev eth0 master mgmt
 347
 348 vrf_create red 10
 349 ip link set dev eth1 master red
 350 ip link set dev eth2 master red
 351 ip link set dev eth5 master red
 352
 353 vrf_create blue 66
 354 ip link set dev eth3 master blue
 355
 356 vrf_create green 81
 357 ip link set dev eth4 master green
 358
 359
 360 Interface addresses from /etc/network/interfaces:
 361 auto eth0
 362 iface eth0 inet static
 363       address 10.0.0.2
 364       netmask 255.255.255.0
 365       gateway 10.0.0.254
 366
 367 iface eth0 inet6 static
 368       address 2000:1::2
 369       netmask 120
 370
 371 auto eth1
 372 iface eth1 inet static
 373       address 10.2.1.2
 374       netmask 255.255.255.0
 375
 376 iface eth1 inet6 static
 377       address 2002:1::2
 378       netmask 120
 379
 380 auto eth2
 381 iface eth2 inet static
 382       address 10.2.2.2
 383       netmask 255.255.255.0
 384
 385 iface eth2 inet6 static
 386       address 2002:2::2
 387       netmask 120
 388
 389 auto eth3
 390 iface eth3 inet static
 391       address 10.2.3.2
 392       netmask 255.255.255.0
 393
 394 iface eth3 inet6 static
 395       address 2002:3::2
 396       netmask 120
 397
 398 auto eth4
 399 iface eth4 inet static
 400       address 10.2.4.2
 401       netmask 255.255.255.0
 402
 403 iface eth4 inet6 static
 404       address 2002:4::2
 405       netmask 120