| 1 |
.TH IP\-VRF 8 "7 Dec 2016" "iproute2" "Linux" |
| 2 |
.SH NAME |
| 3 |
ip-vrf \- run a command against a vrf |
| 4 |
.SH SYNOPSIS |
| 5 |
.sp |
| 6 |
.ad l |
| 7 |
.in +8 |
| 8 |
.ti -8 |
| 9 |
.B ip |
| 10 |
.B vrf |
| 11 |
.RI " { " COMMAND " | " |
| 12 |
.BR help " }" |
| 13 |
.sp |
| 14 |
|
| 15 |
.ti -8 |
| 16 |
.BR "ip vrf show" |
| 17 |
.RI "[ " NAME " ]" |
| 18 |
|
| 19 |
.ti -8 |
| 20 |
.BR "ip vrf identify" |
| 21 |
.RI "[ " PID " ]" |
| 22 |
|
| 23 |
.ti -8 |
| 24 |
.BR "ip vrf pids" |
| 25 |
.I NAME |
| 26 |
|
| 27 |
.ti -8 |
| 28 |
.BR "ip vrf exec " |
| 29 |
.RI "[ " NAME " ] " command ... |
| 30 |
|
| 31 |
.SH DESCRIPTION |
| 32 |
A VRF provides traffic isolation at layer 3 for routing, similar to how a |
| 33 |
VLAN is used to isolate traffic at layer 2. Fundamentally, a VRF is a separate |
| 34 |
routing table. Network devices are associated with a VRF by enslaving the |
| 35 |
device to the VRF. At that point network addresses assigned to the device are |
| 36 |
local to the VRF with host and connected routes moved to the table associated |
| 37 |
with the VRF. |
| 38 |
|
| 39 |
A process can specify a VRF using several APIs -- binding the socket to the |
| 40 |
VRF device using SO_BINDTODEVICE, setting the VRF association using |
| 41 |
IP_UNICAST_IF or IPV6_UNICAST_IF, or specifying the VRF for a specific message |
| 42 |
using IP_PKTINFO or IPV6_PKTINFO. |
| 43 |
|
| 44 |
By default a process is not bound to any VRF. An association can be set |
| 45 |
explicitly by making the program use one of the APIs mentioned above or |
| 46 |
implicitly using a helper to set SO_BINDTODEVICE for all IPv4 and IPv6 |
| 47 |
sockets (AF_INET and AF_INET6) when the socket is created. This ip-vrf command |
| 48 |
is a helper to run a command against a specific VRF with the VRF association |
| 49 |
inherited parent to child. |
| 50 |
|
| 51 |
.TP |
| 52 |
.B ip vrf show [ NAME ] - Show all configured VRF |
| 53 |
.sp |
| 54 |
This command lists all VRF and their corresponding table ids. If NAME is |
| 55 |
given, then only that VRF and table id is shown. The latter command is |
| 56 |
useful for scripting where the table id for a VRF is needed. |
| 57 |
|
| 58 |
.TP |
| 59 |
.B ip vrf exec [ NAME ] cmd ... - Run cmd against the named VRF |
| 60 |
.sp |
| 61 |
This command allows applications that are VRF unaware to be run against |
| 62 |
a VRF other than the default VRF (main table). A command can be run against |
| 63 |
the default VRF by passing the "default" as the VRF name. This is useful if |
| 64 |
the current shell is associated with another VRF (e.g, Management VRF). |
| 65 |
|
| 66 |
This command requires the system to be booted with cgroup v2 (e.g. with systemd, |
| 67 |
add systemd.unified_cgroup_hierarchy=1 to the kernel command line). |
| 68 |
|
| 69 |
This command also requires to be run as root. Alternatively it |
| 70 |
can be run by an unprivileged user if the following |
| 71 |
.BR capabilities (7) |
| 72 |
are given: |
| 73 |
|
| 74 |
.RS |
| 75 |
.IP \fBCAP_BPF\fP |
| 76 |
To load the BPF program. |
| 77 |
.IP \fBCAP_NET_ADMIN\fP |
| 78 |
To set the socket into the cgroup. |
| 79 |
.IP \fBCAP_DAC_OVERRIDE\fP |
| 80 |
To create the cgroup subdir in /sys. |
| 81 |
.RE |
| 82 |
|
| 83 |
.IP |
| 84 |
If these capabilities are added and if |
| 85 |
.BR ip (8) |
| 86 |
is built with |
| 87 |
.BR libcap (3) |
| 88 |
then these capabilities will be dropped before |
| 89 |
.BR cmd |
| 90 |
is executed by |
| 91 |
.B ip vrf exec. |
| 92 |
For every other unprivileged invocation of |
| 93 |
.BR ip (8) |
| 94 |
all capabilities will be dropped. |
| 95 |
|
| 96 |
.br |
| 97 |
.B NOTE: |
| 98 |
capabilities will |
| 99 |
.B NOT |
| 100 |
be dropped if |
| 101 |
.B CAP_NET_ADMIN |
| 102 |
is set to |
| 103 |
.B INHERITABLE |
| 104 |
to avoid breaking programs with ambient capabilities that call ip. |
| 105 |
|
| 106 |
.TP |
| 107 |
.B ip vrf identify [PID] - Report VRF association for process |
| 108 |
.sp |
| 109 |
This command shows the VRF association of the specified process. If PID is |
| 110 |
not specified then the id of the current process is used. |
| 111 |
|
| 112 |
.TP |
| 113 |
.B ip vrf pids NAME - Report processes associated with the named VRF |
| 114 |
.sp |
| 115 |
This command shows all process ids that are associated with the given |
| 116 |
VRF. |
| 117 |
|
| 118 |
.SH CAVEATS |
| 119 |
This command requires a kernel compiled with CGROUPS and CGROUP_BPF enabled. |
| 120 |
|
| 121 |
The VRF helper *only* affects network layer sockets. |
| 122 |
|
| 123 |
.SH EXAMPLES |
| 124 |
.PP |
| 125 |
ip vrf exec red ssh 10.100.1.254 |
| 126 |
.RS |
| 127 |
Executes ssh to 10.100.1.254 against the VRF red table. |
| 128 |
.RE |
| 129 |
|
| 130 |
.SH SEE ALSO |
| 131 |
.br |
| 132 |
.BR ip (8), |
| 133 |
.BR ip-link (8), |
| 134 |
.BR ip-address (8), |
| 135 |
.BR ip-route (8), |
| 136 |
.BR ip-neighbor (8) |
| 137 |
|
| 138 |
.SH AUTHOR |
| 139 |
Original Manpage by David Ahern |