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.\" 4. 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 xns , 136.Fl inet6 , 137or 138.Fl inet 139modifiers, only routes having destinations with addresses in the 140delineated family will be deleted. 141.Pp 142The other commands have the following syntax: 143.Pp 144.Bd -ragged -offset indent -compact 145.Nm 146.Op Fl n 147.Ar command 148.Op Fl net No \&| Fl host 149.Ar destination gateway 150.Op Ar netmask 151.Ed 152.Pp 153where 154.Ar destination 155is the destination host or network, 156.Ar gateway 157is the next-hop intermediary via which packets should be routed. 158Routes to a particular host may be distinguished from those to 159a network by interpreting the Internet address specified as the 160.Ar destination 161argument. 162The optional modifiers 163.Fl net 164and 165.Fl host 166force the destination to be interpreted as a network or a host, respectively. 167Otherwise, if the 168.Ar destination 169has a 170.Dq local address part 171of 172INADDR_ANY 173.Pq Li 0.0.0.0 , 174or if the 175.Ar destination 176is the symbolic name of a network, then the route is 177assumed to be to a network; otherwise, it is presumed to be a 178route to a host. 179Optionally, the 180.Ar destination 181could also be specified in the 182.Ar net Ns / Ns Ar bits 183format. 184.Pp 185For example, 186.Li 128.32 187is interpreted as 188.Fl host Li 128.0.0.32 ; 189.Li 128.32.130 190is interpreted as 191.Fl host Li 128.32.0.130 ; 192.Fl net Li 128.32 193is interpreted as 194.Li 128.32.0.0; 195.Fl net Li 128.32.130 196is interpreted as 197.Li 128.32.130.0; 198and 199.Li 192.168.64/20 200is interpreted as 201.Fl net Li 192.168.64 Fl netmask Li 255.255.240.0 . 202.Pp 203A 204.Ar destination 205of 206.Ar default 207is a synonym for 208.Fl net Li 0.0.0.0 , 209which is the default route. 210.Pp 211If the destination is directly reachable 212via an interface requiring 213no intermediary system to act as a gateway, the 214.Fl interface 215modifier should be specified; 216the gateway given is the address of this host on the common network, 217indicating the interface to be used for transmission. 218Alternately, if the interface is point to point the name of the interface 219itself may be given, in which case the route remains valid even 220if the local or remote addresses change. 221.Pp 222The optional modifiers 223.Fl mpls , 224.Fl xns , 225.Fl osi , 226and 227.Fl link 228specify that all subsequent addresses are in the 229.Tn MPLS , 230.Tn XNS , 231or 232.Tn OSI 233address families, 234or are specified as link-level addresses, 235and the names must be numeric specifications rather than 236symbolic names. 237.Pp 238The optional 239.Fl netmask 240modifier is intended 241to achieve the effect of an 242.Tn OSI 243.Tn ESIS 244redirect with the netmask option, 245or to manually add subnet routes with 246netmasks different from that of the implied network interface 247(as would otherwise be communicated using the OSPF or ISIS routing protocols). 248One specifies an additional ensuing address parameter 249(to be interpreted as a network mask). 250The implicit network mask generated in the AF_INET case 251can be overridden by making sure this option follows the destination parameter. 252.Pp 253For 254.Dv AF_INET6 , 255the 256.Fl prefixlen 257qualifier 258is available instead of the 259.Fl mask 260qualifier because non-continuous masks are not allowed in IPv6. 261For example, 262.Fl prefixlen Li 32 263specifies network mask of 264.Li ffff:ffff:0000:0000:0000:0000:0000:0000 265to be used. 266The default value of prefixlen is 64 to get along with 267the aggregatable address. 268But 0 is assumed if 269.Cm default 270is specified. 271Note that the qualifier works only for 272.Dv AF_INET6 273address family. 274.Pp 275Routes have associated flags which influence operation of the protocols 276when sending to destinations matched by the routes. 277These flags may be set (or sometimes cleared) 278by indicating the following corresponding modifiers: 279.Bd -literal 280-cloning RTF_CLONING - generates a new route on use 281-xresolve RTF_XRESOLVE - emit mesg on use (for external lookup) 282-iface ~RTF_GATEWAY - destination is directly reachable 283-static RTF_STATIC - manually added route 284-nostatic ~RTF_STATIC - pretend route added by kernel or daemon 285-reject RTF_REJECT - emit an ICMP unreachable when matched 286-blackhole RTF_BLACKHOLE - silently discard pkts (during updates) 287-proto1 RTF_PROTO1 - set protocol specific routing flag #1 288-proto2 RTF_PROTO2 - set protocol specific routing flag #2 289-llinfo RTF_LLINFO - validly translates proto addr to link addr 290.Ed 291.Pp 292The optional modifiers 293.Fl rtt , 294.Fl rttvar , 295.Fl sendpipe , 296.Fl recvpipe , 297.Fl mtu , 298.Fl hopcount , 299.Fl expire , 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 IPXrouted 8 , 465.Xr routed 8 466.\".Xr XNSrouted 8 467.Sh HISTORY 468The 469.Nm 470utility appeared in 471.Bx 4.2 . 472.Sh BUGS 473The first paragraph may have slightly exaggerated 474.Xr routed 8 Ns 's 475abilities. 476