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
 107 .Dq Cd netstat -r
 108 (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
 137 .Dq flush
 138 the routing tables of all gateway entries.
 139 When the address family may is specified by any of the
 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 and
 229 .Fl link
 230 specify that all subsequent addresses are in the
 231 .Tn MPLS
 232 address family
 233 or are specified as link-level addresses,
 234 and the names must be numeric specifications rather than
 235 symbolic names.
 236 .Pp
 237 The optional
 238 .Fl netmask
 239 modifier is intended to manually add subnet routes with
 240 netmasks different from that of the implied network interface.
 241 One specifies an additional ensuing address parameter
 242 (to be interpreted as a network mask).
 243 The implicit network mask generated in the AF_INET case
 244 can be overridden by making sure this option follows the destination parameter.
 245 .Pp
 246 For
 247 .Dv AF_INET6 ,
 248 the
 249 .Fl prefixlen
 250 qualifier
 251 is available instead of the
 252 .Fl mask
 253 qualifier because non-continuous masks are not allowed in IPv6.
 254 For example,
 255 .Fl prefixlen Li 32
 256 specifies network mask of
 257 .Li ffff:ffff:0000:0000:0000:0000:0000:0000
 258 to be used.
 259 The default value of prefixlen is 64 to get along with
 260 the aggregatable address.
 261 But 0 is assumed if
 262 .Cm default
 263 is specified.
 264 Note that the qualifier works only for
 265 .Dv AF_INET6
 266 address family.
 267 .Pp
 268 Routes have associated flags which influence operation of the protocols
 269 when sending to destinations matched by the routes.
 270 These flags may be set (or sometimes cleared)
 271 by indicating the following corresponding modifiers:
 272 .Bd -literal
 273 -cloning   RTF_CLONING    - generates a new route on use
 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 .Fl msl ,
 294 .Fl iw ,
 295 .Fl iwmax
 296 and
 297 .Fl ssthresh
 298 provide initial values to quantities maintained in the routing entry
 299 by transport level protocols, such as TCP or TP4.
 300 These may be individually locked by preceding each such modifier to
 301 be locked by
 302 the
 303 .Fl lock
 304 meta-modifier, or one can
 305 specify that all ensuing metrics may be locked by the
 306 .Fl lockrest
 307 meta-modifier.
 308 .Pp
 309 In a
 310 .Cm change
 311 or
 312 .Cm add
 313 command where the destination and gateway are not sufficient to specify
 314 the route (as in the
 315 .Tn ISO
 316 case where several interfaces may have the
 317 same address), the
 318 .Fl ifp
 319 or
 320 .Fl ifa
 321 modifiers may be used to determine the interface or interface address.
 322 .Pp
 323 The optional
 324 .Fl proxy
 325 modifier specifies that the
 326 .Dv RTF_LLINFO
 327 routing table entry is the
 328 .Dq published (proxy-only)
 329 .Tn ARP
 330 entry, as reported by
 331 .Xr arp 8 .
 332 .Pp
 333 All symbolic names specified for a
 334 .Ar destination
 335 or
 336 .Ar gateway
 337 are looked up first as a host name using
 338 .Xr gethostbyname 3 .
 339 If this lookup fails,
 340 .Xr getnetbyname 3
 341 is then used to interpret the name as that of a network.
 342 .Pp
 343 The optional
 344 .Fl push ,
 345 .Fl pop ,
 346 and
 347 .Fl swap
 348 modifiers may be used to specify the desired MPLS label
 349 operations for the route. Each route may have up to 3
 350 label operations assigned to it. The label operations
 351 may be combined between them, but specifically the
 352 .Fl push
 353 and
 354 .Fl pop
 355 operations may be repeated if the intent is to push or pop
 356 more than one label at once. The
 357 .Fl swap
 358 operation always swaps the outer label and may not be
 359 repeated.
 360 Here are some MPLS route examples:
 361 .Pp
 362 Add an normal inet route, but push an MPLS
 363 .Ar label
 364 to the packet:
 365 .Pp
 366 .Bd -ragged -offset indent -compact
 367 .Nm
 368 .Cm add
 369 .Ar destination gateway
 370 .Fl push
 371 .Ar label
 372 .Ed
 373 .Pp
 374 Add an normal inet route, but double-push an MPLS
 375 .Ar inner-label
 376 and an
 377 .Ar outer-label
 378 to the packet:
 379 .Pp
 380 .Bd -ragged -offset indent -compact
 381 .Nm
 382 .Cm add
 383 .Ar destination gateway
 384 .Fl push
 385 .Ar inner-label
 386 .Fl push
 387 .Ar outer-label
 388 .Ed
 389 .Pp
 390 Add an MPLS route for an
 391 .Ar incoming-label
 392 to be forwarded to
 393 .Ar gateway
 394 and swap that label with
 395 .Ar new-label :
 396 .Pp
 397 .Bd -ragged -offset indent -compact
 398 .Nm
 399 .Cm add
 400 .Fl mpls
 401 .Ar incoming-label
 402 .Fl inet
 403 .Ar gateway
 404 .Fl swap
 405 .Ar new-label
 406 .Ed
 407 .Pp
 408 The
 409 .Nm
 410 utility uses a routing socket and the new message types
 411 .Dv RTM_ADD , RTM_DELETE , RTM_GET ,
 412 and
 413 .Dv RTM_CHANGE .
 414 As such, only the super-user may modify
 415 the routing tables.
 416 .Sh EXIT STATUS
 417 .Ex -std
 418 .Sh DIAGNOSTICS
 419 .Bl -tag -width indent
 420 .It Sy "add [host \&| network ] %s: gateway %s flags %x"
 421 The specified route is being added to the tables.  The
 422 values printed are from the routing table entry supplied
 423 in the
 424 .Xr ioctl 2
 425 call.
 426 If the gateway address used was not the primary address of the gateway
 427 (the first one returned by
 428 .Xr gethostbyname 3 ) ,
 429 the gateway address is printed numerically as well as symbolically.
 430 .It Sy "delete [ host \&| network ] %s: gateway %s flags %x"
 431 As above, but when deleting an entry.
 432 .It Sy "%s %s done"
 433 When the
 434 .Cm flush
 435 command is specified, each routing table entry deleted
 436 is indicated with a message of this form.
 437 .It Sy "Network is unreachable"
 438 An attempt to add a route failed because the gateway listed was not
 439 on a directly-connected network.
 440 The next-hop gateway must be given.
 441 .It Sy "not in table"
 442 A delete operation was attempted for an entry which
 443 wasn't present in the tables.
 444 .It Sy "routing table overflow"
 445 An add operation was attempted, but the system was
 446 low on resources and was unable to allocate memory
 447 to create the new entry.
 448 .It Sy "gateway uses the same route"
 449 A
 450 .Cm change
 451 operation resulted in a route whose gateway uses the
 452 same route as the one being changed.
 453 The next-hop gateway should be reachable through a different route.
 454 .El
 455 .Sh SEE ALSO
 456 .\".Xr esis 4 ,
 457 .Xr netintro 4 ,
 458 .Xr route 4 ,
 459 .Xr arp 8 ,
 460 .Xr routed 8
 461 .Sh HISTORY
 462 The
 463 .Nm
 464 utility appeared in
 465 .Bx 4.2 .
 466 .Sh BUGS
 467 The first paragraph may have slightly exaggerated
 468 .Xr routed 8 Ns 's
 469 abilities.