man/man8/ip-netns.8

   1 .TH IP\-NETNS 8 "16 Jan 2013" "iproute2" "Linux"
   2 .SH NAME
   3 ip-netns \- process network namespace management
   4 .SH SYNOPSIS
   5 .sp
   6 .ad l
   7 .in +8
   8 .ti -8
   9 .B ip
  10 .RI "[ " OPTIONS " ]"
  11 .B netns
  12 .RI  " { " COMMAND " | "
  13 .BR help " }"
  14 .sp
  15 .ti -8
  16 .BR "ip netns" " [ " list " ]"
  17
  18 .ti -8
  19 .B ip netns add
  20 .I NETNSNAME
  21
  22 .ti -8
  23 .B ip [-all] netns del
  24 .RI "[ " NETNSNAME " ]"
  25
  26 .ti -8
  27 .B ip netns set
  28 .I NETNSNAME NETNSID
  29
  30 .ti -8
  31 .BR "ip netns identify"
  32 .RI "[ " PID " ]"
  33
  34 .ti -8
  35 .BR "ip netns pids"
  36 .I NETNSNAME
  37
  38 .ti -8
  39 .BR "ip [-all] netns exec "
  40 .RI "[ " NETNSNAME " ] " command ...
  41
  42 .ti -8
  43 .BR "ip netns monitor"
  44
  45 .ti -8
  46 .BR "ip netns list-id"
  47
  48 .SH DESCRIPTION
  49 A network namespace is logically another copy of the network stack,
  50 with its own routes, firewall rules, and network devices.
  51
  52 By default a process inherits its network namespace from its parent. Initially all
  53 the processes share the same default network namespace from the init process.
  54
  55 By convention a named network namespace is an object at
  56 .BR "/var/run/netns/" NAME
  57 that can be opened. The file descriptor resulting from opening
  58 .BR "/var/run/netns/" NAME
  59 refers to the specified network namespace. Holding that file
  60 descriptor open keeps the network namespace alive. The file
  61 descriptor can be used with the
  62 .B setns(2)
  63 system call to change the network namespace associated with a task.
  64
  65 For applications that are aware of network namespaces, the convention
  66 is to look for global network configuration files first in
  67 .BR "/etc/netns/" NAME "/"
  68 then in
  69 .BR "/etc/".
  70 For example, if you want a different version of
  71 .BR /etc/resolv.conf
  72 for a network namespace used to isolate your vpn you would name it
  73 .BR /etc/netns/myvpn/resolv.conf.
  74
  75 .B ip netns exec
  76 automates handling of this configuration, file convention for network
  77 namespace unaware applications, by creating a mount namespace and
  78 bind mounting all of the per network namespace configure files into
  79 their traditional location in /etc.
  80
  81 .TP
  82 .B ip netns list - show all of the named network namespaces
  83 .sp
  84 This command displays all of the network namespaces in /var/run/netns
  85
  86 .TP
  87 .B ip netns add NAME - create a new named network namespace
  88 .sp
  89 If NAME is available in /var/run/netns/ this command creates a new
  90 network namespace and assigns NAME.
  91
  92 .TP
  93 .B ip [-all] netns delete [ NAME ] - delete the name of a network namespace(s)
  94 .sp
  95 If NAME is present in /var/run/netns it is umounted and the mount
  96 point is removed. If this is the last user of the network namespace the
  97 network namespace will be freed and all physical devices will be moved to the
  98 default one, otherwise the network namespace persists until it has no more
  99 users. ip netns delete may fail if the mount point is in use in another mount
 100 namespace.
 101
 102 If
 103 .B -all
 104 option was specified then all the network namespace names will be removed.
 105
 106 It is possible to lose the physical device when it was moved to netns and
 107 then this netns was deleted with a running process:
 108
 109 .RS 10
 110 $ ip netns add net0
 111 .RE
 112 .RS 10
 113 $ ip link set dev eth0 netns net0
 114 .RE
 115 .RS 10
 116 $ ip netns exec net0 SOME_PROCESS_IN_BACKGROUND
 117 .RE
 118 .RS 10
 119 $ ip netns del net0
 120 .RE
 121
 122 .RS
 123 and eth0 will appear in the default netns only after SOME_PROCESS_IN_BACKGROUND
 124 will exit or will be killed. To prevent this the processes running in net0
 125 should be killed before deleting the netns:
 126
 127 .RE
 128 .RS 10
 129 $ ip netns pids net0 | xargs kill
 130 .RE
 131 .RS 10
 132 $ ip netns del net0
 133 .RE
 134
 135 .TP
 136 .B ip netns set NAME NETNSID - assign an id to a peer network namespace
 137 .sp
 138 This command assigns a id to a peer network namespace. This id is valid
 139 only in the current network namespace.
 140 If the keyword "auto" is specified an available nsid will be chosen.
 141 This id will be used by the kernel in some netlink messages. If no id is
 142 assigned when the kernel needs it, it will be automatically assigned by
 143 the kernel.
 144 Once it is assigned, it's not possible to change it.
 145
 146 .TP
 147 .B ip netns identify [PID] - Report network namespaces names for process
 148 .sp
 149 This command walks through /var/run/netns and finds all the network
 150 namespace names for network namespace of the specified process, if PID is
 151 not specified then the current process will be used.
 152
 153 .TP
 154 .B ip netns pids NAME - Report processes in the named network namespace
 155 .sp
 156 This command walks through proc and finds all of the process who have
 157 the named network namespace as their primary network namespace.
 158
 159 .TP
 160 .B ip [-all] netns exec [ NAME ] cmd ... - Run cmd in the named network namespace
 161 .sp
 162 This command allows applications that are network namespace unaware
 163 to be run in something other than the default network namespace with
 164 all of the configuration for the specified network namespace appearing
 165 in the customary global locations. A network namespace and bind mounts
 166 are used to move files from their network namespace specific location
 167 to their default locations without affecting other processes.
 168
 169 If
 170 .B -all
 171 option was specified then
 172 .B cmd
 173 will be executed synchronously on the each named network namespace even if
 174 .B cmd
 175 fails on some of them. Network namespace name is printed on each
 176 .B cmd
 177 executing.
 178
 179 .TP
 180 .B ip netns monitor - Report as network namespace names are added and deleted
 181 .sp
 182 This command watches network namespace name addition and deletion events
 183 and prints a line for each event it sees.
 184
 185 .TP
 186 .B ip netns list-id - list network namespace ids (nsid)
 187 .sp
 188 Network namespace ids are used to identify a peer network namespace. This
 189 command displays nsid of the current network namespace and provides the
 190 corresponding iproute2 netns name (from /var/run/netns) if any.
 191
 192 .SH EXAMPLES
 193 .PP
 194 ip netns list
 195 .RS
 196 Shows the list of current named network namespaces
 197 .RE
 198 .PP
 199 ip netns add vpn
 200 .RS
 201 Creates a network namespace and names it vpn
 202 .RE
 203 .PP
 204 ip netns exec vpn ip link set lo up
 205 .RS
 206 Bring up the loopback interface in the vpn network namespace.
 207 .RE
 208
 209 .SH SEE ALSO
 210 .br
 211 .BR ip (8)
 212
 213 .SH AUTHOR
 214 Original Manpage by Eric W. Biederman