Debian Codegraph @

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

raw
1 .TH "IP\-ADDRESS" 8 "20 Dec 2011" "iproute2" "Linux"
2 .SH "NAME"
3 ip-address \- protocol address management
4 .SH "SYNOPSIS"
5 .sp
6 .ad l
7 .in +8
8 .ti -8
9 .B ip
10 .RI "[ " OPTIONS " ]"
11 .B address
12 .RI " { " COMMAND " | "
13 .BR help " }"
14 .sp
15
16 .ti -8
17 .BR "ip address" " { " add " | " change " | " replace " } "
18 .IB IFADDR " dev " IFNAME
19 .RI "[ " LIFETIME " ] [ " CONFFLAG-LIST " ]"
20
21 .ti -8
22 .BR "ip address delete"
23 .IB IFADDR " dev " IFNAME " [ " mngtmpaddr " ]"
24
25 .ti -8
26 .BR "ip address" " { " save " | " flush " } [ " dev
27 .IR IFNAME " ] [ "
28 .B scope
29 .IR SCOPE-ID " ] [ "
30 .B metric
31 .IR METRIC " ] [ "
32 .B to
33 .IR PREFIX " ] [ " FLAG-LIST " ] [ "
34 .B label
35 .IR PATTERN " ] [ { " up " | " down " } ]"
36
37 .ti -8
38 .BR "ip address" " [ " show " [ " dev
39 .IR IFNAME " ] [ "
40 .B scope
41 .IR SCOPE-ID " ] [ "
42 .B to
43 .IR PREFIX " ] [ " FLAG-LIST " ] [ "
44 .B label
45 .IR PATTERN " ] [ "
46 .B master
47 .IR DEVICE " ] [ "
48 .B type
49 .IR TYPE " ] [ "
50 .B vrf
51 .IR NAME " ] [ { "
52 .BR up " | " down " } ] ["
53 .BR nomaster " ]"
54 .B proto
55 .IR ADDRPROTO " ] ]"
56
57 .ti -8
58 .BR "ip address" " { " showdump " | " restore " }"
59
60 .ti -8
61 .IR IFADDR " := " PREFIX " | " ADDR
62 .B peer
63 .IR PREFIX " [ "
64 .B broadcast
65 .IR ADDR " ] [ "
66 .B anycast
67 .IR ADDR " ] [ "
68 .B label
69 .IR LABEL " ] [ "
70 .B scope
71 .IR SCOPE-ID " ] [ "
72 .B proto
73 .IR ADDRPROTO " ]"
74
75 .ti -8
76 .IR SCOPE-ID " := "
77 .RB "[ " host " | " link " | " global " | "
78 .IR NUMBER " ]"
79
80 .ti -8
81 .IR ADDRPROTO " := [ "
82 .IR NAME " | " NUMBER " ]"
83
84 .ti -8
85 .IR FLAG-LIST " := [ " FLAG-LIST " ] " FLAG
86
87 .ti -8
88 .IR FLAG " := ["
89 .RB [ - ] permanent " |"
90 .RB [ - ] dynamic " |"
91 .RB [ - ] secondary " |"
92 .RB [ - ] primary " |"
93 .RB [ - ] tentative " |"
94 .RB [ - ] deprecated " |"
95 .RB [ - ] dadfailed " |"
96 .RB [ - ] temporary " |"
97 .IR CONFFLAG-LIST " ]"
98
99 .ti -8
100 .IR CONFFLAG-LIST " := [ " CONFFLAG-LIST " ] " CONFFLAG
101
102 .ti -8
103 .IR CONFFLAG " := "
104 .RB "[ " home " | " mngtmpaddr " | " nodad " | " optimistic " | " noprefixroute " | " autojoin " ]"
105
106 .ti -8
107 .IR LIFETIME " := [ "
108 .BI valid_lft " LFT"
109 .RB "] [ " preferred_lft
110 .IR LFT " ]"
111
112 .ti -8
113 .IR LFT " := [ "
114 .BR forever " |"
115 .IR SECONDS " ]"
116
117 .ti -8
118 .IR TYPE " := [ "
119 .BR bridge " | "
120 .BR bridge_slave " |"
121 .BR bond " | "
122 .BR bond_slave " |"
123 .BR can " | "
124 .BR dummy " | "
125 .BR hsr " | "
126 .BR ifb " | "
127 .BR ipoib " |"
128 .BR macvlan " | "
129 .BR macvtap " | "
130 .BR vcan " | "
131 .BR veth " | "
132 .BR vlan " | "
133 .BR vxlan " |"
134 .BR ip6tnl " |"
135 .BR ipip " |"
136 .BR sit " |"
137 .BR gre " |"
138 .BR gretap " |"
139 .BR erspan " |"
140 .BR ip6gre " |"
141 .BR ip6gretap " |"
142 .BR ip6erspan " |"
143 .BR vti " |"
144 .BR vrf " |"
145 .BR nlmon " |"
146 .BR ipvlan " |"
147 .BR lowpan " |"
148 .BR geneve " |"
149 .BR macsec " |"
150 .BR netkit " ]"
151
152 .SH "DESCRIPTION"
153 The
154 .B address
155 is a protocol (IPv4 or IPv6) address attached
156 to a network device. Each device must have at least one address
157 to use the corresponding protocol. It is possible to have several
158 different addresses attached to one device. These addresses are not
159 discriminated, so that the term
160 .B alias
161 is not quite appropriate for them and we do not use it in this document.
162 .sp
163 The
164 .B ip address
165 command displays addresses and their properties, adds new addresses
166 and deletes old ones.
167
168 .SS ip address add - add new protocol address.
169
170 .TP
171 .BI dev " IFNAME "
172 the name of the device to add the address to.
173
174 .TP
175 .BI local " ADDRESS " (default)
176 the address of the interface. The format of the address depends
177 on the protocol. It is a dotted quad for IP and a sequence of
178 hexadecimal halfwords separated by colons for IPv6. The
179 .I ADDRESS
180 may be followed by a slash and a decimal number which encodes
181 the network prefix length.
182
183 .TP
184 .BI peer " ADDRESS"
185 the address of the remote endpoint for pointopoint interfaces.
186 Again, the
187 .I ADDRESS
188 may be followed by a slash and a decimal number, encoding the network
189 prefix length. If a peer address is specified, the local address
190 cannot have a prefix length. The network prefix is associated
191 with the peer rather than with the local address.
192
193 .TP
194 .BI broadcast " ADDRESS"
195 the broadcast address on the interface.
196 .sp
197 It is possible to use the special symbols
198 .B '+'
199 and
200 .B '-'
201 instead of the broadcast address. In this case, the broadcast address
202 is derived by setting/resetting the host bits of the interface prefix.
203
204 .TP
205 .BI label " LABEL"
206 Each address may be tagged with a label string.
207 The maximum allowed total length of label is 15 characters.
208
209 .TP
210 .BI scope " SCOPE_VALUE"
211 the scope of the area where this address is valid.
212 The available scopes are listed in
213 .BR /usr/share/iproute2/rt_scopes " or " /etc/iproute2/rt_scopes
214 (has precedence if exists).
215 Predefined scope values are:
216
217 .in +8
218 .B global
219 - the address is globally valid.
220 .sp
221 .B site
222 - (IPv6 only, deprecated) the address is site local, i.e. it is
223 valid inside this site.
224 .sp
225 .B link
226 - the address is link local, i.e. it is valid only on this device.
227 .sp
228 .B host
229 - the address is valid only inside this host.
230 .in -8
231
232 .TP
233 .BI metric " NUMBER"
234 priority of prefix route associated with address.
235
236 .TP
237 .BI valid_lft " LFT"
238 the valid lifetime of this address; see section 5.5.4 of
239 RFC 4862. When it expires, the address is removed by the kernel.
240 Defaults to
241 .BR "forever" .
242
243 .TP
244 .BI preferred_lft " LFT"
245 the preferred lifetime of this address; see section 5.5.4
246 of RFC 4862. When it expires, the address is no longer used for new
247 outgoing connections. Defaults to
248 .BR "forever" .
249
250 .TP
251 .B home
252 (IPv6 only) designates this address the "home address" as defined in
253 RFC 6275.
254
255 .TP
256 .B mngtmpaddr
257 (IPv6 only) make the kernel manage temporary addresses created from this one as
258 template on behalf of Privacy Extensions (RFC3041). For this to become active,
259 the \fBuse_tempaddr\fP sysctl setting has to be set to a value greater than
260 zero. The given address needs to have a prefix length of 64. This flag allows
261 to use privacy extensions in a manually configured network, just like if
262 stateless auto-configuration was active.
263
264 .TP
265 .B nodad
266 (IPv6 only) do not perform Duplicate Address Detection (RFC 4862) when
267 adding this address.
268
269 .TP
270 .B optimistic
271 (IPv6 only) When performing Duplicate Address Detection, use the RFC 4429
272 optimistic variant.
273
274 .TP
275 .B noprefixroute
276 Do not automatically create a route for the network prefix of the added
277 address, and don't search for one to delete when removing the address. Changing
278 an address to add this flag will remove the automatically added prefix route,
279 changing it to remove this flag will create the prefix route automatically.
280
281 .TP
282 .B autojoin
283 Joining multicast groups on Ethernet level via
284 .B "ip maddr"
285 command does not work if connected to an Ethernet switch that does IGMP
286 snooping since the switch would not replicate multicast packets on ports that
287 did not have IGMP reports for the multicast addresses.
288
289 Linux VXLAN interfaces created via
290 .B "ip link add vxlan"
291 have the
292 .B group
293 option that enables them to do the required join.
294
295 Using the
296 .B autojoin
297 flag when adding a multicast address enables similar functionality for
298 Openvswitch VXLAN interfaces as well as other tunneling mechanisms that need to
299 receive multicast traffic.
300
301 .TP
302 .BI proto " ADDRPROTO"
303 the protocol identifier of this route.
304 .I ADDRPROTO
305 may be a number or a string from the file
306 .BR /usr/share/iproute2/rt_addrprotos " or " /etc/iproute2/rt_addrprotos
307 (has precedence if exists). A directory named
308 .BR rt_addrprotos.d
309 is also scanned in either location.
310 If the protocol ID is not given,
311
312 .B ip assumes protocol 0. Several protocol
313 values have a fixed interpretation. Namely:
314
315 .in +8
316 .B kernel_lo
317 - The ::1 address that kernel installs on a loopback netdevice has this
318 protocol value
319 .sp
320
321 .B kernel_ra
322 - IPv6 addresses installed in response to router advertisement messages
323 .sp
324
325 .B kernel_ll
326 - Link-local addresses have this protocol value
327 .sp
328 .in -8
329
330 .sp
331 The rest of the values are not reserved and the administrator is free
332 to assign (or not to assign) protocol tags.
333
334 .SS ip address delete - delete protocol address
335 .B Arguments:
336 coincide with the arguments of
337 .B ip address add.
338 .sp
339 The device name is a required argument.
340
341 .SS ip address show - look at protocol addresses
342
343 .TP
344 .BI dev " IFNAME " (default)
345 name of device.
346
347 .TP
348 .BI scope " SCOPE_VAL"
349 only list addresses with this scope.
350
351 .TP
352 .BI to " PREFIX"
353 only list addresses matching this prefix.
354
355 .TP
356 .BI label " PATTERN"
357 only list addresses with labels matching the
358 .IR "PATTERN" .
359 .I PATTERN
360 is a usual shell style pattern.
361
362 .TP
363 .BI master " DEVICE"
364 only list interfaces enslaved to this master device.
365
366 .TP
367 .BI vrf " NAME "
368 only list interfaces enslaved to this vrf.
369
370 .TP
371 .BI type " TYPE"
372 only list interfaces of the given type.
373
374 Note that the type name is not checked against the list of supported types -
375 instead it is sent as-is to the kernel. Later it is used to filter the returned
376 interface list by comparing it with the relevant attribute in case the kernel
377 didn't filter already. Therefore any string is accepted, but may lead to empty
378 output.
379
380 .TP
381 .B up
382 only list running interfaces.
383
384 .TP
385 .B down
386 only list not running interfaces.
387
388 .TP
389 .B nomaster
390 only list interfaces with no master.
391
392 .TP
393 .BR dynamic " and " permanent
394 (IPv6 only) only list addresses installed due to stateless
395 address configuration or only list permanent (not dynamic)
396 addresses. These two flags are inverses of each other, so
397 .BR -dynamic " is equal to " permanent " and "
398 .BR -permanent " is equal to " dynamic .
399
400 .TP
401 .B tentative
402 (IPv6 only) only list addresses which have not yet passed duplicate
403 address detection.
404
405 .TP
406 .B -tentative
407 (IPv6 only) only list addresses which are not in the process of
408 duplicate address detection currently.
409
410 .TP
411 .B deprecated
412 (IPv6 only) only list deprecated addresses.
413
414 .TP
415 .B -deprecated
416 (IPv6 only) only list addresses not being deprecated.
417
418 .TP
419 .B dadfailed
420 (IPv6 only) only list addresses which have failed duplicate
421 address detection.
422
423 .TP
424 .B -dadfailed
425 (IPv6 only) only list addresses which have not failed duplicate
426 address detection.
427
428 .TP
429 .BR temporary " or " secondary
430 List temporary IPv6 or secondary IPv4 addresses only. The Linux kernel shares a
431 single bit for those, so they are actually aliases for each other although the
432 meaning differs depending on address family.
433
434 .TP
435 .BR -temporary " or " -secondary
436 These flags are aliases for
437 .BR primary .
438
439 .TP
440 .B primary
441 List only primary addresses, in IPv6 exclude temporary ones. This flag is the
442 inverse of
443 .BR temporary " and " secondary .
444
445 .TP
446 .B -primary
447 This is an alias for
448 .BR temporary " or " secondary .
449
450 .TP
451 .BI proto " ADDRPROTO"
452 Only show addresses with a given protocol, or those for which the kernel
453 response did not include protocol. See the corresponding argument to
454 .B ip address add
455 for details about address protocols.
456
457 .SS ip address flush - flush protocol addresses
458 This command flushes the protocol addresses selected by some criteria.
459
460 .PP
461 This command has the same arguments as
462 .BR show " except that " type " and " master " selectors are not supported."
463 Another difference is that it does not run when no arguments are given.
464
465 .PP
466 .B Warning:
467 This command and other
468 .B flush
469 commands are unforgiving. They will cruelly purge all the addresses.
470
471 .PP
472 With the
473 .B -statistics
474 option, the command becomes verbose. It prints out the number of deleted
475 addresses and the number of rounds made to flush the address list.
476 If this option is given twice,
477 .B ip address flush
478 also dumps all the deleted addresses in the format described in the
479 previous subsection.
480
481 .SH "EXAMPLES"
482 .PP
483 ip address show
484 .RS 4
485 Shows IPv4 and IPv6 addresses assigned to all network interfaces. The 'show'
486 subcommand can be omitted.
487 .RE
488 .PP
489 ip address show up
490 .RS 4
491 Same as above except that only addresses assigned to active network interfaces
492 are shown.
493 .RE
494 .PP
495 ip address show dev eth0
496 .RS 4
497 Shows IPv4 and IPv6 addresses assigned to network interface eth0.
498 .RE
499 .PP
500 ip address add 2001:0db8:85a3::0370:7334/64 dev eth1
501 .RS 4
502 Adds an IPv6 address to network interface eth1.
503 .RE
504 .PP
505 ip address delete 2001:0db8:85a3::0370:7334/64 dev eth1
506 .RS 4
507 Delete the IPv6 address added above.
508 .RE
509 .PP
510 ip address flush dev eth4 scope global
511 .RS 4
512 Removes all global IPv4 and IPv6 addresses from device eth4. Without 'scope
513 global' it would remove all addresses including IPv6 link-local ones.
514 .RE
515
516 .SH SEE ALSO
517 .br
518 .BR ip (8)
519
520 .SH AUTHOR
521 Original Manpage by Michail Litvak <[email protected]>