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