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