Eric W. Biederman | 1e9014a | 2013-01-17 14:47:47 +0000 | [diff] [blame] | 1 | .TH IP\-NETNS 8 "16 Jan 2013" "iproute2" "Linux" |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 2 | .SH NAME |
Stephen Hemminger | aab2702 | 2012-01-10 10:47:28 -0800 | [diff] [blame] | 3 | ip-netns \- process network namespace management |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 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 |
Phil Sutter | 57e1ace | 2016-03-02 19:20:00 +0100 | [diff] [blame] | 16 | .BR "ip netns" " [ " list " ]" |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 17 | |
| 18 | .ti -8 |
Vadim Kochan | 3372493 | 2015-01-18 16:10:19 +0200 | [diff] [blame] | 19 | .B ip netns add |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 20 | .I NETNSNAME |
| 21 | |
| 22 | .ti -8 |
Vadim Kochan | 3372493 | 2015-01-18 16:10:19 +0200 | [diff] [blame] | 23 | .B ip [-all] netns del |
| 24 | .RI "[ " NETNSNAME " ]" |
| 25 | |
| 26 | .ti -8 |
Phil Sutter | 57e1ace | 2016-03-02 19:20:00 +0100 | [diff] [blame] | 27 | .B ip netns set |
Nicolas Dichtel | d182ee1 | 2015-02-17 17:30:37 +0100 | [diff] [blame] | 28 | .I NETNSNAME NETNSID |
| 29 | |
| 30 | .ti -8 |
Eric W. Biederman | 9a7b3d9 | 2013-01-17 14:48:15 +0000 | [diff] [blame] | 31 | .BR "ip netns identify" |
vadimk | 0948adc | 2014-11-07 18:25:30 +0200 | [diff] [blame] | 32 | .RI "[ " PID " ]" |
Eric W. Biederman | 9a7b3d9 | 2013-01-17 14:48:15 +0000 | [diff] [blame] | 33 | |
| 34 | .ti -8 |
| 35 | .BR "ip netns pids" |
| 36 | .I NETNSNAME |
| 37 | |
| 38 | .ti -8 |
Vadim Kochan | b13ba03 | 2015-01-18 16:10:18 +0200 | [diff] [blame] | 39 | .BR "ip [-all] netns exec " |
| 40 | .RI "[ " NETNSNAME " ] " command ... |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 41 | |
Eric W. Biederman | 1e9014a | 2013-01-17 14:47:47 +0000 | [diff] [blame] | 42 | .ti -8 |
| 43 | .BR "ip netns monitor" |
| 44 | |
Nicolas Dichtel | d652ccb | 2015-04-15 14:23:22 +0200 | [diff] [blame] | 45 | .ti -8 |
| 46 | .BR "ip netns list-id" |
| 47 | |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 48 | .SH DESCRIPTION |
| 49 | A network namespace is logically another copy of the network stack, |
Stephen Hemminger | cc57430 | 2012-11-12 08:05:45 -0800 | [diff] [blame] | 50 | with its own routes, firewall rules, and network devices. |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 51 | |
Vadim Kochan | 599fc31 | 2015-03-24 11:41:52 +0200 | [diff] [blame] | 52 | By default a process inherits its network namespace from its parent. Initially all |
Vadim Kochan | ee9b347 | 2015-03-15 17:49:16 +0200 | [diff] [blame] | 53 | the processes share the same default network namespace from the init process. |
| 54 | |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 55 | By convention a named network namespace is an object at |
| 56 | .BR "/var/run/netns/" NAME |
Pavel Šimerda | a89d532 | 2015-04-07 08:41:36 -0700 | [diff] [blame] | 57 | that can be opened. The file descriptor resulting from opening |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 58 | .BR "/var/run/netns/" NAME |
Pavel Šimerda | a89d532 | 2015-04-07 08:41:36 -0700 | [diff] [blame] | 59 | refers to the specified network namespace. Holding that file |
| 60 | descriptor open keeps the network namespace alive. The file |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 61 | descriptor can be used with the |
| 62 | .B setns(2) |
| 63 | system call to change the network namespace associated with a task. |
| 64 | |
Kees van Reeuwijk | 4957250 | 2013-02-08 03:32:36 +0000 | [diff] [blame] | 65 | For applications that are aware of network namespaces, the convention |
| 66 | is to look for global network configuration files first in |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 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 | |
esr@thyrsus.com | 61f541f | 2013-06-21 15:57:21 -0400 | [diff] [blame] | 81 | .TP |
| 82 | .B ip netns list - show all of the named network namespaces |
| 83 | .sp |
Eric W. Biederman | 1e9014a | 2013-01-17 14:47:47 +0000 | [diff] [blame] | 84 | This command displays all of the network namespaces in /var/run/netns |
| 85 | |
esr@thyrsus.com | 61f541f | 2013-06-21 15:57:21 -0400 | [diff] [blame] | 86 | .TP |
| 87 | .B ip netns add NAME - create a new named network namespace |
| 88 | .sp |
Eric W. Biederman | 1e9014a | 2013-01-17 14:47:47 +0000 | [diff] [blame] | 89 | If NAME is available in /var/run/netns/ this command creates a new |
| 90 | network namespace and assigns NAME. |
| 91 | |
esr@thyrsus.com | 61f541f | 2013-06-21 15:57:21 -0400 | [diff] [blame] | 92 | .TP |
Vadim Kochan | 3372493 | 2015-01-18 16:10:19 +0200 | [diff] [blame] | 93 | .B ip [-all] netns delete [ NAME ] - delete the name of a network namespace(s) |
esr@thyrsus.com | 61f541f | 2013-06-21 15:57:21 -0400 | [diff] [blame] | 94 | .sp |
Eric W. Biederman | 1e9014a | 2013-01-17 14:47:47 +0000 | [diff] [blame] | 95 | If NAME is present in /var/run/netns it is umounted and the mount |
Pavel Šimerda | a89d532 | 2015-04-07 08:41:36 -0700 | [diff] [blame] | 96 | point is removed. If this is the last user of the network namespace the |
Vadim Kochan | ee9b347 | 2015-03-15 17:49:16 +0200 | [diff] [blame] | 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. |
Eric W. Biederman | 1e9014a | 2013-01-17 14:47:47 +0000 | [diff] [blame] | 101 | |
Vadim Kochan | 3372493 | 2015-01-18 16:10:19 +0200 | [diff] [blame] | 102 | If |
| 103 | .B -all |
| 104 | option was specified then all the network namespace names will be removed. |
| 105 | |
Vadim Kochan | ee9b347 | 2015-03-15 17:49:16 +0200 | [diff] [blame] | 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 | |
Vadim Kochan | 599fc31 | 2015-03-24 11:41:52 +0200 | [diff] [blame] | 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 |
Vadim Kochan | ee9b347 | 2015-03-15 17:49:16 +0200 | [diff] [blame] | 121 | |
Vadim Kochan | bbf2f7c | 2015-04-02 18:08:03 +0300 | [diff] [blame] | 122 | .RS |
Vadim Kochan | ee9b347 | 2015-03-15 17:49:16 +0200 | [diff] [blame] | 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 | |
Vadim Kochan | bbf2f7c | 2015-04-02 18:08:03 +0300 | [diff] [blame] | 127 | .RE |
| 128 | .RS 10 |
| 129 | $ ip netns pids net0 | xargs kill |
| 130 | .RE |
| 131 | .RS 10 |
| 132 | $ ip netns del net0 |
| 133 | .RE |
Vadim Kochan | ee9b347 | 2015-03-15 17:49:16 +0200 | [diff] [blame] | 134 | |
esr@thyrsus.com | 61f541f | 2013-06-21 15:57:21 -0400 | [diff] [blame] | 135 | .TP |
Nicolas Dichtel | d182ee1 | 2015-02-17 17:30:37 +0100 | [diff] [blame] | 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 | This id will be used by the kernel in some netlink messages. If no id is |
| 141 | assigned when the kernel needs it, it will be automatically assigned by |
| 142 | the kernel. |
| 143 | Once it is assigned, it's not possible to change it. |
| 144 | |
| 145 | .TP |
vadimk | 0948adc | 2014-11-07 18:25:30 +0200 | [diff] [blame] | 146 | .B ip netns identify [PID] - Report network namespaces names for process |
esr@thyrsus.com | 61f541f | 2013-06-21 15:57:21 -0400 | [diff] [blame] | 147 | .sp |
Eric W. Biederman | 9a7b3d9 | 2013-01-17 14:48:15 +0000 | [diff] [blame] | 148 | This command walks through /var/run/netns and finds all the network |
vadimk | 0948adc | 2014-11-07 18:25:30 +0200 | [diff] [blame] | 149 | namespace names for network namespace of the specified process, if PID is |
| 150 | not specified then the current process will be used. |
Eric W. Biederman | 9a7b3d9 | 2013-01-17 14:48:15 +0000 | [diff] [blame] | 151 | |
esr@thyrsus.com | 61f541f | 2013-06-21 15:57:21 -0400 | [diff] [blame] | 152 | .TP |
| 153 | .B ip netns pids NAME - Report processes in the named network namespace |
| 154 | .sp |
Eric W. Biederman | 9a7b3d9 | 2013-01-17 14:48:15 +0000 | [diff] [blame] | 155 | This command walks through proc and finds all of the process who have |
| 156 | the named network namespace as their primary network namespace. |
| 157 | |
esr@thyrsus.com | 61f541f | 2013-06-21 15:57:21 -0400 | [diff] [blame] | 158 | .TP |
Vadim Kochan | b13ba03 | 2015-01-18 16:10:18 +0200 | [diff] [blame] | 159 | .B ip [-all] netns exec [ NAME ] cmd ... - Run cmd in the named network namespace |
esr@thyrsus.com | 61f541f | 2013-06-21 15:57:21 -0400 | [diff] [blame] | 160 | .sp |
Eric W. Biederman | 1e9014a | 2013-01-17 14:47:47 +0000 | [diff] [blame] | 161 | This command allows applications that are network namespace unaware |
| 162 | to be run in something other than the default network namespace with |
| 163 | all of the configuration for the specified network namespace appearing |
Pavel Šimerda | a89d532 | 2015-04-07 08:41:36 -0700 | [diff] [blame] | 164 | in the customary global locations. A network namespace and bind mounts |
Eric W. Biederman | 1e9014a | 2013-01-17 14:47:47 +0000 | [diff] [blame] | 165 | are used to move files from their network namespace specific location |
| 166 | to their default locations without affecting other processes. |
| 167 | |
Vadim Kochan | b13ba03 | 2015-01-18 16:10:18 +0200 | [diff] [blame] | 168 | If |
| 169 | .B -all |
| 170 | option was specified then |
| 171 | .B cmd |
| 172 | will be executed synchronously on the each named network namespace even if |
| 173 | .B cmd |
| 174 | fails on some of them. Network namespace name is printed on each |
| 175 | .B cmd |
| 176 | executing. |
| 177 | |
esr@thyrsus.com | 61f541f | 2013-06-21 15:57:21 -0400 | [diff] [blame] | 178 | .TP |
| 179 | .B ip netns monitor - Report as network namespace names are added and deleted |
| 180 | .sp |
Eric W. Biederman | 1e9014a | 2013-01-17 14:47:47 +0000 | [diff] [blame] | 181 | This command watches network namespace name addition and deletion events |
| 182 | and prints a line for each event it sees. |
| 183 | |
Nicolas Dichtel | d652ccb | 2015-04-15 14:23:22 +0200 | [diff] [blame] | 184 | .TP |
| 185 | .B ip netns list-id - list network namespace ids (nsid) |
| 186 | .sp |
| 187 | Network namespace ids are used to identify a peer network namespace. This |
| 188 | command displays nsid of the current network namespace and provides the |
| 189 | corresponding iproute2 netns name (from /var/run/netns) if any. |
| 190 | |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 191 | .SH EXAMPLES |
Eric W. Biederman | 1e9014a | 2013-01-17 14:47:47 +0000 | [diff] [blame] | 192 | .PP |
| 193 | ip netns list |
| 194 | .RS |
| 195 | Shows the list of current named network namespaces |
| 196 | .RE |
| 197 | .PP |
| 198 | ip netns add vpn |
| 199 | .RS |
| 200 | Creates a network namespace and names it vpn |
| 201 | .RE |
| 202 | .PP |
| 203 | ip netns exec vpn ip link set lo up |
| 204 | .RS |
| 205 | Bring up the loopback interface in the vpn network namespace. |
| 206 | .RE |
Stephen Hemminger | 2a9721f | 2011-12-22 10:34:03 -0800 | [diff] [blame] | 207 | |
| 208 | .SH SEE ALSO |
| 209 | .br |
| 210 | .BR ip (8) |
| 211 | |
| 212 | .SH AUTHOR |
| 213 | Original Manpage by Eric W. Biederman |