ip-netns.8 (7254B)
- .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 "/run/netns/" NAME
- that can be opened. The file descriptor resulting from opening
- .BR "/run/netns/" 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 "/etc/netns/" 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 /etc/netns/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 /run/netns
- .TP
- .B ip netns add NAME - create a new named network namespace
- .sp
- If NAME is available in /run/netns 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 /run/netns 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 /run/netns 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 /run/netns 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 /run/netns) 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>