| blob | 6a11d7258c010d683ebf171529d7b0dab9d2bb98 |
1 '\" te
2 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH ROUTE 8 "May 13, 2017"
7 .SH NAME
8 route \- manually manipulate the routing tables
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBroute\fR [\fB-fnvq\fR] \fIsub-command\fR [ [\fImodifiers\fR] \fIargs\fR]
13 .fi
15 .LP
16 .nf
17 \fBroute\fR [\fB-fnvq\fR] [\fB-p\fR [\fB-R\fR \fIroot-dir\fR]] add | delete [\fImodifiers\fR] \fIdestination\fR \fIgateway\fR
18 [\fIargs\fR]
19 .fi
21 .LP
22 .nf
23 \fBroute\fR [\fB-fnvq\fR] change | get [\fImodifiers\fR] \fIdestination\fR
24 [\fIgateway\fR [\fIargs\fR]]
25 .fi
27 .LP
28 .nf
29 \fBroute\fR [\fB-fn\fR] monitor [\fImodifiers\fR]
30 .fi
32 .LP
33 .nf
34 \fBroute\fR [\fB-fnvq\fR] flush [\fImodifiers\fR]
35 .fi
37 .LP
38 .nf
39 \fBroute\fR \fB-p\fR [\fB-R\fR \fIroot-dir\fR] show
40 .fi
42 .SH DESCRIPTION
43 .LP
44 \fBroute\fR manually manipulates the network routing tables. These tables are
45 normally maintained by the system routing daemon, such as \fBin.routed\fR(8)
46 and \fBin.ripngd\fR(8).
47 .sp
48 .LP
49 \fBroute\fR supports a limited number of general options, but a rich command
50 language. Users can specify an arbitrary request that can be delivered by means
51 of the programmatic interface discussed in \fBroute\fR(7P).
52 .sp
53 .LP
54 \fBroute\fR uses a routing socket and the new message types \fBRTM_ADD\fR,
55 \fBRTM_DELETE\fR, \fBRTM_GET\fR, and \fBRTM_CHANGE\fR. While only superusers
56 can modify routing tables, the \fBRTM_GET\fR operation is allowed for
57 non-privileged users.
58 .SH OPTIONS
59 .ne 2
60 .na
61 \fB\fB-f\fR\fR
62 .ad
63 .RS 15n
64 Flush the routing tables of all gateway entries. If you use the \fB-f\fR option
65 in conjunction with any of the \fBroute\fR subcommands, \fBroute\fR flushes
66 the gateways before performing the subcommand. Specify the table to flush by
67 placing the \fBinet\fR or \fBinet6\fR modifier immediately after the \fB-f\fR
68 option. If unspecified, flushing IPv4 (\fBinet\fR) routes is the default.
69 .RE
71 .sp
72 .ne 2
73 .na
74 \fB\fB-n\fR\fR
75 .ad
76 .RS 15n
77 Prevent attempts to print host and network names symbolically when reporting
78 actions. This option is useful when name servers are unavailable.
79 .RE
81 .sp
82 .ne 2
83 .na
84 \fB\fB-p\fR\fR
85 .ad
86 .RS 15n
87 Make changes to the network route tables persistent across system restarts. The
88 operation is applied to the network routing tables first and, if successful, is
89 then applied to the list of saved routes used at system startup. In determining
90 whether an operation was successful, a failure to add a route that already
91 exists or to delete a route that is not in the routing table is ignored.
92 Particular care should be taken when using host or network names in persistent
93 routes, as network-based name resolution services are not available at the time
94 routes are added at startup.
95 .RE
97 .sp
98 .ne 2
99 .na
100 \fB\fB-q\fR\fR
101 .ad
102 .RS 15n
103 Suppress all output.
104 .RE
106 .sp
107 .ne 2
108 .na
109 \fB\fB-R\fR \fIroot-dir\fR\fR
110 .ad
111 .RS 15n
112 Specify an alternate root directory where \fBroute\fR applies changes. This
113 option is ignored unless used in conjunction with the \fB-p\fR option. When
114 \fB-R\fR is specified, route changes are applied only to the list of saved
115 routes to be used at startup, \fBnot\fR to the network routing tables. In
116 addition, certain checks, such as the existence of network interfaces used with
117 \fB-ifp\fR, are skipped.
118 .RE
120 .sp
121 .ne 2
122 .na
123 \fB\fB-v\fR\fR
124 .ad
125 .RS 15n
126 Print additional details in verbose mode.
127 .RE
129 .SS "Subcommands"
130 .LP
131 The following subcommands are supported:
132 .sp
133 .ne 2
134 .na
135 \fB\fBadd\fR\fR
136 .ad
137 .RS 11n
138 Add a route.
139 .RE
141 .sp
142 .ne 2
143 .na
144 \fB\fBchange\fR\fR
145 .ad
146 .RS 11n
147 Change aspects of a route (such as its gateway).
148 .RE
150 .sp
151 .ne 2
152 .na
153 \fB\fBdelete\fR\fR
154 .ad
155 .RS 11n
156 Delete a specific route.
157 .RE
159 .sp
160 .ne 2
161 .na
162 \fB\fBflush\fR\fR
163 .ad
164 .RS 11n
165 Remove all gateway entries from the routing table.
166 .RE
168 .sp
169 .ne 2
170 .na
171 \fB\fBget\fR\fR
172 .ad
173 .RS 11n
174 Look up and display the route for a destination.
175 .RE
177 .sp
178 .ne 2
179 .na
180 \fB\fBmonitor\fR\fR
181 .ad
182 .RS 11n
183 Continuously report any changes to the routing information base, routing lookup
184 misses, or suspected network partitionings.
185 .RE
187 .sp
188 .ne 2
189 .na
190 \fB\fBshow\fR\fR
191 .ad
192 .RS 11n
193 Display the list of routes to be applied at system startup. Can be used only in
194 conjunction with the \fB-p\fR option.
195 .RE
197 .sp
198 .LP
199 The \fBadd\fR and \fBdelete\fR subcommands have the following syntax:
200 .sp
201 .in +2
202 .nf
203 route [ -fnvq ] cmd \fIdestination\fR \fIgateway\fR [metric/netmask]
204 .fi
205 .in -2
206 .sp
208 .sp
209 .LP
210 where \fIcmd\fR is \fBadd\fR or \fBdelete\fR, \fIdestination\fR is the
211 destination host or network, and \fIgateway\fR is the next-hop intermediary
212 through which packets should be routed. Modifiers described in \fBOPERANDS\fR
213 can be placed anywhere on the command line.
214 .sp
215 .LP
216 The \fBget\fR and \fBchange\fR subcommands have the following syntax:
217 .sp
218 .in +2
219 .nf
220 route [ -fnvq ] \fIcmd\fR \fIdestination\fR [\fIgateway\fR [metric/netmask]]
221 .fi
222 .in -2
223 .sp
225 .sp
226 .LP
227 where \fIcmd\fR is \fBget\fR or \fBchange\fR, \fIdestination\fR is the
228 destination host or network, and \fIgateway\fR is the next-hop intermediary
229 through which packets should be routed. Modifiers described in \fBOPERANDS\fR
230 can be placed anywhere on the command line.
231 .sp
232 .LP
233 The \fBmonitor\fR subcommand has the following syntax:
234 .sp
235 .in +2
236 .nf
237 route monitor [ -inet | -inet6 ]
238 .fi
239 .in -2
240 .sp
242 .SH OPERANDS
243 .LP
244 \fBroute\fR executes its subcommands on routes to destinations by way of
245 gateways.
246 .SS "Destinations and Gateways"
247 .LP
248 By default, destination and gateway addresses are interpreted as IPv4
249 addresses. All symbolic names are tried first as a host name, using
250 \fBgetipnodebyname\fR(3SOCKET). If this lookup fails in the AF_INET case,
251 \fBgetnetbyname\fR(3SOCKET) interprets the name as that of a network.
252 .sp
253 .LP
254 Including an optional modifier on the command line before the address changes
255 how the \fBroute\fR subcommand interprets it.
256 .sp
257 .LP
258 The following modifiers are supported:
259 .sp
260 .ne 2
261 .na
262 \fB\fB-inet\fR\fR
263 .ad
264 .RS 10n
265 Force the address to be interpreted as an IPv4 address, that is, under the
266 \fBAF_INET\fR address family.
267 .RE
269 .sp
270 .ne 2
271 .na
272 \fB\fB-inet6\fR\fR
273 .ad
274 .RS 10n
275 Force the address to be interpreted as an IPv6 address, that is, under the
276 \fBAF_INET6\fR address family.
277 .RE
279 .sp
280 .LP
281 For IPv4 addresses, routes to a particular host are by default distinguished
282 from those to a network by interpreting the Internet address specified as the
283 destination. If the destination has a \fBlocal address part\fR (that is, the
284 portion not covered by the netmask) of \fB0\fR, or if the destination is
285 resolved as the symbolic name of a network, then the route is assumed to be to
286 a network; otherwise, it is presumed to be a route to a host.
287 .sp
288 .LP
289 You can force this selection by using one of the following modifiers:
290 .sp
291 .ne 2
292 .na
293 \fB\fB-host\fR\fR
294 .ad
295 .RS 9n
296 Force the destination to be interpreted as a host.
297 .RE
299 .sp
300 .ne 2
301 .na
302 \fB\fB-net\fR\fR
303 .ad
304 .RS 9n
305 Force the destination to be interpreted as a network.
306 .RE
308 .sp
309 .LP
310 For example:
311 .sp
313 .sp
314 .TS
315 c c
316 l l .
317 Destination Destination Equivalent
318 _
319 \fB128.32\fR \fB-host\fR \fB128.0.0.32\fR
320 \fB128.32.130\fR \fB-host\fR \fB128.32.0.130\fR
321 \fB-net\fR \fB128.32\fR \fB128.32.0.0\fR
322 \fB-net\fR \fB128.32.130\fR \fB\fR\fB128.32.130.0\fR
323 .TE
325 .sp
326 .LP
327 Two modifiers avoid confusion between addresses and keywords (for example.,
328 \fBhost\fR used as a symbolic host name). You can distinguish a
329 \fIdestination\fR by preceding it with the \fB-dst\fR modifier. You can
330 distinguish a gateway address by using the \fB-gateway\fR modifier. If the
331 destination is directly reachable by way of an interface requiring no
332 intermediary IP router to act as a gateway, this can be indicated by using the
333 \fB-interface\fR or \fB-iface\fR modifier.
334 .sp
335 .LP
336 In the following example, the route does not refer to an external gateway
337 (router), but rather to one of the machine's interfaces. Packets with IP
338 destination addresses matching the destination and mask on such a route are
339 sent out on the interface identified by the gateway address. For interfaces
340 using the ARP protocol, this type of route is used to specify that all matching
341 destinations are local to the physical link. That is, a host could be
342 configured to ARP for all addresses, without regard to the configured interface
343 netmask, by adding a default route using this command. For example:
344 .sp
345 .in +2
346 .nf
347 example# route add default \fIhostname\fR -interface
348 .fi
349 .in -2
350 .sp
352 .sp
353 .LP
354 where gateway address \fIhostname\fR is the name or IP address associated with
355 the network interface over which all matching packets should be sent. On a host
356 with a single network interface, \fIhostname\fR is usually the same as the
357 \fInodename\fR returned by the \fBuname -n\fR command. See \fBuname\fR(1).
358 .sp
359 .LP
360 For backward compatibility with older systems, directly reachable routes can
361 also be specified by placing a \fB0\fR after the gateway address:
362 .sp
363 .in +2
364 .nf
365 example# route add default \fIhostname\fR 0
366 .fi
367 .in -2
368 .sp
370 .sp
371 .LP
372 This value was once a route metric, but this metric is no longer used. If the
373 value is specified as \fB0\fR, then the destination is directly reachable
374 (equivalent to specifying \fB-\fR\fBinterface\fR). If it is non-zero but cannot
375 be interpreted as a subnet mask, then a gateway is used (default).
376 .sp
377 .LP
378 With the \fBAF_INET\fR address family or an IPv4 address, a separate subnet
379 mask can be specified. This can be specified in one of the following ways:
380 .RS +4
381 .TP
382 .ie t \(bu
383 .el o
384 IP address following the gateway address . This is typically specified in
385 \fIdecimal dot\fR notation as for \fBinet_addr\fR(3) rather than in
386 symbolic form.
387 .RE
388 .RS +4
389 .TP
390 .ie t \(bu
391 .el o
392 IP address following the \fB-netmask\fR qualifier.
393 .RE
394 .RS +4
395 .TP
396 .ie t \(bu
397 .el o
398 Slash character and a decimal length appended to the destination address.
399 .RE
400 .sp
401 .LP
402 If a subnet mask is not specified, the mask used is the subnet mask of the
403 output interface selected by the gateway address, if the classful network of
404 the destination is the same as the classful network of the interface.
405 Otherwise, the classful network mask for the destination address is used.
406 .sp
407 .LP
408 Each of the following examples creates an IPv4 route to the destination
409 \fB192.0.2.32\fR subnet with a subnet mask of \fB255.255.255.224\fR:
410 .sp
411 .in +2
412 .nf
413 example# route add 192.0.2.32/27 somegateway
414 example# route add 192.0.2.32 -netmask 255.255.255.224 somegateway
415 example# route add 192.0.2.32 somegateway 255.255.255.224
416 .fi
417 .in -2
418 .sp
420 .sp
421 .LP
422 For IPv6, only the slash format is accepted. The following example creates an
423 IPv6 route to the destination \fB33fe::\fR with a netmask of \fB16\fR one-bits
424 followed by 112 zero-bits.
425 .sp
426 .in +2
427 .nf
428 example# route add -inet6 3ffe::/16 somegateway
429 .fi
430 .in -2
431 .sp
433 .sp
434 .LP
435 In cases where the gateway does not uniquely identify the output interface (for
436 example, when several interfaces have the same address), you can use the
437 \fB-ifp\fR \fIifname\fR modifier to specify the interface by name. For
438 example, \fB\fR\fB-ifp\fR \fBlo0\fR associates the route with the \fBlo0\fR
439 interface. If the named interface is an underlying interface in an IPMP (IP
440 multipathing) group, then requests to add a route will automatically be
441 translated to the corresponding IPMP IP interface, and requests to delete or
442 change a route on an underlying interface will fail.
443 .SS "Routing Flags"
444 .LP
445 Routes have associated flags that influence operation of the protocols when
446 sending to destinations matched by the routes. These flags can be set (and in
447 some cases cleared, indicated by \fB~\fR) by including the following modifiers
448 on the command line:
449 .sp
451 .sp
452 .TS
453 c c c
454 l l l .
455 Modifier Flag Description
456 _
457 \fB-interface\fR \fB~RTF_GATEWAY\fR Destination is directly reachable
458 \fB-iface\fR \fB~RTF_GATEWAY\fR Alias for interface modifier
459 \fB-static\fR \fBRTF_STATIC\fR Manually added route
460 \fB-nostatic\fR \fB~RTF_STATIC\fR T{
461 Pretend route was added by kernel or routing daemon
462 T}
463 \fB-reject\fR \fBRTF_REJECT\fR Emit an ICMP unreachable when matched
464 \fB-blackhole\fR \fBRTF_BLACKHOLE\fR Silently discard packets duing updates
465 \fB-proto1\fR \fBRTF_PROTO1\fR Set protocol specific routing flag #1
466 \fB-proto2\fR \fBRTF_PROTO2\fR Set protocol specific routing flag #2
467 \fB-private\fR \fBRTF_PRIVATE\fR Do not advertise this route
468 \fB-setsrc\fR \fBRTF_SETSRC\fR Assigns the default source address
469 .TE
471 .sp
472 .LP
473 The optional modifiers \fB-rtt\fR, \fB-rttvar\fR, \fB-sendpipe\fR,
474 \fB-recvpipe\fR, \fB-mtu\fR, \fB-hopcount\fR, \fB-expire\fR, and
475 \fB-ssthresh\fR provide initial values to quantities maintained in the routing
476 entry by transport level protocols, such as \fBTCP\fR. These can be
477 individually locked either by preceding each modifier to be locked by the
478 \fB-lock\fR meta-modifier, or by specifying that all ensuing metrics can be
479 locked by the \fB-lockrest\fR meta-modifier.
480 .sp
481 .LP
482 Some transport layer protocols can support only some of these metrics. The
483 following optional modifiers are supported:
484 .sp
485 .ne 2
486 .na
487 \fB\fB-expire\fR\fR
488 .ad
489 .RS 13n
490 Lifetime for the entry. This optional modifier is not currently supported.
491 .RE
493 .sp
494 .ne 2
495 .na
496 \fB\fB-hopcount\fR\fR
497 .ad
498 .RS 13n
499 Maximum hop count. This optional modifier is not currently supported.
500 .RE
502 .sp
503 .ne 2
504 .na
505 \fB\fB-mtu\fR\fR
506 .ad
507 .RS 13n
508 Maximum MTU in bytes.
509 .RE
511 .sp
512 .ne 2
513 .na
514 \fB\fB-recvpipe\fR\fR
515 .ad
516 .RS 13n
517 Receive pipe size in bytes.
518 .RE
520 .sp
521 .ne 2
522 .na
523 \fB\fB-rtt\fR\fR
524 .ad
525 .RS 13n
526 Round trip time in microseconds.
527 .RE
529 .sp
530 .ne 2
531 .na
532 \fB\fB-rttvar\fR\fR
533 .ad
534 .RS 13n
535 Round trip time variance in microseconds.
536 .RE
538 .sp
539 .ne 2
540 .na
541 \fB\fB-sendpipe\fR\fR
542 .ad
543 .RS 13n
544 Send pipe size in bytes.
545 .RE
547 .sp
548 .ne 2
549 .na
550 \fB\fB-ssthresh\fR\fR
551 .ad
552 .RS 13n
553 Send pipe size threshold in bytes.
554 .RE
556 .SS "Compatibility"
557 .LP
558 The modifiers \fBhost\fR and \fBnet\fR are taken to be equivalent to
559 \fB-\fR\fBhost\fR and \fB-net\fR\fB\fR. To specify a symbolic address that
560 matches one of these names, use the \fBdst\fR or \fBgateway\fR keyword to
561 distinguish it. For example: \fB\fR\fB-dst\fR \fBhost\fR
562 .sp
563 .LP
564 The following two flags are also accepted for compatibility with older systems,
565 but have no effect.
566 .sp
568 .sp
569 .TS
570 c c
571 l l .
572 Modifier Flag
573 _
574 \fB-cloning\fR RTF_CLONING
575 \fB-xresolve\fR RTF_XRESOLVE
576 .TE
578 .sp
579 .LP
580 The \fB\fR\fB-ifa\fR \fBhostname\fR modifier is also accepted, but has no
581 effect.
582 .SH FILES
583 .ne 2
584 .na
585 \fB\fB/etc/defaultrouter\fR\fR
586 .ad
587 .RS 22n
588 List of default routers
589 .RE
591 .sp
592 .ne 2
593 .na
594 \fB\fB/etc/hosts\fR\fR
595 .ad
596 .RS 22n
597 List of host names and net addresses
598 .RE
600 .sp
601 .ne 2
602 .na
603 \fB\fB/etc/networks\fR\fR
604 .ad
605 .RS 22n
606 List of network names and addresses
607 .RE
609 .SH SEE ALSO
610 .LP
611 \fBuname\fR(1), \fBin.ripngd\fR(8), \fBin.routed\fR(8), \fBnetstat\fR(8),
612 \fBrouted\fR(8), \fBioctl\fR(2), \fBgetipnodebyname\fR(3SOCKET),
613 \fBgetnetbyname\fR(3), \fBinet_addr\fR(3), \fBdefaultrouter\fR(4),
614 \fBhosts\fR(4), \fBnetworks\fR(4), \fBattributes\fR(5), \fBARP\fR(7P),
615 \fBip\fR(7P), \fBroute\fR(7P), \fBrouting\fR(7P)
616 .SH DIAGNOSTICS
617 .ne 2
618 .na
619 \fB\fBadd\fR [ \fBhost\fR\||\ \fBnetwork\|]\fR \fIdestination\fR:\fIgateway\fR
620 \fIflags\fR\fR
621 .ad
622 .sp .6
623 .RS 4n
624 The specified route is being added to the tables. The values printed are from
625 the routing table entry supplied in the \fBioctl\fR(2) call. If the gateway
626 address used was not the primary address of the gateway (the first one returned
627 by \fBgetipnodebyname\fR(3SOCKET)) the gateway address is printed numerically
628 as well as symbolically.
629 .RE
631 .sp
632 .ne 2
633 .na
634 \fB\fBdelete\fR [ \fBhost\fR\||\ \fBnetwork\fR\|]
635 \fIdestination\fR:\fIgateway\fR \fIflags\fR\fR
636 .ad
637 .br
638 .na
639 \fB\fBchange\fR [ \fBhost\fR\||\ \fBnetwork\fR\|]
640 \fIdestination\fR:\fIgateway\fR \fIflags\fR\fR
641 .ad
642 .sp .6
643 .RS 4n
644 As \fBadd\fR, but when deleting or changing an entry.
645 .RE
647 .sp
648 .ne 2
649 .na
650 \fB\fIdestination\fR \fBdone\fR\fR
651 .ad
652 .sp .6
653 .RS 4n
654 When the \fB-f\fR flag is specified, or the \fBflush\fR subcommand is used,
655 each routing table entry deleted is indicated with a message of this form.
656 .RE
658 .sp
659 .ne 2
660 .na
661 \fB\fBNetwork is unreachable\fR\fR
662 .ad
663 .sp .6
664 .RS 4n
665 An attempt to add a route failed because the gateway listed was not on a
666 directly-connected network. Give the next-hop gateway instead.
667 .RE
669 .sp
670 .ne 2
671 .na
672 \fB\fBnot in table\fR\fR
673 .ad
674 .sp .6
675 .RS 4n
676 A \fBdelete\fR operation was attempted for an entry that is not in the table.
677 .RE
679 .sp
680 .ne 2
681 .na
682 \fB\fBentry exists\fR\fR
683 .ad
684 .sp .6
685 .RS 4n
686 An \fBadd\fR operation was attempted for a route that already exists in the
687 kernel.
688 .RE
690 .sp
691 .ne 2
692 .na
693 \fB\fBrouting table overflow\fR\fR
694 .ad
695 .sp .6
696 .RS 4n
697 An operation was attempted, but the system was unable to allocate memory to
698 create the new entry.
699 .RE
701 .sp
702 .ne 2
703 .na
704 \fB\fBinsufficient privileges\fR\fR
705 .ad
706 .sp .6
707 .RS 4n
708 An attempt to add, delete, change, or flush a route failed because the calling
709 process does not have appropriate privileges.
710 .RE
712 .SH NOTES
713 .LP
714 Specifying that destinations are local (with the \fB-interface\fRmodifier)
715 assumes that the routers implement \fBproxy ARP\fR, meaning that they respond
716 to ARP queries for all reachable destinations. Normally, using either router
717 discovery or RIP is more reliable and scalable than using proxy ARP. See
718 \fBin.routed\fR(8) for information related to RIP.
719 .sp
720 .LP
721 Combining the all destinations are local route with subnet or network routes
722 can lead to unpredictable results. The search order as it relates to the all
723 destinations are local route are undefined and can vary from release to
724 release.