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 October 17, 2013 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-proto3 RTF_PROTO3 - set protocol specific routing flag #3 305.Ed 306.Pp 307The optional modifiers 308.Fl rtt , 309.Fl rttvar , 310.Fl sendpipe , 311.Fl recvpipe , 312.Fl mtu , 313.Fl hopcount , 314.Fl expire , 315and 316.Fl ssthresh 317provide initial values to quantities maintained in the routing entry 318by transport level protocols, such as TCP or TP4. 319These may be individually locked by preceding each such modifier to 320be locked by 321the 322.Fl lock 323meta-modifier, or one can 324specify that all ensuing metrics may be locked by the 325.Fl lockrest 326meta-modifier. 327.Pp 328Note that 329.Fl expire 330accepts expiration time of the route as the number of seconds since the 331Epoch 332.Pq see Xr time 3 . 333When the first character of the number is 334.Dq + 335or 336.Dq - , 337it is interpreted as a value relative to the current time. 338.Pp 339The optional modifier 340.Fl fib Ar number 341specifies that the command will be applied to a non-default FIB. 342The 343.Ar number 344must be smaller than the 345.Va net.fibs 346.Xr sysctl 8 347MIB. 348When this modifier is not specified, 349or a negative number is specified, 350the default FIB shown in the 351.Va net.my_fibnum 352.Xr sysctl 8 353MIB will be used. 354.Pp 355The 356.Ar number 357allows multiple FIBs by a comma-separeted list and/or range 358specification. 359The 360.Qq Fl fib Li 2,4,6 361means the FIB number 2, 4, and 6. 362The 363.Qq Fl fib Li 1,3-5,6 364means the 1, 3, 4, 5, and 6. 365.Pp 366In a 367.Cm change 368or 369.Cm add 370command where the destination and gateway are not sufficient to specify 371the route (as in the 372.Tn ISO 373case where several interfaces may have the 374same address), the 375.Fl ifp 376or 377.Fl ifa 378modifiers may be used to determine the interface or interface address. 379.Pp 380All symbolic names specified for a 381.Ar destination 382or 383.Ar gateway 384are looked up first as a host name using 385.Xr gethostbyname 3 . 386If this lookup fails, 387.Xr getnetbyname 3 388is then used to interpret the name as that of a network. 389.Pp 390The 391.Nm 392utility uses a routing socket and the new message types 393.Dv RTM_ADD , RTM_DELETE , RTM_GET , 394and 395.Dv RTM_CHANGE . 396As such, only the super-user may modify 397the routing tables. 398.Sh EXIT STATUS 399.Ex -std 400.Sh EXAMPLES 401Add a default route to the network routing table. 402This will send all packets for destinations not available in the routing table 403to the default gateway at 192.168.1.1: 404.Pp 405.Dl route add -net 0.0.0.0/0 192.168.1.1 406.Pp 407A shorter version of adding a default route can also be written as: 408.Pp 409.Dl route add default 192.168.1.1 410.Pp 411Add a static route to the 172.16.10.0/24 network via the 172.16.1.1 gateway: 412.Pp 413.Dl route add -net 172.16.10.0/24 172.16.1.1 414.Pp 415Change the gateway of an already established static route in the routing table: 416.Pp 417.Dl route change -net 172.16.10.0/24 172.16.1.2 418.Pp 419Display the route for a destination network: 420.Pp 421.Dl route show 172.16.10.0 422.Pp 423Delete a static route from the routing table: 424.Pp 425.Dl route delete -net 172.16.10.0/24 172.16.1.2 426.Pp 427Remove all routes from the routing table: 428.Pp 429.Dl route flush 430.Sh DIAGNOSTICS 431.Bl -diag 432.It "add [host \&| network ] %s: gateway %s flags %x" 433The specified route is being added to the tables. 434The 435values printed are from the routing table entry supplied 436in the 437.Xr ioctl 2 438call. 439If the gateway address used was not the primary address of the gateway 440(the first one returned by 441.Xr gethostbyname 3 ) , 442the gateway address is printed numerically as well as symbolically. 443.It "delete [ host \&| network ] %s: gateway %s flags %x" 444As above, but when deleting an entry. 445.It "%s %s done" 446When the 447.Cm flush 448command is specified, each routing table entry deleted 449is indicated with a message of this form. 450.It "Network is unreachable" 451An attempt to add a route failed because the gateway listed was not 452on a directly-connected network. 453The next-hop gateway must be given. 454.It "not in table" 455A delete operation was attempted for an entry which 456was not present in the tables. 457.It "routing table overflow" 458An add operation was attempted, but the system was 459low on resources and was unable to allocate memory 460to create the new entry. 461.It "gateway uses the same route" 462A 463.Cm change 464operation resulted in a route whose gateway uses the 465same route as the one being changed. 466The next-hop gateway should be reachable through a different route. 467.El 468.Sh SEE ALSO 469.\".Xr esis 4 , 470.Xr netintro 4 , 471.Xr route 4 , 472.Xr arp 8 , 473.Xr IPXrouted 8 , 474.Xr routed 8 475.\".Xr XNSrouted 8 476.Sh HISTORY 477The 478.Nm 479utility appeared in 480.Bx 4.2 . 481.Sh BUGS 482The first paragraph may have slightly exaggerated 483.Xr routed 8 Ns 's 484abilities. 485.Pp 486Currently, routes with the 487.Dv RTF_BLACKHOLE 488flag set need to have the gateway set to an instance of the 489.Xr lo 4 490driver, using the 491.Fl iface 492option, for the flag to have any effect; unless IP fast forwarding 493is enabled, in which case the meaning of the flag will always 494be honored. 495