File:  [DragonFly] / src / sbin / route / route.8
Revision 1.4: download - view: text, annotated - select for diffs
Tue Mar 23 18:25:51 2004 UTC (10 years, 7 months ago) by dillon
Branches: MAIN
CVS tags: HEAD, DragonFly_Stable, DragonFly_Snap29Sep2004, DragonFly_Snap13Sep2004, DragonFly_RELEASE_1_4_Slip, DragonFly_RELEASE_1_4, DragonFly_RELEASE_1_2_Slip, DragonFly_RELEASE_1_2, DragonFly_1_0_REL, DragonFly_1_0_RC1, DragonFly_1_0A_REL
Add -w, which prints the full width of the data being represented even if
it overflows the column, and do not truncate the base domain from displayed
host names.  This is for programmatic interfaces and for sysops
who really want to see the whole host name.

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