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