xref: /freebsd/sbin/route/route.8 (revision 13de33a5dc2304b13d595d75d48c51793958474f)
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$
30.\"
31.Dd October 17, 2013
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.Ar command
41.Oo
42.Op Ar modifiers
43.Ar args
44.Oc
45.Sh DESCRIPTION
46The
47.Nm
48utility is used to manually manipulate the network
49routing tables.
50It 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 d
66Run in debug-only mode, i.e., do not actually modify the routing table.
67.It Fl n
68Bypass attempts to print host and network names symbolically
69when reporting actions.
70(The process of translating between symbolic
71names and numerical equivalents can be quite time consuming, and
72may require correct operation of the network; thus it may be expedient
73to forget this, especially when attempting to repair networking operations).
74.It Fl t
75Run in test-only mode.
76.Pa /dev/null
77is used instead of a socket.
78.It Fl v
79(verbose) Print additional details.
80.It Fl q
81Suppress all output from the
82.Cm add , change , delete ,
83and
84.Cm flush
85commands.
86.El
87.Pp
88The
89.Nm
90utility provides the following 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 del
100Another name for the
101.Cm delete
102command.
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.
107.It Cm monitor
108Continuously report any changes to the routing information base,
109routing lookup misses, or suspected network partitionings.
110.It Cm show
111Another name for the
112.Cm get
113command.
114.El
115.Pp
116The monitor command has the syntax:
117.Pp
118.Bd -ragged -offset indent -compact
119.Nm
120.Op Fl n
121.Cm monitor Op Fl fib Ar number
122.Ed
123.Pp
124The flush command has the syntax:
125.Pp
126.Bd -ragged -offset indent -compact
127.Nm
128.Oo Fl n Cm flush Oc Oo Ar family Oc Op Fl fib Ar number
129.Ed
130.Pp
131If the
132.Cm flush
133command is specified,
134.Nm
135will ``flush'' the routing tables of all gateway entries.
136When the address family may is specified by any of the
137.Fl osi ,
138.Fl xns ,
139.Fl atalk ,
140.Fl inet6 ,
141or
142.Fl inet
143modifiers, only routes having destinations with addresses in the
144delineated family will be deleted.
145When a
146.Fl fib
147option is specified, the operation will be applied to
148the specified FIB
149.Pq routing table .
150.Pp
151The other commands have the following syntax:
152.Pp
153.Bd -ragged -offset indent -compact
154.Nm
155.Op Fl n
156.Ar command
157.Op Fl net No \&| Fl host
158.Ar destination gateway
159.Op Ar netmask
160.Op Fl fib Ar number
161.Ed
162.Pp
163where
164.Ar destination
165is the destination host or network,
166.Ar gateway
167is the next-hop intermediary via which packets should be routed.
168Routes to a particular host may be distinguished from those to
169a network by interpreting the Internet address specified as the
170.Ar destination
171argument.
172The optional modifiers
173.Fl net
174and
175.Fl host
176force the destination to be interpreted as a network or a host, respectively.
177Otherwise, if the
178.Ar destination
179has a
180.Dq local address part
181of
182INADDR_ANY
183.Pq Li 0.0.0.0 ,
184or if the
185.Ar destination
186is the symbolic name of a network, then the route is
187assumed to be to a network; otherwise, it is presumed to be a
188route to a host.
189Optionally, the
190.Ar destination
191could also be specified in the
192.Ar net Ns / Ns Ar bits
193format.
194.Pp
195For example,
196.Li 128.32
197is interpreted as
198.Fl host Li 128.0.0.32 ;
199.Li 128.32.130
200is interpreted as
201.Fl host Li 128.32.0.130 ;
202.Fl net Li 128.32
203is interpreted as
204.Li 128.32.0.0;
205.Fl net Li 128.32.130
206is interpreted as
207.Li 128.32.130.0;
208and
209.Li 192.168.64/20
210is interpreted as
211.Fl net Li 192.168.64 Fl netmask Li 255.255.240.0 .
212.Pp
213A
214.Ar destination
215of
216.Ar default
217is a synonym for the default route.
218For
219.Li IPv4
220it is
221.Fl net Fl inet Li 0.0.0.0 ,
222and for
223.Li IPv6
224it is
225.Fl net Fl inet6 Li :: .
226.Pp
227If the destination is directly reachable
228via an interface requiring
229no intermediary system to act as a gateway, the
230.Fl interface
231modifier should be specified;
232the gateway given is the address of this host on the common network,
233indicating the interface to be used for transmission.
234Alternately, if the interface is point to point the name of the interface
235itself may be given, in which case the route remains valid even
236if the local or remote addresses change.
237.Pp
238The optional modifiers
239.Fl xns ,
240.Fl osi ,
241.Fl atalk ,
242and
243.Fl link
244specify that all subsequent addresses are in the
245.Tn XNS ,
246.Tn OSI ,
247or
248.Tn AppleTalk
249address families,
250or are specified as link-level addresses,
251and the names must be numeric specifications rather than
252symbolic names.
253.Pp
254The optional
255.Fl netmask
256modifier is intended
257to achieve the effect of an
258.Tn OSI
259.Tn ESIS
260redirect with the netmask option,
261or to manually add subnet routes with
262netmasks different from that of the implied network interface
263(as would otherwise be communicated using the OSPF or ISIS routing protocols).
264One specifies an additional ensuing address parameter
265(to be interpreted as a network mask).
266The implicit network mask generated in the AF_INET case
267can be overridden by making sure this option follows the destination parameter.
268.Pp
269For
270.Dv AF_INET6 ,
271the
272.Fl prefixlen
273qualifier
274is available instead of the
275.Fl mask
276qualifier because non-continuous masks are not allowed in IPv6.
277For example,
278.Fl prefixlen Li 32
279specifies network mask of
280.Li ffff:ffff:0000:0000:0000:0000:0000:0000
281to be used.
282The default value of prefixlen is 64 to get along with
283the aggregatable address.
284But 0 is assumed if
285.Cm default
286is specified.
287Note that the qualifier works only for
288.Dv AF_INET6
289address family.
290.Pp
291Routes have associated flags which influence operation of the protocols
292when sending to destinations matched by the routes.
293These flags may be set (or sometimes cleared)
294by indicating the following corresponding modifiers:
295.Bd -literal
296-xresolve  RTF_XRESOLVE   - emit mesg on use (for external lookup)
297-iface    ~RTF_GATEWAY    - destination is directly reachable
298-static    RTF_STATIC     - manually added route
299-nostatic ~RTF_STATIC     - pretend route added by kernel or daemon
300-reject    RTF_REJECT     - emit an ICMP unreachable when matched
301-blackhole RTF_BLACKHOLE  - silently discard pkts (during updates)
302-proto1    RTF_PROTO1     - set protocol specific routing flag #1
303-proto2    RTF_PROTO2     - set protocol specific routing flag #2
304-proto3    RTF_PROTO3     - set protocol specific routing flag #3
305.Ed
306.Pp
307The optional modifiers
308.Fl rtt ,
309.Fl rttvar ,
310.Fl sendpipe ,
311.Fl recvpipe ,
312.Fl mtu ,
313.Fl hopcount ,
314.Fl expire ,
315and
316.Fl ssthresh
317provide initial values to quantities maintained in the routing entry
318by transport level protocols, such as TCP or TP4.
319These may be individually locked by preceding each such modifier to
320be locked by
321the
322.Fl lock
323meta-modifier, or one can
324specify that all ensuing metrics may be locked by the
325.Fl lockrest
326meta-modifier.
327.Pp
328Note that
329.Fl expire
330accepts expiration time of the route as the number of seconds since the
331Epoch
332.Pq see Xr time 3 .
333When the first character of the number is
334.Dq +
335or
336.Dq - ,
337it is interpreted as a value relative to the current time.
338.Pp
339The optional modifier
340.Fl fib Ar number
341specifies that the command will be applied to a non-default FIB.
342The
343.Ar number
344must be smaller than the
345.Va net.fibs
346.Xr sysctl 8
347MIB.
348When this modifier is not specified,
349or a negative number is specified,
350the default FIB shown in the
351.Va net.my_fibnum
352.Xr sysctl 8
353MIB will be used.
354.Pp
355The
356.Ar number
357allows multiple FIBs by a comma-separeted list and/or range
358specification.
359The
360.Qq Fl fib Li 2,4,6
361means the FIB number 2, 4, and 6.
362The
363.Qq Fl fib Li 1,3-5,6
364means the 1, 3, 4, 5, and 6.
365.Pp
366In a
367.Cm change
368or
369.Cm add
370command where the destination and gateway are not sufficient to specify
371the route (as in the
372.Tn ISO
373case where several interfaces may have the
374same address), the
375.Fl ifp
376or
377.Fl ifa
378modifiers may be used to determine the interface or interface address.
379.Pp
380All symbolic names specified for a
381.Ar destination
382or
383.Ar gateway
384are looked up first as a host name using
385.Xr gethostbyname 3 .
386If this lookup fails,
387.Xr getnetbyname 3
388is then used to interpret the name as that of a network.
389.Pp
390The
391.Nm
392utility uses a routing socket and the new message types
393.Dv RTM_ADD , RTM_DELETE , RTM_GET ,
394and
395.Dv RTM_CHANGE .
396As such, only the super-user may modify
397the routing tables.
398.Sh EXIT STATUS
399.Ex -std
400.Sh EXAMPLES
401Add a default route to the network routing table.
402This will send all packets for destinations not available in the routing table
403to the default gateway at 192.168.1.1:
404.Pp
405.Dl route add -net 0.0.0.0/0 192.168.1.1
406.Pp
407A shorter version of adding a default route can also be written as:
408.Pp
409.Dl route add default 192.168.1.1
410.Pp
411Add a static route to the 172.16.10.0/24 network via the 172.16.1.1 gateway:
412.Pp
413.Dl route add -net 172.16.10.0/24 172.16.1.1
414.Pp
415Change the gateway of an already established static route in the routing table:
416.Pp
417.Dl route change -net 172.16.10.0/24 172.16.1.2
418.Pp
419Display the route for a destination network:
420.Pp
421.Dl route show 172.16.10.0
422.Pp
423Delete a static route from the routing table:
424.Pp
425.Dl route delete -net 172.16.10.0/24 172.16.1.2
426.Pp
427Remove all routes from the routing table:
428.Pp
429.Dl route flush
430.Sh DIAGNOSTICS
431.Bl -diag
432.It "add [host \&| network ] %s: gateway %s flags %x"
433The specified route is being added to the tables.
434The
435values printed are from the routing table entry supplied
436in the
437.Xr ioctl 2
438call.
439If the gateway address used was not the primary address of the gateway
440(the first one returned by
441.Xr gethostbyname 3 ) ,
442the gateway address is printed numerically as well as symbolically.
443.It "delete [ host \&| network ] %s: gateway %s flags %x"
444As above, but when deleting an entry.
445.It "%s %s done"
446When the
447.Cm flush
448command is specified, each routing table entry deleted
449is indicated with a message of this form.
450.It "Network is unreachable"
451An attempt to add a route failed because the gateway listed was not
452on a directly-connected network.
453The next-hop gateway must be given.
454.It "not in table"
455A delete operation was attempted for an entry which
456was not present in the tables.
457.It "routing table overflow"
458An add operation was attempted, but the system was
459low on resources and was unable to allocate memory
460to create the new entry.
461.It "gateway uses the same route"
462A
463.Cm change
464operation resulted in a route whose gateway uses the
465same route as the one being changed.
466The next-hop gateway should be reachable through a different route.
467.El
468.Sh SEE ALSO
469.\".Xr esis 4 ,
470.Xr netintro 4 ,
471.Xr route 4 ,
472.Xr arp 8 ,
473.Xr IPXrouted 8 ,
474.Xr routed 8
475.\".Xr XNSrouted 8
476.Sh HISTORY
477The
478.Nm
479utility appeared in
480.Bx 4.2 .
481.Sh BUGS
482The first paragraph may have slightly exaggerated
483.Xr routed 8 Ns 's
484abilities.
485.Pp
486Currently, routes with the
487.Dv RTF_BLACKHOLE
488flag set need to have the gateway set to an instance of the
489.Xr lo 4
490driver, using the
491.Fl iface
492option, for the flag to have any effect; unless IP fast forwarding
493is enabled, in which case the meaning of the flag will always
494be honored.
495