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 December 15, 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 inet6 , 147or 148.Fl inet 149modifiers, only routes having destinations with addresses in the 150delineated family will be deleted. 151Additionally, 152.Fl 4 153or 154.Fl 6 155can be used as aliases for 156.Fl inet 157and 158.Fl inet6 159modifiers. 160When a 161.Fl fib 162option is specified, the operation will be applied to 163the specified FIB 164.Pq routing table . 165.Pp 166The add command has the following syntax: 167.Pp 168.Bd -ragged -offset indent -compact 169.Nm 170.Op Fl n 171.Cm add 172.Op Fl net No \&| Fl host 173.Ar destination gateway 174.Op Ar netmask 175.Op Fl fib Ar number 176.Ed 177.Pp 178and the other commands have the following syntax: 179.Pp 180.Bd -ragged -offset indent -compact 181.Nm 182.Op Fl n 183.Ar command 184.Op Fl net No \&| Fl host 185.Ar destination 186.Op Ar gateway Op Ar netmask 187.Op Fl fib Ar number 188.Ed 189.Pp 190where 191.Ar destination 192is the destination host or network, 193.Ar gateway 194is the next-hop intermediary via which packets should be routed. 195Routes to a particular host may be distinguished from those to 196a network by interpreting the Internet address specified as the 197.Ar destination 198argument. 199The optional modifiers 200.Fl net 201and 202.Fl host 203force the destination to be interpreted as a network or a host, respectively. 204Otherwise, if the 205.Ar destination 206has a 207.Dq local address part 208of 209INADDR_ANY 210.Pq Li 0.0.0.0 , 211or if the 212.Ar destination 213is the symbolic name of a network, then the route is 214assumed to be to a network; otherwise, it is presumed to be a 215route to a host. 216Optionally, the 217.Ar destination 218could also be specified in the 219.Ar net Ns / Ns Ar bits 220format. 221.Pp 222For example, 223.Li 128.32 224is interpreted as 225.Fl host Li 128.0.0.32 ; 226.Li 128.32.130 227is interpreted as 228.Fl host Li 128.32.0.130 ; 229.Fl net Li 128.32 230is interpreted as 231.Li 128.32.0.0; 232.Fl net Li 128.32.130 233is interpreted as 234.Li 128.32.130.0; 235and 236.Li 192.168.64/20 237is interpreted as 238.Fl net Li 192.168.64 Fl netmask Li 255.255.240.0 . 239.Pp 240A 241.Ar destination 242of 243.Ar default 244is a synonym for the default route. 245For 246.Li IPv4 247it is 248.Fl net Fl inet Li 0.0.0.0 , 249and for 250.Li IPv6 251it is 252.Fl net Fl inet6 Li :: . 253.Pp 254If the destination is directly reachable 255via an interface requiring 256no intermediary system to act as a gateway, the 257.Fl interface 258modifier should be specified; 259the gateway given is the address of this host on the common network, 260indicating the interface to be used for transmission. 261Alternately, if the interface is point to point the name of the interface 262itself may be given, in which case the route remains valid even 263if the local or remote addresses change. 264.Pp 265The optional 266.Fl netmask 267modifier is intended 268to achieve the effect of an 269.Tn OSI 270.Tn ESIS 271redirect with the netmask option, 272or to manually add subnet routes with 273netmasks different from that of the implied network interface 274(as would otherwise be communicated using the OSPF or ISIS routing protocols). 275One specifies an additional ensuing address parameter 276(to be interpreted as a network mask). 277The implicit network mask generated in the AF_INET case 278can be overridden by making sure this option follows the destination parameter. 279.Pp 280For 281.Dv AF_INET6 , 282the 283.Fl prefixlen 284qualifier 285is available instead of the 286.Fl mask 287qualifier because non-continuous masks are not allowed in IPv6. 288For example, 289.Fl prefixlen Li 32 290specifies that a network mask of 291.Li ffff:ffff:0000:0000:0000:0000:0000:0000 292will be used. 293The default prefixlen is 64. 294However, it is assumed to be 0 if 295.Cm default 296is specified for 297.Ar destination . 298Note that the qualifier works only for 299.Dv AF_INET6 300address family. 301.Pp 302Routes have associated flags which influence operation of the protocols 303when sending to destinations matched by the routes. 304These flags may be set (or sometimes cleared) 305by indicating the following corresponding modifiers: 306.Bd -literal 307-xresolve RTF_XRESOLVE - emit mesg on use (for external lookup) 308-iface ~RTF_GATEWAY - destination is directly reachable 309-static RTF_STATIC - manually added route 310-nostatic ~RTF_STATIC - pretend route added by kernel or daemon 311-reject RTF_REJECT - emit an ICMP unreachable when matched 312-blackhole RTF_BLACKHOLE - silently discard pkts (during updates) 313-proto1 RTF_PROTO1 - set protocol specific routing flag #1 314-proto2 RTF_PROTO2 - set protocol specific routing flag #2 315.Ed 316.Pp 317The optional modifiers 318.Fl rtt , 319.Fl rttvar , 320.Fl sendpipe , 321.Fl recvpipe , 322.Fl mtu , 323.Fl hopcount , 324.Fl expire , 325and 326.Fl ssthresh 327provide initial values to quantities maintained in the routing entry 328by transport level protocols, such as TCP or TP4. 329These may be individually locked by preceding each such modifier to 330be locked by 331the 332.Fl lock 333meta-modifier, or one can 334specify that all ensuing metrics may be locked by the 335.Fl lockrest 336meta-modifier. 337.Pp 338Note that 339.Fl expire 340accepts expiration time of the route as the number of seconds since the 341Epoch 342.Pq see Xr time 3 . 343When the first character of the number is 344.Dq + 345or 346.Dq - , 347it is interpreted as a value relative to the current time. 348.Pp 349The optional modifier 350.Fl fib Ar number 351specifies that the command will be applied to a non-default FIB. 352The 353.Ar number 354must be smaller than the 355.Va net.fibs 356.Xr sysctl 8 357MIB. 358When this modifier is not specified, 359or a negative number is specified, 360the default FIB shown in the 361.Va net.my_fibnum 362.Xr sysctl 8 363MIB will be used. 364.Pp 365The 366.Ar number 367allows multiple FIBs by a comma-separeted list and/or range 368specification. 369The 370.Qq Fl fib Li 2,4,6 371means the FIB number 2, 4, and 6. 372The 373.Qq Fl fib Li 1,3-5,6 374means the 1, 3, 4, 5, and 6. 375.Pp 376In a 377.Cm change 378or 379.Cm add 380command where the destination and gateway are not sufficient to specify 381the route (as in the 382.Tn ISO 383case where several interfaces may have the 384same address), the 385.Fl ifp 386or 387.Fl ifa 388modifiers may be used to determine the interface or interface address. 389.Pp 390All symbolic names specified for a 391.Ar destination 392or 393.Ar gateway 394are looked up first as a host name using 395.Xr gethostbyname 3 . 396If this lookup fails, 397.Xr getnetbyname 3 398is then used to interpret the name as that of a network. 399.Pp 400The 401.Nm 402utility uses a routing socket and the new message types 403.Dv RTM_ADD , RTM_DELETE , RTM_GET , 404and 405.Dv RTM_CHANGE . 406As such, only the super-user may modify 407the routing tables. 408.Sh EXIT STATUS 409.Ex -std 410.Sh EXAMPLES 411Add a default route to the network routing table. 412This will send all packets for destinations not available in the routing table 413to the default gateway at 192.168.1.1: 414.Pp 415.Dl route add -net 0.0.0.0/0 192.168.1.1 416.Pp 417A shorter version of adding a default route can also be written as: 418.Pp 419.Dl route add default 192.168.1.1 420.Pp 421Add a static route to the 172.16.10.0/24 network via the 172.16.1.1 gateway: 422.Pp 423.Dl route add -net 172.16.10.0/24 172.16.1.1 424.Pp 425Change the gateway of an already established static route in the routing table: 426.Pp 427.Dl route change -net 172.16.10.0/24 172.16.1.2 428.Pp 429Display the route for a destination network: 430.Pp 431.Dl route show 172.16.10.0 432.Pp 433Delete a static route from the routing table: 434.Pp 435.Dl route delete -net 172.16.10.0/24 172.16.1.2 436.Pp 437Remove all routes from the routing table: 438.Pp 439.Dl route flush 440.Pp 441List all routing tables: 442.Pp 443.Dl netstat -r 444.Sh DIAGNOSTICS 445.Bl -diag 446.It "add [host \&| network ] %s: gateway %s flags %x" 447The specified route is being added to the tables. 448The 449values printed are from the routing table entry supplied 450in the 451.Xr ioctl 2 452call. 453If the gateway address used was not the primary address of the gateway 454(the first one returned by 455.Xr gethostbyname 3 ) , 456the gateway address is printed numerically as well as symbolically. 457.It "delete [ host \&| network ] %s: gateway %s flags %x" 458As above, but when deleting an entry. 459.It "%s %s done" 460When the 461.Cm flush 462command is specified, each routing table entry deleted 463is indicated with a message of this form. 464.It "Network is unreachable" 465An attempt to add a route failed because the gateway listed was not 466on a directly-connected network. 467The next-hop gateway must be given. 468.It "not in table" 469A delete operation was attempted for an entry which 470was not present in the tables. 471.It "routing table overflow" 472An add operation was attempted, but the system was 473low on resources and was unable to allocate memory 474to create the new entry. 475.It "gateway uses the same route" 476A 477.Cm change 478operation resulted in a route whose gateway uses the 479same route as the one being changed. 480The next-hop gateway should be reachable through a different route. 481.El 482.Sh SEE ALSO 483.\".Xr esis 4 , 484.Xr netstat 1 , 485.Xr netintro 4 , 486.Xr route 4 , 487.Xr arp 8 , 488.Xr routed 8 489.Sh HISTORY 490The 491.Nm 492utility appeared in 493.Bx 4.2 . 494.Sh BUGS 495The first paragraph may have slightly exaggerated 496.Xr routed 8 Ns 's 497abilities. 498.Pp 499Currently, routes with the 500.Dv RTF_BLACKHOLE 501flag set need to have the gateway set to an instance of the 502.Xr lo 4 503driver, using the 504.Fl iface 505option, for the flag to have any effect; unless IP fast forwarding 506is enabled, in which case the meaning of the flag will always 507be honored. 508