clone.2: Document CLONE_NEWNET

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/clone.2 b/man2/clone.2
index c148168adfa2c716874420c82f0a948e92c3b918..a976d77a94d2e27cec0bc0c32e0ea0ff8a25c1c2 100644 (file)
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -39,7 +39,6 @@
 .\"
 .\" FIXME Document CLONE_NEWUSER, which is new in 2.6.23
 .\"       (also supported for unshare()?)
-.\" FIXME Document CLONE_NEWNET, new in Linux 2.6.24
 .\" FIXME . 2.6.25 marks the unused CLONE_STOPPED as obsolete, and it will
 .\"       probably be removed in the future.
 .\"
@@ -288,6 +287,37 @@ configuration options and that the process be privileged
 This flag can't be specified in conjunction with
 .BR CLONE_SYSVSEM .
 .TP
+.BR CLONE_NEWNET " (since Linux 2.6.24)"
+(The implementation of this flag is not yet complete,
+but probably will be mostly complete by about Linux 2.6.28.)
+
+If
+.B CLONE_NEWNET
+is set, then create the process in a new network namespace.
+If this flag is not set, then (as with
+.BR fork (2)),
+the process is created in the same network namespace as
+the calling process.
+This flag is intended for the implementation of containers.
+
+A network namespace provides an isolated view of the networking stack
+(network device interfaces, IPv4 and IPv6 protocol stacks,
+IP routing tables, firewall rules, the
+.I /proc/net
+and
+.I /sys/class/net
+directory trees, sockets, etc.).
+A physical network device can live in exactly one
+network namespace.
+A virtual network device ("veth") pair provides a pipe-like abstraction
+that can be used to create tunnels between network namespaces,
+and can be used to create a bridge to a physical network device
+in another namespace.
+
+Use of this flag requires: a kernel configured with the
+.B CONFIG_NET_NS
+option and that the process be privileged
+.TP
 .BR CLONE_NEWNS " (since Linux 2.4.19)"
 Start the child in a new mount namespace.
 
@@ -824,6 +854,14 @@ and
 options.
 .TP
 .B EINVAL
+.BR CLONE_NEWNET
+was specified in
+.IR flags ,
+but the kernel was not configured with the
+.B CONFIG_NET_NS
+option.
+.TP
+.B EINVAL
 .BR CLONE_NEWPID
 was specified in
 .IR flags ,
@@ -846,6 +884,7 @@ copied.
 .TP
 .B EPERM
 .BR CLONE_NEWIPC ,
+.BR CLONE_NEWNET ,
 .BR CLONE_NEWNS ,
 .BR CLONE_NEWPID ,
 or