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