Commit 58ccb2b2 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by David S. Miller
Browse files

docs: networking: convert vrf.txt to ReST 



- add SPDX header;
- adjust title markup;
- Add a subtitle for the first section;
- mark code blocks and literals as such;
- adjust identation, whitespaces and blank lines;
- add to networking/index.rst.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: default avatarDavid Ahern <dsahern@gmail.com>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent 961fb1ff

Documentation/networking/index.rst

+1 −0
Original line number Original line Diff line number Diff line
@@ -113,6 +113,7 @@ Contents: 
   tproxy

   tproxy

   tuntap

   tuntap

   udplite

   udplite

   vrf





.. only::  subproject and html

.. only::  subproject and html

Documentation/networking/vrf.txt→Documentation/networking/vrf.rst

+451 −0
Original line number Original line Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



====================================

Virtual Routing and Forwarding (VRF)

Virtual Routing and Forwarding (VRF)

====================================

====================================



The VRF Device

==============



The VRF device combined with ip rules provides the ability to create virtual

The VRF device combined with ip rules provides the ability to create virtual

routing and forwarding domains (aka VRFs, VRF-lite to be specific) in the

routing and forwarding domains (aka VRFs, VRF-lite to be specific) in the

Linux network stack. One use case is the multi-tenancy problem where each

Linux network stack. One use case is the multi-tenancy problem where each
@@ -22,7 +29,7 @@ and then VRF devices provide L3 separation. 
Design

Design

------

------

A VRF device is created with an associated route table. Network interfaces

A VRF device is created with an associated route table. Network interfaces

are then enslaved to a VRF device:

are then enslaved to a VRF device::





	 +-----------------------------+

	 +-----------------------------+

	 |           vrf-blue          |  ===> route table 10

	 |           vrf-blue          |  ===> route table 10
@@ -41,15 +48,15 @@ in the IPv4 and IPv6 processing stacks giving the impression that packets 
flow through the VRF device. Similarly on egress routing rules are used to

flow through the VRF device. Similarly on egress routing rules are used to

send packets to the VRF device driver before getting sent out the actual

send packets to the VRF device driver before getting sent out the actual

interface. This allows tcpdump on a VRF device to capture all packets into

interface. This allows tcpdump on a VRF device to capture all packets into

and out of the VRF as a whole.[1] Similarly, netfilter[2] and tc rules can be

and out of the VRF as a whole\ [1]_. Similarly, netfilter\ [2]_ and tc rules

applied using the VRF device to specify rules that apply to the VRF domain

can be applied using the VRF device to specify rules that apply to the VRF

as a whole.

domain as a whole.





[1] Packets in the forwarded state do not flow through the device, so those

.. [1] Packets in the forwarded state do not flow through the device, so those

       packets are not seen by tcpdump. Will revisit this limitation in a

       packets are not seen by tcpdump. Will revisit this limitation in a

       future release.

       future release.





[2] Iptables on ingress supports PREROUTING with skb->dev set to the real

.. [2] Iptables on ingress supports PREROUTING with skb->dev set to the real

       ingress device and both INPUT and PREROUTING rules with skb->dev set to

       ingress device and both INPUT and PREROUTING rules with skb->dev set to

       the VRF device. For egress POSTROUTING and OUTPUT rules can be written

       the VRF device. For egress POSTROUTING and OUTPUT rules can be written

       using either the VRF device or real egress device.

       using either the VRF device or real egress device.
@@ -57,7 +64,9 @@ as a whole. 
Setup

Setup

-----

-----

1. VRF device is created with an association to a FIB table.

1. VRF device is created with an association to a FIB table.

   e.g, ip link add vrf-blue type vrf table 10

   e.g,::



	ip link add vrf-blue type vrf table 10

	ip link set dev vrf-blue up

	ip link set dev vrf-blue up





2. An l3mdev FIB rule directs lookups to the table associated with the device.

2. An l3mdev FIB rule directs lookups to the table associated with the device.
@@ -66,11 +75,13 @@ Setup 
   default preference of 1000. Users may delete the rule if desired and add

   default preference of 1000. Users may delete the rule if desired and add

   with a different priority or install per-VRF rules.

   with a different priority or install per-VRF rules.





   Prior to the v4.8 kernel iif and oif rules are needed for each VRF device:

   Prior to the v4.8 kernel iif and oif rules are needed for each VRF device::



       ip ru add oif vrf-blue table 10

       ip ru add oif vrf-blue table 10

       ip ru add iif vrf-blue table 10

       ip ru add iif vrf-blue table 10





3. Set the default route for the table (and hence default route for the VRF).

3. Set the default route for the table (and hence default route for the VRF)::



       ip route add table 10 unreachable default metric 4278198272

       ip route add table 10 unreachable default metric 4278198272





   This high metric value ensures that the default unreachable route can

   This high metric value ensures that the default unreachable route can
@@ -78,7 +89,8 @@ Setup 
   kernel metrics as a combined admin distance (upper byte) and priority

   kernel metrics as a combined admin distance (upper byte) and priority

   (lower 3 bytes).  Thus the above metric translates to [255/8192].

   (lower 3 bytes).  Thus the above metric translates to [255/8192].





4. Enslave L3 interfaces to a VRF device.

4. Enslave L3 interfaces to a VRF device::



       ip link set dev eth1 master vrf-blue

       ip link set dev eth1 master vrf-blue





   Local and connected routes for enslaved devices are automatically moved to

   Local and connected routes for enslaved devices are automatically moved to
@@ -87,17 +99,19 @@ Setup 
   FIB table following the enslavement.

   FIB table following the enslavement.





   The IPv6 sysctl option keep_addr_on_down can be enabled to keep IPv6 global

   The IPv6 sysctl option keep_addr_on_down can be enabled to keep IPv6 global

   addresses as VRF enslavement changes.

   addresses as VRF enslavement changes::



       sysctl -w net.ipv6.conf.all.keep_addr_on_down=1

       sysctl -w net.ipv6.conf.all.keep_addr_on_down=1





5. Additional VRF routes are added to associated table.

5. Additional VRF routes are added to associated table::



       ip route add table 10 ...

       ip route add table 10 ...









Applications

Applications

------------

------------

Applications that are to work within a VRF need to bind their socket to the

Applications that are to work within a VRF need to bind their socket to the

VRF device:

VRF device::





    setsockopt(sd, SOL_SOCKET, SO_BINDTODEVICE, dev, strlen(dev)+1);

    setsockopt(sd, SOL_SOCKET, SO_BINDTODEVICE, dev, strlen(dev)+1);
@@ -110,7 +124,7 @@ the same port if they bind to an l3mdev. 




TCP & UDP services running in the default VRF context (ie., not bound

TCP & UDP services running in the default VRF context (ie., not bound

to any VRF device) can work across all VRF domains by enabling the

to any VRF device) can work across all VRF domains by enabling the

tcp_l3mdev_accept and udp_l3mdev_accept sysctl options:

tcp_l3mdev_accept and udp_l3mdev_accept sysctl options::





    sysctl -w net.ipv4.tcp_l3mdev_accept=1

    sysctl -w net.ipv4.tcp_l3mdev_accept=1

    sysctl -w net.ipv4.udp_l3mdev_accept=1

    sysctl -w net.ipv4.udp_l3mdev_accept=1
@@ -123,14 +137,14 @@ using a socket not bound to the corresponding VRF. This allows e.g. older ping 
implementations to be run with specifying the device but without executing it

implementations to be run with specifying the device but without executing it

in the VRF. This option can be disabled so that packets received in a VRF

in the VRF. This option can be disabled so that packets received in a VRF

context are only handled by a raw socket bound to the VRF, and packets in the

context are only handled by a raw socket bound to the VRF, and packets in the

default VRF are only handled by a socket not bound to any VRF:

default VRF are only handled by a socket not bound to any VRF::





    sysctl -w net.ipv4.raw_l3mdev_accept=0

    sysctl -w net.ipv4.raw_l3mdev_accept=0





netfilter rules on the VRF device can be used to limit access to services

netfilter rules on the VRF device can be used to limit access to services

running in the default VRF context as well.

running in the default VRF context as well.





################################################################################

--------------------------------------------------------------------------------





Using iproute2 for VRFs

Using iproute2 for VRFs

=======================

=======================
@@ -140,7 +154,8 @@ older form without it. 




1. Create a VRF

1. Create a VRF





   To instantiate a VRF device and associate it with a table:

   To instantiate a VRF device and associate it with a table::



       $ ip link add dev NAME type vrf table ID

       $ ip link add dev NAME type vrf table ID





   As of v4.8 the kernel supports the l3mdev FIB rule where a single rule

   As of v4.8 the kernel supports the l3mdev FIB rule where a single rule
@@ -149,11 +164,13 @@ older form without it. 




2. List VRFs

2. List VRFs





   To list VRFs that have been created:

   To list VRFs that have been created::



       $ ip [-d] link show type vrf

       $ ip [-d] link show type vrf

	 NOTE: The -d option is needed to show the table id

	 NOTE: The -d option is needed to show the table id





   For example:

   For example::



       $ ip -d link show type vrf

       $ ip -d link show type vrf

       11: mgmt: <NOARP,MASTER,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000

       11: mgmt: <NOARP,MASTER,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000

	   link/ether 72:b3:ba:91:e2:24 brd ff:ff:ff:ff:ff:ff promiscuity 0

	   link/ether 72:b3:ba:91:e2:24 brd ff:ff:ff:ff:ff:ff promiscuity 0
@@ -169,7 +186,7 @@ older form without it. 
	   vrf table 81 addrgenmode eui64

	   vrf table 81 addrgenmode eui64









   Or in brief output:

   Or in brief output::





       $ ip -br link show type vrf

       $ ip -br link show type vrf

       mgmt         UP             72:b3:ba:91:e2:24 <NOARP,MASTER,UP,LOWER_UP>

       mgmt         UP             72:b3:ba:91:e2:24 <NOARP,MASTER,UP,LOWER_UP>
@@ -181,24 +198,28 @@ older form without it. 
3. Assign a Network Interface to a VRF

3. Assign a Network Interface to a VRF





   Network interfaces are assigned to a VRF by enslaving the netdevice to a

   Network interfaces are assigned to a VRF by enslaving the netdevice to a

   VRF device:

   VRF device::



       $ ip link set dev NAME master NAME

       $ ip link set dev NAME master NAME





   On enslavement connected and local routes are automatically moved to the

   On enslavement connected and local routes are automatically moved to the

   table associated with the VRF device.

   table associated with the VRF device.





   For example:

   For example::



       $ ip link set dev eth0 master mgmt

       $ ip link set dev eth0 master mgmt









4. Show Devices Assigned to a VRF

4. Show Devices Assigned to a VRF





   To show devices that have been assigned to a specific VRF add the master

   To show devices that have been assigned to a specific VRF add the master

   option to the ip command:

   option to the ip command::



       $ ip link show vrf NAME

       $ ip link show vrf NAME

       $ ip link show master NAME

       $ ip link show master NAME





   For example:

   For example::



       $ ip link show vrf red

       $ ip link show vrf red

       3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master red state UP mode DEFAULT group default qlen 1000

       3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master red state UP mode DEFAULT group default qlen 1000

	   link/ether 02:00:00:00:02:02 brd ff:ff:ff:ff:ff:ff

	   link/ether 02:00:00:00:02:02 brd ff:ff:ff:ff:ff:ff
@@ -208,7 +229,8 @@ older form without it. 
	   link/ether 02:00:00:00:02:06 brd ff:ff:ff:ff:ff:ff

	   link/ether 02:00:00:00:02:06 brd ff:ff:ff:ff:ff:ff









   Or using the brief output:

   Or using the brief output::



       $ ip -br link show vrf red

       $ ip -br link show vrf red

       eth1             UP             02:00:00:00:02:02 <BROADCAST,MULTICAST,UP,LOWER_UP>

       eth1             UP             02:00:00:00:02:02 <BROADCAST,MULTICAST,UP,LOWER_UP>

       eth2             UP             02:00:00:00:02:03 <BROADCAST,MULTICAST,UP,LOWER_UP>

       eth2             UP             02:00:00:00:02:03 <BROADCAST,MULTICAST,UP,LOWER_UP>
@@ -218,11 +240,13 @@ older form without it. 
5. Show Neighbor Entries for a VRF

5. Show Neighbor Entries for a VRF





   To list neighbor entries associated with devices enslaved to a VRF device

   To list neighbor entries associated with devices enslaved to a VRF device

   add the master option to the ip command:

   add the master option to the ip command::



       $ ip [-6] neigh show vrf NAME

       $ ip [-6] neigh show vrf NAME

       $ ip [-6] neigh show master NAME

       $ ip [-6] neigh show master NAME





   For example:

   For example::



       $  ip neigh show vrf red

       $  ip neigh show vrf red

       10.2.1.254 dev eth1 lladdr a6:d9:c7:4f:06:23 REACHABLE

       10.2.1.254 dev eth1 lladdr a6:d9:c7:4f:06:23 REACHABLE

       10.2.2.254 dev eth2 lladdr 5e:54:01:6a:ee:80 REACHABLE

       10.2.2.254 dev eth2 lladdr 5e:54:01:6a:ee:80 REACHABLE
@@ -234,11 +258,13 @@ older form without it. 
6. Show Addresses for a VRF

6. Show Addresses for a VRF





   To show addresses for interfaces associated with a VRF add the master

   To show addresses for interfaces associated with a VRF add the master

   option to the ip command:

   option to the ip command::



       $ ip addr show vrf NAME

       $ ip addr show vrf NAME

       $ ip addr show master NAME

       $ ip addr show master NAME





   For example:

   For example::



	$ ip addr show vrf red

	$ ip addr show vrf red

	3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master red state UP group default qlen 1000

	3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master red state UP group default qlen 1000

	    link/ether 02:00:00:00:02:02 brd ff:ff:ff:ff:ff:ff

	    link/ether 02:00:00:00:02:02 brd ff:ff:ff:ff:ff:ff
@@ -259,7 +285,8 @@ older form without it. 
	7: eth5: <BROADCAST,MULTICAST> mtu 1500 qdisc noop master red state DOWN group default qlen 1000

	7: eth5: <BROADCAST,MULTICAST> mtu 1500 qdisc noop master red state DOWN group default qlen 1000

	    link/ether 02:00:00:00:02:06 brd ff:ff:ff:ff:ff:ff

	    link/ether 02:00:00:00:02:06 brd ff:ff:ff:ff:ff:ff





   Or in brief format:

   Or in brief format::



	$ ip -br addr show vrf red

	$ ip -br addr show vrf red

	eth1             UP             10.2.1.2/24 2002:1::2/120 fe80::ff:fe00:202/64

	eth1             UP             10.2.1.2/24 2002:1::2/120 fe80::ff:fe00:202/64

	eth2             UP             10.2.2.2/24 2002:2::2/120 fe80::ff:fe00:203/64

	eth2             UP             10.2.2.2/24 2002:2::2/120 fe80::ff:fe00:203/64
@@ -269,11 +296,13 @@ older form without it. 
7. Show Routes for a VRF

7. Show Routes for a VRF





   To show routes for a VRF use the ip command to display the table associated

   To show routes for a VRF use the ip command to display the table associated

   with the VRF device:

   with the VRF device::



       $ ip [-6] route show vrf NAME

       $ ip [-6] route show vrf NAME

       $ ip [-6] route show table ID

       $ ip [-6] route show table ID





   For example:

   For example::



	$ ip route show vrf red

	$ ip route show vrf red

	unreachable default  metric 4278198272

	unreachable default  metric 4278198272

	broadcast 10.2.1.0 dev eth1  proto kernel  scope link  src 10.2.1.2

	broadcast 10.2.1.0 dev eth1  proto kernel  scope link  src 10.2.1.2
@@ -305,11 +334,13 @@ older form without it. 




8. Route Lookup for a VRF

8. Route Lookup for a VRF





   A test route lookup can be done for a VRF:

   A test route lookup can be done for a VRF::



       $ ip [-6] route get vrf NAME ADDRESS

       $ ip [-6] route get vrf NAME ADDRESS

       $ ip [-6] route get oif NAME ADDRESS

       $ ip [-6] route get oif NAME ADDRESS





   For example:

   For example::



	$ ip route get 10.2.1.40 vrf red

	$ ip route get 10.2.1.40 vrf red

	10.2.1.40 dev eth1  table red  src 10.2.1.2

	10.2.1.40 dev eth1  table red  src 10.2.1.2

	    cache

	    cache
@@ -321,18 +352,20 @@ older form without it. 
9. Removing Network Interface from a VRF

9. Removing Network Interface from a VRF





   Network interfaces are removed from a VRF by breaking the enslavement to

   Network interfaces are removed from a VRF by breaking the enslavement to

   the VRF device:

   the VRF device::



       $ ip link set dev NAME nomaster

       $ ip link set dev NAME nomaster





   Connected routes are moved back to the default table and local entries are

   Connected routes are moved back to the default table and local entries are

   moved to the local table.

   moved to the local table.





   For example:

   For example::



    $ ip link set dev eth0 nomaster

    $ ip link set dev eth0 nomaster





--------------------------------------------------------------------------------

--------------------------------------------------------------------------------





Commands used in this example:

Commands used in this example::





     cat >> /etc/iproute2/rt_tables.d/vrf.conf <<EOF

     cat >> /etc/iproute2/rt_tables.d/vrf.conf <<EOF

     1  mgmt

     1  mgmt

MAINTAINERS

+1 −1
Original line number Original line Diff line number Diff line
@@ -18106,7 +18106,7 @@ M: David Ahern <dsahern@kernel.org> 
M:	Shrijeet Mukherjee <shrijeet@gmail.com>

M:	Shrijeet Mukherjee <shrijeet@gmail.com>

L:	netdev@vger.kernel.org

L:	netdev@vger.kernel.org

S:	Maintained

S:	Maintained

F:	Documentation/networking/vrf.txt

F:	Documentation/networking/vrf.rst

F:	drivers/net/vrf.c

F:	drivers/net/vrf.c











VSPRINTF




VSPRINTF