1.\" $OpenBSD: route.8,v 1.95 2021/01/02 15:35:24 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 2 2021 $ 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.Bl -tag -width Fl -compact 201.It Xo 202.Ic route 203.Op Fl T Ar rtable 204.Tg 205.Cm sourceaddr 206.Op Fl inet Ns | Ns Fl inet6 207.Op Ar address 208.Xc 209.It Xo 210.Ic route 211.Op Fl T Ar rtable 212.Tg 213.Cm sourceaddr 214.Op Fl inet Ns | Ns Fl inet6 215.Fl ifp 216.Ar interface 217.Xc 218.Pp 219Set the preferred source address. 220If 221.Ar address 222is the word "default", 0.0.0.0 or ::, source address will 223be chosen by the kernel for the matching address family. 224When 225.Ar address 226is omitted, preferred source address is printed if set. 227If 228.Fl ifp 229is used, source will use IP assigned to 230.Ar interface . 231The preferred source will not be used when: 232.Pp 233.Bl -bullet -compact 234.It 235destination is on-link 236.It 237source address is assigned to a disabled interface 238.El 239.El 240.Pp 241.Tg destination 242.Tg gateway 243The other commands relating to adding, changing, or deleting routes 244have the syntax: 245.Pp 246.Bl -tag -width Fl -compact 247.It Xo 248.Nm route 249.Op Fl dnqtv 250.Op Fl T Ar rtable 251.Tg 252.Cm add 253.Op Ar modifiers 254.Ar destination gateway 255.Xc 256.It Xo 257.Nm route 258.Op Fl dnqtv 259.Op Fl T Ar rtable 260.Tg 261.Cm change 262.Op Ar modifiers 263.Ar destination gateway 264.Xc 265.It Xo 266.Nm route 267.Op Fl dnqtv 268.Op Fl T Ar rtable 269.Tg 270.Cm del Ns Op Cm ete 271.Op Ar modifiers 272.Ar destination gateway 273.Xc 274.El 275.Pp 276.Ar destination 277is the destination host or network; 278.Ar gateway 279is the next-hop intermediary via which packets should be routed. 280Routes to a particular host may be distinguished from those to 281a network by interpreting the Internet address specified as the 282.Ar destination 283argument. 284The optional modifiers 285.Tg 286.Fl net 287and 288.Tg 289.Fl host 290cause the destination to be interpreted as a network or a host, respectively. 291Otherwise, type is chosen based on the following rules: 292.Pp 293.Tg default 294The route is assumed to be to a network if any of the following apply to 295.Ar destination : 296.Pp 297.Bl -bullet -compact 298.It 299it is the word "default", equivalent to 0/0 300.It 301it is an IPv4 address with less than 3 dots 302.It 303it is an IPv4 address with a 304.Dq / Ns Em XX 305suffix (where 306.Em XX 307is the number of bits in the network portion of the address 308and is less than 32) 309.It 310it is an IPv6 address with a 311.Dq / Ns Em XX 312suffix (where 313.Em XX 314is the number of bits in the network portion of the address 315and is less than 128) 316.It 317it is the symbolic name of a network. 318.El 319.Pp 320If 321.Ar destination 322is a valid IP address or host name, it is presumed to be a route to a host. 323.Pp 324For example, 325.Li 192.168.1.1 326is interpreted as 327.Fl host Li 192.168.1.1 328and 329.Li 192.168.1 330is interpreted as 331.Fl net Li 192.168.1 . 332Note, however, that 333.Li 192.168.2.0 334will be interpreted as 335.Fl host Li 192.168.2.0 336since it is a complete IP address with 3 dots. 337In this case the number of bits in the network portion of the address must 338be explicitly listed, for example 339.Li 192.168.2.0/24 , 340.Li 192.168.2/24 , 341or alternately 342.Li 192.168.2 . 343.Pp 344If the destination is directly reachable 345via an interface requiring 346no intermediary system to act as a gateway, the 347.Tg 348.Fl iface 349modifier should be specified; 350the gateway given is the address of this host on the common network, 351indicating the interface to be used for transmission. 352.Pp 353To allow addresses to be interpreted as belonging to a particular address 354family (as well as for use in the 355.Tg 356.Ar family 357arguments to some commands), the following modifiers may be used: 358.Pp 359.Bl -tag -width -inet6 -compact 360.It Fl inet 361Internet Protocol version 4 (IPv4) addresses 362(see 363.Xr ip 4 ) 364.It Fl inet6 365Internet Protocol version 6 (IPv6) addresses 366(see 367.Xr ip6 4 ) 368.It Fl link 369Hardware (link-level) addresses 370.It Fl mpls 371MPLS addresses 372.It Fl sa 373Actual 374.Vt sockaddr 375data, in hexadecimal format 376.El 377.Pp 378In the absence of modifiers, an address is assumed to be IPv4, 379unless containing a 380.Sq :\& 381character, when it is treated as IPv6. 382.Pp 383The optional modifier 384.Fl link 385specifies that all subsequent addresses are specified as link-level addresses, 386and the names must be numeric specifications rather than 387symbolic names. 388.Pp 389The optional 390.Tg 391.Fl netmask 392qualifier is intended to manually add subnet routes with 393netmasks different from that of the implied network interface 394(as would otherwise be communicated using a routing protocol). 395One specifies an additional ensuing address parameter 396(to be interpreted as a network mask). 397The implicit network mask generated in the 398.Dv AF_INET 399case 400can be overridden by making sure this option follows the 401.Ar destination 402parameter. 403.Tg 404.Fl prefixlen 405is also available for a similar purpose, for IPv6/v4. 406.Pp 407A specific routing priority can be specified with the optional 408.Tg 409.Fl priority 410qualifier. 411If no priority is specified the kernel will set a priority depending on the 412.Dv RTF_STATIC 413flag to either 414.Dv RTP_STATIC 415or 416.Dv RTP_DEFAULT . 417Note that priority 1 is reserved for kernel use. 418.Pp 419The optional 420.Tg 421.Fl mpath 422modifier needs to be specified with the 423.Cm add 424command to be able to enter multiple gateways for the same destination address 425(multipath). 426When multiple routes exist for a destination, one route is selected based 427on the source address of the packet. 428The 429.Xr sysctl 8 430variables 431.Va net.inet.ip.multipath 432and 433.Va net.inet6.ip6.multipath 434are used to control multipath routing. 435If set to 1, 436multiple routes with the same priority are used equally; 437if set to 0, 438the first route selected will be used for subsequent packets to that 439destination regardless of source. 440.Pp 441When inserting MPLS routes, 442particular modifiers must be used. 443The 444.Tg 445.Fl mplslabel 446modifier needs to be specified in an ingress LSR to associate a particular 447label to an IPv4/IPv6 route. 448The MPLS traffic 449.Fl in 450and 451.Fl out 452modifiers are intended to identify the ingress label and, optionally, 453the outgoing one. 454Additionally, one of the following operations must be used: 455.Fl push , 456.Fl pop 457and 458.Fl swap . 459Route's nexthop can be specified with the modifier 460.Fl inet . 461.Pp 462Routes have associated flags which influence operation of the protocols 463when sending to destinations matched by the routes. 464These flags may be set (or sometimes cleared) 465by indicating the following corresponding modifiers: 466.Bl -column "-blackhole" "RTF_BLACKHOLE" "description" 467.It Fl blackhole Ta Dv RTF_BLACKHOLE Ta "silently discard pkts (during updates)" 468.It Fl cloning Ta Dv RTF_CLONING Ta "generates a new route on use" 469.It Fl iface Ta Pf ~ Dv RTF_GATEWAY Ta "destination is directly reachable" 470.It Fl llinfo Ta Dv RTF_LLINFO Ta "validly translates proto addr to link addr" 471.It Fl mpath Ta Dv RTF_MPATH Ta "multiple gateways for a destination exist" 472.It Fl nostatic Ta Pf ~ Dv RTF_STATIC Ta "pretend route added by kernel or daemon" 473.It Fl proto1 Ta Dv RTF_PROTO1 Ta "set protocol specific routing flag #1" 474.It Fl proto2 Ta Dv RTF_PROTO2 Ta "set protocol specific routing flag #2" 475.It Fl reject Ta Dv RTF_REJECT Ta "emit an ICMP unreachable when matched" 476.It Fl static Ta Dv RTF_STATIC Ta "manually added route" 477.El 478.Pp 479The optional modifiers 480.Fl expire 481and 482.Fl mtu 483provide initial values to quantities maintained in the routing entry 484by transport level protocols, such as TCP (see 485.Xr tcp 4 ) . 486They have the following meanings: 487.Pp 488.Bl -tag -width "-priority n" -compact 489.It Fl expire Ar n 490Lifetime for route (e.g., if generated by a redirect). 491.It Fl mtu Ar n 492Maximum transmission unit (MTU) size for this path. 493.El 494.Pp 495These may be individually locked by preceding each such modifier to 496be locked by 497the 498.Tg 499.Fl lock 500meta-modifier, or one can 501specify that all ensuing metrics may be locked by the 502.Fl lockrest 503meta-modifier. 504.Pp 505In a 506.Cm change 507or 508.Cm add 509command where the destination and gateway are not sufficient to specify 510the route, the 511.Tg 512.Fl ifp 513or 514.Tg 515.Fl ifa 516modifiers may be used to determine the interface name or interface address. 517.Pp 518The optional 519.Tg 520.Fl label 521modifier specifies on route addition or modification that the route 522should have the given 523.Em label 524associated with it. 525Route labels can be used to attach arbitrary information to a route. 526.Pp 527All symbolic names specified for a 528.Ar destination 529or 530.Ar gateway 531are looked up using 532.Xr gethostbyname 3 . 533.Pp 534.Nm 535uses a routing socket (see 536.Xr route 4 ) 537and the message types 538.Dv RTM_ADD , 539.Dv RTM_DELETE , 540.Dv RTM_GET , 541and 542.Dv RTM_CHANGE . 543As such, only the superuser may modify 544the routing tables. 545.Sh FILES 546.Bl -tag -width "/etc/mygate" -compact 547.It Pa /etc/hosts 548host and network name database 549.It Pa /etc/mygate 550default gateway address 551.El 552.Sh EXAMPLES 553Add a static 554.Xr inet 4 555route to the 192.168.5.0/24 network via the 192.168.0.1 gateway: 556.Pp 557.Dl # route add -inet 192.168.5.0/24 192.168.0.1 558.Pp 559Amend the 560.Xr inet 4 561route to the 192.168.5.0/24 network to use the 192.168.0.2 gateway: 562.Pp 563.Dl # route change -inet 192.168.5.0/24 192.168.0.2 564.Pp 565Delete the 566.Xr inet 4 567route to the 192.168.5.0/24 network: 568.Pp 569.Dl # route delete -inet 192.168.5.0/24 570.Sh DIAGNOSTICS 571.Bl -diag 572.It "%s: gateway %s flags %x" 573The specified route is being added to or deleted from the tables. 574If the gateway address used was not the primary address of the gateway 575(the first one returned by 576.Xr gethostbyname 3 ) , 577the gateway address is printed numerically as well as symbolically. 578.It "%s %s done" 579When the 580.Cm flush 581command is specified, each routing table entry deleted 582is indicated with a message of this form. 583.It "Network is unreachable" 584An attempt to add a route failed because the gateway listed was not 585on a directly connected network. 586The next-hop gateway must be given. 587.It "not in table" 588A 589.Cm delete 590operation was attempted for an entry which 591wasn't present in the tables. 592.It "routing table overflow" 593An 594.Cm add 595operation was attempted, but the system was 596low on resources and was unable to allocate memory 597to create the new entry. 598.El 599.Sh SEE ALSO 600.Xr netstat 1 , 601.Xr gethostbyname 3 , 602.Xr netintro 4 , 603.Xr route 4 , 604.Xr tcp 4 , 605.Xr hosts 5 , 606.Xr mygate 5 , 607.Xr bgpd 8 , 608.Xr ospfd 8 , 609.Xr ripd 8 , 610.Xr sysctl 8 611.Sh HISTORY 612The 613.Nm 614command appeared in 615.Bx 4.2 . 616IPv6 support was added by WIDE/KAME project. 617.Pp 618The 619.Fl recvpipe , 620.Fl hopcount , 621.Fl sendpipe , 622.Fl ssthres , 623.Fl rtt , 624and 625.Fl rttvar 626modifiers used to be used to initialize various quantities in routing 627table entries. 628The routing system no longer uses these values and the modifiers 629exist now only for compatibility with other operating systems. 630.Sh BUGS 631Some uses of the 632.Fl ifa 633or 634.Fl ifp 635modifiers with the 636.Cm add 637command will incorrectly fail with a 638.Dq Network is unreachable 639message if there is no default route. 640See case 641.Dv RTM_ADD 642in 643.Fn route_output 644from 645.Pa sys/net/rtsock.c 646for details. 647