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 .\" 4. 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$
  30 .\"
  31 .Dd November 17, 2012
  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 .Ar command
  41 .Oo
  42 .Op Ar modifiers
  43 .Ar args
  44 .Oc
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility is used to manually manipulate the network
  49 routing tables.
  50 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 d
  66 Run in debug-only mode, i.e., do not actually modify the routing table.
  67 .It Fl n
  68 Bypass attempts to print host and network names symbolically
  69 when reporting actions.
  70 (The process of translating between symbolic
  71 names and numerical equivalents can be quite time consuming, and
  72 may require correct operation of the network; thus it may be expedient
  73 to forget this, especially when attempting to repair networking operations).
  74 .It Fl t
  75 Run in test-only mode.
  76 .Pa /dev/null
  77 is used instead of a socket.
  78 .It Fl v
  79 (verbose) Print additional details.
  80 .It Fl q
  81 Suppress all output from the
  82 .Cm add , change , delete ,
  83 and
  84 .Cm flush
  85 commands.
  86 .El
  87 .Pp
  88 The
  89 .Nm
  90 utility provides the following 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 del
 100 Another name for the
 101 .Cm delete
 102 command.
 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 monitor
 108 Continuously report any changes to the routing information base,
 109 routing lookup misses, or suspected network partitionings.
 110 .It Cm show
 111 Another name for the
 112 .Cm get
 113 command.
 114 .El
 115 .Pp
 116 The monitor command has the syntax:
 117 .Pp
 118 .Bd -ragged -offset indent -compact
 119 .Nm
 120 .Op Fl n
 121 .Cm monitor Op Fl fib Ar number
 122 .Ed
 123 .Pp
 124 The flush command has the syntax:
 125 .Pp
 126 .Bd -ragged -offset indent -compact
 127 .Nm
 128 .Oo Fl n Cm flush Oc Oo Ar family Oc Op Fl fib Ar number
 129 .Ed
 130 .Pp
 131 If the
 132 .Cm flush
 133 command is specified,
 134 .Nm
 135 will ``flush'' the routing tables of all gateway entries.
 136 When the address family may is specified by any of the
 137 .Fl osi ,
 138 .Fl xns ,
 139 .Fl atalk ,
 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 When a
 146 .Fl fib
 147 option is specified, the operation will be applied to
 148 the specified FIB
 149 .Pq routing table .
 150 .Pp
 151 The other commands have the following syntax:
 152 .Pp
 153 .Bd -ragged -offset indent -compact
 154 .Nm
 155 .Op Fl n
 156 .Ar command
 157 .Op Fl net No \&| Fl host
 158 .Ar destination gateway
 159 .Op Ar netmask
 160 .Op Fl fib Ar number
 161 .Ed
 162 .Pp
 163 where
 164 .Ar destination
 165 is the destination host or network,
 166 .Ar gateway
 167 is the next-hop intermediary via which packets should be routed.
 168 Routes to a particular host may be distinguished from those to
 169 a network by interpreting the Internet address specified as the
 170 .Ar destination
 171 argument.
 172 The optional modifiers
 173 .Fl net
 174 and
 175 .Fl host
 176 force the destination to be interpreted as a network or a host, respectively.
 177 Otherwise, if the
 178 .Ar destination
 179 has a
 180 .Dq local address part
 181 of
 182 INADDR_ANY
 183 .Pq Li 0.0.0.0 ,
 184 or if the
 185 .Ar destination
 186 is the symbolic name of a network, then the route is
 187 assumed to be to a network; otherwise, it is presumed to be a
 188 route to a host.
 189 Optionally, the
 190 .Ar destination
 191 could also be specified in the
 192 .Ar net Ns / Ns Ar bits
 193 format.
 194 .Pp
 195 For example,
 196 .Li 128.32
 197 is interpreted as
 198 .Fl host Li 128.0.0.32 ;
 199 .Li 128.32.130
 200 is interpreted as
 201 .Fl host Li 128.32.0.130 ;
 202 .Fl net Li 128.32
 203 is interpreted as
 204 .Li 128.32.0.0;
 205 .Fl net Li 128.32.130
 206 is interpreted as
 207 .Li 128.32.130.0;
 208 and
 209 .Li 192.168.64/20
 210 is interpreted as
 211 .Fl net Li 192.168.64 Fl netmask Li 255.255.240.0 .
 212 .Pp
 213 A
 214 .Ar destination
 215 of
 216 .Ar default
 217 is a synonym for the default route.
 218 For
 219 .Li IPv4
 220 it is
 221 .Fl net Fl inet Li 0.0.0.0 ,
 222 and for
 223 .Li IPv6
 224 it is
 225 .Fl net Fl inet6 Li :: .
 226 .Pp
 227 If the destination is directly reachable
 228 via an interface requiring
 229 no intermediary system to act as a gateway, the
 230 .Fl interface
 231 modifier should be specified;
 232 the gateway given is the address of this host on the common network,
 233 indicating the interface to be used for transmission.
 234 Alternately, if the interface is point to point the name of the interface
 235 itself may be given, in which case the route remains valid even
 236 if the local or remote addresses change.
 237 .Pp
 238 The optional modifiers
 239 .Fl xns ,
 240 .Fl osi ,
 241 .Fl atalk ,
 242 and
 243 .Fl link
 244 specify that all subsequent addresses are in the
 245 .Tn XNS ,
 246 .Tn OSI ,
 247 or
 248 .Tn AppleTalk
 249 address families,
 250 or are specified as link-level addresses,
 251 and the names must be numeric specifications rather than
 252 symbolic names.
 253 .Pp
 254 The optional
 255 .Fl netmask
 256 modifier is intended
 257 to achieve the effect of an
 258 .Tn OSI
 259 .Tn ESIS
 260 redirect with the netmask option,
 261 or to manually add subnet routes with
 262 netmasks different from that of the implied network interface
 263 (as would otherwise be communicated using the OSPF or ISIS routing protocols).
 264 One specifies an additional ensuing address parameter
 265 (to be interpreted as a network mask).
 266 The implicit network mask generated in the AF_INET case
 267 can be overridden by making sure this option follows the destination parameter.
 268 .Pp
 269 For
 270 .Dv AF_INET6 ,
 271 the
 272 .Fl prefixlen
 273 qualifier
 274 is available instead of the
 275 .Fl mask
 276 qualifier because non-continuous masks are not allowed in IPv6.
 277 For example,
 278 .Fl prefixlen Li 32
 279 specifies network mask of
 280 .Li ffff:ffff:0000:0000:0000:0000:0000:0000
 281 to be used.
 282 The default value of prefixlen is 64 to get along with
 283 the aggregatable address.
 284 But 0 is assumed if
 285 .Cm default
 286 is specified.
 287 Note that the qualifier works only for
 288 .Dv AF_INET6
 289 address family.
 290 .Pp
 291 Routes have associated flags which influence operation of the protocols
 292 when sending to destinations matched by the routes.
 293 These flags may be set (or sometimes cleared)
 294 by indicating the following corresponding modifiers:
 295 .Bd -literal
 296 -xresolve  RTF_XRESOLVE   - emit mesg on use (for external lookup)
 297 -iface    ~RTF_GATEWAY    - destination is directly reachable
 298 -static    RTF_STATIC     - manually added route
 299 -nostatic ~RTF_STATIC     - pretend route added by kernel or daemon
 300 -reject    RTF_REJECT     - emit an ICMP unreachable when matched
 301 -blackhole RTF_BLACKHOLE  - silently discard pkts (during updates)
 302 -proto1    RTF_PROTO1     - set protocol specific routing flag #1
 303 -proto2    RTF_PROTO2     - set protocol specific routing flag #2
 304 .Ed
 305 .Pp
 306 The optional modifiers
 307 .Fl rtt ,
 308 .Fl rttvar ,
 309 .Fl sendpipe ,
 310 .Fl recvpipe ,
 311 .Fl mtu ,
 312 .Fl hopcount ,
 313 .Fl expire ,
 314 and
 315 .Fl ssthresh
 316 provide initial values to quantities maintained in the routing entry
 317 by transport level protocols, such as TCP or TP4.
 318 These may be individually locked by preceding each such modifier to
 319 be locked by
 320 the
 321 .Fl lock
 322 meta-modifier, or one can
 323 specify that all ensuing metrics may be locked by the
 324 .Fl lockrest
 325 meta-modifier.
 326 .Pp
 327 The optional modifier
 328 .Fl fib Ar number
 329 specifies that the command will be applied to a non-default FIB.
 330 The
 331 .Ar number
 332 must be smaller than the
 333 .Va net.fibs
 334 .Xr sysctl 8
 335 MIB.
 336 When this modifier is not specified,
 337 or a negative number is specified,
 338 the default FIB shown in the
 339 .Va net.my_fibnum
 340 .Xr sysctl 8
 341 MIB will be used.
 342 .Pp
 343 The
 344 .Ar number
 345 allows multiple FIBs by a comma-separeted list and/or range
 346 specification.
 347 The
 348 .Qq Fl fib Li 2,4,6
 349 means the FIB number 2, 4, and 6.
 350 The
 351 .Qq Fl fib Li 1,3-5,6
 352 means the 1, 3, 4, 5, and 6.
 353 .Pp
 354 In a
 355 .Cm change
 356 or
 357 .Cm add
 358 command where the destination and gateway are not sufficient to specify
 359 the route (as in the
 360 .Tn ISO
 361 case where several interfaces may have the
 362 same address), the
 363 .Fl ifp
 364 or
 365 .Fl ifa
 366 modifiers may be used to determine the interface or interface address.
 367 .Pp
 368 All symbolic names specified for a
 369 .Ar destination
 370 or
 371 .Ar gateway
 372 are looked up first as a host name using
 373 .Xr gethostbyname 3 .
 374 If this lookup fails,
 375 .Xr getnetbyname 3
 376 is then used to interpret the name as that of a network.
 377 .Pp
 378 The
 379 .Nm
 380 utility uses a routing socket and the new message types
 381 .Dv RTM_ADD , RTM_DELETE , RTM_GET ,
 382 and
 383 .Dv RTM_CHANGE .
 384 As such, only the super-user may modify
 385 the routing tables.
 386 .Sh EXIT STATUS
 387 .Ex -std
 388 .Sh EXAMPLES
 389 Add a default route to the network routing table.
 390 This will send all packets for destinations not available in the routing table
 391 to the default gateway at 192.168.1.1:
 392 .Pp
 393 .Dl route add -net 0.0.0.0/0 192.168.1.1
 394 .Pp
 395 A shorter version of adding a default route can also be written as:
 396 .Pp
 397 .Dl route add default 192.168.1.1
 398 .Pp
 399 Add a static route to the 172.16.10.0/24 network via the 172.16.1.1 gateway:
 400 .Pp
 401 .Dl route add -net 172.16.10.0/24 172.16.1.1
 402 .Pp
 403 Change the gateway of an already established static route in the routing table:
 404 .Pp
 405 .Dl route change -net 172.16.10.0/24 172.16.1.2
 406 .Pp
 407 Display the route for a destination network:
 408 .Pp
 409 .Dl route show 172.16.10.0
 410 .Pp
 411 Delete a static route from the routing table:
 412 .Pp
 413 .Dl route delete -net 172.16.10.0/24 172.16.1.2
 414 .Pp
 415 Remove all routes from the routing table:
 416 .Pp
 417 .Dl route flush
 418 .Sh DIAGNOSTICS
 419 .Bl -diag
 420 .It "add [host \&| network ] %s: gateway %s flags %x"
 421 The specified route is being added to the tables.
 422 The
 423 values printed are from the routing table entry supplied
 424 in the
 425 .Xr ioctl 2
 426 call.
 427 If the gateway address used was not the primary address of the gateway
 428 (the first one returned by
 429 .Xr gethostbyname 3 ) ,
 430 the gateway address is printed numerically as well as symbolically.
 431 .It "delete [ host \&| network ] %s: gateway %s flags %x"
 432 As above, but when deleting an entry.
 433 .It "%s %s done"
 434 When the
 435 .Cm flush
 436 command is specified, each routing table entry deleted
 437 is indicated with a message of this form.
 438 .It "Network is unreachable"
 439 An attempt to add a route failed because the gateway listed was not
 440 on a directly-connected network.
 441 The next-hop gateway must be given.
 442 .It "not in table"
 443 A delete operation was attempted for an entry which
 444 was not present in the tables.
 445 .It "routing table overflow"
 446 An add operation was attempted, but the system was
 447 low on resources and was unable to allocate memory
 448 to create the new entry.
 449 .It "gateway uses the same route"
 450 A
 451 .Cm change
 452 operation resulted in a route whose gateway uses the
 453 same route as the one being changed.
 454 The next-hop gateway should be reachable through a different route.
 455 .El
 456 .Sh SEE ALSO
 457 .\".Xr esis 4 ,
 458 .Xr netintro 4 ,
 459 .Xr route 4 ,
 460 .Xr arp 8 ,
 461 .Xr IPXrouted 8 ,
 462 .Xr routed 8
 463 .\".Xr XNSrouted 8
 464 .Sh HISTORY
 465 The
 466 .Nm
 467 utility appeared in
 468 .Bx 4.2 .
 469 .Sh BUGS
 470 The first paragraph may have slightly exaggerated
 471 .Xr routed 8 Ns 's
 472 abilities.
 473 .Pp
 474 Currently, routes with the
 475 .Dv RTF_BLACKHOLE
 476 flag set need to have the gateway set to an instance of the
 477 .Xr lo 4
 478 driver, using the
 479 .Fl iface
 480 option, for the flag to have any effect; unless IP fast forwarding
 481 is enabled, in which case the meaning of the flag will always
 482 be honored.