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