1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)route.8 8.3 (Berkeley) 3/19/94 29.\" $FreeBSD$ 30.\" 31.Dd April 11, 2021 32.Dt ROUTE 8 33.Os 34.Sh NAME 35.Nm route 36.Nd manually manipulate the routing tables 37.Sh SYNOPSIS 38.Nm 39.Op Fl dnqtv 40.Ar command 41.Oo 42.Op Ar modifiers 43.Ar args 44.Oc 45.Sh DESCRIPTION 46The 47.Nm 48utility is used to manually manipulate the network 49routing tables. 50It normally is not needed, as a 51system routing table management daemon, such as 52.Xr routed 8 , 53should tend to this task. 54.Pp 55The 56.Nm 57utility supports a limited number of general options, 58but a rich command language, enabling the user to specify 59any arbitrary request that could be delivered via the 60programmatic interface discussed in 61.Xr route 4 . 62.Pp 63The following options are available: 64.Bl -tag -width indent 65.It Fl 4 66Specify 67.Cm inet 68address family as family hint for subcommands. 69.It Fl 6 70Specify 71.Cm inet6 72address family as family hint for subcommands. 73.It Fl d 74Run in debug-only mode, i.e., do not actually modify the routing table. 75.It Fl n 76Bypass attempts to print host and network names symbolically 77when reporting actions. 78(The process of translating between symbolic 79names and numerical equivalents can be quite time consuming, and 80may require correct operation of the network; thus it may be expedient 81to forget this, especially when attempting to repair networking operations). 82.It Fl t 83Run in test-only mode. 84.Pa /dev/null 85is used instead of a socket. 86.It Fl v 87(verbose) Print additional details. 88.It Fl q 89Suppress all output from the 90.Cm add , change , delete , 91and 92.Cm flush 93commands. 94.El 95.Pp 96The 97.Nm 98utility provides the following commands: 99.Pp 100.Bl -tag -width Fl -compact 101.It Cm add 102Add a route. 103.It Cm flush 104Remove all routes. 105.It Cm delete 106Delete a specific route. 107.It Cm del 108Another name for the 109.Cm delete 110command. 111.It Cm change 112Change aspects of a route (such as its gateway). 113.It Cm get 114Lookup and display the route for a destination. 115.It Cm monitor 116Continuously report any changes to the routing information base, 117routing lookup misses, or suspected network partitionings. 118.It Cm show 119Another name for the 120.Cm get 121command. 122.El 123.Pp 124The monitor command has the syntax: 125.Pp 126.Bd -ragged -offset indent -compact 127.Nm 128.Op Fl n 129.Cm monitor Op Fl fib Ar number 130.Ed 131.Pp 132The flush command has the syntax: 133.Pp 134.Bd -ragged -offset indent -compact 135.Nm 136.Op Fl n 137.Cm flush Oc Oo Ar family Oc Op Fl fib Ar number 138.Ed 139.Pp 140If the 141.Cm flush 142command is specified, 143.Nm 144will ``flush'' the routing tables of all gateway entries. 145When the address family may is specified by any of the 146.Fl osi , 147.Fl xns , 148.Fl inet6 , 149or 150.Fl inet 151modifiers, only routes having destinations with addresses in the 152delineated family will be deleted. 153Additionally, 154.Fl 4 155or 156.Fl 6 157can be used as aliases for 158.Fl inet 159and 160.Fl inet6 161modifiers. 162When a 163.Fl fib 164option is specified, the operation will be applied to 165the specified FIB 166.Pq routing table . 167.Pp 168The add command has the following syntax: 169.Pp 170.Bd -ragged -offset indent -compact 171.Nm 172.Op Fl n 173.Cm add 174.Op Fl net No \&| Fl host 175.Ar destination gateway 176.Op Ar netmask 177.Op Fl fib Ar number 178.Ed 179.Pp 180and the other commands have the following syntax: 181.Pp 182.Bd -ragged -offset indent -compact 183.Nm 184.Op Fl n 185.Ar command 186.Op Fl net No \&| Fl host 187.Ar destination 188.Op Ar gateway Op Ar netmask 189.Op Fl fib Ar number 190.Ed 191.Pp 192where 193.Ar destination 194is the destination host or network, 195.Ar gateway 196is the next-hop intermediary via which packets should be routed. 197Routes to a particular host may be distinguished from those to 198a network by interpreting the Internet address specified as the 199.Ar destination 200argument. 201The optional modifiers 202.Fl net 203and 204.Fl host 205force the destination to be interpreted as a network or a host, respectively. 206Otherwise, if the 207.Ar destination 208has a 209.Dq local address part 210of 211INADDR_ANY 212.Pq Li 0.0.0.0 , 213or if the 214.Ar destination 215is the symbolic name of a network, then the route is 216assumed to be to a network; otherwise, it is presumed to be a 217route to a host. 218Optionally, the 219.Ar destination 220could also be specified in the 221.Ar net Ns / Ns Ar bits 222format. 223.Pp 224For example, 225.Li 128.32 226is interpreted as 227.Fl host Li 128.0.0.32 ; 228.Li 128.32.130 229is interpreted as 230.Fl host Li 128.32.0.130 ; 231.Fl net Li 128.32 232is interpreted as 233.Li 128.32.0.0; 234.Fl net Li 128.32.130 235is interpreted as 236.Li 128.32.130.0; 237and 238.Li 192.168.64/20 239is interpreted as 240.Fl net Li 192.168.64 Fl netmask Li 255.255.240.0 . 241.Pp 242A 243.Ar destination 244of 245.Ar default 246is a synonym for the default route. 247For 248.Li IPv4 249it is 250.Fl net Fl inet Li 0.0.0.0 , 251and for 252.Li IPv6 253it is 254.Fl net Fl inet6 Li :: . 255.Pp 256If the destination is directly reachable 257via an interface requiring 258no intermediary system to act as a gateway, the 259.Fl interface 260modifier should be specified; 261the gateway given is the address of this host on the common network, 262indicating the interface to be used for transmission. 263Alternately, if the interface is point to point the name of the interface 264itself may be given, in which case the route remains valid even 265if the local or remote addresses change. 266.Pp 267The optional modifiers 268.Fl xns , 269.Fl osi , 270and 271.Fl link 272specify that all subsequent addresses are in the 273.Tn XNS 274or 275.Tn OSI 276address families, 277or are specified as link-level addresses, 278and the names must be numeric specifications rather than 279symbolic names. 280.Pp 281The optional 282.Fl netmask 283modifier is intended 284to achieve the effect of an 285.Tn OSI 286.Tn ESIS 287redirect with the netmask option, 288or to manually add subnet routes with 289netmasks different from that of the implied network interface 290(as would otherwise be communicated using the OSPF or ISIS routing protocols). 291One specifies an additional ensuing address parameter 292(to be interpreted as a network mask). 293The implicit network mask generated in the AF_INET case 294can be overridden by making sure this option follows the destination parameter. 295.Pp 296For 297.Dv AF_INET6 , 298the 299.Fl prefixlen 300qualifier 301is available instead of the 302.Fl mask 303qualifier because non-continuous masks are not allowed in IPv6. 304For example, 305.Fl prefixlen Li 32 306specifies that a network mask of 307.Li ffff:ffff:0000:0000:0000:0000:0000:0000 308will be used. 309The default prefixlen is 64. 310However, it is assumed to be 0 if 311.Cm default 312is specified for 313.Ar destination . 314Note that the qualifier works only for 315.Dv AF_INET6 316address family. 317.Pp 318Routes have associated flags which influence operation of the protocols 319when sending to destinations matched by the routes. 320These flags may be set (or sometimes cleared) 321by indicating the following corresponding modifiers: 322.Bd -literal 323-xresolve RTF_XRESOLVE - emit mesg on use (for external lookup) 324-iface ~RTF_GATEWAY - destination is directly reachable 325-static RTF_STATIC - manually added route 326-nostatic ~RTF_STATIC - pretend route added by kernel or daemon 327-reject RTF_REJECT - emit an ICMP unreachable when matched 328-blackhole RTF_BLACKHOLE - silently discard pkts (during updates) 329-proto1 RTF_PROTO1 - set protocol specific routing flag #1 330-proto2 RTF_PROTO2 - set protocol specific routing flag #2 331.Ed 332.Pp 333The optional modifiers 334.Fl rtt , 335.Fl rttvar , 336.Fl sendpipe , 337.Fl recvpipe , 338.Fl mtu , 339.Fl hopcount , 340.Fl expire , 341and 342.Fl ssthresh 343provide initial values to quantities maintained in the routing entry 344by transport level protocols, such as TCP or TP4. 345These may be individually locked by preceding each such modifier to 346be locked by 347the 348.Fl lock 349meta-modifier, or one can 350specify that all ensuing metrics may be locked by the 351.Fl lockrest 352meta-modifier. 353.Pp 354Note that 355.Fl expire 356accepts expiration time of the route as the number of seconds since the 357Epoch 358.Pq see Xr time 3 . 359When the first character of the number is 360.Dq + 361or 362.Dq - , 363it is interpreted as a value relative to the current time. 364.Pp 365The optional modifier 366.Fl fib Ar number 367specifies that the command will be applied to a non-default FIB. 368The 369.Ar number 370must be smaller than the 371.Va net.fibs 372.Xr sysctl 8 373MIB. 374When this modifier is not specified, 375or a negative number is specified, 376the default FIB shown in the 377.Va net.my_fibnum 378.Xr sysctl 8 379MIB will be used. 380.Pp 381The 382.Ar number 383allows multiple FIBs by a comma-separeted list and/or range 384specification. 385The 386.Qq Fl fib Li 2,4,6 387means the FIB number 2, 4, and 6. 388The 389.Qq Fl fib Li 1,3-5,6 390means the 1, 3, 4, 5, and 6. 391.Pp 392In a 393.Cm change 394or 395.Cm add 396command where the destination and gateway are not sufficient to specify 397the route (as in the 398.Tn ISO 399case where several interfaces may have the 400same address), the 401.Fl ifp 402or 403.Fl ifa 404modifiers may be used to determine the interface or interface address. 405.Pp 406All symbolic names specified for a 407.Ar destination 408or 409.Ar gateway 410are looked up first as a host name using 411.Xr gethostbyname 3 . 412If this lookup fails, 413.Xr getnetbyname 3 414is then used to interpret the name as that of a network. 415.Pp 416The 417.Nm 418utility uses a routing socket and the new message types 419.Dv RTM_ADD , RTM_DELETE , RTM_GET , 420and 421.Dv RTM_CHANGE . 422As such, only the super-user may modify 423the routing tables. 424.Sh EXIT STATUS 425.Ex -std 426.Sh EXAMPLES 427Add a default route to the network routing table. 428This will send all packets for destinations not available in the routing table 429to the default gateway at 192.168.1.1: 430.Pp 431.Dl route add -net 0.0.0.0/0 192.168.1.1 432.Pp 433A shorter version of adding a default route can also be written as: 434.Pp 435.Dl route add default 192.168.1.1 436.Pp 437Add a static route to the 172.16.10.0/24 network via the 172.16.1.1 gateway: 438.Pp 439.Dl route add -net 172.16.10.0/24 172.16.1.1 440.Pp 441Change the gateway of an already established static route in the routing table: 442.Pp 443.Dl route change -net 172.16.10.0/24 172.16.1.2 444.Pp 445Display the route for a destination network: 446.Pp 447.Dl route show 172.16.10.0 448.Pp 449Delete a static route from the routing table: 450.Pp 451.Dl route delete -net 172.16.10.0/24 172.16.1.2 452.Pp 453Remove all routes from the routing table: 454.Pp 455.Dl route flush 456.Pp 457List all routing tables: 458.Pp 459.Dl netstat -r 460.Sh DIAGNOSTICS 461.Bl -diag 462.It "add [host \&| network ] %s: gateway %s flags %x" 463The specified route is being added to the tables. 464The 465values printed are from the routing table entry supplied 466in the 467.Xr ioctl 2 468call. 469If the gateway address used was not the primary address of the gateway 470(the first one returned by 471.Xr gethostbyname 3 ) , 472the gateway address is printed numerically as well as symbolically. 473.It "delete [ host \&| network ] %s: gateway %s flags %x" 474As above, but when deleting an entry. 475.It "%s %s done" 476When the 477.Cm flush 478command is specified, each routing table entry deleted 479is indicated with a message of this form. 480.It "Network is unreachable" 481An attempt to add a route failed because the gateway listed was not 482on a directly-connected network. 483The next-hop gateway must be given. 484.It "not in table" 485A delete operation was attempted for an entry which 486was not present in the tables. 487.It "routing table overflow" 488An add operation was attempted, but the system was 489low on resources and was unable to allocate memory 490to create the new entry. 491.It "gateway uses the same route" 492A 493.Cm change 494operation resulted in a route whose gateway uses the 495same route as the one being changed. 496The next-hop gateway should be reachable through a different route. 497.El 498.Sh SEE ALSO 499.\".Xr esis 4 , 500.Xr netstat 1 , 501.Xr netintro 4 , 502.Xr route 4 , 503.Xr arp 8 , 504.Xr routed 8 505.\".Xr XNSrouted 8 506.Sh HISTORY 507The 508.Nm 509utility appeared in 510.Bx 4.2 . 511.Sh BUGS 512The first paragraph may have slightly exaggerated 513.Xr routed 8 Ns 's 514abilities. 515.Pp 516Currently, routes with the 517.Dv RTF_BLACKHOLE 518flag set need to have the gateway set to an instance of the 519.Xr lo 4 520driver, using the 521.Fl iface 522option, for the flag to have any effect; unless IP fast forwarding 523is enabled, in which case the meaning of the flag will always 524be honored. 525