sbin/route/route.8

   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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)route.8     8.3 (Berkeley) 3/19/94
  33 .\" $FreeBSD: src/sbin/route/route.8,v 1.17.2.9 2003/02/24 00:56:43 trhodes Exp $
  34 .\"
  35 .Dd June 8, 2001
  36 .Dt ROUTE 8
  37 .Os
  38 .Sh NAME
  39 .Nm route
  40 .Nd manually manipulate the routing tables
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl dnqtv
  44 .Op Fl c Ar cpu
  45 .Ar command
  46 .Oo
  47 .Op Ar modifiers
  48 .Ar args
  49 .Oc
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 utility is used to manually manipulate the network
  54 routing tables.  It normally is not needed, as a
  55 system routing table management daemon such as
  56 .Xr routed 8 ,
  57 should tend to this task.
  58 .Pp
  59 The
  60 .Nm
  61 utility supports a limited number of general options,
  62 but a rich command language, enabling the user to specify
  63 any arbitrary request that could be delivered via the
  64 programmatic interface discussed in
  65 .Xr route 4 .
  66 .Pp
  67 The following options are available:
  68 .Bl -tag -width indent
  69 .It Fl c Ar cpu
  70 On SMP systems the route table is replicated.  This option allows the
  71 route table for a specific cpu to be accessed and exists primarily
  72 for debugging purposes.
  73 .It Fl n
  74 Bypass attempts to print host and network names symbolically
  75 when reporting actions.  (The process of translating between symbolic
  76 names and numerical equivalents can be quite time consuming, and
  77 may require correct operation of the network; thus it may be expedient
  78 to forget this, especially when attempting to repair networking operations).
  79 .It Fl v
  80 (verbose) Print additional details.
  81 .It Fl q
  82 Suppress all output from the
  83 .Cm add , delete ,
  84 and
  85 .Cm flush
  86 commands.
  87 .It Fl w
  88 Print the full width of the data being represented even if it would overflow
  89 the column.
  90 .El
  91 .Pp
  92 The
  93 .Nm
  94 utility provides six commands:
  95 .Pp
  96 .Bl -tag -width Fl -compact
  97 .It Cm add
  98 Add a route.
  99 .It Cm flush
 100 Remove all routes.
 101 .It Cm delete
 102 Delete a specific route.
 103 .It Cm change
 104 Change aspects of a route (such as its gateway).
 105 .It Cm get
 106 Lookup and display the route for a destination.
 107 .It Cm show
 108 Print out the route table similar to "netstat \-r" (see
 109 .Xr netstat 1 ) .
 110 .It Cm monitor
 111 Continuously report any changes to the routing information base,
 112 routing lookup misses, or suspected network partitionings.
 113 .El
 114 .Pp
 115 The monitor command has the syntax:
 116 .Pp
 117 .Bd -ragged -offset indent -compact
 118 .Nm
 119 .Op Fl n
 120 .Cm monitor
 121 .Ed
 122 .Pp
 123 The flush command has the syntax:
 124 .Pp
 125 .Bd -ragged -offset indent -compact
 126 .Nm
 127 .Op Fl n
 128 .Cm flush
 129 .Op Ar family
 130 .Ed
 131 .Pp
 132 If the
 133 .Cm flush
 134 command is specified,
 135 .Nm
 136 will ``flush'' the routing tables of all gateway entries.
 137 When the address family may is specified by any of the
 138 .Fl osi ,
 139 .Fl xns ,
 140 .Fl inet6 ,
 141 or
 142 .Fl inet
 143 modifiers, only routes having destinations with addresses in the
 144 delineated family will be deleted.
 145 .Pp
 146 The other commands have the following syntax:
 147 .Pp
 148 .Bd -ragged -offset indent -compact
 149 .Nm
 150 .Op Fl n
 151 .Ar command
 152 .Op Fl net No \&| Fl host
 153 .Ar destination gateway
 154 .Op Ar netmask
 155 .Ed
 156 .Pp
 157 where
 158 .Ar destination
 159 is the destination host or network,
 160 .Ar gateway
 161 is the next-hop intermediary via which packets should be routed.
 162 Routes to a particular host may be distinguished from those to
 163 a network by interpreting the Internet address specified as the
 164 .Ar destination
 165 argument.
 166 The optional modifiers
 167 .Fl net
 168 and
 169 .Fl host
 170 force the destination to be interpreted as a network or a host, respectively.
 171 Otherwise, if the
 172 .Ar destination
 173 has a
 174 .Dq local address part
 175 of
 176 INADDR_ANY
 177 .Pq Li 0.0.0.0 ,
 178 or if the
 179 .Ar destination
 180 is the symbolic name of a network, then the route is
 181 assumed to be to a network; otherwise, it is presumed to be a
 182 route to a host.
 183 Optionally, the
 184 .Ar destination
 185 could also be specified in the
 186 .Ar net Ns / Ns Ar bits
 187 format.
 188 .Pp
 189 For example,
 190 .Li 128.32
 191 is interpreted as
 192 .Fl host Li 128.0.0.32 ;
 193 .Li 128.32.130
 194 is interpreted as
 195 .Fl host Li 128.32.0.130 ;
 196 .Fl net Li 128.32
 197 is interpreted as
 198 .Li 128.32.0.0;
 199 .Fl net Li 128.32.130
 200 is interpreted as
 201 .Li 128.32.130.0;
 202 and
 203 .Li 192.168.64/20
 204 is interpreted as
 205 .Fl net Li 192.168.64 Fl netmask Li 255.255.240.0 .
 206 .Pp
 207 A
 208 .Ar destination
 209 of
 210 .Ar default
 211 is a synonym for
 212 .Fl net Li 0.0.0.0 ,
 213 which is the default route.
 214 .Pp
 215 If the destination is directly reachable
 216 via an interface requiring
 217 no intermediary system to act as a gateway, the
 218 .Fl interface
 219 modifier should be specified;
 220 the gateway given is the address of this host on the common network,
 221 indicating the interface to be used for transmission.
 222 Alternately, if the interface is point to point the name of the interface
 223 itself may be given, in which case the route remains valid even
 224 if the local or remote addresses change.
 225 .Pp
 226 The optional modifiers
 227 .Fl mpls ,
 228 .Fl xns ,
 229 .Fl osi ,
 230 and
 231 .Fl link
 232 specify that all subsequent addresses are in the
 233 .Tn MPLS ,
 234 .Tn XNS ,
 235 or
 236 .Tn OSI
 237 address families,
 238 or are specified as link-level addresses,
 239 and the names must be numeric specifications rather than
 240 symbolic names.
 241 .Pp
 242 The optional
 243 .Fl netmask
 244 modifier is intended
 245 to achieve the effect of an
 246 .Tn OSI
 247 .Tn ESIS
 248 redirect with the netmask option,
 249 or to manually add subnet routes with
 250 netmasks different from that of the implied network interface
 251 (as would otherwise be communicated using the OSPF or ISIS routing protocols).
 252 One specifies an additional ensuing address parameter
 253 (to be interpreted as a network mask).
 254 The implicit network mask generated in the AF_INET case
 255 can be overridden by making sure this option follows the destination parameter.
 256 .Pp
 257 For
 258 .Dv AF_INET6 ,
 259 the
 260 .Fl prefixlen
 261 qualifier
 262 is available instead of the
 263 .Fl mask
 264 qualifier because non-continuous masks are not allowed in IPv6.
 265 For example,
 266 .Fl prefixlen Li 32
 267 specifies network mask of
 268 .Li ffff:ffff:0000:0000:0000:0000:0000:0000
 269 to be used.
 270 The default value of prefixlen is 64 to get along with
 271 the aggregatable address.
 272 But 0 is assumed if
 273 .Cm default
 274 is specified.
 275 Note that the qualifier works only for
 276 .Dv AF_INET6
 277 address family.
 278 .Pp
 279 Routes have associated flags which influence operation of the protocols
 280 when sending to destinations matched by the routes.
 281 These flags may be set (or sometimes cleared)
 282 by indicating the following corresponding modifiers:
 283 .Bd -literal
 284 -cloning   RTF_CLONING    - generates a new route on use
 285 -xresolve  RTF_XRESOLVE   - emit mesg on use (for external lookup)
 286 -iface    ~RTF_GATEWAY    - destination is directly reachable
 287 -static    RTF_STATIC     - manually added route
 288 -nostatic ~RTF_STATIC     - pretend route added by kernel or daemon
 289 -reject    RTF_REJECT     - emit an ICMP unreachable when matched
 290 -blackhole RTF_BLACKHOLE  - silently discard pkts (during updates)
 291 -proto1    RTF_PROTO1     - set protocol specific routing flag #1
 292 -proto2    RTF_PROTO2     - set protocol specific routing flag #2
 293 -llinfo    RTF_LLINFO     - validly translates proto addr to link addr
 294 .Ed
 295 .Pp
 296 The optional modifiers
 297 .Fl rtt ,
 298 .Fl rttvar ,
 299 .Fl sendpipe ,
 300 .Fl recvpipe ,
 301 .Fl mtu ,
 302 .Fl hopcount ,
 303 .Fl expire ,
 304 and
 305 .Fl ssthresh
 306 provide initial values to quantities maintained in the routing entry
 307 by transport level protocols, such as TCP or TP4.
 308 These may be individually locked by preceding each such modifier to
 309 be locked by
 310 the
 311 .Fl lock
 312 meta-modifier, or one can
 313 specify that all ensuing metrics may be locked by the
 314 .Fl lockrest
 315 meta-modifier.
 316 .Pp
 317 In a
 318 .Cm change
 319 or
 320 .Cm add
 321 command where the destination and gateway are not sufficient to specify
 322 the route (as in the
 323 .Tn ISO
 324 case where several interfaces may have the
 325 same address), the
 326 .Fl ifp
 327 or
 328 .Fl ifa
 329 modifiers may be used to determine the interface or interface address.
 330 .Pp
 331 The optional
 332 .Fl proxy
 333 modifier specifies that the
 334 .Dv RTF_LLINFO
 335 routing table entry is the
 336 .Dq published (proxy-only)
 337 .Tn ARP
 338 entry, as reported by
 339 .Xr arp 8 .
 340 .Pp
 341 All symbolic names specified for a
 342 .Ar destination
 343 or
 344 .Ar gateway
 345 are looked up first as a host name using
 346 .Xr gethostbyname 3 .
 347 If this lookup fails,
 348 .Xr getnetbyname 3
 349 is then used to interpret the name as that of a network.
 350 .Pp
 351 The optional
 352 .Fl push ,
 353 .Fl pop ,
 354 and
 355 .Fl swap
 356 modifiers may be used to specify the desired mpls label
 357 operations for the route. Each route may have up to 3
 358 label operations assigned to it. The label operations
 359 may be combined between them, but specifically the
 360 .Fl push
 361 and
 362 .Fl pop
 363 operations may be repeated if the intent is to push or pop
 364 more than one label at once. The
 365 .Fl swap
 366 operation always swaps the outer label and may not be
 367 repeated.
 368 Here are some MPLS route examples:
 369 .Pp
 370 Add an normal inet route, but push an mpls
 371 .Ar label
 372 to the packet:
 373 .Pp
 374 .Bd -ragged -offset indent -compact
 375 .Nm
 376 .Cm add
 377 .Ar destination gateway
 378 .Fl push
 379 .Ar label
 380 .Ed
 381 .Pp
 382 Add an normal inet route, but double-push an mpls
 383 .Ar inner-label
 384 and an
 385 .Ar outer-label
 386 to the packet:
 387 .Pp
 388 .Bd -ragged -offset indent -compact
 389 .Nm
 390 .Cm add
 391 .Ar destination gateway
 392 .Fl push
 393 .Ar inner-label
 394 .Fl push
 395 .Ar outer-label
 396 .Ed
 397 .Pp
 398 Add an mpls route for an
 399 .Ar incoming-label
 400 to be forwarded to
 401 .Ar gateway
 402 and swap that label with
 403 .Ar new-label :
 404 .Pp
 405 .Bd -ragged -offset indent -compact
 406 .Nm
 407 .Cm add
 408 .Fl mpls
 409 .Ar incoming-label
 410 .Fl inet
 411 .Ar gateway
 412 .Fl swap
 413 .Ar new-label
 414 .Ed
 415 .Pp
 416 The
 417 .Nm
 418 utility uses a routing socket and the new message types
 419 .Dv RTM_ADD , RTM_DELETE , RTM_GET ,
 420 and
 421 .Dv RTM_CHANGE .
 422 As such, only the super-user may modify
 423 the routing tables.
 424 .Sh EXIT STATUS
 425 .Ex -std
 426 .Sh DIAGNOSTICS
 427 .Bl -diag
 428 .It "add [host \&| network ] %s: gateway %s flags %x"
 429 The specified route is being added to the tables.  The
 430 values printed are from the routing table entry supplied
 431 in the
 432 .Xr ioctl 2
 433 call.
 434 If the gateway address used was not the primary address of the gateway
 435 (the first one returned by
 436 .Xr gethostbyname 3 ) ,
 437 the gateway address is printed numerically as well as symbolically.
 438 .It "delete [ host \&| network ] %s: gateway %s flags %x"
 439 As above, but when deleting an entry.
 440 .It "%s %s done"
 441 When the
 442 .Cm flush
 443 command is specified, each routing table entry deleted
 444 is indicated with a message of this form.
 445 .It "Network is unreachable"
 446 An attempt to add a route failed because the gateway listed was not
 447 on a directly-connected network.
 448 The next-hop gateway must be given.
 449 .It "not in table"
 450 A delete operation was attempted for an entry which
 451 wasn't present in the tables.
 452 .It "routing table overflow"
 453 An add operation was attempted, but the system was
 454 low on resources and was unable to allocate memory
 455 to create the new entry.
 456 .It "gateway uses the same route"
 457 A
 458 .Cm change
 459 operation resulted in a route whose gateway uses the
 460 same route as the one being changed.
 461 The next-hop gateway should be reachable through a different route.
 462 .El
 463 .Sh SEE ALSO
 464 .\".Xr esis 4 ,
 465 .Xr netintro 4 ,
 466 .Xr route 4 ,
 467 .Xr arp 8 ,
 468 .Xr IPXrouted 8 ,
 469 .Xr routed 8
 470 .\".Xr XNSrouted 8
 471 .Sh HISTORY
 472 The
 473 .Nm
 474 utility appeared in
 475 .Bx 4.2 .
 476 .Sh BUGS
 477 The first paragraph may have slightly exaggerated
 478 .Xr routed 8 Ns 's
 479 abilities.