Commit | Line | Data |
---|---|---|
984263bc MD |
1 | .\" Copyright (c) 1983, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
dc71b7ab | 12 | .\" 3. Neither the name of the University nor the names of its contributors |
984263bc MD |
13 | .\" may be used to endorse or promote products derived from this software |
14 | .\" without specific prior written permission. | |
15 | .\" | |
16 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
17 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
18 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
19 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
20 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
21 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
22 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
23 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
24 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
25 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
26 | .\" SUCH DAMAGE. | |
27 | .\" | |
28 | .\" @(#)route.8 8.3 (Berkeley) 3/19/94 | |
29 | .\" $FreeBSD: src/sbin/route/route.8,v 1.17.2.9 2003/02/24 00:56:43 trhodes Exp $ | |
30 | .\" | |
6ec8f7f2 | 31 | .Dd August 8, 2015 |
984263bc MD |
32 | .Dt ROUTE 8 |
33 | .Os | |
34 | .Sh NAME | |
35 | .Nm route | |
36 | .Nd manually manipulate the routing tables | |
37 | .Sh SYNOPSIS | |
38 | .Nm | |
39 | .Op Fl dnqtv | |
b06a5e2a | 40 | .Op Fl c Ar cpu |
984263bc MD |
41 | .Ar command |
42 | .Oo | |
43 | .Op Ar modifiers | |
44 | .Ar args | |
45 | .Oc | |
46 | .Sh DESCRIPTION | |
47 | The | |
48 | .Nm | |
49 | utility is used to manually manipulate the network | |
50 | routing tables. It normally is not needed, as a | |
51 | system routing table management daemon such as | |
52 | .Xr routed 8 , | |
53 | should tend to this task. | |
54 | .Pp | |
55 | The | |
56 | .Nm | |
57 | utility supports a limited number of general options, | |
58 | but a rich command language, enabling the user to specify | |
59 | any arbitrary request that could be delivered via the | |
60 | programmatic interface discussed in | |
61 | .Xr route 4 . | |
62 | .Pp | |
63 | The following options are available: | |
64 | .Bl -tag -width indent | |
b06a5e2a MD |
65 | .It Fl c Ar cpu |
66 | On SMP systems the route table is replicated. This option allows the | |
67 | route table for a specific cpu to be accessed and exists primarily | |
68 | for debugging purposes. | |
984263bc MD |
69 | .It Fl n |
70 | Bypass attempts to print host and network names symbolically | |
71 | when reporting actions. (The process of translating between symbolic | |
72 | names and numerical equivalents can be quite time consuming, and | |
73 | may require correct operation of the network; thus it may be expedient | |
74 | to forget this, especially when attempting to repair networking operations). | |
75 | .It Fl v | |
76 | (verbose) Print additional details. | |
77 | .It Fl q | |
78 | Suppress all output from the | |
79 | .Cm add , delete , | |
80 | and | |
81 | .Cm flush | |
82 | commands. | |
9ddb32ba MD |
83 | .It Fl w |
84 | Print the full width of the data being represented even if it would overflow | |
85 | the column. | |
984263bc MD |
86 | .El |
87 | .Pp | |
88 | The | |
89 | .Nm | |
90 | utility provides six commands: | |
91 | .Pp | |
92 | .Bl -tag -width Fl -compact | |
93 | .It Cm add | |
94 | Add a route. | |
95 | .It Cm flush | |
96 | Remove all routes. | |
97 | .It Cm delete | |
98 | Delete a specific route. | |
99 | .It Cm change | |
100 | Change aspects of a route (such as its gateway). | |
101 | .It Cm get | |
102 | Lookup and display the route for a destination. | |
147a7be0 MD |
103 | .It Cm show |
104 | Print out the route table similar to "netstat \-r" (see | |
105 | .Xr netstat 1 ) . | |
984263bc MD |
106 | .It Cm monitor |
107 | Continuously report any changes to the routing information base, | |
108 | routing lookup misses, or suspected network partitionings. | |
109 | .El | |
110 | .Pp | |
111 | The monitor command has the syntax: | |
112 | .Pp | |
113 | .Bd -ragged -offset indent -compact | |
114 | .Nm | |
115 | .Op Fl n | |
116 | .Cm monitor | |
117 | .Ed | |
118 | .Pp | |
119 | The flush command has the syntax: | |
120 | .Pp | |
121 | .Bd -ragged -offset indent -compact | |
122 | .Nm | |
123 | .Op Fl n | |
124 | .Cm flush | |
125 | .Op Ar family | |
126 | .Ed | |
127 | .Pp | |
128 | If the | |
129 | .Cm flush | |
130 | command is specified, | |
131 | .Nm | |
132 | will ``flush'' the routing tables of all gateway entries. | |
133 | When the address family may is specified by any of the | |
6ec8f7f2 | 134 | .Fl inet6 |
984263bc MD |
135 | or |
136 | .Fl inet | |
137 | modifiers, only routes having destinations with addresses in the | |
138 | delineated family will be deleted. | |
139 | .Pp | |
140 | The other commands have the following syntax: | |
141 | .Pp | |
142 | .Bd -ragged -offset indent -compact | |
143 | .Nm | |
144 | .Op Fl n | |
145 | .Ar command | |
146 | .Op Fl net No \&| Fl host | |
147 | .Ar destination gateway | |
148 | .Op Ar netmask | |
149 | .Ed | |
150 | .Pp | |
151 | where | |
152 | .Ar destination | |
153 | is the destination host or network, | |
154 | .Ar gateway | |
155 | is the next-hop intermediary via which packets should be routed. | |
156 | Routes to a particular host may be distinguished from those to | |
157 | a network by interpreting the Internet address specified as the | |
158 | .Ar destination | |
159 | argument. | |
160 | The optional modifiers | |
161 | .Fl net | |
162 | and | |
163 | .Fl host | |
164 | force the destination to be interpreted as a network or a host, respectively. | |
165 | Otherwise, if the | |
166 | .Ar destination | |
167 | has a | |
168 | .Dq local address part | |
169 | of | |
170 | INADDR_ANY | |
171 | .Pq Li 0.0.0.0 , | |
172 | or if the | |
173 | .Ar destination | |
174 | is the symbolic name of a network, then the route is | |
175 | assumed to be to a network; otherwise, it is presumed to be a | |
176 | route to a host. | |
177 | Optionally, the | |
178 | .Ar destination | |
179 | could also be specified in the | |
180 | .Ar net Ns / Ns Ar bits | |
181 | format. | |
182 | .Pp | |
183 | For example, | |
184 | .Li 128.32 | |
185 | is interpreted as | |
186 | .Fl host Li 128.0.0.32 ; | |
187 | .Li 128.32.130 | |
188 | is interpreted as | |
189 | .Fl host Li 128.32.0.130 ; | |
190 | .Fl net Li 128.32 | |
191 | is interpreted as | |
192 | .Li 128.32.0.0; | |
193 | .Fl net Li 128.32.130 | |
194 | is interpreted as | |
195 | .Li 128.32.130.0; | |
196 | and | |
197 | .Li 192.168.64/20 | |
198 | is interpreted as | |
199 | .Fl net Li 192.168.64 Fl netmask Li 255.255.240.0 . | |
200 | .Pp | |
201 | A | |
202 | .Ar destination | |
203 | of | |
204 | .Ar default | |
205 | is a synonym for | |
206 | .Fl net Li 0.0.0.0 , | |
207 | which is the default route. | |
208 | .Pp | |
209 | If the destination is directly reachable | |
210 | via an interface requiring | |
211 | no intermediary system to act as a gateway, the | |
212 | .Fl interface | |
213 | modifier should be specified; | |
214 | the gateway given is the address of this host on the common network, | |
215 | indicating the interface to be used for transmission. | |
216 | Alternately, if the interface is point to point the name of the interface | |
217 | itself may be given, in which case the route remains valid even | |
218 | if the local or remote addresses change. | |
219 | .Pp | |
220 | The optional modifiers | |
6ec8f7f2 | 221 | .Fl mpls |
984263bc MD |
222 | and |
223 | .Fl link | |
224 | specify that all subsequent addresses are in the | |
6ec8f7f2 SW |
225 | .Tn MPLS |
226 | address family | |
984263bc MD |
227 | or are specified as link-level addresses, |
228 | and the names must be numeric specifications rather than | |
229 | symbolic names. | |
230 | .Pp | |
231 | The optional | |
232 | .Fl netmask | |
6ec8f7f2 SW |
233 | modifier is intended to manually add subnet routes with |
234 | netmasks different from that of the implied network interface. | |
984263bc MD |
235 | One specifies an additional ensuing address parameter |
236 | (to be interpreted as a network mask). | |
237 | The implicit network mask generated in the AF_INET case | |
238 | can be overridden by making sure this option follows the destination parameter. | |
239 | .Pp | |
240 | For | |
241 | .Dv AF_INET6 , | |
242 | the | |
243 | .Fl prefixlen | |
244 | qualifier | |
245 | is available instead of the | |
246 | .Fl mask | |
247 | qualifier because non-continuous masks are not allowed in IPv6. | |
248 | For example, | |
249 | .Fl prefixlen Li 32 | |
250 | specifies network mask of | |
251 | .Li ffff:ffff:0000:0000:0000:0000:0000:0000 | |
252 | to be used. | |
253 | The default value of prefixlen is 64 to get along with | |
254 | the aggregatable address. | |
255 | But 0 is assumed if | |
256 | .Cm default | |
257 | is specified. | |
258 | Note that the qualifier works only for | |
259 | .Dv AF_INET6 | |
260 | address family. | |
261 | .Pp | |
262 | Routes have associated flags which influence operation of the protocols | |
263 | when sending to destinations matched by the routes. | |
264 | These flags may be set (or sometimes cleared) | |
265 | by indicating the following corresponding modifiers: | |
266 | .Bd -literal | |
267 | -cloning RTF_CLONING - generates a new route on use | |
268 | -xresolve RTF_XRESOLVE - emit mesg on use (for external lookup) | |
269 | -iface ~RTF_GATEWAY - destination is directly reachable | |
270 | -static RTF_STATIC - manually added route | |
271 | -nostatic ~RTF_STATIC - pretend route added by kernel or daemon | |
272 | -reject RTF_REJECT - emit an ICMP unreachable when matched | |
273 | -blackhole RTF_BLACKHOLE - silently discard pkts (during updates) | |
274 | -proto1 RTF_PROTO1 - set protocol specific routing flag #1 | |
275 | -proto2 RTF_PROTO2 - set protocol specific routing flag #2 | |
276 | -llinfo RTF_LLINFO - validly translates proto addr to link addr | |
277 | .Ed | |
278 | .Pp | |
279 | The optional modifiers | |
280 | .Fl rtt , | |
281 | .Fl rttvar , | |
282 | .Fl sendpipe , | |
283 | .Fl recvpipe , | |
284 | .Fl mtu , | |
285 | .Fl hopcount , | |
286 | .Fl expire , | |
bd549c9a SZ |
287 | .Fl msl , |
288 | .Fl iw , | |
289 | .Fl iwmax | |
984263bc MD |
290 | and |
291 | .Fl ssthresh | |
292 | provide initial values to quantities maintained in the routing entry | |
293 | by transport level protocols, such as TCP or TP4. | |
294 | These may be individually locked by preceding each such modifier to | |
295 | be locked by | |
296 | the | |
297 | .Fl lock | |
298 | meta-modifier, or one can | |
299 | specify that all ensuing metrics may be locked by the | |
300 | .Fl lockrest | |
301 | meta-modifier. | |
302 | .Pp | |
303 | In a | |
304 | .Cm change | |
305 | or | |
306 | .Cm add | |
307 | command where the destination and gateway are not sufficient to specify | |
308 | the route (as in the | |
309 | .Tn ISO | |
310 | case where several interfaces may have the | |
311 | same address), the | |
312 | .Fl ifp | |
313 | or | |
314 | .Fl ifa | |
315 | modifiers may be used to determine the interface or interface address. | |
316 | .Pp | |
317 | The optional | |
318 | .Fl proxy | |
319 | modifier specifies that the | |
320 | .Dv RTF_LLINFO | |
321 | routing table entry is the | |
322 | .Dq published (proxy-only) | |
323 | .Tn ARP | |
324 | entry, as reported by | |
325 | .Xr arp 8 . | |
326 | .Pp | |
327 | All symbolic names specified for a | |
328 | .Ar destination | |
329 | or | |
330 | .Ar gateway | |
331 | are looked up first as a host name using | |
332 | .Xr gethostbyname 3 . | |
333 | If this lookup fails, | |
334 | .Xr getnetbyname 3 | |
335 | is then used to interpret the name as that of a network. | |
336 | .Pp | |
9b42cabe NA |
337 | The optional |
338 | .Fl push , | |
339 | .Fl pop , | |
340 | and | |
341 | .Fl swap | |
342 | modifiers may be used to specify the desired mpls label | |
343 | operations for the route. Each route may have up to 3 | |
344 | label operations assigned to it. The label operations | |
345 | may be combined between them, but specifically the | |
346 | .Fl push | |
347 | and | |
348 | .Fl pop | |
349 | operations may be repeated if the intent is to push or pop | |
350 | more than one label at once. The | |
351 | .Fl swap | |
352 | operation always swaps the outer label and may not be | |
917db758 | 353 | repeated. |
9b42cabe NA |
354 | Here are some MPLS route examples: |
355 | .Pp | |
356 | Add an normal inet route, but push an mpls | |
357 | .Ar label | |
358 | to the packet: | |
359 | .Pp | |
360 | .Bd -ragged -offset indent -compact | |
361 | .Nm | |
362 | .Cm add | |
363 | .Ar destination gateway | |
364 | .Fl push | |
365 | .Ar label | |
366 | .Ed | |
367 | .Pp | |
368 | Add an normal inet route, but double-push an mpls | |
369 | .Ar inner-label | |
370 | and an | |
371 | .Ar outer-label | |
372 | to the packet: | |
373 | .Pp | |
374 | .Bd -ragged -offset indent -compact | |
375 | .Nm | |
376 | .Cm add | |
377 | .Ar destination gateway | |
378 | .Fl push | |
379 | .Ar inner-label | |
380 | .Fl push | |
381 | .Ar outer-label | |
382 | .Ed | |
383 | .Pp | |
384 | Add an mpls route for an | |
385 | .Ar incoming-label | |
386 | to be forwarded to | |
387 | .Ar gateway | |
388 | and swap that label with | |
389 | .Ar new-label : | |
390 | .Pp | |
391 | .Bd -ragged -offset indent -compact | |
392 | .Nm | |
393 | .Cm add | |
394 | .Fl mpls | |
395 | .Ar incoming-label | |
396 | .Fl inet | |
397 | .Ar gateway | |
398 | .Fl swap | |
399 | .Ar new-label | |
400 | .Ed | |
401 | .Pp | |
984263bc MD |
402 | The |
403 | .Nm | |
404 | utility uses a routing socket and the new message types | |
405 | .Dv RTM_ADD , RTM_DELETE , RTM_GET , | |
406 | and | |
407 | .Dv RTM_CHANGE . | |
408 | As such, only the super-user may modify | |
409 | the routing tables. | |
19fe1c42 SW |
410 | .Sh EXIT STATUS |
411 | .Ex -std | |
984263bc MD |
412 | .Sh DIAGNOSTICS |
413 | .Bl -diag | |
414 | .It "add [host \&| network ] %s: gateway %s flags %x" | |
415 | The specified route is being added to the tables. The | |
416 | values printed are from the routing table entry supplied | |
417 | in the | |
418 | .Xr ioctl 2 | |
419 | call. | |
420 | If the gateway address used was not the primary address of the gateway | |
421 | (the first one returned by | |
422 | .Xr gethostbyname 3 ) , | |
423 | the gateway address is printed numerically as well as symbolically. | |
424 | .It "delete [ host \&| network ] %s: gateway %s flags %x" | |
425 | As above, but when deleting an entry. | |
426 | .It "%s %s done" | |
427 | When the | |
428 | .Cm flush | |
429 | command is specified, each routing table entry deleted | |
430 | is indicated with a message of this form. | |
431 | .It "Network is unreachable" | |
432 | An attempt to add a route failed because the gateway listed was not | |
433 | on a directly-connected network. | |
434 | The next-hop gateway must be given. | |
435 | .It "not in table" | |
436 | A delete operation was attempted for an entry which | |
437 | wasn't present in the tables. | |
438 | .It "routing table overflow" | |
439 | An add operation was attempted, but the system was | |
440 | low on resources and was unable to allocate memory | |
441 | to create the new entry. | |
442 | .It "gateway uses the same route" | |
443 | A | |
444 | .Cm change | |
445 | operation resulted in a route whose gateway uses the | |
446 | same route as the one being changed. | |
447 | The next-hop gateway should be reachable through a different route. | |
448 | .El | |
984263bc MD |
449 | .Sh SEE ALSO |
450 | .\".Xr esis 4 , | |
451 | .Xr netintro 4 , | |
452 | .Xr route 4 , | |
453 | .Xr arp 8 , | |
984263bc | 454 | .Xr routed 8 |
984263bc MD |
455 | .Sh HISTORY |
456 | The | |
457 | .Nm | |
458 | utility appeared in | |
459 | .Bx 4.2 . | |
460 | .Sh BUGS | |
461 | The first paragraph may have slightly exaggerated | |
462 | .Xr routed 8 Ns 's | |
463 | abilities. |