diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-04 14:18:53 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-04 14:18:53 +0000 |
commit | a0e0018c9a7ef5ce7f6d2c3ae16aecbbd16a8f67 (patch) | |
tree | 8feaf1a1932871b139b3b30be4c09c66489918be /man/man8/ip-netns.8.in | |
parent | Initial commit. (diff) | |
download | iproute2-upstream/6.1.0.tar.xz iproute2-upstream/6.1.0.zip |
Adding upstream version 6.1.0.upstream/6.1.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | man/man8/ip-netns.8.in | 271 |
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> |