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