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