1.\" $OpenBSD: route.8,v 1.78 2015/09/11 20:08:40 mpi 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: September 11 2015 $ 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. 89The default is to use the current routing 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 to use the 109routing table and appropriate routing 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.Op Fl priority Ar priority 169.Xc 170Print out the route table similar to "netstat -r" (see 171.Xr netstat 1 ) . 172.Pp 173If 174.Fl gateway 175is specified, only routes whose gateway are in the 176same address family as the destination are shown. 177.Pp 178If 179.Fl label 180is specified, only routes with the specified label are shown. 181.Pp 182If 183.Fl priority 184is specified, only routes with the specified (numeric) priority are shown. 185Some well known priorities can be given by name. 186If the priority is negative, then routes that do not match the numeric 187priority are shown. 188.El 189.Pp 190The other commands relating to adding, changing, or deleting routes 191have the syntax: 192.Pp 193.Bl -tag -width Fl -compact 194.It Xo 195.Nm route 196.Op Fl dnqtv 197.Op Fl T Ar tableid 198.Cm add 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 change 207.Op Ar modifiers 208.Ar destination gateway 209.Xc 210.It Xo 211.Nm route 212.Op Fl dnqtv 213.Op Fl T Ar tableid 214.Cm delete 215.Op Ar modifiers 216.Ar destination gateway 217.Xc 218.El 219.Pp 220.Ar destination 221is the destination host or network; 222.Ar gateway 223is the next-hop intermediary via which packets should be routed. 224Routes to a particular host may be distinguished from those to 225a network by interpreting the Internet address specified as the 226.Ar destination 227argument. 228The optional modifiers 229.Fl net 230and 231.Fl host 232cause the destination to be interpreted as a network or a host, respectively. 233Otherwise, type is chosen based on the following rules: 234.Pp 235The route is assumed to be to a network if any of the following apply to 236.Ar destination : 237.Pp 238.Bl -bullet -compact 239.It 240it is the word "default", equivalent to 0/0 241.It 242it is an IPv4 address with less than 3 dots 243.It 244it is an IPv4 address with a 245.Dq / Ns Em XX 246suffix (where 247.Em XX 248is the number of bits in the network portion of the address 249and is less than 32) 250.It 251it is an IPv6 address with a 252.Dq / Ns Em XX 253suffix (where 254.Em XX 255is the number of bits in the network portion of the address 256and is less than 128) 257.It 258it is the symbolic name of a network. 259.El 260.Pp 261If 262.Ar destination 263is a valid IP address or host name, it is presumed to be a route to a host. 264.Pp 265For example, 266.Li 192.168.1.1 267is interpreted as 268.Fl host Li 192.168.1.1 269and 270.Li 192.168.1 271is interpreted as 272.Fl net Li 192.168.1 . 273Note, however, that 274.Li 192.168.2.0 275will be interpreted as 276.Fl host Li 192.168.2.0 277since it is a complete IP address with 3 dots. 278In this case the number of bits in the network portion of the address must 279be explicitly listed, for example 280.Li 192.168.2.0/24 , 281.Li 192.168.2/24 , 282or alternately 283.Li 192.168.2 . 284.Pp 285If the destination is directly reachable 286via an interface requiring 287no intermediary system to act as a gateway, the 288.Fl iface 289modifier should be specified; 290the gateway given is the address of this host on the common network, 291indicating the interface to be used for transmission. 292.Pp 293To allow addresses to be interpreted as belonging to a particular address 294family (as well as for use in the 295.Ar family 296arguments to some commands), the following modifiers may be used: 297.Pp 298.Bl -tag -width -inet6 -compact 299.It Fl inet 300Internet Protocol version 4 (IPv4) addresses 301(see 302.Xr ip 4 ) 303.It Fl inet6 304Internet Protocol version 6 (IPv6) addresses 305(see 306.Xr ip6 4 ) 307.It Fl link 308Hardware (link-level) addresses 309.It Fl mpls 310MPLS addresses 311.It Fl sa 312Actual 313.Vt sockaddr 314data, in hexadecimal format 315.El 316.Pp 317In the absence of modifiers, an address is assumed to be IPv4, 318unless containing a 319.Sq :\& 320character, when it is treated as IPv6. 321.Pp 322The optional modifier 323.Fl link 324specifies that all subsequent addresses are specified as link-level addresses, 325and the names must be numeric specifications rather than 326symbolic names. 327.Pp 328The optional 329.Fl netmask 330qualifier is intended to manually add subnet routes with 331netmasks different from that of the implied network interface 332(as would otherwise be communicated using a routing protocol). 333One specifies an additional ensuing address parameter 334(to be interpreted as a network mask). 335The implicit network mask generated in the 336.Dv AF_INET 337case 338can be overridden by making sure this option follows the 339.Ar destination 340parameter. 341.Fl prefixlen 342is also available for a similar purpose, for IPv6/v4. 343.Pp 344A specific routing priority can be specified with the optional 345.Fl priority 346qualifier. 347If no priority is specified the kernel will set a priority depending on the 348RTF_STATIC flag to either RTP_STATIC or RTP_DEFAULT. 349Note that priority 1 is reserved for kernel use. 350.Pp 351The optional 352.Fl mpath 353modifier needs to be specified with the 354.Cm add 355command to be able to enter multiple gateways for the same destination address 356(multipath). 357When multiple routes exist for a destination, one route is selected based 358on the source address of the packet. 359The 360.Xr sysctl 8 361variables 362.Va net.inet.ip.multipath 363and 364.Va net.inet6.ip6.multipath 365are used to control multipath routing. 366If set to 1, 367multiple routes with the same priority are used equally; 368if set to 0, 369the first route selected will be used for subsequent packets to that 370destination regardless of source. 371.Pp 372When inserting MPLS routes, 373particular modifiers must be used. 374The 375.Fl mplslabel 376modifier needs to be specified in an ingress LSR to associate a particular 377label to an IPv4/IPv6 route. 378The MPLS traffic 379.Fl in 380and 381.Fl out 382modifiers are intended to identify the ingress label and, optionally, 383the outgoing one. 384Additionally, one of the following operations must be used: 385.Fl push , 386.Fl pop 387and 388.Fl swap . 389Route's nexthop can be specified with the modifier 390.Fl inet . 391.Pp 392Routes have associated flags which influence operation of the protocols 393when sending to destinations matched by the routes. 394These flags may be set (or sometimes cleared) 395by indicating the following corresponding modifiers: 396.Bl -column "-blackhole" "RTF_BLACKHOLE" "description" 397.It Fl blackhole Ta Dv RTF_BLACKHOLE Ta "silently discard pkts (during updates)" 398.It Fl cloning Ta Dv RTF_CLONING Ta "generates a new route on use" 399.It Fl iface Ta Dv ~RTF_GATEWAY Ta "destination is directly reachable" 400.It Fl llinfo Ta Dv RTF_LLINFO Ta "validly translates proto addr to link addr" 401.It Fl mpath Ta Dv RTF_MPATH Ta "multiple gateways for a destination exist" 402.It Fl nostatic Ta Dv ~RTF_STATIC Ta "pretend route added by kernel or daemon" 403.It Fl proto1 Ta Dv RTF_PROTO1 Ta "set protocol specific routing flag #1" 404.It Fl proto2 Ta Dv RTF_PROTO2 Ta "set protocol specific routing flag #2" 405.It Fl reject Ta Dv RTF_REJECT Ta "emit an ICMP unreachable when matched" 406.It Fl static Ta Dv RTF_STATIC Ta "manually added route" 407.El 408.Pp 409The optional modifiers 410.Fl expire 411and 412.Fl mtu 413provide initial values to quantities maintained in the routing entry 414by transport level protocols, such as TCP (see 415.Xr tcp 4 ) . 416They have the following meanings: 417.Pp 418.Bl -tag -width "-priority n" -compact 419.It Fl expire Ar n 420Lifetime for route (e.g., if generated by a redirect). 421.It Fl mtu Ar n 422Maximum transmission unit 423.Tn ( MTU ) 424size for this path. 425.El 426.Pp 427These may be individually locked by preceding each such modifier to 428be locked by 429the 430.Fl lock 431meta-modifier, or one can 432specify that all ensuing metrics may be locked by the 433.Fl lockrest 434meta-modifier. 435.Pp 436In a 437.Cm change 438or 439.Cm add 440command where the destination and gateway are not sufficient to specify 441the route, the 442.Fl ifp 443or 444.Fl ifa 445modifiers may be used to determine the interface name or interface address. 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. 507If the gateway address used was not the primary address of the gateway 508(the first one returned by 509.Xr gethostbyname 3 ) , 510the gateway address is printed numerically as well as symbolically. 511.It "%s %s done" 512When the 513.Cm flush 514command is specified, each routing table entry deleted 515is indicated with a message of this form. 516.It "Network is unreachable" 517An attempt to add a route failed because the gateway listed was not 518on a directly connected network. 519The next-hop gateway must be given. 520.It "not in table" 521A 522.Cm delete 523operation was attempted for an entry which 524wasn't present in the tables. 525.It "routing table overflow" 526An 527.Cm add 528operation was attempted, but the system was 529low on resources and was unable to allocate memory 530to create the new entry. 531.El 532.Sh SEE ALSO 533.Xr netstat 1 , 534.Xr gethostbyname 3 , 535.Xr getnetbyname 3 , 536.Xr netintro 4 , 537.Xr route 4 , 538.Xr tcp 4 , 539.Xr hosts 5 , 540.Xr mygate 5 , 541.Xr networks 5 , 542.Xr bgpd 8 , 543.Xr ospfd 8 , 544.Xr ripd 8 , 545.Xr sysctl 8 546.Sh HISTORY 547The 548.Nm 549command appeared in 550.Bx 4.2 . 551IPv6 support was added by WIDE/KAME project. 552.Pp 553The 554.Fl recvpipe , 555.Fl hopcount , 556.Fl sendpipe , 557.Fl ssthres , 558.Fl rtt , 559and 560.Fl rttvar 561modifiers used to be used to initialize various quantities in routing 562table entries. 563The routing system no longer uses these values and the modifiers 564exist now only for compatibility with other operating systems. 565.Sh BUGS 566Some uses of the 567.Fl ifa 568or 569.Fl ifp 570modifiers with the 571.Cm add 572command will incorrectly fail with a 573.Dq Network is unreachable 574message if there is no default route. 575See case 576.Dv RTM_ADD 577in 578.Fn route_output 579from 580.Pa sys/net/rtsock.c 581for details. 582