1 files changed, 86 insertions, 0 deletions
diff --git a/man/man4/veth.4 b/man/man4/veth.4
new file mode 100644
index 000000000..690a2087e
--- /dev/null
+++ b/man/man4/veth.4
@@ -0,0 +1,86 @@
+.\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb@sourcepole.ch),
+.\"     Fri, 03 Nov 2012 22:35:33 +0100
+.\" and Copyright (c) 2012 Eric W. Biederman <ebiederm@xmission.com>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\"
+.TH veth 4 (date) "Linux man-pages (unreleased)"
+.SH NAME
+veth \- Virtual Ethernet Device
+.SH DESCRIPTION
+The
+.B veth
+devices are virtual Ethernet devices.
+They can act as tunnels between network namespaces to create
+a bridge to a physical network device in another namespace,
+but can also be used as standalone network devices.
+.P
+.B veth
+devices are always created in interconnected pairs.
+A pair can be created using the command:
+.P
+.in +4n
+.EX
+# ip link add <p1-name> type veth peer name <p2-name>
+.EE
+.in
+.P
+In the above,
+.I p1-name
+and
+.I p2-name
+are the names assigned to the two connected end points.
+.P
+Packets transmitted on one device in the pair are immediately received on
+the other device.
+When either device is down, the link state of the pair is down.
+.P
+.B veth
+device pairs are useful for combining the network
+facilities of the kernel together in interesting ways.
+A particularly interesting use case is to place one end of a
+.B veth
+pair in one network namespace and the other end in another network namespace,
+thus allowing communication between network namespaces.
+To do this, one can provide the
+.B netns
+parameter when creating the interfaces:
+.P
+.in +4n
+.EX
+# ip link add <p1\-name> netns <p1\-ns> type veth peer <p2\-name> netns <p2\-ns>
+.EE
+.in
+.P
+or, for an existing
+.B veth
+pair, move one side to the other namespace:
+.P
+.in +4n
+.EX
+# ip link set <p2\-name> netns <p2\-ns>
+.EE
+.in
+.P
+.BR ethtool (8)
+can be used to find the peer of a
+.B veth
+network interface, using commands something like:
+.P
+.in +4n
+.EX
+# \fBip link add ve_A type veth peer name ve_B\fP   # Create veth pair
+# \fBethtool \-S ve_A\fP         # Discover interface index of peer
+NIC statistics:
+     peer_ifindex: 16
+# \fBip link | grep \[aq]\[ha]16:\[aq]\fP   # Look up interface
+16: ve_B@ve_A: <BROADCAST,MULTICAST,M\-DOWN> mtu 1500 qdisc ...
+.EE
+.in
+.SH "SEE ALSO"
+.BR clone (2),
+.BR network_namespaces (7),
+.BR ip (8),
+.BR ip\-link (8),
+.BR ip\-netns (8)