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