Debian Codegraph @

upstream/debian-unstable/man8/ip-netns.8

raw
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]>