1.\" $OpenBSD: route.8,v 1.70 2012/07/13 10:15:53 benno Exp $ 2.\" $NetBSD: route.8,v 1.6 1995/03/18 15:00:13 cgd Exp $ 3.\" 4.\" Copyright (c) 1983, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)route.8 8.3 (Berkeley) 3/19/94 32.\" 33.Dd $Mdocdate: July 13 2012 $ 34.Dt ROUTE 8 35.Os 36.Sh NAME 37.Nm route 38.Nd manually manipulate the routing tables 39.Sh SYNOPSIS 40.Nm route 41.Op Fl dnqtv 42.Op Fl T Ar tableid 43.Ar command 44.Oo 45.Op Ar modifiers 46.Ar args 47.Oc 48.Sh DESCRIPTION 49.Nm 50is a utility used to manually view and manipulate the network routing tables. 51Except for setting up the default route, it normally is not needed to 52manipulate routes, as a 53system routing table management daemon, such as 54.Xr ripd 8 , 55.Xr ospfd 8 , 56or 57.Xr bgpd 8 , 58should tend to this task. 59.Pp 60.Nm 61can be used to modify nearly any aspect of the routing policy, 62except packet forwarding, which can be manipulated through the 63.Xr sysctl 8 64command. 65.Pp 66The 67.Nm 68utility supports a limited number of general options, 69but a rich command language enables the user to specify 70any arbitrary request that could be delivered via the 71programmatic interface discussed in 72.Xr route 4 . 73.Pp 74The options are as follows: 75.Bl -tag -width Ds 76.It Fl d 77Run in debug-only mode, i.e., don't actually modify the routing table. 78.It Fl n 79Bypass attempts to print host and network names symbolically 80when reporting actions. 81(The process of translating between symbolic 82names and numerical equivalents can be quite time consuming, and 83may require correct operation of the network; thus it may be expedient 84to forgo this, especially when attempting to repair networking operations.) 85.It Fl q 86Suppress all output. 87.It Fl T Ar tableid 88Select an alternate routing table to modify or query. 89Table 0 is the default table. 90.It Fl t 91Write routing messages to a fake device 92.Pa ( /dev/null ) 93instead of a real routing socket to test route manipulation. 94.It Fl v 95(verbose) Print additional details. 96.El 97.Pp 98The 99.Nm 100utility provides the following simple commands: 101.Bl -tag -width Fl 102.It Xo 103.Nm route 104.Op Fl T Ar tableid 105.Cm exec 106.Op Ar command ... 107.Xc 108Execute a command forcing the process and its children into the 109routing domain as specified with the 110.Fl T Ar tableid 111option. 112.It Xo 113.Nm route 114.Op Fl nqv 115.Op Fl T Ar tableid 116.Cm flush 117.Op Ar modifiers 118.Xc 119Delete all gateway entries from the routing table. 120When the address family is specified by any one of the 121.Ar family 122modifiers (listed below), only routes having destinations with addresses 123in the delineated family will be deleted. 124Also, only routes matching a specific interface or priority can be flushed 125by using the 126.Fl iface 127or 128.Fl priority 129modifiers. 130.It Xo 131.Nm route 132.Op Fl nv 133.Op Fl T Ar tableid 134.Cm get 135.Op Ar modifiers 136.Ar address 137.Xc 138Extract a routing entry from the kernel. 139If 140.Fl gateway 141is specified, only routes whose gateway are in the 142same address family as the destination are shown. 143.It Xo 144.Nm 145.Op Fl n 146.Cm monitor 147.Op Ar modifiers 148.Xc 149Continuously report any changes to the routing information base, 150routing lookup misses, or suspected network partitionings. 151.Pp 152When the address family is specified by any one of the 153.Ar family 154modifiers (listed below), only routes having destinations with addresses 155in the delineated family will be shown. 156If the 157.Fl iface 158modifier is used only interface specific messages (link state changes) 159are shown. 160.It Xo 161.Nm route 162.Op Fl nv 163.Op Fl T Ar tableid 164.Cm show 165.Op Ar family 166.Op Fl gateway 167.Op Fl label Ar label 168.Xc 169Print out the route table similar to "netstat -r" (see 170.Xr netstat 1 ) . 171.Pp 172If 173.Fl gateway 174is specified, only routes whose gateway are in the 175same address family as the destination are shown. 176.Pp 177If 178.Fl label 179is specified, only routes with the specified label are shown. 180.El 181.Pp 182The other commands relating to adding, changing, or deleting routes 183have the syntax: 184.Pp 185.Bl -tag -width Fl -compact 186.It Xo 187.Nm route 188.Op Fl dnqtv 189.Op Fl T Ar tableid 190.Cm add 191.Op Ar modifiers 192.Ar destination gateway 193.Xc 194.It Xo 195.Nm route 196.Op Fl dnqtv 197.Op Fl T Ar tableid 198.Cm change 199.Op Ar modifiers 200.Ar destination gateway 201.Xc 202.It Xo 203.Nm route 204.Op Fl dnqtv 205.Op Fl T Ar tableid 206.Cm delete 207.Op Ar modifiers 208.Ar destination gateway 209.Xc 210.El 211.Pp 212.Ar destination 213is the destination host or network; 214.Ar gateway 215is the next-hop intermediary via which packets should be routed. 216Routes to a particular host may be distinguished from those to 217a network by interpreting the Internet address specified as the 218.Ar destination 219argument. 220The optional modifiers 221.Fl net 222and 223.Fl host 224cause the destination to be interpreted as a network or a host, respectively. 225Otherwise, type is chosen based on the following rules: 226.Pp 227The route is assumed to be to a network if any of the following apply to 228.Ar destination : 229.Pp 230.Bl -bullet -compact 231.It 232it is the word "default", equivalent to 0/0 233.It 234it is an IPv4 address with less than 3 dots 235.It 236it is an IPv4 address with a 237.Dq / Ns Em XX 238suffix (where 239.Em XX 240is the number of bits in the network portion of the address 241and is less than 32) 242.It 243it is an IPv6 address with a 244.Dq / Ns Em XX 245suffix (where 246.Em XX 247is the number of bits in the network portion of the address 248and is less than 128) 249.It 250it is the symbolic name of a network. 251.El 252.Pp 253If 254.Ar destination 255is a valid IP address or host name, it is presumed to be a route to a host. 256.Pp 257For example, 258.Li 192.168.1.1 259is interpreted as 260.Fl host Li 192.168.1.1 261and 262.Li 192.168.1 263is interpreted as 264.Fl net Li 192.168.1 . 265Note, however, that 266.Li 192.168.2.0 267will be interpreted as 268.Fl host Li 192.168.2.0 269since it is a complete IP address with 3 dots. 270In this case the number of bits in the network portion of the address must 271be explicitly listed, for example 272.Li 192.168.2.0/24 , 273.Li 192.168.2/24 , 274or alternately 275.Li 192.168.2 . 276.Pp 277If the destination is directly reachable 278via an interface requiring 279no intermediary system to act as a gateway, the 280.Fl iface 281modifier should be specified; 282the gateway given is the address of this host on the common network, 283indicating the interface to be used for transmission. 284.Pp 285To allow addresses to be interpreted as belonging to a particular address 286family (as well as for use in the 287.Ar family 288arguments to some commands), the following modifiers may be used: 289.Pp 290.Bl -tag -width -inet6 -compact 291.It Fl inet 292Internet Protocol version 4 (IPv4) addresses 293(see 294.Xr ip 4 ) 295.It Fl inet6 296Internet Protocol version 6 (IPv6) addresses 297(see 298.Xr ip6 4 ) 299.It Fl encap 300IPsec 301(see 302.Xr ipsec 4 ) 303.It Fl link 304Hardware (link-level) addresses 305.It Fl mpls 306MPLS addresses 307.It Fl sa 308Actual 309.Vt sockaddr 310data, in hexadecimal format 311.El 312.Pp 313The optional modifier 314.Fl link 315specifies that all subsequent addresses are specified as link-level addresses, 316and the names must be numeric specifications rather than 317symbolic names. 318.Pp 319The optional 320.Fl netmask 321qualifier is intended to manually add subnet routes with 322netmasks different from that of the implied network interface 323(as would otherwise be communicated using a routing protocol). 324One specifies an additional ensuing address parameter 325(to be interpreted as a network mask). 326The implicit network mask generated in the 327.Dv AF_INET 328case 329can be overridden by making sure this option follows the 330.Ar destination 331parameter. 332.Fl prefixlen 333is also available for a similar purpose, for IPv6/v4. 334.Pp 335A specific routing priority can be specified with the optional 336.Fl priority 337qualifier. 338If no priority is specified the kernel will set a priority depending on the 339RTF_STATIC flag to either RTP_STATIC or RTP_DEFAULT. 340.Pp 341The optional 342.Fl mpath 343modifier needs to be specified with the 344.Cm add 345command to be able to enter multiple gateways for the same destination address 346(multipath). 347When multiple routes exist for a destination, one route is selected based 348on the source address of the packet. 349The 350.Xr sysctl 8 351variables 352.Va net.inet.ip.multipath 353and 354.Va net.inet6.ip6.multipath 355are used to control multipath routing. 356If set to 1, 357multiple routes with the same priority are used equally; 358if set to 0, 359the first route selected will be used for subsequent packets to that 360destination regardless of source. 361.Pp 362When inserting MPLS routes, 363particular modifiers must be used. 364The 365.Fl mplslabel 366modifier needs to be specified in an ingress LSR to associate a particular 367label to an IPv4/IPv6 route. 368The MPLS traffic 369.Fl in 370and 371.Fl out 372modifiers are intended to identify the ingress label and, optionally, 373the outgoing one. 374Additionally, one of the following operations must be used: 375.Fl push , 376.Fl pop 377and 378.Fl swap . 379Route's nexthop can be specified with the modifier 380.Fl inet . 381.Pp 382Routes have associated flags which influence operation of the protocols 383when sending to destinations matched by the routes. 384These flags may be set (or sometimes cleared) 385by indicating the following corresponding modifiers: 386.Bl -column "-blackhole" "RTF_BLACKHOLE" "description" 387.It Fl blackhole Ta Dv RTF_BLACKHOLE Ta "silently discard pkts (during updates)" 388.It Fl cloning Ta Dv RTF_CLONING Ta "generates a new route on use" 389.It Fl iface Ta Dv ~RTF_GATEWAY Ta "destination is directly reachable" 390.It Fl llinfo Ta Dv RTF_LLINFO Ta "validly translates proto addr to link addr" 391.It Fl mpath Ta Dv RTF_MPATH Ta "multiple gateways for a destination exist" 392.It Fl nostatic Ta Dv ~RTF_STATIC Ta "pretend route added by kernel or daemon" 393.It Fl proto1 Ta Dv RTF_PROTO1 Ta "set protocol specific routing flag #1" 394.It Fl proto2 Ta Dv RTF_PROTO2 Ta "set protocol specific routing flag #2" 395.It Fl reject Ta Dv RTF_REJECT Ta "emit an ICMP unreachable when matched" 396.It Fl static Ta Dv RTF_STATIC Ta "manually added route" 397.It Fl xresolve Ta Dv RTF_XRESOLVE Ta "emit mesg on use (for external lookup)" 398.El 399.Pp 400The optional modifiers 401.Fl expire 402and 403.Fl mtu 404provide initial values to quantities maintained in the routing entry 405by transport level protocols, such as TCP (see 406.Xr tcp 4 ) . 407They have the following meanings: 408.Pp 409.Bl -tag -width "-priority n" -compact 410.It Fl expire Ar n 411Lifetime for route (e.g., if generated by a redirect). 412.It Fl mtu Ar n 413Maximum transmission unit 414.Tn ( MTU ) 415size for this path. 416.El 417.Pp 418These may be individually locked by preceding each such modifier to 419be locked by 420the 421.Fl lock 422meta-modifier, or one can 423specify that all ensuing metrics may be locked by the 424.Fl lockrest 425meta-modifier. 426.Pp 427In a 428.Cm change 429or 430.Cm add 431command where the destination and gateway are not sufficient to specify 432the route, the 433.Fl ifp 434or 435.Fl ifa 436modifiers may be used to determine the interface name or interface address. 437.Pp 438The optional 439.Fl genmask 440modifier specifies that a cloning mask is present. 441This specifies the mask applied when determining if a child route should 442be created. 443It is only applicable to network routes with the 444.Dv RTF_CLONING 445flag set. 446.Pp 447The optional 448.Fl label 449modifier specifies on route addition or modification that the route 450should have the given 451.Em label 452associated with it. 453Route labels can be used to attach arbitrary information to a route. 454.Pp 455All symbolic names specified for a 456.Ar destination 457or 458.Ar gateway 459are looked up first as a network name using 460.Xr getnetbyname 3 . 461If this lookup fails, 462.Xr gethostbyname 3 463is then used to interpret the name as a valid host name. 464.Pp 465.Nm 466uses a routing socket (see 467.Xr route 4 ) 468and the message types 469.Dv RTM_ADD , 470.Dv RTM_DELETE , 471.Dv RTM_GET , 472and 473.Dv RTM_CHANGE . 474As such, only the superuser may modify 475the routing tables. 476.Sh FILES 477.Bl -tag -width "/etc/networks" -compact 478.It Pa /etc/hosts 479host name database 480.It Pa /etc/mygate 481default gateway address 482.It Pa /etc/networks 483network name database 484.El 485.Sh EXAMPLES 486Add a static 487.Xr inet 4 488route to the 192.168.5.0/24 network via the 192.168.0.1 gateway: 489.Pp 490.Dl # route add -inet 192.168.5.0/24 192.168.0.1 491.Pp 492Amend the 493.Xr inet 4 494route to the 192.168.5.0/24 network to use the 192.168.0.2 gateway: 495.Pp 496.Dl # route change -inet 192.168.5.0/24 192.168.0.2 497.Pp 498Delete the 499.Xr inet 4 500route to the 192.168.5.0/24 network: 501.Pp 502.Dl # route delete -inet 192.168.5.0/24 503.Sh DIAGNOSTICS 504.Bl -diag 505.It "%s: gateway %s flags %x" 506The specified route is being added to or deleted from the tables. 507The values printed are from the routing table entry supplied in the 508.Xr ioctl 2 509call. 510If the gateway address used was not the primary address of the gateway 511(the first one returned by 512.Xr gethostbyname 3 ) , 513the gateway address is printed numerically as well as symbolically. 514.It "%s %s done" 515When the 516.Cm flush 517command is specified, each routing table entry deleted 518is indicated with a message of this form. 519.It "Network is unreachable" 520An attempt to add a route failed because the gateway listed was not 521on a directly connected network. 522The next-hop gateway must be given. 523.It "not in table" 524A 525.Cm delete 526operation was attempted for an entry which 527wasn't present in the tables. 528.It "routing table overflow" 529An 530.Cm add 531operation was attempted, but the system was 532low on resources and was unable to allocate memory 533to create the new entry. 534.El 535.Sh SEE ALSO 536.Xr netstat 1 , 537.Xr gethostbyname 3 , 538.Xr getnetbyname 3 , 539.Xr netintro 4 , 540.Xr route 4 , 541.Xr tcp 4 , 542.Xr hosts 5 , 543.Xr mygate 5 , 544.Xr networks 5 , 545.Xr bgpd 8 , 546.Xr ospfd 8 , 547.Xr ripd 8 , 548.Xr sysctl 8 549.Sh HISTORY 550The 551.Nm 552command appeared in 553.Bx 4.2 . 554IPv6 support was added by WIDE/KAME project. 555.Pp 556The 557.Fl recvpipe , 558.Fl hopcount , 559.Fl sendpipe , 560.Fl ssthres , 561.Fl rtt , 562and 563.Fl rttvar 564modifiers used to be used to initialize various quantities in routing 565table entries. 566The routing system no longer uses these values and the modifiers 567exist now only for compatibility with other operating systems. 568.Sh BUGS 569Some uses of the 570.Fl ifa 571or 572.Fl ifp 573modifiers with the 574.Cm add 575command will incorrectly fail with a 576.Dq Network is unreachable 577message if there is no default route. 578See case 579.Dv RTM_ADD 580in 581.Fn route_output 582from 583.Pa sys/net/rtsock.c 584for details. 585