1.\" $NetBSD: route.8,v 1.29 2002/02/08 13:32:32 hubertf Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)route.8 8.4 (Berkeley) 6/1/94 35.\" 36.Dd October 23, 1998 37.Dt ROUTE 8 38.Os 39.Sh NAME 40.Nm route 41.Nd manually manipulate the routing tables 42.Sh SYNOPSIS 43.Nm 44.Op Fl fnqsv 45.Ar command 46.Oo 47.Op Ar modifiers 48.Ar args 49.Oc 50.Sh DESCRIPTION 51.Nm 52is a utility used to manually manipulate the network 53routing tables. 54Except for setting up the default route, it is normally not needed, 55as a system routing table management daemon such as 56.Xr routed 8 , 57should tend to this task. 58.Pp 59.Nm 60can be used to modify nearly any aspect of the routing policy, 61except packet forwarding, which can be manipulated through the 62.Xr sysctl 8 63command. 64.Pp 65The 66.Nm 67utility supports a limited number of general options, 68but a rich command language, enabling the user to specify 69any arbitrary request that could be delivered via the 70programmatic interface discussed in 71.Xr route 4 . 72.Pp 73.Bl -tag -width Ds 74.It Fl f 75Remove all routes (as per 76.Cm flush ) . 77If used in conjunction with the 78.Cm add , 79.Cm change , 80.Cm delete 81or 82.Cm get 83commands, 84.Nm 85removes the routes before performing the command. 86.It Fl n 87Bypasses attempts to print host and network names symbolically 88when reporting actions. 89(The process of translating between symbolic 90names and numerical equivalents can be quite time consuming, and 91may require correct operation of the network; thus it may be expedient 92to forgo this, especially when attempting to repair networking operations). 93.It Fl q 94Suppress all output from commands that manipulate the routing table. 95.It Fl s 96(short) Suppresses all output from a 97.Cm get 98command except for the actual gateway that will be used. 99How the gateway is printed depends on the type of route being looked up. 100.It Fl v 101(verbose) Print additional details. 102.El 103.Pp 104The 105.Nm 106utility provides several commands: 107.Pp 108.Bl -tag -width Fl -compact 109.It Cm add 110Add a route. 111.It Cm flush 112Remove all routes. 113.It Cm delete 114Delete a specific route. 115.It Cm change 116Change aspects of a route (such as its gateway). 117.It Cm get 118Lookup and display the route for a destination. 119.It Cm show 120Print out the route table similar to "netstat \-r" (see 121.Xr netstat 1 ) . 122.It Cm monitor 123Continuously report any changes to the routing information base, 124routing lookup misses, or suspected network partitionings. 125.El 126.Pp 127The monitor command has the syntax 128.Pp 129.Bd -filled -offset indent -compact 130.Nm "" Op Fl n 131.Cm monitor 132.Ed 133.Pp 134The flush command has the syntax 135.Pp 136.Bd -filled -offset indent -compact 137.Nm "" Op Fl n 138.Cm flush 139.Op Ar family 140.Ed 141.Pp 142If the 143.Cm flush 144command is specified, 145.Nm 146will ``flush'' the routing tables of all gateway entries. 147When the address family is specified by any of the 148.Fl osi , 149.Fl xns , 150.Fl atalk , 151.Fl inet , 152or 153.Fl inet6 154modifiers, only routes having destinations with addresses in the 155delineated family will be manipulated. 156.Pp 157The other commands have the following syntax: 158.Pp 159.Bd -filled -offset indent -compact 160.Nm "" Op Fl n 161.Ar command 162.Op Fl net No \&| Fl host 163.Ar destination gateway 164.Ed 165.Pp 166where 167.Ar destination 168is the destination host or network, and 169.Ar gateway 170is the next-hop intermediary via which packets should be routed. 171Routes to a particular host may be distinguished from those to 172a network by interpreting the Internet address specified as the 173.Ar destination 174argument. 175The optional modifiers 176.Fl net 177and 178.Fl host 179force the destination to be interpreted as a network or a host, respectively. 180Otherwise, if the 181.Ar destination 182has a ``local address part'' of 183.Dv INADDR_ANY , 184or if the 185.Ar destination 186is the symbolic name of a network, then the route is 187assumed to be to a network; otherwise, it is presumed to be a 188route to a host. 189.Pp 190For example, 191.Li 128.32 192is interpreted as 193.Fl host Li 128.0.0.32 ; 194.Li 128.32.130 195is interpreted as 196.Fl host Li 128.32.0.130 ; 197.Fl net Li 128.32 198is interpreted as 199.Li 128.32.0.0 ; 200and 201.Fl net Li 128.32.130 202is interpreted as 203.Li 128.32.130.0 . 204.Pp 205The keyword 206.Cm default 207can be used as the 208.Ar destination 209to set up a default route to a smart 210.Ar gateway . 211If no other routes match, this default route will be used as a last resort. 212.Pp 213If the destination is directly reachable 214via an interface requiring 215no intermediary system to act as a gateway, the 216.Fl interface 217modifier should be specified; 218the gateway given is the address of this host on the common network, 219indicating the interface to be used for transmission. 220.Pp 221The optional modifiers 222.Fl xns , 223.Fl osi , 224.Fl atalk , 225and 226.Fl link 227specify that all subsequent addresses are in the 228.Tn XNS , 229.Tn OSI , 230or 231.Tn AppleTalk 232address families, 233or are specified as link-level addresses, 234and the names must be numeric specifications rather than 235symbolic names. 236.Pp 237The optional 238.Fl netmask 239qualifier is intended 240to achieve the effect of an 241.Tn OSI 242.Tn ESIS 243redirect with the netmask option, 244or to manually add subnet routes with 245netmasks different from that of the implied network interface 246(as would otherwise be communicated using the OSPF or ISIS routing protocols). 247One specifies an additional ensuing address parameter 248(to be interpreted as a network mask). 249The implicit network mask generated in the 250.Dv AF_INET 251case 252can be overridden by making sure this option follows the destination parameter. 253.Fl prefixlen 254is also available for similar purpose, in IPv4 and IPv6 case. 255.Pp 256Routes have associated flags which influence operation of the protocols 257when sending to destinations matched by the routes. 258These flags may be set (or sometimes cleared) 259by indicating the following corresponding modifiers: 260.Bd -literal 261-cloning RTF_CLONING - generates a new route on use 262-cloned RTF_CLONED - cloned route generated by RTF_CLONING 263-xresolve RTF_XRESOLVE - emit mesg on use (for external lookup) 264-iface ~RTF_GATEWAY - destination is directly reachable 265-static RTF_STATIC - manually added route 266-nostatic ~RTF_STATIC - pretend route added by kernel or daemon 267-reject RTF_REJECT - emit an ICMP unreachable when matched 268-blackhole RTF_BLACKHOLE - silently discard pkts (during updates) 269-proto1 RTF_PROTO1 - set protocol specific routing flag #1 270-proto2 RTF_PROTO2 - set protocol specific routing flag #2 271-llinfo RTF_LLINFO - validly translates proto addr to link addr 272.Ed 273.Pp 274The optional modifiers 275.Fl rtt , 276.Fl rttvar , 277.Fl sendpipe , 278.Fl recvpipe , 279.Fl mtu , 280.Fl hopcount , 281.Fl expire , 282and 283.Fl ssthresh 284provide initial values to quantities maintained in the routing entry 285by transport level protocols, such as TCP or TP4. 286These may be individually locked by preceding each such modifier to 287be locked by 288the 289.Fl lock 290meta-modifier, or one can 291specify that all ensuing metrics may be locked by the 292.Fl lockrest 293meta-modifier. 294.Pp 295In a 296.Cm change 297or 298.Cm add 299command where the destination and gateway are not sufficient to specify 300the route (as in the 301.Tn ISO 302case where several interfaces may have the 303same address), the 304.Fl ifp 305or 306.Fl ifa 307modifiers may be used to determine the interface or interface address. 308.Pp 309All symbolic names specified for a 310.Ar destination 311or 312.Ar gateway 313are looked up first as a host name using 314.Xr gethostbyname 3 . 315If this lookup fails, 316.Xr getnetbyname 3 317is then used to interpret the name as that of a network. 318.Pp 319.Nm 320uses a routing socket and the new message types 321.Dv RTM_ADD , 322.Dv RTM_DELETE , 323.Dv RTM_GET , 324and 325.Dv RTM_CHANGE . 326As such, only the super-user may modify 327the routing tables. 328.Sh EXIT STATUS 329The 330.Nm 331utility exits 0 on success, and \*[Gt]0 if an error occurs. This includes 332the use of the 333.Cm get 334command to look up a route that is incomplete. 335.Sh EXAMPLES 336This sets the default route to 192.168.0.1: 337.Dl route add default 192.168.0.1 338This shows all routes, without DNS resolution (this is useful if the 339DNS is not available): 340.Dl route -n show 341To install a static route through 10.200.0.1 to reach the network 342192.168.1.0/28, use this: 343.Dl route add -net 192.168.1.0 -netmask 255.255.255.248 10.200.0.1 344.Sh DIAGNOSTICS 345.Bl -tag -width Ds 346.It Sy "add [host \&| network ] %s: gateway %s flags %x" 347The specified route is being added to the tables. 348The values printed are from the routing table entry supplied in the 349.Xr ioctl 2 350call. 351If the gateway address used was not the primary address of the gateway 352(the first one returned by 353.Xr gethostbyname 3 ) , 354the gateway address is printed numerically as well as symbolically. 355.It Sy "delete [ host \&| network ] %s: gateway %s flags %x" 356As above, but when deleting an entry. 357.It Sy "%s %s done" 358When the 359.Cm flush 360command is specified, each routing table entry deleted 361is indicated with a message of this form. 362.It Sy "Network is unreachable" 363An attempt to add a route failed because the gateway listed was not 364on a directly-connected network. 365The next-hop gateway must be given. 366.It Sy "not in table" 367A delete operation was attempted for an entry which 368wasn't present in the tables. 369.It Sy "routing table overflow" 370An add operation was attempted, but the system was 371low on resources and was unable to allocate memory 372to create the new entry. 373.It Sy "Permission denied" 374The attempted operation is privileged. 375Only root may modify the routing tables. 376These privileges are enforced by the kernel. 377.El 378.Sh SEE ALSO 379.Xr esis 4 , 380.Xr netintro 4 , 381.Xr route 4 , 382.Xr routed 8 , 383.Xr sysctl 8 384.\" .Xr XNSrouted 8 385.Sh HISTORY 386The 387.Nm 388command appeared in 389.Bx 4.2 . 390IPv6 support was added by WIDE/KAME project. 391.Sh BUGS 392The first paragraph may have slightly exaggerated 393.Xr routed 8 Ns 's 394abilities. 395.Pp 396Some uses of the 397.Fl ifa 398or 399.Fl ifp 400modifiers with the add command will incorrectly fail with a 401.Dq Network is unreachable 402message if there is no default route. 403See case 404.Dv RTM_ADD 405in 406.Pa sys/net/rtsock.c:route_output 407for details. 408