Debian Codegraph @

upstream/debian-trixie/man8/ip-neighbour.8

raw
1 .TH IP\-NEIGHBOUR 8 "20 Dec 2011" "iproute2" "Linux"
2 .SH "NAME"
3 ip-neighbour \- neighbour/arp tables management.
4 .SH "SYNOPSIS"
5 .sp
6 .ad l
7 .in +8
8 .ti -8
9 .B ip
10 .RI "[ " OPTIONS " ]"
11 .B neigh
12 .RI " { " COMMAND " | "
13 .BR help " }"
14 .sp
15
16 .ti -8
17 .BR "ip neigh" " { " add " | " del " | " change " | " replace " } { "
18 .IR ADDR " [ "
19 .B lladdr
20 .IR LLADDR " ] [ "
21 .B nud
22 .IR STATE " ] |"
23 .B proxy
24 .IR ADDR " } [ "
25 .B dev
26 .IR DEV " ] [ "
27 .BR router " ] [ "
28 .BR use " ] [ "
29 .BR managed " ] [ "
30 .BR extern_learn " ]"
31
32 .ti -8
33 .BR "ip neigh" " { " show " | " flush " } [ " proxy " ] [ " to
34 .IR PREFIX " ] [ "
35 .B dev
36 .IR DEV " ] [ "
37 .B nud
38 .IR STATE " ] [ "
39 .B vrf
40 .IR NAME " ] ["
41 .BR nomaster " ]"
42
43 .ti -8
44 .B ip neigh get
45 .IR ADDR
46 .B dev
47 .IR DEV
48
49 .ti -8
50 .IR STATE " := {"
51 .BR permanent " | " noarp " | " stale " | " reachable " | " none " |"
52 .BR incomplete " | " delay " | " probe " | " failed " }"
53
54 .SH DESCRIPTION
55 The
56 .B ip neigh
57 command manipulates
58 .I neighbour
59 objects that establish bindings between protocol addresses and
60 link layer addresses for hosts sharing the same link.
61 Neighbour entries are organized into tables. The IPv4 neighbour table
62 is also known by another name - the ARP table.
63
64 .P
65 The corresponding commands display neighbour bindings
66 and their properties, add new neighbour entries and delete old ones.
67
68 .TP
69 ip neighbour add
70 add a new neighbour entry
71 .TP
72 ip neighbour change
73 change an existing entry
74 .TP
75 ip neighbour replace
76 add a new entry or change an existing one
77 .RS
78 .PP
79 These commands create new neighbour records or update existing ones.
80
81 .TP
82 .BI to " ADDRESS " (default)
83 the protocol address of the neighbour. It is either an IPv4 or IPv6 address.
84
85 .TP
86 .BI dev " NAME"
87 the interface to which this neighbour is attached.
88
89 .TP
90 .BI proxy
91 indicates whether we are proxying for this neighbour entry
92
93 .TP
94 .BI router
95 indicates whether neighbour is a router
96
97 .TP
98 .BI use
99 this neigh entry is in "use". This option can be used to indicate to
100 the kernel that a controller is using this dynamic entry. If the entry
101 does not exist, the kernel will resolve it. If it exists, an attempt
102 to refresh the neighbor entry will be triggered.
103
104 .TP
105 .BI managed
106 this neigh entry is "managed". This option can be used to indicate to
107 the kernel that a controller is using this dynamic entry. In contrast
108 to "use", if the entry does not exist, the kernel will resolve it and
109 periodically attempt to auto-refresh the neighbor entry such that it
110 remains in resolved state when possible.
111
112 .TP
113 .BI extern_learn
114 this neigh entry was learned externally. This option can be used to
115 indicate to the kernel that this is a controller learnt dynamic entry.
116 Kernel will not gc such an entry.
117
118 .TP
119 .BI lladdr " LLADDRESS"
120 the link layer address of the neighbour.
121 .I LLADDRESS
122 can also be
123 .BR "null" .
124
125 .TP
126 .BI nud " STATE"
127 the state of the neighbour entry.
128 .B nud
129 is an abbreviation for 'Neighbour Unreachability Detection'.
130 The state can take one of the following values:
131
132 .RS
133 .TP
134 .B permanent
135 the neighbour entry is valid forever and can be only
136 be removed administratively.
137 .TP
138 .B noarp
139 the neighbour entry is valid. No attempts to validate
140 this entry will be made but it can be removed when its lifetime expires.
141 .TP
142 .B reachable
143 the neighbour entry is valid until the reachability
144 timeout expires.
145 .TP
146 .B stale
147 the neighbour entry is valid but suspicious.
148 This option to
149 .B ip neigh
150 does not change the neighbour state if it was valid and the address
151 is not changed by this command.
152 .TP
153 .B none
154 this is a pseudo state used when initially creating a neighbour entry or after
155 trying to remove it before it becomes free to do so.
156 .TP
157 .B incomplete
158 the neighbour entry has not (yet) been validated/resolved.
159 .TP
160 .B delay
161 neighbor entry validation is currently delayed.
162 .TP
163 .B probe
164 neighbor is being probed.
165 .TP
166 .B failed
167 max number of probes exceeded without success, neighbor validation has
168 ultimately failed.
169 .RE
170 .RE
171
172 .TP
173 ip neighbour delete
174 delete a neighbour entry
175 .RS
176 .PP
177 The arguments are the same as with
178 .BR "ip neigh add" ,
179 except that
180 .B lladdr
181 and
182 .B nud
183 are ignored.
184
185 .PP
186 .B Warning:
187 Attempts to delete or manually change a
188 .B noarp
189 entry created by the kernel may result in unpredictable behaviour.
190 Particularly, the kernel may try to resolve this address even
191 on a
192 .B NOARP
193 interface or if the address is multicast or broadcast.
194 .RE
195
196 .TP
197 ip neighbour show
198 list neighbour entries
199 .RS
200 .TP
201 .BI to " ADDRESS " (default)
202 the prefix selecting the neighbours to list.
203
204 .TP
205 .BI dev " NAME"
206 only list the neighbours attached to this device.
207
208 .TP
209 .BI vrf " NAME"
210 only list the neighbours for given VRF.
211
212 .TP
213 .BI nomaster
214 only list neighbours attached to an interface with no master.
215
216 .TP
217 .BI proxy
218 list neighbour proxies.
219
220 .TP
221 .B unused
222 only list neighbours which are not currently in use.
223
224 .TP
225 .BI nud " STATE"
226 only list neighbour entries in this state.
227 .I NUD_STATE
228 takes values listed below or the special value
229 .B all
230 which means all states. This option may occur more than once.
231 If this option is absent,
232 .B ip
233 lists all entries except for
234 .B none
235 and
236 .BR "noarp" .
237 .RE
238
239 .TP
240 ip neighbour flush
241 flush neighbour entries
242 .RS
243 This command has the same arguments as
244 .B show.
245 The differences are that it does not run when no arguments are given,
246 and that the default neighbour states to be flushed do not include
247 .B permanent
248 and
249 .BR "noarp" .
250
251 .PP
252 With the
253 .B -statistics
254 option, the command becomes verbose. It prints out the number of
255 deleted neighbours and the number of rounds made to flush the
256 neighbour table. If the option is given
257 twice,
258 .B ip neigh flush
259 also dumps all the deleted neighbours.
260 .RE
261
262 .TP
263 ip neigh get
264 lookup a neighbour entry to a destination given a device
265 .RS
266
267 .TP
268 .BI proxy
269 indicates whether we should lookup a proxy neighbour entry
270
271 .TP
272 .BI to " ADDRESS " (default)
273 the prefix selecting the neighbour to query.
274
275 .TP
276 .BI dev " NAME"
277 get neighbour entry attached to this device.
278 .RE
279
280 .SH EXAMPLES
281 .PP
282 ip neighbour
283 .RS
284 Shows the current neighbour table in kernel.
285 .RE
286 .PP
287 ip neigh flush dev eth0
288 .RS
289 Removes entries in the neighbour table on device eth0.
290 .RE
291 .PP
292 ip neigh get 10.0.1.10 dev eth0
293 .RS
294 Performs a neighbour lookup in the kernel and returns
295 a neighbour entry.
296 .RE
297
298 .SH SEE ALSO
299 .br
300 .BR ip (8)
301
302 .SH AUTHOR
303 Original Manpage by Michail Litvak <[email protected]>