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 January 8, 2016 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 dnqtvw 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 d 70(debug) Print additional details for monitor and rtmsg commands. 71.It Fl n 72Bypass attempts to print host and network names symbolically 73when reporting actions. (The process of translating between symbolic 74names and numerical equivalents can be quite time consuming, and 75may require correct operation of the network; thus it may be expedient 76to forget this, especially when attempting to repair networking operations). 77.It Fl v 78(verbose) Print additional details. 79.It Fl q 80Suppress all output from the 81.Cm add , delete , 82and 83.Cm flush 84commands. 85.It Fl w 86Print the full width of the data being represented even if it would overflow 87the column. 88.El 89.Pp 90The 91.Nm 92utility provides six commands: 93.Pp 94.Bl -tag -width Fl -compact 95.It Cm add 96Add a route. 97.It Cm flush 98Remove all routes. 99.It Cm delete 100Delete a specific route. 101.It Cm change 102Change aspects of a route (such as its gateway). 103.It Cm get 104Lookup and display the route for a destination. 105.It Cm show 106Print out the route table similar to "netstat \-r" (see 107.Xr netstat 1 ) . 108.It Cm monitor 109Continuously report any changes to the routing information base, 110routing lookup misses, or suspected network partitionings. 111.El 112.Pp 113The monitor command has the syntax: 114.Pp 115.Bd -ragged -offset indent -compact 116.Nm 117.Op Fl n 118.Cm monitor 119.Ed 120.Pp 121The flush command has the syntax: 122.Pp 123.Bd -ragged -offset indent -compact 124.Nm 125.Op Fl n 126.Cm flush 127.Op Ar family 128.Ed 129.Pp 130If the 131.Cm flush 132command is specified, 133.Nm 134will ``flush'' the routing tables of all gateway entries. 135When the address family may is specified by any of the 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 224and 225.Fl link 226specify that all subsequent addresses are in the 227.Tn MPLS 228address family 229or are specified as link-level addresses, 230and the names must be numeric specifications rather than 231symbolic names. 232.Pp 233The optional 234.Fl netmask 235modifier is intended to manually add subnet routes with 236netmasks different from that of the implied network interface. 237One specifies an additional ensuing address parameter 238(to be interpreted as a network mask). 239The implicit network mask generated in the AF_INET case 240can be overridden by making sure this option follows the destination parameter. 241.Pp 242For 243.Dv AF_INET6 , 244the 245.Fl prefixlen 246qualifier 247is available instead of the 248.Fl mask 249qualifier because non-continuous masks are not allowed in IPv6. 250For example, 251.Fl prefixlen Li 32 252specifies network mask of 253.Li ffff:ffff:0000:0000:0000:0000:0000:0000 254to be used. 255The default value of prefixlen is 64 to get along with 256the aggregatable address. 257But 0 is assumed if 258.Cm default 259is specified. 260Note that the qualifier works only for 261.Dv AF_INET6 262address family. 263.Pp 264Routes have associated flags which influence operation of the protocols 265when sending to destinations matched by the routes. 266These flags may be set (or sometimes cleared) 267by indicating the following corresponding modifiers: 268.Bd -literal 269-cloning RTF_CLONING - generates a new route on use 270-xresolve RTF_XRESOLVE - emit mesg on use (for external lookup) 271-iface ~RTF_GATEWAY - destination is directly reachable 272-static RTF_STATIC - manually added route 273-nostatic ~RTF_STATIC - pretend route added by kernel or daemon 274-reject RTF_REJECT - emit an ICMP unreachable when matched 275-blackhole RTF_BLACKHOLE - silently discard pkts (during updates) 276-proto1 RTF_PROTO1 - set protocol specific routing flag #1 277-proto2 RTF_PROTO2 - set protocol specific routing flag #2 278-llinfo RTF_LLINFO - validly translates proto addr to link addr 279.Ed 280.Pp 281The optional modifiers 282.Fl rtt , 283.Fl rttvar , 284.Fl sendpipe , 285.Fl recvpipe , 286.Fl mtu , 287.Fl hopcount , 288.Fl expire , 289.Fl msl , 290.Fl iw , 291.Fl iwmax 292and 293.Fl ssthresh 294provide initial values to quantities maintained in the routing entry 295by transport level protocols, such as TCP or TP4. 296These may be individually locked by preceding each such modifier to 297be locked by 298the 299.Fl lock 300meta-modifier, or one can 301specify that all ensuing metrics may be locked by the 302.Fl lockrest 303meta-modifier. 304.Pp 305In a 306.Cm change 307or 308.Cm add 309command where the destination and gateway are not sufficient to specify 310the route (as in the 311.Tn ISO 312case where several interfaces may have the 313same address), the 314.Fl ifp 315or 316.Fl ifa 317modifiers may be used to determine the interface or interface address. 318.Pp 319The optional 320.Fl proxy 321modifier specifies that the 322.Dv RTF_LLINFO 323routing table entry is the 324.Dq published (proxy-only) 325.Tn ARP 326entry, as reported by 327.Xr arp 8 . 328.Pp 329All symbolic names specified for a 330.Ar destination 331or 332.Ar gateway 333are looked up first as a host name using 334.Xr gethostbyname 3 . 335If this lookup fails, 336.Xr getnetbyname 3 337is then used to interpret the name as that of a network. 338.Pp 339The optional 340.Fl push , 341.Fl pop , 342and 343.Fl swap 344modifiers may be used to specify the desired mpls label 345operations for the route. Each route may have up to 3 346label operations assigned to it. The label operations 347may be combined between them, but specifically the 348.Fl push 349and 350.Fl pop 351operations may be repeated if the intent is to push or pop 352more than one label at once. The 353.Fl swap 354operation always swaps the outer label and may not be 355repeated. 356Here are some MPLS route examples: 357.Pp 358Add an normal inet route, but push an mpls 359.Ar label 360to the packet: 361.Pp 362.Bd -ragged -offset indent -compact 363.Nm 364.Cm add 365.Ar destination gateway 366.Fl push 367.Ar label 368.Ed 369.Pp 370Add an normal inet route, but double-push an mpls 371.Ar inner-label 372and an 373.Ar outer-label 374to the packet: 375.Pp 376.Bd -ragged -offset indent -compact 377.Nm 378.Cm add 379.Ar destination gateway 380.Fl push 381.Ar inner-label 382.Fl push 383.Ar outer-label 384.Ed 385.Pp 386Add an mpls route for an 387.Ar incoming-label 388to be forwarded to 389.Ar gateway 390and swap that label with 391.Ar new-label : 392.Pp 393.Bd -ragged -offset indent -compact 394.Nm 395.Cm add 396.Fl mpls 397.Ar incoming-label 398.Fl inet 399.Ar gateway 400.Fl swap 401.Ar new-label 402.Ed 403.Pp 404The 405.Nm 406utility uses a routing socket and the new message types 407.Dv RTM_ADD , RTM_DELETE , RTM_GET , 408and 409.Dv RTM_CHANGE . 410As such, only the super-user may modify 411the routing tables. 412.Sh EXIT STATUS 413.Ex -std 414.Sh DIAGNOSTICS 415.Bl -diag 416.It "add [host \&| network ] %s: gateway %s flags %x" 417The specified route is being added to the tables. The 418values printed are from the routing table entry supplied 419in the 420.Xr ioctl 2 421call. 422If the gateway address used was not the primary address of the gateway 423(the first one returned by 424.Xr gethostbyname 3 ) , 425the gateway address is printed numerically as well as symbolically. 426.It "delete [ host \&| network ] %s: gateway %s flags %x" 427As above, but when deleting an entry. 428.It "%s %s done" 429When the 430.Cm flush 431command is specified, each routing table entry deleted 432is indicated with a message of this form. 433.It "Network is unreachable" 434An attempt to add a route failed because the gateway listed was not 435on a directly-connected network. 436The next-hop gateway must be given. 437.It "not in table" 438A delete operation was attempted for an entry which 439wasn't present in the tables. 440.It "routing table overflow" 441An add operation was attempted, but the system was 442low on resources and was unable to allocate memory 443to create the new entry. 444.It "gateway uses the same route" 445A 446.Cm change 447operation resulted in a route whose gateway uses the 448same route as the one being changed. 449The next-hop gateway should be reachable through a different route. 450.El 451.Sh SEE ALSO 452.\".Xr esis 4 , 453.Xr netintro 4 , 454.Xr route 4 , 455.Xr arp 8 , 456.Xr routed 8 457.Sh HISTORY 458The 459.Nm 460utility appeared in 461.Bx 4.2 . 462.Sh BUGS 463The first paragraph may have slightly exaggerated 464.Xr routed 8 Ns 's 465abilities. 466