1.\" $NetBSD: route.8,v 1.65 2021/01/02 22:02:27 uwe Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)route.8 8.4 (Berkeley) 6/1/94 31.\" 32.Dd August 29, 2020 33.Dt ROUTE 8 34.Os 35.Sh NAME 36.Nm route 37.Nd manually manipulate the routing tables 38.Sh SYNOPSIS 39.Nm 40.Op Fl dfLnqSsTtv 41.Ar command 42.Oo 43.Op Ar modifiers 44.Ar args 45.Oc 46.Sh DESCRIPTION 47.Nm 48is a utility used to manually manipulate the network 49routing tables. 50Except for setting up the default route, it is normally not needed, 51as a system routing table management daemon such as 52.Xr routed 8 , 53should tend to this task. 54.Pp 55.Nm 56can be used to modify nearly any aspect of the routing policy, 57except packet forwarding, which can be manipulated through the 58.Xr sysctl 8 59command. 60.Pp 61The 62.Nm 63utility supports a limited number of general options, 64but a rich command language, enabling the user to specify 65any arbitrary request that could be delivered via the 66programmatic interface discussed in 67.Xr route 4 . 68.Bl -tag -width Ds 69.It Fl d 70Turn on debugging 71.It Fl f 72Remove all routes (as per 73.Cm flush ) . 74If used in conjunction with the 75.Cm add , 76.Cm change , 77.Cm delete 78or 79.Cm get 80commands, 81.Nm 82removes the routes before performing the command. 83.It Fl L 84Don't show link layer entries in routing table. 85.It Fl n 86Bypasses attempts to print host and network names symbolically 87when reporting actions. 88(The process of translating between symbolic 89names and numerical equivalents can be quite time consuming, and 90may require correct operation of the network; thus it may be expedient 91to forgo this, especially when attempting to repair networking operations). 92.It Fl q 93Suppress all output from commands that manipulate the routing table. 94.It Fl S 95Print a space when a flag is missing so that flags are vertically aligned 96instead of printing the flags that are set as a contiguous string. 97.It Fl s 98(short) Suppresses all output from a 99.Cm get 100command except for the actual gateway that will be used. 101How the gateway is printed depends on the type of route being looked up. 102.It Fl T 103Show tags in the route display. 104.It Fl t 105Test only, don't perform any actions. 106.It Fl v 107(verbose) Print additional details. 108.El 109.Pp 110The 111.Nm 112utility provides several commands: 113.Pp 114.Bl -tag -width Fl -compact 115.It Cm add 116Add a route. 117.It Cm flush 118Remove all routes. 119.It Cm flushall 120Remove all routes including the default gateway. 121.It Cm delete 122Delete a specific route. 123.It Cm change 124Change aspects of a route (such as its gateway). 125.It Cm get 126Lookup and display the route for a destination. 127.It Cm show 128Print out the route table similar to "netstat \-r" (see 129.Xr netstat 1 ) . 130.It Cm monitor 131Continuously report any changes to the routing information base, 132routing lookup misses, or suspected network partitionings. 133.El 134.Pp 135The monitor command has the syntax 136.Pp 137.Bd -filled -offset indent -compact 138.Nm 139.Op Fl n 140.Cm monitor 141.Op Fl c Ar count 142.Ed 143.Pp 144If 145.Ar count 146is specified, 147.Nm 148exits after receiving 149.Ar count 150routing messages. 151.Pp 152The flush command has the syntax 153.Pp 154.Bd -filled -offset indent -compact 155.Nm 156.Op Fl n 157.Cm flush 158.Op Ar family 159.Ed 160.Pp 161If the 162.Cm flush 163command is specified, 164.Nm 165will ``flush'' the routing tables of all gateway entries. 166When the address family is specified by any of the 167.Fl atalk , 168.Fl inet , 169.Fl inet6 , 170or 171.Fl mpls 172modifiers, only routes having destinations with addresses in the 173delineated family will be manipulated. 174.Pp 175The other commands have the following syntax: 176.Pp 177.Bd -filled -offset indent -compact 178.Nm 179.Op Fl n 180.Ar command 181.Op Fl net No \&| Fl host 182.Ar destination gateway 183.Ed 184.Pp 185where 186.Ar destination 187is the destination host or network, and 188.Ar gateway 189is the next-hop intermediary via which packets should be routed. 190Routes to a particular host may be distinguished from those to 191a network by interpreting the Internet address specified as the 192.Ar destination 193argument. 194The optional modifiers 195.Fl net 196and 197.Fl host 198force the destination to be interpreted as a network or a host, respectively. 199Otherwise, if the 200.Ar destination 201has a ``local address part'' of 202.Dv INADDR_ANY , 203or if the 204.Ar destination 205is the symbolic name of a network, then the route is 206assumed to be to a network; otherwise, it is presumed to be a 207route to a host. 208Optionally, the 209.Ar destination 210can also be specified in the 211.Ar net Ns / Ns Ar bits 212format. 213.Pp 214For example, 215.Li 128.32 216is interpreted as 217.Fl host Li 128.0.0.32 ; 218.Li 128.32.130 219is interpreted as 220.Fl host Li 128.32.0.130 ; 221.Fl net Li 128.32 222is interpreted as 223.Li 128.32.0.0 ; 224and 225.Fl net Li 128.32.130 226is interpreted as 227.Li 128.32.130.0 . 228.Pp 229The keyword 230.Cm default 231can be used as the 232.Ar destination 233to set up a default route to a smart 234.Ar gateway . 235If no other routes match, this default route will be used as a last resort. 236.Pp 237If the destination is directly reachable 238via an interface requiring 239no intermediary system to act as a gateway, the 240.Fl interface 241modifier should be specified; 242the gateway given is the address of this host on the common network, 243indicating the interface to be used for transmission. 244.Pp 245The optional modifiers 246.Fl atalk , 247and 248.Fl link 249specify that all subsequent addresses are in the 250.Tn AppleTalk 251address family, 252or are specified as link-level addresses in the form described in 253.Xr link_addr 3 , 254and the names must be numeric specifications rather than 255symbolic names. 256.Pp 257The optional modifier 258.Fl tag 259specifies an address associated with the route. 260How the address is used is specific to the address family of 261the destination and the interface used to forward the packet. 262Currently route tags are consumed only by the 263.Xr mpls 4 264stack; therefore 265.Nm 266assumes that the subsequent addresses are in the 267.Tn MPLS 268address family. 269See 270.Xr mpls 4 271for examples of setting routes involving MPLS. 272.Pp 273The optional 274.Fl netmask 275qualifier is intended 276to achieve the effect of an 277.Tn ESIS 278redirect with the netmask option, 279or to manually add subnet routes with 280netmasks different from that of the implied network interface 281(as would otherwise be communicated using the OSPF or ISIS routing protocols). 282One specifies an additional ensuing address parameter 283(to be interpreted as a network mask). 284The implicit network mask generated in the 285.Dv AF_INET 286case 287can be overridden by making sure this option follows the destination parameter. 288.Fl prefixlen 289is also available for similar purpose, in IPv4 and IPv6 case. 290.Pp 291Routes have associated flags which influence operation of the protocols 292when sending to destinations matched by the routes. 293These flags are displayed using the following ID characters in the routing 294display and may be set (or sometimes cleared) 295by indicating the following corresponding modifiers: 296.Bl -column "ID" "xnoblackhole" "xRTF_BLACKHOLE" "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 297.It Sy "ID" Ta Sy "Modifier" Ta Sy " Flag Bit" Ta Sy "Description" 298.It Li 1 Ta -proto1 Ta " RTF_PROTO1" Ta set protocol specific flag #1 299.It Li 2 Ta -proto2 Ta " RTF_PROTO2" Ta set protocol specific flag #2 300.It Li B Ta -blackhole Ta " RTF_BLACKHOLE" Ta discard pkts (during updates) 301.It Li " " Ta -noblackhole Ta ~RTF_BLACKHOLE Ta clear blackhole flag 302.It Li b Ta "" Ta " RTF_BROADCAST" Ta route represents a broadcast address 303.It Li C Ta -cloning Ta " RTF_CLONING" Ta (deprecated) same as 304.Fl connected 305.It Li " " Ta -nocloning Ta ~RTF_CLONING Ta (deprecated) same as 306.Fl noconnected 307.It Li C Ta -connected Ta " RTF_CONNECTED" Ta treat as a connected route 308.It Li " " Ta -noconnected Ta ~RTF_CONNECTED Ta stop treating a connected route 309.It Li D Ta "" Ta " RTF_DYNAMIC" Ta created dynamically (redirect) 310.It Li G Ta "" Ta " RTF_GATEWAY" Ta forward to dest by intermediary 311.It Li " " Ta -iface Ta ~RTF_GATEWAY Ta destination is directly reachable 312.It Li H Ta "" Ta " RTF_HOST" Ta host entry (net otherwise) 313.It Li L Ta "" Ta " RTF_LLDATA" Ta local link, generated by ARP or NDP 314.It Li l Ta "" Ta " RTF_LOCAL" Ta route represents a local address 315.It Li M Ta "" Ta " RTF_MODIFIED" Ta modified dynamically (redirect) 316.It Li p Ta -proxy Ta " RTF_ANNOUNCE" Ta make entry a link level proxy 317.It Li R Ta -reject Ta " RTF_REJECT" Ta send ICMP unreachable on match 318.It Li " " Ta -noreject Ta ~RTF_REJECT Ta clear reject flag 319.It Li S Ta -static Ta " RTF_STATIC" Ta manually added route 320.It Li " " Ta -nostatic Ta ~RTF_STATIC Ta pretend route added automatically 321.It Li U Ta "" Ta " RTF_UP" Ta route usable 322.El 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 345In a 346.Cm change 347or 348.Cm add 349command where the destination and gateway are not sufficient to specify 350the route the 351.Fl ifp 352or 353.Fl ifa 354modifiers may be used to determine the interface or interface address. 355.Pp 356All symbolic names specified for a 357.Ar destination 358or 359.Ar gateway 360are looked up first as a host name using 361.Xr gethostbyname 3 . 362If this lookup fails, 363.Xr getnetbyname 3 364is then used to interpret the name as that of a network. 365.Pp 366.Nm 367uses a routing socket and the new message types 368.Dv RTM_ADD , 369.Dv RTM_DELETE , 370.Dv RTM_GET , 371and 372.Dv RTM_CHANGE . 373As such, only the super-user may modify 374the routing tables. 375.Sh EXIT STATUS 376.Ex -std route 377This includes the use of the 378.Cm get 379command to look up a route that is incomplete. 380.Sh EXAMPLES 381This sets the default route to 192.168.0.1: 382.Dl route add default 192.168.0.1 383This shows all routes, without DNS resolution (this is useful if the 384DNS is not available): 385.Dl route -n show 386To install a static route through 10.200.0.1 to reach the network 387192.168.1.0/28, use this: 388.Dl route add -net 192.168.1.0 -netmask 255.255.255.240 10.200.0.1 389.Sh DIAGNOSTICS 390.Bl -tag -width Ds 391.It Sy "add [host \&| network ] %s: gateway %s flags %x" 392The specified route is being added to the tables. 393The values printed are from the routing table entry supplied in the 394.Xr ioctl 2 395call. 396If the gateway address used was not the primary address of the gateway 397(the first one returned by 398.Xr gethostbyname 3 ) , 399the gateway address is printed numerically as well as symbolically. 400.It Sy "delete [ host \&| network ] %s: gateway %s flags %x" 401As above, but when deleting an entry. 402.It Sy "%s %s done" 403When the 404.Cm flush 405command is specified, each routing table entry deleted 406is indicated with a message of this form. 407.It Sy "Network is unreachable" 408An attempt to add a route failed because the gateway listed was not 409on a directly-connected network. 410The next-hop gateway must be given. 411.It Sy "not in table" 412A delete operation was attempted for an entry which 413wasn't present in the tables. 414.It Sy "routing table overflow" 415An add operation was attempted, but the system was 416low on resources and was unable to allocate memory 417to create the new entry. 418.It Sy "Permission denied" 419The attempted operation is privileged. 420Only root may modify the routing tables. 421These privileges are enforced by the kernel. 422.El 423.Sh SEE ALSO 424.Xr mpls 4 , 425.Xr netintro 4 , 426.Xr route 4 , 427.Xr routed 8 , 428.Xr sysctl 8 429.Sh HISTORY 430The 431.Nm 432command appeared in 433.Bx 4.2 . 434IPv6 support was added by WIDE/KAME project. 435.Pp 436Since 437.Nx 8.0 , 438.Fl cloned , 439.Fl nocloned , 440.Fl llinfo 441and 442.Fl xresolve 443were obsolete and 444.Fl cloning 445and 446.Fl nocloning 447were deprecated. 448.Fl connected 449and 450.Fl noconnected 451appeared in 452.Nx 8.0 . 453.Sh BUGS 454The first paragraph may have slightly exaggerated 455.Xr routed 8 Ns 's 456abilities. 457.Pp 458Some uses of the 459.Fl ifa 460or 461.Fl ifp 462modifiers with the add command will incorrectly fail with a 463.Dq Network is unreachable 464message if there is no default route. 465See case 466.Dv RTM_ADD 467in 468.Pa sys/net/rtsock.c:route_output 469for details. 470