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