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