summaryrefslogtreecommitdiffstats
path: root/man/man8/ip-netns.8.in
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man/man8/ip-netns.8.in271
1 files changed, 271 insertions, 0 deletions
diff --git a/man/man8/ip-netns.8.in b/man/man8/ip-netns.8.in
new file mode 100644
index 0000000..2911bdd
--- /dev/null
+++ b/man/man8/ip-netns.8.in
@@ -0,0 +1,271 @@
+.TH IP\-NETNS 8 "16 Jan 2013" "iproute2" "Linux"
+.SH NAME
+ip-netns \- process network namespace management
+.SH SYNOPSIS
+.sp
+.ad l
+.in +8
+.ti -8
+.B ip
+.RI "[ " OPTIONS " ]"
+.B netns
+.RI " { " COMMAND " | "
+.BR help " }"
+.sp
+.ti -8
+.BR "ip netns" " [ " list " ]"
+
+.ti -8
+.B ip netns add
+.I NETNSNAME
+
+.ti -8
+.B ip netns attach
+.I NETNSNAME PID
+
+.ti -8
+.B ip [-all] netns del
+.RI "[ " NETNSNAME " ]"
+
+.ti -8
+.B ip netns set
+.I NETNSNAME NETNSID
+
+.ti -8
+.IR NETNSID " := " auto " | " POSITIVE-INT
+
+.ti -8
+.BR "ip netns identify"
+.RI "[ " PID " ]"
+
+.ti -8
+.BR "ip netns pids"
+.I NETNSNAME
+
+.ti -8
+.BR "ip [-all] netns exec "
+.RI "[ " NETNSNAME " ] " command ...
+
+.ti -8
+.BR "ip netns monitor"
+
+.ti -8
+.BR "ip netns list-id"
+.RI "[ target-nsid " POSITIVE-INT " ] [ nsid " POSITIVE-INT " ]"
+
+.SH DESCRIPTION
+A network namespace is logically another copy of the network stack,
+with its own routes, firewall rules, and network devices.
+
+By default a process inherits its network namespace from its parent. Initially all
+the processes share the same default network namespace from the init process.
+
+By convention a named network namespace is an object at
+.BR "@NETNS_RUN_DIR@/" NAME
+that can be opened. The file descriptor resulting from opening
+.BR "@NETNS_RUN_DIR@/" NAME
+refers to the specified network namespace. Holding that file
+descriptor open keeps the network namespace alive. The file
+descriptor can be used with the
+.B setns(2)
+system call to change the network namespace associated with a task.
+
+For applications that are aware of network namespaces, the convention
+is to look for global network configuration files first in
+.BR "@NETNS_ETC_DIR@/" NAME "/"
+then in
+.BR "/etc/".
+For example, if you want a different version of
+.BR /etc/resolv.conf
+for a network namespace used to isolate your vpn you would name it
+.BR @NETNS_ETC_DIR@/myvpn/resolv.conf.
+
+.B ip netns exec
+automates handling of this configuration, file convention for network
+namespace unaware applications, by creating a mount namespace and
+bind mounting all of the per network namespace configure files into
+their traditional location in /etc.
+
+.TP
+.B ip netns list - show all of the named network namespaces
+.sp
+This command displays all of the network namespaces in @NETNS_RUN_DIR@
+
+.TP
+.B ip netns add NAME - create a new named network namespace
+.sp
+If NAME is available in @NETNS_RUN_DIR@ this command creates a new
+network namespace and assigns NAME.
+
+.TP
+.B ip netns attach NAME PID - create a new named network namespace
+.sp
+If NAME is available in @NETNS_RUN_DIR@ this command attaches the network
+namespace of the process PID to NAME as if it were created with ip netns.
+
+.TP
+.B ip [-all] netns delete [ NAME ] - delete the name of a network namespace(s)
+.sp
+If NAME is present in @NETNS_RUN_DIR@ it is umounted and the mount
+point is removed. If this is the last user of the network namespace the
+network namespace will be freed and all physical devices will be moved to the
+default one, otherwise the network namespace persists until it has no more
+users. ip netns delete may fail if the mount point is in use in another mount
+namespace.
+
+If
+.B -all
+option was specified then all the network namespace names will be removed.
+
+It is possible to lose the physical device when it was moved to netns and
+then this netns was deleted with a running process:
+
+.RS 10
+$ ip netns add net0
+.RE
+.RS 10
+$ ip link set dev eth0 netns net0
+.RE
+.RS 10
+$ ip netns exec net0 SOME_PROCESS_IN_BACKGROUND
+.RE
+.RS 10
+$ ip netns del net0
+.RE
+
+.RS
+and eth0 will appear in the default netns only after SOME_PROCESS_IN_BACKGROUND
+will exit or will be killed. To prevent this the processes running in net0
+should be killed before deleting the netns:
+
+.RE
+.RS 10
+$ ip netns pids net0 | xargs kill
+.RE
+.RS 10
+$ ip netns del net0
+.RE
+
+.TP
+.B ip netns set NAME NETNSID - assign an id to a peer network namespace
+.sp
+This command assigns a id to a peer network namespace. This id is valid
+only in the current network namespace.
+If the keyword "auto" is specified an available nsid will be chosen.
+This id will be used by the kernel in some netlink messages. If no id is
+assigned when the kernel needs it, it will be automatically assigned by
+the kernel.
+Once it is assigned, it's not possible to change it.
+
+.TP
+.B ip netns identify [PID] - Report network namespaces names for process
+.sp
+This command walks through @NETNS_RUN_DIR@ and finds all the network
+namespace names for network namespace of the specified process, if PID is
+not specified then the current process will be used.
+
+.TP
+.B ip netns pids NAME - Report processes in the named network namespace
+.sp
+This command walks through proc and finds all of the process who have
+the named network namespace as their primary network namespace.
+
+.TP
+.B ip [-all] netns exec [ NAME ] cmd ... - Run cmd in the named network namespace
+.sp
+This command allows applications that are network namespace unaware
+to be run in something other than the default network namespace with
+all of the configuration for the specified network namespace appearing
+in the customary global locations. A network namespace and bind mounts
+are used to move files from their network namespace specific location
+to their default locations without affecting other processes.
+
+If
+.B -all
+option was specified then
+.B cmd
+will be executed synchronously on the each named network namespace even if
+.B cmd
+fails on some of them. Network namespace name is printed on each
+.B cmd
+executing.
+
+.TP
+.B ip netns monitor - Report as network namespace names are added and deleted
+.sp
+This command watches network namespace name addition and deletion events
+and prints a line for each event it sees.
+
+.TP
+.B ip netns list-id [target-nsid POSITIVE-INT] [nsid POSITIVE-INT] - list network namespace ids (nsid)
+.sp
+Network namespace ids are used to identify a peer network namespace. This
+command displays nsids of the current network namespace and provides the
+corresponding iproute2 netns name (from @NETNS_RUN_DIR@) if any.
+
+The
+.B target-nsid
+option enables to display nsids of the specified network namespace instead of the current network
+namespace. This
+.B target-nsid
+is a nsid from the current network namespace.
+
+The
+.B nsid
+option enables to display only this nsid. It is a nsid from the current network namespace. In
+combination with the
+.B target-nsid
+option, it enables to convert a specific nsid from the current network namespace to a nsid of the
+.B target-nsid
+network namespace.
+
+.SH EXAMPLES
+.PP
+ip netns list
+.RS
+Shows the list of current named network namespaces
+.RE
+.PP
+ip netns add vpn
+.RS
+Creates a network namespace and names it vpn
+.RE
+.PP
+ip netns exec vpn ip link set lo up
+.RS
+Bring up the loopback interface in the vpn network namespace.
+.RE
+.PP
+ip netns add foo
+.br
+ip netns add bar
+.br
+ip netns set foo 12
+.br
+ip netns set bar 13
+.br
+ip -n foo netns set foo 22
+.br
+ip -n foo netns set bar 23
+.br
+ip -n bar netns set foo 32
+.br
+ip -n bar netns set bar 33
+.br
+ip netns list-id target-nsid 12
+.RS
+Shows the list of nsids from the network namespace foo.
+.RE
+ip netns list-id target-nsid 12 nsid 13
+.RS
+Get nsid of bar from the network namespace foo (result is 23).
+.RE
+
+.SH SEE ALSO
+.br
+.BR ip (8)
+
+.SH AUTHOR
+Original Manpage by Eric W. Biederman
+.br
+Manpage revised by Nicolas Dichtel <nicolas.dichtel@6wind.com>