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: src/sbin/route/route.8,v 1.17.2.9 2003/02/24 00:56:43 trhodes Exp $ 30.\" 31.Dd June 8, 2001 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.Op Fl c Ar cpu 41.Ar command 42.Oo 43.Op Ar modifiers 44.Ar args 45.Oc 46.Sh DESCRIPTION 47The 48.Nm 49utility is used to manually manipulate the network 50routing tables. It 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 c Ar cpu 66On SMP systems the route table is replicated. This option allows the 67route table for a specific cpu to be accessed and exists primarily 68for debugging purposes. 69.It Fl n 70Bypass attempts to print host and network names symbolically 71when reporting actions. (The process of translating between symbolic 72names and numerical equivalents can be quite time consuming, and 73may require correct operation of the network; thus it may be expedient 74to forget this, especially when attempting to repair networking operations). 75.It Fl v 76(verbose) Print additional details. 77.It Fl q 78Suppress all output from the 79.Cm add , delete , 80and 81.Cm flush 82commands. 83.It Fl w 84Print the full width of the data being represented even if it would overflow 85the column. 86.El 87.Pp 88The 89.Nm 90utility provides six commands: 91.Pp 92.Bl -tag -width Fl -compact 93.It Cm add 94Add a route. 95.It Cm flush 96Remove all routes. 97.It Cm delete 98Delete a specific route. 99.It Cm change 100Change aspects of a route (such as its gateway). 101.It Cm get 102Lookup and display the route for a destination. 103.It Cm show 104Print out the route table similar to "netstat \-r" (see 105.Xr netstat 1 ) . 106.It Cm monitor 107Continuously report any changes to the routing information base, 108routing lookup misses, or suspected network partitionings. 109.El 110.Pp 111The monitor command has the syntax: 112.Pp 113.Bd -ragged -offset indent -compact 114.Nm 115.Op Fl n 116.Cm monitor 117.Ed 118.Pp 119The flush command has the syntax: 120.Pp 121.Bd -ragged -offset indent -compact 122.Nm 123.Op Fl n 124.Cm flush 125.Op Ar family 126.Ed 127.Pp 128If the 129.Cm flush 130command is specified, 131.Nm 132will ``flush'' the routing tables of all gateway entries. 133When the address family may is specified by any of the 134.Fl osi , 135.Fl inet6 , 136or 137.Fl inet 138modifiers, only routes having destinations with addresses in the 139delineated family will be deleted. 140.Pp 141The other commands have the following syntax: 142.Pp 143.Bd -ragged -offset indent -compact 144.Nm 145.Op Fl n 146.Ar command 147.Op Fl net No \&| Fl host 148.Ar destination gateway 149.Op Ar netmask 150.Ed 151.Pp 152where 153.Ar destination 154is the destination host or network, 155.Ar gateway 156is the next-hop intermediary via which packets should be routed. 157Routes to a particular host may be distinguished from those to 158a network by interpreting the Internet address specified as the 159.Ar destination 160argument. 161The optional modifiers 162.Fl net 163and 164.Fl host 165force the destination to be interpreted as a network or a host, respectively. 166Otherwise, if the 167.Ar destination 168has a 169.Dq local address part 170of 171INADDR_ANY 172.Pq Li 0.0.0.0 , 173or if the 174.Ar destination 175is the symbolic name of a network, then the route is 176assumed to be to a network; otherwise, it is presumed to be a 177route to a host. 178Optionally, the 179.Ar destination 180could also be specified in the 181.Ar net Ns / Ns Ar bits 182format. 183.Pp 184For example, 185.Li 128.32 186is interpreted as 187.Fl host Li 128.0.0.32 ; 188.Li 128.32.130 189is interpreted as 190.Fl host Li 128.32.0.130 ; 191.Fl net Li 128.32 192is interpreted as 193.Li 128.32.0.0; 194.Fl net Li 128.32.130 195is interpreted as 196.Li 128.32.130.0; 197and 198.Li 192.168.64/20 199is interpreted as 200.Fl net Li 192.168.64 Fl netmask Li 255.255.240.0 . 201.Pp 202A 203.Ar destination 204of 205.Ar default 206is a synonym for 207.Fl net Li 0.0.0.0 , 208which is the default route. 209.Pp 210If the destination is directly reachable 211via an interface requiring 212no intermediary system to act as a gateway, the 213.Fl interface 214modifier should be specified; 215the gateway given is the address of this host on the common network, 216indicating the interface to be used for transmission. 217Alternately, if the interface is point to point the name of the interface 218itself may be given, in which case the route remains valid even 219if the local or remote addresses change. 220.Pp 221The optional modifiers 222.Fl mpls , 223.Fl osi , 224and 225.Fl link 226specify that all subsequent addresses are in the 227.Tn MPLS , 228or 229.Tn OSI 230address families, 231or are specified as link-level addresses, 232and the names must be numeric specifications rather than 233symbolic names. 234.Pp 235The optional 236.Fl netmask 237modifier is intended 238to achieve the effect of an 239.Tn OSI 240.Tn ESIS 241redirect with the netmask option, 242or to manually add subnet routes with 243netmasks different from that of the implied network interface 244(as would otherwise be communicated using the OSPF or ISIS routing protocols). 245One specifies an additional ensuing address parameter 246(to be interpreted as a network mask). 247The implicit network mask generated in the AF_INET case 248can be overridden by making sure this option follows the destination parameter. 249.Pp 250For 251.Dv AF_INET6 , 252the 253.Fl prefixlen 254qualifier 255is available instead of the 256.Fl mask 257qualifier because non-continuous masks are not allowed in IPv6. 258For example, 259.Fl prefixlen Li 32 260specifies network mask of 261.Li ffff:ffff:0000:0000:0000:0000:0000:0000 262to be used. 263The default value of prefixlen is 64 to get along with 264the aggregatable address. 265But 0 is assumed if 266.Cm default 267is specified. 268Note that the qualifier works only for 269.Dv AF_INET6 270address family. 271.Pp 272Routes have associated flags which influence operation of the protocols 273when sending to destinations matched by the routes. 274These flags may be set (or sometimes cleared) 275by indicating the following corresponding modifiers: 276.Bd -literal 277-cloning RTF_CLONING - generates a new route on use 278-xresolve RTF_XRESOLVE - emit mesg on use (for external lookup) 279-iface ~RTF_GATEWAY - destination is directly reachable 280-static RTF_STATIC - manually added route 281-nostatic ~RTF_STATIC - pretend route added by kernel or daemon 282-reject RTF_REJECT - emit an ICMP unreachable when matched 283-blackhole RTF_BLACKHOLE - silently discard pkts (during updates) 284-proto1 RTF_PROTO1 - set protocol specific routing flag #1 285-proto2 RTF_PROTO2 - set protocol specific routing flag #2 286-llinfo RTF_LLINFO - validly translates proto addr to link addr 287.Ed 288.Pp 289The optional modifiers 290.Fl rtt , 291.Fl rttvar , 292.Fl sendpipe , 293.Fl recvpipe , 294.Fl mtu , 295.Fl hopcount , 296.Fl expire , 297.Fl msl , 298.Fl iw , 299.Fl iwmax 300and 301.Fl ssthresh 302provide initial values to quantities maintained in the routing entry 303by transport level protocols, such as TCP or TP4. 304These may be individually locked by preceding each such modifier to 305be locked by 306the 307.Fl lock 308meta-modifier, or one can 309specify that all ensuing metrics may be locked by the 310.Fl lockrest 311meta-modifier. 312.Pp 313In a 314.Cm change 315or 316.Cm add 317command where the destination and gateway are not sufficient to specify 318the route (as in the 319.Tn ISO 320case where several interfaces may have the 321same address), the 322.Fl ifp 323or 324.Fl ifa 325modifiers may be used to determine the interface or interface address. 326.Pp 327The optional 328.Fl proxy 329modifier specifies that the 330.Dv RTF_LLINFO 331routing table entry is the 332.Dq published (proxy-only) 333.Tn ARP 334entry, as reported by 335.Xr arp 8 . 336.Pp 337All symbolic names specified for a 338.Ar destination 339or 340.Ar gateway 341are looked up first as a host name using 342.Xr gethostbyname 3 . 343If this lookup fails, 344.Xr getnetbyname 3 345is then used to interpret the name as that of a network. 346.Pp 347The optional 348.Fl push , 349.Fl pop , 350and 351.Fl swap 352modifiers may be used to specify the desired mpls label 353operations for the route. Each route may have up to 3 354label operations assigned to it. The label operations 355may be combined between them, but specifically the 356.Fl push 357and 358.Fl pop 359operations may be repeated if the intent is to push or pop 360more than one label at once. The 361.Fl swap 362operation always swaps the outer label and may not be 363repeated. 364Here are some MPLS route examples: 365.Pp 366Add an normal inet route, but push an mpls 367.Ar label 368to the packet: 369.Pp 370.Bd -ragged -offset indent -compact 371.Nm 372.Cm add 373.Ar destination gateway 374.Fl push 375.Ar label 376.Ed 377.Pp 378Add an normal inet route, but double-push an mpls 379.Ar inner-label 380and an 381.Ar outer-label 382to the packet: 383.Pp 384.Bd -ragged -offset indent -compact 385.Nm 386.Cm add 387.Ar destination gateway 388.Fl push 389.Ar inner-label 390.Fl push 391.Ar outer-label 392.Ed 393.Pp 394Add an mpls route for an 395.Ar incoming-label 396to be forwarded to 397.Ar gateway 398and swap that label with 399.Ar new-label : 400.Pp 401.Bd -ragged -offset indent -compact 402.Nm 403.Cm add 404.Fl mpls 405.Ar incoming-label 406.Fl inet 407.Ar gateway 408.Fl swap 409.Ar new-label 410.Ed 411.Pp 412The 413.Nm 414utility uses a routing socket and the new message types 415.Dv RTM_ADD , RTM_DELETE , RTM_GET , 416and 417.Dv RTM_CHANGE . 418As such, only the super-user may modify 419the routing tables. 420.Sh EXIT STATUS 421.Ex -std 422.Sh DIAGNOSTICS 423.Bl -diag 424.It "add [host \&| network ] %s: gateway %s flags %x" 425The specified route is being added to the tables. The 426values printed are from the routing table entry supplied 427in the 428.Xr ioctl 2 429call. 430If the gateway address used was not the primary address of the gateway 431(the first one returned by 432.Xr gethostbyname 3 ) , 433the gateway address is printed numerically as well as symbolically. 434.It "delete [ host \&| network ] %s: gateway %s flags %x" 435As above, but when deleting an entry. 436.It "%s %s done" 437When the 438.Cm flush 439command is specified, each routing table entry deleted 440is indicated with a message of this form. 441.It "Network is unreachable" 442An attempt to add a route failed because the gateway listed was not 443on a directly-connected network. 444The next-hop gateway must be given. 445.It "not in table" 446A delete operation was attempted for an entry which 447wasn't present in the tables. 448.It "routing table overflow" 449An add operation was attempted, but the system was 450low on resources and was unable to allocate memory 451to create the new entry. 452.It "gateway uses the same route" 453A 454.Cm change 455operation resulted in a route whose gateway uses the 456same route as the one being changed. 457The next-hop gateway should be reachable through a different route. 458.El 459.Sh SEE ALSO 460.\".Xr esis 4 , 461.Xr netintro 4 , 462.Xr route 4 , 463.Xr arp 8 , 464.Xr routed 8 465.Sh HISTORY 466The 467.Nm 468utility appeared in 469.Bx 4.2 . 470.Sh BUGS 471The first paragraph may have slightly exaggerated 472.Xr routed 8 Ns 's 473abilities. 474