man4/veth.4

   1 .\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb@sourcepole.ch),
   2 .\"     Fri, 03 Nov 2012 22:35:33 +0100
   3 .\" and Copyright (c) 2012 Eric W. Biederman <ebiederm@xmission.com>
   4 .\"
   5 .\" SPDX-License-Identifier: GPL-2.0-or-later
   6 .\"
   7 .\"
   8 .TH veth 4 (date) "Linux man-pages (unreleased)"
   9 .SH NAME
  10 veth \- Virtual Ethernet Device
  11 .SH DESCRIPTION
  12 The
  13 .B veth
  14 devices are virtual Ethernet devices.
  15 They can act as tunnels between network namespaces to create
  16 a bridge to a physical network device in another namespace,
  17 but can also be used as standalone network devices.
  18 .P
  19 .B veth
  20 devices are always created in interconnected pairs.
  21 A pair can be created using the command:
  22 .P
  23 .in +4n
  24 .EX
  25 # ip link add <p1-name> type veth peer name <p2-name>
  26 .EE
  27 .in
  28 .P
  29 In the above,
  30 .I p1-name
  31 and
  32 .I p2-name
  33 are the names assigned to the two connected end points.
  34 .P
  35 Packets transmitted on one device in the pair are immediately received on
  36 the other device.
  37 When either device is down, the link state of the pair is down.
  38 .P
  39 .B veth
  40 device pairs are useful for combining the network
  41 facilities of the kernel together in interesting ways.
  42 A particularly interesting use case is to place one end of a
  43 .B veth
  44 pair in one network namespace and the other end in another network namespace,
  45 thus allowing communication between network namespaces.
  46 To do this, one can provide the
  47 .B netns
  48 parameter when creating the interfaces:
  49 .P
  50 .in +4n
  51 .EX
  52 # ip link add <p1\-name> netns <p1\-ns> type veth peer <p2\-name> netns <p2\-ns>
  53 .EE
  54 .in
  55 .P
  56 or, for an existing
  57 .B veth
  58 pair, move one side to the other namespace:
  59 .P
  60 .in +4n
  61 .EX
  62 # ip link set <p2\-name> netns <p2\-ns>
  63 .EE
  64 .in
  65 .P
  66 .BR ethtool (8)
  67 can be used to find the peer of a
  68 .B veth
  69 network interface, using commands something like:
  70 .P
  71 .in +4n
  72 .EX
  73 # \fBip link add ve_A type veth peer name ve_B\fP   # Create veth pair
  74 # \fBethtool \-S ve_A\fP         # Discover interface index of peer
  75 NIC statistics:
  76      peer_ifindex: 16
  77 # \fBip link | grep \[aq]\[ha]16:\[aq]\fP   # Look up interface
  78 16: ve_B@ve_A: <BROADCAST,MULTICAST,M\-DOWN> mtu 1500 qdisc ...
  79 .EE
  80 .in
  81 .SH "SEE ALSO"
  82 .BR clone (2),
  83 .BR network_namespaces (7),
  84 .BR ip (8),
  85 .BR ip\-link (8),
  86 .BR ip\-netns (8)