File:  [DragonFly] / src / sbin / route / route.8
Revision 1.3: download - view: text, annotated - select for diffs
Tue Mar 23 17:56:29 2004 UTC (10 years, 7 months ago) by dillon
Branches: MAIN
CVS tags: HEAD
Add 'route show' to the route command, plus style cleanups.

Submitted-by: Andre Nathan <andre@digirati.com.br>
Taken-from: OpenBSD and NetBSD

    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.3 2004/03/23 17:56:29 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 show
  101: Print out the route table similar to "netstat \-r" (see
  102: .Xr netstat 1 ) .
  103: .It Cm monitor
  104: Continuously report any changes to the routing information base,
  105: routing lookup misses, or suspected network partitionings.
  106: .El
  107: .Pp
  108: The monitor command has the syntax:
  109: .Pp
  110: .Bd -ragged -offset indent -compact
  111: .Nm
  112: .Op Fl n
  113: .Cm monitor
  114: .Ed
  115: .Pp
  116: The flush command has the syntax:
  117: .Pp
  118: .Bd -ragged -offset indent -compact
  119: .Nm
  120: .Op Fl n
  121: .Cm flush
  122: .Op Ar family
  123: .Ed
  124: .Pp
  125: If the
  126: .Cm flush
  127: command is specified,
  128: .Nm
  129: will ``flush'' the routing tables of all gateway entries.
  130: When the address family may is specified by any of the
  131: .Fl osi ,
  132: .Fl xns ,
  133: .Fl atalk ,
  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 xns ,
  222: .Fl osi ,
  223: .Fl atalk ,
  224: and
  225: .Fl link
  226: specify that all subsequent addresses are in the
  227: .Tn XNS ,
  228: .Tn OSI ,
  229: or
  230: .Tn AppleTalk
  231: address families,
  232: or are specified as link-level addresses,
  233: and the names must be numeric specifications rather than
  234: symbolic names.
  235: .Pp
  236: The optional
  237: .Fl netmask
  238: modifier is intended
  239: to achieve the effect of an
  240: .Tn OSI
  241: .Tn ESIS
  242: redirect with the netmask option,
  243: or to manually add subnet routes with
  244: netmasks different from that of the implied network interface
  245: (as would otherwise be communicated using the OSPF or ISIS routing protocols).
  246: One specifies an additional ensuing address parameter
  247: (to be interpreted as a network mask).
  248: The implicit network mask generated in the AF_INET case
  249: can be overridden by making sure this option follows the destination parameter.
  250: .Pp
  251: For
  252: .Dv AF_INET6 ,
  253: the
  254: .Fl prefixlen
  255: qualifier
  256: is available instead of the
  257: .Fl mask
  258: qualifier because non-continuous masks are not allowed in IPv6.
  259: For example,
  260: .Fl prefixlen Li 32
  261: specifies network mask of
  262: .Li ffff:ffff:0000:0000:0000:0000:0000:0000
  263: to be used.
  264: The default value of prefixlen is 64 to get along with
  265: the aggregatable address.
  266: But 0 is assumed if
  267: .Cm default
  268: is specified.
  269: Note that the qualifier works only for
  270: .Dv AF_INET6
  271: address family.
  272: .Pp
  273: Routes have associated flags which influence operation of the protocols
  274: when sending to destinations matched by the routes.
  275: These flags may be set (or sometimes cleared)
  276: by indicating the following corresponding modifiers:
  277: .Bd -literal
  278: -cloning   RTF_CLONING    - generates a new route on use
  279: -xresolve  RTF_XRESOLVE   - emit mesg on use (for external lookup)
  280: -iface    ~RTF_GATEWAY    - destination is directly reachable
  281: -static    RTF_STATIC     - manually added route
  282: -nostatic ~RTF_STATIC     - pretend route added by kernel or daemon
  283: -reject    RTF_REJECT     - emit an ICMP unreachable when matched
  284: -blackhole RTF_BLACKHOLE  - silently discard pkts (during updates)
  285: -proto1    RTF_PROTO1     - set protocol specific routing flag #1
  286: -proto2    RTF_PROTO2     - set protocol specific routing flag #2
  287: -llinfo    RTF_LLINFO     - validly translates proto addr to link addr
  288: .Ed
  289: .Pp
  290: The optional modifiers
  291: .Fl rtt ,
  292: .Fl rttvar ,
  293: .Fl sendpipe ,
  294: .Fl recvpipe ,
  295: .Fl mtu ,
  296: .Fl hopcount ,
  297: .Fl expire ,
  298: and
  299: .Fl ssthresh
  300: provide initial values to quantities maintained in the routing entry
  301: by transport level protocols, such as TCP or TP4.
  302: These may be individually locked by preceding each such modifier to
  303: be locked by
  304: the
  305: .Fl lock
  306: meta-modifier, or one can
  307: specify that all ensuing metrics may be locked by the
  308: .Fl lockrest
  309: meta-modifier.
  310: .Pp
  311: In a
  312: .Cm change
  313: or
  314: .Cm add
  315: command where the destination and gateway are not sufficient to specify
  316: the route (as in the
  317: .Tn ISO
  318: case where several interfaces may have the
  319: same address), the
  320: .Fl ifp
  321: or
  322: .Fl ifa
  323: modifiers may be used to determine the interface or interface address.
  324: .Pp
  325: The optional
  326: .Fl proxy
  327: modifier specifies that the
  328: .Dv RTF_LLINFO
  329: routing table entry is the
  330: .Dq published (proxy-only)
  331: .Tn ARP
  332: entry, as reported by
  333: .Xr arp 8 .
  334: .Pp
  335: All symbolic names specified for a
  336: .Ar destination
  337: or
  338: .Ar gateway
  339: are looked up first as a host name using
  340: .Xr gethostbyname 3 .
  341: If this lookup fails,
  342: .Xr getnetbyname 3
  343: is then used to interpret the name as that of a network.
  344: .Pp
  345: The
  346: .Nm
  347: utility uses a routing socket and the new message types
  348: .Dv RTM_ADD , RTM_DELETE , RTM_GET ,
  349: and
  350: .Dv RTM_CHANGE .
  351: As such, only the super-user may modify
  352: the routing tables.
  353: .Sh DIAGNOSTICS
  354: .Bl -diag
  355: .It "add [host \&| network ] %s: gateway %s flags %x"
  356: The specified route is being added to the tables.  The
  357: values printed are from the routing table entry supplied
  358: in the
  359: .Xr ioctl 2
  360: call.
  361: If the gateway address used was not the primary address of the gateway
  362: (the first one returned by
  363: .Xr gethostbyname 3 ) ,
  364: the gateway address is printed numerically as well as symbolically.
  365: .It "delete [ host \&| network ] %s: gateway %s flags %x"
  366: As above, but when deleting an entry.
  367: .It "%s %s done"
  368: When the
  369: .Cm flush
  370: command is specified, each routing table entry deleted
  371: is indicated with a message of this form.
  372: .It "Network is unreachable"
  373: An attempt to add a route failed because the gateway listed was not
  374: on a directly-connected network.
  375: The next-hop gateway must be given.
  376: .It "not in table"
  377: A delete operation was attempted for an entry which
  378: wasn't present in the tables.
  379: .It "routing table overflow"
  380: An add operation was attempted, but the system was
  381: low on resources and was unable to allocate memory
  382: to create the new entry.
  383: .It "gateway uses the same route"
  384: A
  385: .Cm change
  386: operation resulted in a route whose gateway uses the
  387: same route as the one being changed.
  388: The next-hop gateway should be reachable through a different route.
  389: .El
  390: .Pp
  391: .Ex -std
  392: .Sh SEE ALSO
  393: .\".Xr esis 4 ,
  394: .Xr netintro 4 ,
  395: .Xr route 4 ,
  396: .Xr arp 8 ,
  397: .Xr IPXrouted 8 ,
  398: .Xr routed 8
  399: .\".Xr XNSrouted 8
  400: .Sh HISTORY
  401: The
  402: .Nm
  403: utility appeared in
  404: .Bx 4.2 .
  405: .Sh BUGS
  406: The first paragraph may have slightly exaggerated
  407: .Xr routed 8 Ns 's
  408: abilities.