]>
Commit | Line | Data |
---|---|---|
1e9014a7 | 1 | .TH IP\-NETNS 8 "16 Jan 2013" "iproute2" "Linux" |
2a9721f1 | 2 | .SH NAME |
aab2702d | 3 | ip-netns \- process network namespace management |
2a9721f1 SH |
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 | |
57e1ace0 | 16 | .BR "ip netns" " [ " list " ]" |
2a9721f1 SH |
17 | |
18 | .ti -8 | |
33724939 | 19 | .B ip netns add |
2a9721f1 SH |
20 | .I NETNSNAME |
21 | ||
33724939 VK |
22 | .ti -8 |
23 | .B ip [-all] netns del | |
24 | .RI "[ " NETNSNAME " ]" | |
25 | ||
d182ee13 | 26 | .ti -8 |
57e1ace0 | 27 | .B ip netns set |
d182ee13 ND |
28 | .I NETNSNAME NETNSID |
29 | ||
9a7b3d91 EB |
30 | .ti -8 |
31 | .BR "ip netns identify" | |
0948adc0 | 32 | .RI "[ " PID " ]" |
9a7b3d91 EB |
33 | |
34 | .ti -8 | |
35 | .BR "ip netns pids" | |
36 | .I NETNSNAME | |
37 | ||
2a9721f1 | 38 | .ti -8 |
b13ba03f VK |
39 | .BR "ip [-all] netns exec " |
40 | .RI "[ " NETNSNAME " ] " command ... | |
2a9721f1 | 41 | |
1e9014a7 EB |
42 | .ti -8 |
43 | .BR "ip netns monitor" | |
44 | ||
d652ccbf ND |
45 | .ti -8 |
46 | .BR "ip netns list-id" | |
47 | ||
2a9721f1 SH |
48 | .SH DESCRIPTION |
49 | A network namespace is logically another copy of the network stack, | |
cc574302 | 50 | with its own routes, firewall rules, and network devices. |
2a9721f1 | 51 | |
599fc319 | 52 | By default a process inherits its network namespace from its parent. Initially all |
ee9b3477 VK |
53 | the processes share the same default network namespace from the init process. |
54 | ||
2a9721f1 SH |
55 | By convention a named network namespace is an object at |
56 | .BR "/var/run/netns/" NAME | |
a89d5329 | 57 | that can be opened. The file descriptor resulting from opening |
2a9721f1 | 58 | .BR "/var/run/netns/" NAME |
a89d5329 PŠ |
59 | refers to the specified network namespace. Holding that file |
60 | descriptor open keeps the network namespace alive. The file | |
2a9721f1 SH |
61 | descriptor can be used with the |
62 | .B setns(2) | |
63 | system call to change the network namespace associated with a task. | |
64 | ||
49572501 KR |
65 | For applications that are aware of network namespaces, the convention |
66 | is to look for global network configuration files first in | |
2a9721f1 SH |
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 | ||
61f541fe | 81 | .TP |
82 | .B ip netns list - show all of the named network namespaces | |
83 | .sp | |
1e9014a7 EB |
84 | This command displays all of the network namespaces in /var/run/netns |
85 | ||
61f541fe | 86 | .TP |
87 | .B ip netns add NAME - create a new named network namespace | |
88 | .sp | |
1e9014a7 EB |
89 | If NAME is available in /var/run/netns/ this command creates a new |
90 | network namespace and assigns NAME. | |
91 | ||
61f541fe | 92 | .TP |
33724939 | 93 | .B ip [-all] netns delete [ NAME ] - delete the name of a network namespace(s) |
61f541fe | 94 | .sp |
1e9014a7 | 95 | If NAME is present in /var/run/netns it is umounted and the mount |
a89d5329 | 96 | point is removed. If this is the last user of the network namespace the |
ee9b3477 VK |
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. | |
1e9014a7 | 101 | |
33724939 VK |
102 | If |
103 | .B -all | |
104 | option was specified then all the network namespace names will be removed. | |
105 | ||
ee9b3477 VK |
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 | ||
599fc319 VK |
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 | |
ee9b3477 | 121 | |
bbf2f7c6 | 122 | .RS |
ee9b3477 VK |
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 | ||
bbf2f7c6 VK |
127 | .RE |
128 | .RS 10 | |
129 | $ ip netns pids net0 | xargs kill | |
130 | .RE | |
131 | .RS 10 | |
132 | $ ip netns del net0 | |
133 | .RE | |
ee9b3477 | 134 | |
d182ee13 ND |
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. | |
375d51ca | 140 | If the keyword "auto" is specified an available nsid will be chosen. |
d182ee13 ND |
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 | ||
61f541fe | 146 | .TP |
0948adc0 | 147 | .B ip netns identify [PID] - Report network namespaces names for process |
61f541fe | 148 | .sp |
9a7b3d91 | 149 | This command walks through /var/run/netns and finds all the network |
0948adc0 | 150 | namespace names for network namespace of the specified process, if PID is |
151 | not specified then the current process will be used. | |
9a7b3d91 | 152 | |
61f541fe | 153 | .TP |
154 | .B ip netns pids NAME - Report processes in the named network namespace | |
155 | .sp | |
9a7b3d91 EB |
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 | ||
61f541fe | 159 | .TP |
b13ba03f | 160 | .B ip [-all] netns exec [ NAME ] cmd ... - Run cmd in the named network namespace |
61f541fe | 161 | .sp |
1e9014a7 EB |
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 | |
a89d5329 | 165 | in the customary global locations. A network namespace and bind mounts |
1e9014a7 EB |
166 | are used to move files from their network namespace specific location |
167 | to their default locations without affecting other processes. | |
168 | ||
b13ba03f VK |
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 | ||
61f541fe | 179 | .TP |
180 | .B ip netns monitor - Report as network namespace names are added and deleted | |
181 | .sp | |
1e9014a7 EB |
182 | This command watches network namespace name addition and deletion events |
183 | and prints a line for each event it sees. | |
184 | ||
d652ccbf ND |
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 | ||
2a9721f1 | 192 | .SH EXAMPLES |
1e9014a7 EB |
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 | |
2a9721f1 SH |
208 | |
209 | .SH SEE ALSO | |
210 | .br | |
211 | .BR ip (8) | |
212 | ||
213 | .SH AUTHOR | |
214 | Original Manpage by Eric W. Biederman |