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