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