man/man8/ip-vrf.8

   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 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.
  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.
  77
  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