xref: /dragonfly/sbin/route/route.8 (revision 1de703da)
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
51The
52.Nm
53utility is used to manually manipulate the network
54routing tables.  It normally is not needed, as a
55system routing table management daemon such as
56.Xr routed 8 ,
57should tend to this task.
58.Pp
59The
60.Nm
61utility supports a limited number of general options,
62but a rich command language, enabling the user to specify
63any arbitrary request that could be delivered via the
64programmatic interface discussed in
65.Xr route 4 .
66.Pp
67The following options are available:
68.Bl -tag -width indent
69.It Fl n
70Bypass attempts to print host and network names symbolically
71when reporting actions.  (The process of translating between symbolic
72names and numerical equivalents can be quite time consuming, and
73may require correct operation of the network; thus it may be expedient
74to forget this, especially when attempting to repair networking operations).
75.It Fl v
76(verbose) Print additional details.
77.It Fl q
78Suppress all output from the
79.Cm add , delete ,
80and
81.Cm flush
82commands.
83.El
84.Pp
85The
86.Nm
87utility provides six commands:
88.Pp
89.Bl -tag -width Fl -compact
90.It Cm add
91Add a route.
92.It Cm flush
93Remove all routes.
94.It Cm delete
95Delete a specific route.
96.It Cm change
97Change aspects of a route (such as its gateway).
98.It Cm get
99Lookup and display the route for a destination.
100.It Cm monitor
101Continuously report any changes to the routing information base,
102routing lookup misses, or suspected network partitionings.
103.El
104.Pp
105The 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
113The 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
122If the
123.Cm flush
124command is specified,
125.Nm
126will ``flush'' the routing tables of all gateway entries.
127When the address family may is specified by any of the
128.Fl osi ,
129.Fl xns ,
130.Fl atalk ,
131.Fl inet6 ,
132or
133.Fl inet
134modifiers, only routes having destinations with addresses in the
135delineated family will be deleted.
136.Pp
137The 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
148where
149.Ar destination
150is the destination host or network,
151.Ar gateway
152is the next-hop intermediary via which packets should be routed.
153Routes to a particular host may be distinguished from those to
154a network by interpreting the Internet address specified as the
155.Ar destination
156argument.
157The optional modifiers
158.Fl net
159and
160.Fl host
161force the destination to be interpreted as a network or a host, respectively.
162Otherwise, if the
163.Ar destination
164has a
165.Dq local address part
166of
167INADDR_ANY
168.Pq Li 0.0.0.0 ,
169or if the
170.Ar destination
171is the symbolic name of a network, then the route is
172assumed to be to a network; otherwise, it is presumed to be a
173route to a host.
174Optionally, the
175.Ar destination
176could also be specified in the
177.Ar net Ns / Ns Ar bits
178format.
179.Pp
180For example,
181.Li 128.32
182is interpreted as
183.Fl host Li 128.0.0.32 ;
184.Li 128.32.130
185is interpreted as
186.Fl host Li 128.32.0.130 ;
187.Fl net Li 128.32
188is interpreted as
189.Li 128.32.0.0;
190.Fl net Li 128.32.130
191is interpreted as
192.Li 128.32.130.0;
193and
194.Li 192.168.64/20
195is interpreted as
196.Fl net Li 192.168.64 Fl netmask Li 255.255.240.0 .
197.Pp
198A
199.Ar destination
200of
201.Ar default
202is a synonym for
203.Fl net Li 0.0.0.0 ,
204which is the default route.
205.Pp
206If the destination is directly reachable
207via an interface requiring
208no intermediary system to act as a gateway, the
209.Fl interface
210modifier should be specified;
211the gateway given is the address of this host on the common network,
212indicating the interface to be used for transmission.
213Alternately, if the interface is point to point the name of the interface
214itself may be given, in which case the route remains valid even
215if the local or remote addresses change.
216.Pp
217The optional modifiers
218.Fl xns ,
219.Fl osi ,
220.Fl atalk ,
221and
222.Fl link
223specify that all subsequent addresses are in the
224.Tn XNS ,
225.Tn OSI ,
226or
227.Tn AppleTalk
228address families,
229or are specified as link-level addresses,
230and the names must be numeric specifications rather than
231symbolic names.
232.Pp
233The optional
234.Fl netmask
235modifier is intended
236to achieve the effect of an
237.Tn OSI
238.Tn ESIS
239redirect with the netmask option,
240or to manually add subnet routes with
241netmasks different from that of the implied network interface
242(as would otherwise be communicated using the OSPF or ISIS routing protocols).
243One specifies an additional ensuing address parameter
244(to be interpreted as a network mask).
245The implicit network mask generated in the AF_INET case
246can be overridden by making sure this option follows the destination parameter.
247.Pp
248For
249.Dv AF_INET6 ,
250the
251.Fl prefixlen
252qualifier
253is available instead of the
254.Fl mask
255qualifier because non-continuous masks are not allowed in IPv6.
256For example,
257.Fl prefixlen Li 32
258specifies network mask of
259.Li ffff:ffff:0000:0000:0000:0000:0000:0000
260to be used.
261The default value of prefixlen is 64 to get along with
262the aggregatable address.
263But 0 is assumed if
264.Cm default
265is specified.
266Note that the qualifier works only for
267.Dv AF_INET6
268address family.
269.Pp
270Routes have associated flags which influence operation of the protocols
271when sending to destinations matched by the routes.
272These flags may be set (or sometimes cleared)
273by 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
287The optional modifiers
288.Fl rtt ,
289.Fl rttvar ,
290.Fl sendpipe ,
291.Fl recvpipe ,
292.Fl mtu ,
293.Fl hopcount ,
294.Fl expire ,
295and
296.Fl ssthresh
297provide initial values to quantities maintained in the routing entry
298by transport level protocols, such as TCP or TP4.
299These may be individually locked by preceding each such modifier to
300be locked by
301the
302.Fl lock
303meta-modifier, or one can
304specify that all ensuing metrics may be locked by the
305.Fl lockrest
306meta-modifier.
307.Pp
308In a
309.Cm change
310or
311.Cm add
312command where the destination and gateway are not sufficient to specify
313the route (as in the
314.Tn ISO
315case where several interfaces may have the
316same address), the
317.Fl ifp
318or
319.Fl ifa
320modifiers may be used to determine the interface or interface address.
321.Pp
322The optional
323.Fl proxy
324modifier specifies that the
325.Dv RTF_LLINFO
326routing table entry is the
327.Dq published (proxy-only)
328.Tn ARP
329entry, as reported by
330.Xr arp 8 .
331.Pp
332All symbolic names specified for a
333.Ar destination
334or
335.Ar gateway
336are looked up first as a host name using
337.Xr gethostbyname 3 .
338If this lookup fails,
339.Xr getnetbyname 3
340is then used to interpret the name as that of a network.
341.Pp
342The
343.Nm
344utility uses a routing socket and the new message types
345.Dv RTM_ADD , RTM_DELETE , RTM_GET ,
346and
347.Dv RTM_CHANGE .
348As such, only the super-user may modify
349the routing tables.
350.Sh DIAGNOSTICS
351.Bl -diag
352.It "add [host \&| network ] %s: gateway %s flags %x"
353The specified route is being added to the tables.  The
354values printed are from the routing table entry supplied
355in the
356.Xr ioctl 2
357call.
358If the gateway address used was not the primary address of the gateway
359(the first one returned by
360.Xr gethostbyname 3 ) ,
361the gateway address is printed numerically as well as symbolically.
362.It "delete [ host \&| network ] %s: gateway %s flags %x"
363As above, but when deleting an entry.
364.It "%s %s done"
365When the
366.Cm flush
367command is specified, each routing table entry deleted
368is indicated with a message of this form.
369.It "Network is unreachable"
370An attempt to add a route failed because the gateway listed was not
371on a directly-connected network.
372The next-hop gateway must be given.
373.It "not in table"
374A delete operation was attempted for an entry which
375wasn't present in the tables.
376.It "routing table overflow"
377An add operation was attempted, but the system was
378low on resources and was unable to allocate memory
379to create the new entry.
380.It "gateway uses the same route"
381A
382.Cm change
383operation resulted in a route whose gateway uses the
384same route as the one being changed.
385The 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
398The
399.Nm
400utility appeared in
401.Bx 4.2 .
402.Sh BUGS
403The first paragraph may have slightly exaggerated
404.Xr routed 8 Ns 's
405abilities.
406