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 .\" $DragonFly: src/sbin/route/route.8,v 1.2 2003/06/17 04:27:34 dillon Exp $
  35 .\"
  36 .Dd June 8, 2001
  37 .Dt ROUTE 8
  38 .Os
  39 .Sh NAME
  40 .Nm route
  41 .Nd manually manipulate the routing tables
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl dnqtv
  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 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 .El
  84 .Pp
  85 The
  86 .Nm
  87 utility provides six commands:
  88 .Pp
  89 .Bl -tag -width Fl -compact
  90 .It Cm add
  91 Add a route.
  92 .It Cm flush
  93 Remove all routes.
  94 .It Cm delete
  95 Delete a specific route.
  96 .It Cm change
  97 Change aspects of a route (such as its gateway).
  98 .It Cm get
  99 Lookup and display the route for a destination.
 100 .It Cm monitor
 101 Continuously report any changes to the routing information base,
 102 routing lookup misses, or suspected network partitionings.
 103 .El
 104 .Pp
 105 The monitor command has the syntax:
 106 .Pp
 107 .Bd -ragged -offset indent -compact
 108 .Nm
 109 .Op Fl n
 110 .Cm monitor
 111 .Ed
 112 .Pp
 113 The flush command has the syntax:
 114 .Pp
 115 .Bd -ragged -offset indent -compact
 116 .Nm
 117 .Op Fl n
 118 .Cm flush
 119 .Op Ar family
 120 .Ed
 121 .Pp
 122 If the
 123 .Cm flush
 124 command is specified,
 125 .Nm
 126 will ``flush'' the routing tables of all gateway entries.
 127 When the address family may is specified by any of the
 128 .Fl osi ,
 129 .Fl xns ,
 130 .Fl atalk ,
 131 .Fl inet6 ,
 132 or
 133 .Fl inet
 134 modifiers, only routes having destinations with addresses in the
 135 delineated family will be deleted.
 136 .Pp
 137 The other commands have the following syntax:
 138 .Pp
 139 .Bd -ragged -offset indent -compact
 140 .Nm
 141 .Op Fl n
 142 .Ar command
 143 .Op Fl net No \&| Fl host
 144 .Ar destination gateway
 145 .Op Ar netmask
 146 .Ed
 147 .Pp
 148 where
 149 .Ar destination
 150 is the destination host or network,
 151 .Ar gateway
 152 is the next-hop intermediary via which packets should be routed.
 153 Routes to a particular host may be distinguished from those to
 154 a network by interpreting the Internet address specified as the
 155 .Ar destination
 156 argument.
 157 The optional modifiers
 158 .Fl net
 159 and
 160 .Fl host
 161 force the destination to be interpreted as a network or a host, respectively.
 162 Otherwise, if the
 163 .Ar destination
 164 has a
 165 .Dq local address part
 166 of
 167 INADDR_ANY
 168 .Pq Li 0.0.0.0 ,
 169 or if the
 170 .Ar destination
 171 is the symbolic name of a network, then the route is
 172 assumed to be to a network; otherwise, it is presumed to be a
 173 route to a host.
 174 Optionally, the
 175 .Ar destination
 176 could also be specified in the
 177 .Ar net Ns / Ns Ar bits
 178 format.
 179 .Pp
 180 For example,
 181 .Li 128.32
 182 is interpreted as
 183 .Fl host Li 128.0.0.32 ;
 184 .Li 128.32.130
 185 is interpreted as
 186 .Fl host Li 128.32.0.130 ;
 187 .Fl net Li 128.32
 188 is interpreted as
 189 .Li 128.32.0.0;
 190 .Fl net Li 128.32.130
 191 is interpreted as
 192 .Li 128.32.130.0;
 193 and
 194 .Li 192.168.64/20
 195 is interpreted as
 196 .Fl net Li 192.168.64 Fl netmask Li 255.255.240.0 .
 197 .Pp
 198 A
 199 .Ar destination
 200 of
 201 .Ar default
 202 is a synonym for
 203 .Fl net Li 0.0.0.0 ,
 204 which is the default route.
 205 .Pp
 206 If the destination is directly reachable
 207 via an interface requiring
 208 no intermediary system to act as a gateway, the
 209 .Fl interface
 210 modifier should be specified;
 211 the gateway given is the address of this host on the common network,
 212 indicating the interface to be used for transmission.
 213 Alternately, if the interface is point to point the name of the interface
 214 itself may be given, in which case the route remains valid even
 215 if the local or remote addresses change.
 216 .Pp
 217 The optional modifiers
 218 .Fl xns ,
 219 .Fl osi ,
 220 .Fl atalk ,
 221 and
 222 .Fl link
 223 specify that all subsequent addresses are in the
 224 .Tn XNS ,
 225 .Tn OSI ,
 226 or
 227 .Tn AppleTalk
 228 address families,
 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
 236 to achieve the effect of an
 237 .Tn OSI
 238 .Tn ESIS
 239 redirect with the netmask option,
 240 or to manually add subnet routes with
 241 netmasks different from that of the implied network interface
 242 (as would otherwise be communicated using the OSPF or ISIS routing protocols).
 243 One specifies an additional ensuing address parameter
 244 (to be interpreted as a network mask).
 245 The implicit network mask generated in the AF_INET case
 246 can be overridden by making sure this option follows the destination parameter.
 247 .Pp
 248 For
 249 .Dv AF_INET6 ,
 250 the
 251 .Fl prefixlen
 252 qualifier
 253 is available instead of the
 254 .Fl mask
 255 qualifier because non-continuous masks are not allowed in IPv6.
 256 For example,
 257 .Fl prefixlen Li 32
 258 specifies network mask of
 259 .Li ffff:ffff:0000:0000:0000:0000:0000:0000
 260 to be used.
 261 The default value of prefixlen is 64 to get along with
 262 the aggregatable address.
 263 But 0 is assumed if
 264 .Cm default
 265 is specified.
 266 Note that the qualifier works only for
 267 .Dv AF_INET6
 268 address family.
 269 .Pp
 270 Routes have associated flags which influence operation of the protocols
 271 when sending to destinations matched by the routes.
 272 These flags may be set (or sometimes cleared)
 273 by indicating the following corresponding modifiers:
 274 .Bd -literal
 275 -cloning   RTF_CLONING    - generates a new route on use
 276 -xresolve  RTF_XRESOLVE   - emit mesg on use (for external lookup)
 277 -iface    ~RTF_GATEWAY    - destination is directly reachable
 278 -static    RTF_STATIC     - manually added route
 279 -nostatic ~RTF_STATIC     - pretend route added by kernel or daemon
 280 -reject    RTF_REJECT     - emit an ICMP unreachable when matched
 281 -blackhole RTF_BLACKHOLE  - silently discard pkts (during updates)
 282 -proto1    RTF_PROTO1     - set protocol specific routing flag #1
 283 -proto2    RTF_PROTO2     - set protocol specific routing flag #2
 284 -llinfo    RTF_LLINFO     - validly translates proto addr to link addr
 285 .Ed
 286 .Pp
 287 The optional modifiers
 288 .Fl rtt ,
 289 .Fl rttvar ,
 290 .Fl sendpipe ,
 291 .Fl recvpipe ,
 292 .Fl mtu ,
 293 .Fl hopcount ,
 294 .Fl expire ,
 295 and
 296 .Fl ssthresh
 297 provide initial values to quantities maintained in the routing entry
 298 by transport level protocols, such as TCP or TP4.
 299 These may be individually locked by preceding each such modifier to
 300 be locked by
 301 the
 302 .Fl lock
 303 meta-modifier, or one can
 304 specify that all ensuing metrics may be locked by the
 305 .Fl lockrest
 306 meta-modifier.
 307 .Pp
 308 In a
 309 .Cm change
 310 or
 311 .Cm add
 312 command where the destination and gateway are not sufficient to specify
 313 the route (as in the
 314 .Tn ISO
 315 case where several interfaces may have the
 316 same address), the
 317 .Fl ifp
 318 or
 319 .Fl ifa
 320 modifiers may be used to determine the interface or interface address.
 321 .Pp
 322 The optional
 323 .Fl proxy
 324 modifier specifies that the
 325 .Dv RTF_LLINFO
 326 routing table entry is the
 327 .Dq published (proxy-only)
 328 .Tn ARP
 329 entry, as reported by
 330 .Xr arp 8 .
 331 .Pp
 332 All symbolic names specified for a
 333 .Ar destination
 334 or
 335 .Ar gateway
 336 are looked up first as a host name using
 337 .Xr gethostbyname 3 .
 338 If this lookup fails,
 339 .Xr getnetbyname 3
 340 is then used to interpret the name as that of a network.
 341 .Pp
 342 The
 343 .Nm
 344 utility uses a routing socket and the new message types
 345 .Dv RTM_ADD , RTM_DELETE , RTM_GET ,
 346 and
 347 .Dv RTM_CHANGE .
 348 As such, only the super-user may modify
 349 the routing tables.
 350 .Sh DIAGNOSTICS
 351 .Bl -diag
 352 .It "add [host \&| network ] %s: gateway %s flags %x"
 353 The specified route is being added to the tables.  The
 354 values printed are from the routing table entry supplied
 355 in the
 356 .Xr ioctl 2
 357 call.
 358 If the gateway address used was not the primary address of the gateway
 359 (the first one returned by
 360 .Xr gethostbyname 3 ) ,
 361 the gateway address is printed numerically as well as symbolically.
 362 .It "delete [ host \&| network ] %s: gateway %s flags %x"
 363 As above, but when deleting an entry.
 364 .It "%s %s done"
 365 When the
 366 .Cm flush
 367 command is specified, each routing table entry deleted
 368 is indicated with a message of this form.
 369 .It "Network is unreachable"
 370 An attempt to add a route failed because the gateway listed was not
 371 on a directly-connected network.
 372 The next-hop gateway must be given.
 373 .It "not in table"
 374 A delete operation was attempted for an entry which
 375 wasn't present in the tables.
 376 .It "routing table overflow"
 377 An add operation was attempted, but the system was
 378 low on resources and was unable to allocate memory
 379 to create the new entry.
 380 .It "gateway uses the same route"
 381 A
 382 .Cm change
 383 operation resulted in a route whose gateway uses the
 384 same route as the one being changed.
 385 The next-hop gateway should be reachable through a different route.
 386 .El
 387 .Pp
 388 .Ex -std
 389 .Sh SEE ALSO
 390 .\".Xr esis 4 ,
 391 .Xr netintro 4 ,
 392 .Xr route 4 ,
 393 .Xr arp 8 ,
 394 .Xr IPXrouted 8 ,
 395 .Xr routed 8
 396 .\".Xr XNSrouted 8
 397 .Sh HISTORY
 398 The
 399 .Nm
 400 utility appeared in
 401 .Bx 4.2 .
 402 .Sh BUGS
 403 The first paragraph may have slightly exaggerated
 404 .Xr routed 8 Ns 's
 405 abilities.