projects / mirror_iproute2.git / blame
| Commit | Line | Data |
|---|---|---|
| 1949f82c DA |
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 | ||
| 1dddb605 DA |
15 | .ti -8 |
| 16 | .BR "ip vrf show" | |
| 17 | .RI "[ " NAME " ]" | |
| 18 | ||
| 1949f82c DA |
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 | ||
| 1dddb605 DA |
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 | ||
| 1949f82c DA |
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 | ||
| ba2fc55b LB |
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 ran as root or with the CAP_SYS_ADMIN, | |
| 70 | CAP_NET_ADMIN and CAP_DAC_OVERRIDE capabilities. If built with libcap and if | |
| 71 | capabilities are added to the ip binary program via setcap, the program will | |
| 72 | drop them as the first thing when invoked, unless the command is vrf exec. | |
| 9b13cc98 LB |
73 | .br |
| 74 | NOTE: capabilities will NOT be dropped if CAP_NET_ADMIN is set to INHERITABLE | |
| 75 | to avoid breaking programs with ambient capabilities that call ip. | |
| 76 | Do not set the INHERITABLE flag on the ip binary itself. | |
| ba2fc55b | 77 | |
| 1949f82c DA |
78 | .TP |
| 79 | .B ip vrf identify [PID] - Report VRF association for process | |
| 80 | .sp | |
| 81 | This command shows the VRF association of the specified process. If PID is | |
| 82 | not specified then the id of the current process is used. | |
| 83 | ||
| 84 | .TP | |
| 85 | .B ip vrf pids NAME - Report processes associated with the named VRF | |
| 86 | .sp | |
| 87 | This command shows all process ids that are associated with the given | |
| 88 | VRF. | |
| 89 | ||
| 90 | .SH CAVEATS | |
| 91 | This command requires a kernel compiled with CGROUPS and CGROUP_BPF enabled. | |
| 92 | ||
| 93 | The VRF helper *only* affects network layer sockets. | |
| 94 | ||
| 95 | .SH EXAMPLES | |
| 96 | .PP | |
| 97 | ip vrf exec red ssh 10.100.1.254 | |
| 98 | .RS | |
| 99 | Executes ssh to 10.100.1.254 against the VRF red table. | |
| 100 | .RE | |
| 101 | ||
| 102 | .SH SEE ALSO | |
| 103 | .br | |
| 104 | .BR ip (8), | |
| 105 | .BR ip-link (8), | |
| 106 | .BR ip-address (8), | |
| 107 | .BR ip-route (8), | |
| 108 | .BR ip-neighbor (8) | |
| 109 | ||
| 110 | .SH AUTHOR | |
| 111 | Original Manpage by David Ahern |