sbin/route/route.8

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