1.\" $NetBSD: route.8,v 1.19 1999/07/17 06:51:27 itojun 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 BSD 4.4 39.Sh NAME 40.Nm route 41.Nd manually manipulate the routing tables. 42.Sh SYNOPSIS 43.Nm 44.Op Fl fnqv 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. 54It normally is not needed, as a system routing table management 55daemon such as 56.Xr routed 8 , 57should tend to this task. 58.Pp 59The 60.Nm 61utility supports a limited number of general options, 62but a rich command language, enabling the user to specify 63any arbitrary request that could be delivered via the 64programmatic interface discussed in 65.Xr route 4 . 66.Pp 67.Bl -tag -width Ds 68.It Fl f 69Remove all routes (as per 70.Cm flush ) . 71If used in conjunction with the 72.Cm add , 73.Cm change , 74.Cm delete 75or 76.Cm get 77commands, 78.Nm 79removes the routes before performing the command. 80.It Fl n 81Bypasses attempts to print host and network names symbolically 82when reporting actions. 83(The process of translating between symbolic 84names and numerical equivalents can be quite time consuming, and 85may require correct operation of the network; thus it may be expedient 86to forgo this, especially when attempting to repair networking operations). 87.It Fl q 88Suppress all output. 89.It Fl v 90(verbose) Print additional details. 91.El 92.Pp 93The 94.Nm 95utility provides several commands: 96.Pp 97.Bl -tag -width Fl -compact 98.It Cm add 99Add a route. 100.It Cm flush 101Remove all routes. 102.It Cm delete 103Delete a specific route. 104.It Cm change 105Change aspects of a route (such as its gateway). 106.It Cm get 107Lookup and display the route for a destination. 108.It Cm show 109Print out the route table similar to "netstat \-r" (see 110.Xr netstat 1 ) . 111.It Cm monitor 112Continuously report any changes to the routing information base, 113routing lookup misses, or suspected network partitionings. 114.El 115.Pp 116The monitor command has the syntax 117.Pp 118.Bd -filled -offset indent -compact 119.Nm "" Op Fl n 120.Cm monitor 121.Ed 122.Pp 123The flush command has the syntax 124.Pp 125.Bd -filled -offset indent -compact 126.Nm "" Op Fl n 127.Cm flush 128.Op Ar family 129.Ed 130.Pp 131If the 132.Cm flush 133command is specified, 134.Nm 135will ``flush'' the routing tables of all gateway entries. 136When the address family is specified by any of the 137.Fl osi , 138.Fl xns , 139.Fl atalk , 140.Fl inet , 141or 142.Fl inet6 143modifiers, only routes having destinations with addresses in the 144delineated family will be deleted. 145.Pp 146The other commands have the following syntax: 147.Pp 148.Bd -filled -offset indent -compact 149.Nm "" Op Fl n 150.Ar command 151.Op Fl net No \&| Fl host 152.Ar destination gateway 153.Ed 154.Pp 155where 156.Ar destination 157is the destination host or network, and 158.Ar gateway 159is the next-hop intermediary via which packets should be routed. 160Routes to a particular host may be distinguished from those to 161a network by interpreting the Internet address specified as the 162.Ar destination 163argument. 164The optional modifiers 165.Fl net 166and 167.Fl host 168force the destination to be interpreted as a network or a host, respectively. 169Otherwise, if the 170.Ar destination 171has a ``local address part'' of 172.Dv INADDR_ANY , 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. 178.Pp 179For example, 180.Li 128.32 181is interpreted as 182.Fl host Li 128.0.0.32 ; 183.Li 128.32.130 184is interpreted as 185.Fl host Li 128.32.0.130 ; 186.Fl net Li 128.32 187is interpreted as 188.Li 128.32.0.0; 189and 190.Fl net Li 128.32.130 191is interpreted as 192.Li 128.32.130.0 . 193.Pp 194If the destination is directly reachable 195via an interface requiring 196no intermediary system to act as a gateway, the 197.Fl interface 198modifier should be specified; 199the gateway given is the address of this host on the common network, 200indicating the interface to be used for transmission. 201.Pp 202The optional modifiers 203.Fl xns , 204.Fl osi , 205.Fl atalk , 206and 207.Fl link 208specify that all subsequent addresses are in the 209.Tn XNS , 210.Tn OSI , 211or 212.Tn AppleTalk 213address families, 214or are specified as link-level addresses, 215and the names must be numeric specifications rather than 216symbolic names. 217.Pp 218The optional 219.Fl netmask 220qualifier is intended 221to achieve the effect of an 222.Tn OSI 223.Tn ESIS 224redirect with the netmask option, 225or to manually add subnet routes with 226netmasks different from that of the implied network interface 227(as would otherwise be communicated using the OSPF or ISIS routing protocols). 228One specifies an additional ensuing address parameter 229(to be interpreted as a network mask). 230The implicit network mask generated in the 231.Dv AF_INET 232case 233can be overridden by making sure this option follows the destination parameter. 234.Fl prefixlen 235is also available for similar purpose, in IPv6 case. 236.Pp 237Routes have associated flags which influence operation of the protocols 238when sending to destinations matched by the routes. 239These flags may be set (or sometimes cleared) 240by indicating the following corresponding modifiers: 241.Bd -literal 242-cloning RTF_CLONING - generates a new route on use 243-xresolve RTF_XRESOLVE - emit mesg on use (for external lookup) 244-iface ~RTF_GATEWAY - destination is directly reachable 245-static RTF_STATIC - manually added route 246-nostatic ~RTF_STATIC - pretend route added by kernel or daemon 247-reject RTF_REJECT - emit an ICMP unreachable when matched 248-blackhole RTF_BLACKHOLE - silently discard pkts (during updates) 249-proto1 RTF_PROTO1 - set protocol specific routing flag #1 250-proto2 RTF_PROTO2 - set protocol specific routing flag #2 251-llinfo RTF_LLINFO - validly translates proto addr to link addr 252.Ed 253.Pp 254The optional modifiers 255.Fl rtt , 256.Fl rttvar , 257.Fl sendpipe , 258.Fl recvpipe , 259.Fl mtu , 260.Fl hopcount , 261.Fl expire , 262and 263.Fl ssthresh 264provide initial values to quantities maintained in the routing entry 265by transport level protocols, such as TCP or TP4. 266These may be individually locked by preceding each such modifier to 267be locked by 268the 269.Fl lock 270meta-modifier, or one can 271specify that all ensuing metrics may be locked by the 272.Fl lockrest 273meta-modifier. 274.Pp 275In a 276.Cm change 277or 278.Cm add 279command where the destination and gateway are not sufficient to specify 280the route (as in the 281.Tn ISO 282case where several interfaces may have the 283same address), the 284.Fl ifp 285or 286.Fl ifa 287modifiers may be used to determine the interface or interface address. 288.Pp 289All symbolic names specified for a 290.Ar destination 291or 292.Ar gateway 293are looked up first as a host name using 294.Xr gethostbyname 3 . 295If this lookup fails, 296.Xr getnetbyname 3 297is then used to interpret the name as that of a network. 298.Pp 299.Nm 300uses a routing socket and the new message types 301.Dv RTM_ADD , 302.Dv RTM_DELETE , 303.Dv RTM_GET , 304and 305.Dv RTM_CHANGE . 306As such, only the super-user may modify 307the routing tables. 308.Sh DIAGNOSTICS 309.Bl -tag -width Ds 310.It Sy "add [host \&| network ] %s: gateway %s flags %x" 311The specified route is being added to the tables. 312The values printed are from the routing table entry supplied in the 313.Xr ioctl 2 314call. 315If the gateway address used was not the primary address of the gateway 316(the first one returned by 317.Xr gethostbyname 3 ) , 318the gateway address is printed numerically as well as symbolically. 319.It Sy "delete [ host \&| network ] %s: gateway %s flags %x" 320As above, but when deleting an entry. 321.It Sy "%s %s done" 322When the 323.Cm flush 324command is specified, each routing table entry deleted 325is indicated with a message of this form. 326.It Sy "Network is unreachable" 327An attempt to add a route failed because the gateway listed was not 328on a directly-connected network. 329The next-hop gateway must be given. 330.It Sy "not in table" 331A delete operation was attempted for an entry which 332wasn't present in the tables. 333.It Sy "routing table overflow" 334An add operation was attempted, but the system was 335low on resources and was unable to allocate memory 336to create the new entry. 337.It Sy "Permission denied" 338The attempted operation is privileged. 339Only root may modify the routing tables. 340These privileges are enforced by the kernel. 341.El 342.Sh SEE ALSO 343.Xr netintro 4 , 344.Xr route 4 , 345.Xr esis 4 , 346.Xr routed 8 347.\" .Xr XNSrouted 8 348.Sh HISTORY 349The 350.Nm 351command appeared in 352.Bx 4.2 . 353IPv6 support was added by WIDE/KAME project. 354.Sh BUGS 355The first paragraph may have slightly exaggerated 356.Xr routed 8 Ns 's 357abilities. 358.Pp 359Some uses of the 360.Fl ifa 361or 362.Fl ifp 363modifiers with the add command will incorrectly fail with a 364.Dq Network is unreachable 365message if there is no default route. 366See case 367.Dv RTM_ADD 368in 369.Pa sys/net/rtsock.c:route_output 370for details. 371