xref: /dragonfly/sbin/route/route.8 (revision 3170ffd7)
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: src/sbin/route/route.8,v 1.17.2.9 2003/02/24 00:56:43 trhodes Exp $
30.\"
31.Dd June 8, 2001
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.Op Fl c Ar cpu
41.Ar command
42.Oo
43.Op Ar modifiers
44.Ar args
45.Oc
46.Sh DESCRIPTION
47The
48.Nm
49utility is used to manually manipulate the network
50routing tables.  It normally is not needed, as a
51system routing table management daemon such as
52.Xr routed 8 ,
53should tend to this task.
54.Pp
55The
56.Nm
57utility supports a limited number of general options,
58but a rich command language, enabling the user to specify
59any arbitrary request that could be delivered via the
60programmatic interface discussed in
61.Xr route 4 .
62.Pp
63The following options are available:
64.Bl -tag -width indent
65.It Fl c Ar cpu
66On SMP systems the route table is replicated.  This option allows the
67route table for a specific cpu to be accessed and exists primarily
68for debugging purposes.
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.It Fl w
84Print the full width of the data being represented even if it would overflow
85the column.
86.El
87.Pp
88The
89.Nm
90utility provides six commands:
91.Pp
92.Bl -tag -width Fl -compact
93.It Cm add
94Add a route.
95.It Cm flush
96Remove all routes.
97.It Cm delete
98Delete a specific route.
99.It Cm change
100Change aspects of a route (such as its gateway).
101.It Cm get
102Lookup and display the route for a destination.
103.It Cm show
104Print out the route table similar to "netstat \-r" (see
105.Xr netstat 1 ) .
106.It Cm monitor
107Continuously report any changes to the routing information base,
108routing lookup misses, or suspected network partitionings.
109.El
110.Pp
111The 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
119The 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
128If the
129.Cm flush
130command is specified,
131.Nm
132will ``flush'' the routing tables of all gateway entries.
133When the address family may is specified by any of the
134.Fl osi ,
135.Fl xns ,
136.Fl inet6 ,
137or
138.Fl inet
139modifiers, only routes having destinations with addresses in the
140delineated family will be deleted.
141.Pp
142The other commands have the following syntax:
143.Pp
144.Bd -ragged -offset indent -compact
145.Nm
146.Op Fl n
147.Ar command
148.Op Fl net No \&| Fl host
149.Ar destination gateway
150.Op Ar netmask
151.Ed
152.Pp
153where
154.Ar destination
155is the destination host or network,
156.Ar gateway
157is the next-hop intermediary via which packets should be routed.
158Routes to a particular host may be distinguished from those to
159a network by interpreting the Internet address specified as the
160.Ar destination
161argument.
162The optional modifiers
163.Fl net
164and
165.Fl host
166force the destination to be interpreted as a network or a host, respectively.
167Otherwise, if the
168.Ar destination
169has a
170.Dq local address part
171of
172INADDR_ANY
173.Pq Li 0.0.0.0 ,
174or if the
175.Ar destination
176is the symbolic name of a network, then the route is
177assumed to be to a network; otherwise, it is presumed to be a
178route to a host.
179Optionally, the
180.Ar destination
181could also be specified in the
182.Ar net Ns / Ns Ar bits
183format.
184.Pp
185For example,
186.Li 128.32
187is interpreted as
188.Fl host Li 128.0.0.32 ;
189.Li 128.32.130
190is interpreted as
191.Fl host Li 128.32.0.130 ;
192.Fl net Li 128.32
193is interpreted as
194.Li 128.32.0.0;
195.Fl net Li 128.32.130
196is interpreted as
197.Li 128.32.130.0;
198and
199.Li 192.168.64/20
200is interpreted as
201.Fl net Li 192.168.64 Fl netmask Li 255.255.240.0 .
202.Pp
203A
204.Ar destination
205of
206.Ar default
207is a synonym for
208.Fl net Li 0.0.0.0 ,
209which is the default route.
210.Pp
211If the destination is directly reachable
212via an interface requiring
213no intermediary system to act as a gateway, the
214.Fl interface
215modifier should be specified;
216the gateway given is the address of this host on the common network,
217indicating the interface to be used for transmission.
218Alternately, if the interface is point to point the name of the interface
219itself may be given, in which case the route remains valid even
220if the local or remote addresses change.
221.Pp
222The optional modifiers
223.Fl mpls ,
224.Fl xns ,
225.Fl osi ,
226and
227.Fl link
228specify that all subsequent addresses are in the
229.Tn MPLS ,
230.Tn XNS ,
231or
232.Tn OSI
233address families,
234or are specified as link-level addresses,
235and the names must be numeric specifications rather than
236symbolic names.
237.Pp
238The optional
239.Fl netmask
240modifier is intended
241to achieve the effect of an
242.Tn OSI
243.Tn ESIS
244redirect with the netmask option,
245or to manually add subnet routes with
246netmasks different from that of the implied network interface
247(as would otherwise be communicated using the OSPF or ISIS routing protocols).
248One specifies an additional ensuing address parameter
249(to be interpreted as a network mask).
250The implicit network mask generated in the AF_INET case
251can be overridden by making sure this option follows the destination parameter.
252.Pp
253For
254.Dv AF_INET6 ,
255the
256.Fl prefixlen
257qualifier
258is available instead of the
259.Fl mask
260qualifier because non-continuous masks are not allowed in IPv6.
261For example,
262.Fl prefixlen Li 32
263specifies network mask of
264.Li ffff:ffff:0000:0000:0000:0000:0000:0000
265to be used.
266The default value of prefixlen is 64 to get along with
267the aggregatable address.
268But 0 is assumed if
269.Cm default
270is specified.
271Note that the qualifier works only for
272.Dv AF_INET6
273address family.
274.Pp
275Routes have associated flags which influence operation of the protocols
276when sending to destinations matched by the routes.
277These flags may be set (or sometimes cleared)
278by indicating the following corresponding modifiers:
279.Bd -literal
280-cloning   RTF_CLONING    - generates a new route on use
281-xresolve  RTF_XRESOLVE   - emit mesg on use (for external lookup)
282-iface    ~RTF_GATEWAY    - destination is directly reachable
283-static    RTF_STATIC     - manually added route
284-nostatic ~RTF_STATIC     - pretend route added by kernel or daemon
285-reject    RTF_REJECT     - emit an ICMP unreachable when matched
286-blackhole RTF_BLACKHOLE  - silently discard pkts (during updates)
287-proto1    RTF_PROTO1     - set protocol specific routing flag #1
288-proto2    RTF_PROTO2     - set protocol specific routing flag #2
289-llinfo    RTF_LLINFO     - validly translates proto addr to link addr
290.Ed
291.Pp
292The optional modifiers
293.Fl rtt ,
294.Fl rttvar ,
295.Fl sendpipe ,
296.Fl recvpipe ,
297.Fl mtu ,
298.Fl hopcount ,
299.Fl expire ,
300and
301.Fl ssthresh
302provide initial values to quantities maintained in the routing entry
303by transport level protocols, such as TCP or TP4.
304These may be individually locked by preceding each such modifier to
305be locked by
306the
307.Fl lock
308meta-modifier, or one can
309specify that all ensuing metrics may be locked by the
310.Fl lockrest
311meta-modifier.
312.Pp
313In a
314.Cm change
315or
316.Cm add
317command where the destination and gateway are not sufficient to specify
318the route (as in the
319.Tn ISO
320case where several interfaces may have the
321same address), the
322.Fl ifp
323or
324.Fl ifa
325modifiers may be used to determine the interface or interface address.
326.Pp
327The optional
328.Fl proxy
329modifier specifies that the
330.Dv RTF_LLINFO
331routing table entry is the
332.Dq published (proxy-only)
333.Tn ARP
334entry, as reported by
335.Xr arp 8 .
336.Pp
337All symbolic names specified for a
338.Ar destination
339or
340.Ar gateway
341are looked up first as a host name using
342.Xr gethostbyname 3 .
343If this lookup fails,
344.Xr getnetbyname 3
345is then used to interpret the name as that of a network.
346.Pp
347The optional
348.Fl push ,
349.Fl pop ,
350and
351.Fl swap
352modifiers may be used to specify the desired mpls label
353operations for the route. Each route may have up to 3
354label operations assigned to it. The label operations
355may be combined between them, but specifically the
356.Fl push
357and
358.Fl pop
359operations may be repeated if the intent is to push or pop
360more than one label at once. The
361.Fl swap
362operation always swaps the outer label and may not be
363repeated.
364Here are some MPLS route examples:
365.Pp
366Add an normal inet route, but push an mpls
367.Ar label
368to the packet:
369.Pp
370.Bd -ragged -offset indent -compact
371.Nm
372.Cm add
373.Ar destination gateway
374.Fl push
375.Ar label
376.Ed
377.Pp
378Add an normal inet route, but double-push an mpls
379.Ar inner-label
380and an
381.Ar outer-label
382to the packet:
383.Pp
384.Bd -ragged -offset indent -compact
385.Nm
386.Cm add
387.Ar destination gateway
388.Fl push
389.Ar inner-label
390.Fl push
391.Ar outer-label
392.Ed
393.Pp
394Add an mpls route for an
395.Ar incoming-label
396to be forwarded to
397.Ar gateway
398and swap that label with
399.Ar new-label :
400.Pp
401.Bd -ragged -offset indent -compact
402.Nm
403.Cm add
404.Fl mpls
405.Ar incoming-label
406.Fl inet
407.Ar gateway
408.Fl swap
409.Ar new-label
410.Ed
411.Pp
412The
413.Nm
414utility uses a routing socket and the new message types
415.Dv RTM_ADD , RTM_DELETE , RTM_GET ,
416and
417.Dv RTM_CHANGE .
418As such, only the super-user may modify
419the routing tables.
420.Sh EXIT STATUS
421.Ex -std
422.Sh DIAGNOSTICS
423.Bl -diag
424.It "add [host \&| network ] %s: gateway %s flags %x"
425The specified route is being added to the tables.  The
426values printed are from the routing table entry supplied
427in the
428.Xr ioctl 2
429call.
430If the gateway address used was not the primary address of the gateway
431(the first one returned by
432.Xr gethostbyname 3 ) ,
433the gateway address is printed numerically as well as symbolically.
434.It "delete [ host \&| network ] %s: gateway %s flags %x"
435As above, but when deleting an entry.
436.It "%s %s done"
437When the
438.Cm flush
439command is specified, each routing table entry deleted
440is indicated with a message of this form.
441.It "Network is unreachable"
442An attempt to add a route failed because the gateway listed was not
443on a directly-connected network.
444The next-hop gateway must be given.
445.It "not in table"
446A delete operation was attempted for an entry which
447wasn't present in the tables.
448.It "routing table overflow"
449An add operation was attempted, but the system was
450low on resources and was unable to allocate memory
451to create the new entry.
452.It "gateway uses the same route"
453A
454.Cm change
455operation resulted in a route whose gateway uses the
456same route as the one being changed.
457The next-hop gateway should be reachable through a different route.
458.El
459.Sh SEE ALSO
460.\".Xr esis 4 ,
461.Xr netintro 4 ,
462.Xr route 4 ,
463.Xr arp 8 ,
464.Xr IPXrouted 8 ,
465.Xr routed 8
466.\".Xr XNSrouted 8
467.Sh HISTORY
468The
469.Nm
470utility appeared in
471.Bx 4.2 .
472.Sh BUGS
473The first paragraph may have slightly exaggerated
474.Xr routed 8 Ns 's
475abilities.
476