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