1 .\" $NetBSD: route.8,v 1.55 2015/03/23 18:33:17 roy Exp $
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" @(#)route.8 8.4 (Berkeley) 6/1/94
37 .Nd manually manipulate the routing tables
48 is a utility used to manually manipulate the network
50 Except for setting up the default route, it is normally not needed,
51 as a system routing table management daemon such as
53 should tend to this task.
56 can be used to modify nearly any aspect of the routing policy,
57 except packet forwarding, which can be manipulated through the
63 utility supports a limited number of general options,
64 but a rich command language, enabling the user to specify
65 any arbitrary request that could be delivered via the
66 programmatic interface discussed in
73 Remove all routes (as per
75 If used in conjunction with the
83 removes the routes before performing the command.
85 Don't show link layer entries in routing table.
87 Bypasses attempts to print host and network names symbolically
88 when reporting actions.
89 (The process of translating between symbolic
90 names and numerical equivalents can be quite time consuming, and
91 may require correct operation of the network; thus it may be expedient
92 to forgo this, especially when attempting to repair networking operations).
94 Suppress all output from commands that manipulate the routing table.
96 Print a space when a flag is missing so that flags are vertically aligned
97 instead of printing the flags that are set as a contiguous string.
99 (short) Suppresses all output from a
101 command except for the actual gateway that will be used.
102 How the gateway is printed depends on the type of route being looked up.
104 Show tags in the route display.
106 Test only, don't perform any actions.
108 (verbose) Print additional details.
113 utility provides several commands:
115 .Bl -tag -width Fl -compact
121 Remove all routes including the default gateway.
123 Delete a specific route.
125 Change aspects of a route (such as its gateway).
127 Lookup and display the route for a destination.
129 Print out the route table similar to "netstat \-r" (see
132 Continuously report any changes to the routing information base,
133 routing lookup misses, or suspected network partitionings.
136 The monitor command has the syntax
138 .Bd -filled -offset indent -compact
144 The flush command has the syntax
146 .Bd -filled -offset indent -compact
155 command is specified,
157 will ``flush'' the routing tables of all gateway entries.
158 When the address family is specified by any of the
165 modifiers, only routes having destinations with addresses in the
166 delineated family will be manipulated.
168 The other commands have the following syntax:
170 .Bd -filled -offset indent -compact
174 .Op Fl net No \&| Fl host
175 .Ar destination gateway
180 is the destination host or network, and
182 is the next-hop intermediary via which packets should be routed.
183 Routes to a particular host may be distinguished from those to
184 a network by interpreting the Internet address specified as the
187 The optional modifiers
191 force the destination to be interpreted as a network or a host, respectively.
194 has a ``local address part'' of
198 is the symbolic name of a network, then the route is
199 assumed to be to a network; otherwise, it is presumed to be a
203 can also be specified in the
204 .Ar net Ns / Ns Ar bits
210 .Fl host Li 128.0.0.32 ;
213 .Fl host Li 128.32.0.130 ;
218 .Fl net Li 128.32.130
226 to set up a default route to a smart
228 If no other routes match, this default route will be used as a last resort.
230 If the destination is directly reachable
231 via an interface requiring
232 no intermediary system to act as a gateway, the
234 modifier should be specified;
235 the gateway given is the address of this host on the common network,
236 indicating the interface to be used for transmission.
238 The optional modifiers
243 specify that all subsequent addresses are in the
248 or are specified as link-level addresses in the form described in
250 and the names must be numeric specifications rather than
253 The optional modifier
255 specifies an address associated with the route.
256 How the address is used is specific to the address family of
257 the destination and the interface used to forward the packet.
258 Currently route tags are consumed only by the
262 assumes that the subsequent addresses are in the
267 for examples of setting routes involving MPLS.
271 qualifier is intended
272 to achieve the effect of an
274 redirect with the netmask option,
275 or to manually add subnet routes with
276 netmasks different from that of the implied network interface
277 (as would otherwise be communicated using the OSPF or ISIS routing protocols).
278 One specifies an additional ensuing address parameter
279 (to be interpreted as a network mask).
280 The implicit network mask generated in the
283 can be overridden by making sure this option follows the destination parameter.
285 is also available for similar purpose, in IPv4 and IPv6 case.
287 Routes have associated flags which influence operation of the protocols
288 when sending to destinations matched by the routes.
289 These flags are displayed using the following ID characters in the routing
290 display and may be set (or sometimes cleared)
291 by indicating the following corresponding modifiers:
292 .Bl -column "ID" "xnoblackhole" "xRTF_BLACKHOLE" "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
293 .It Sy "ID" Ta Sy "Modifier" Ta Sy " Flag Bit" Ta Sy "Description"
294 .It Li " " Ta -iface Ta ~RTF_GATEWAY Ta destination is directly reachable
295 .It Li 1 Ta -proto1 Ta " RTF_PROTO1" Ta set protocol specific flag #1
296 .It Li 2 Ta -proto2 Ta " RTF_PROTO2" Ta set protocol specific flag #2
297 .It Li B Ta -blackhole Ta " RTF_BLACKHOLE" Ta discard pkts (during updates)
298 .It Li b Ta "" Ta " RTF_BROADCAST" Ta Route represents a broadcast address
299 .It Li " " Ta -noblackhole Ta ~RTF_BLACKHOLE Ta clear blackhole flag
300 .It Li C Ta -cloning Ta " RTF_CLONING" Ta generates a new route on use
301 .It Li " " Ta -nocloning Ta ~RTF_CLONING Ta stop generating new routes on use
302 .It Li c Ta -cloned Ta " RTF_CLONED" Ta route generated by RTF_CLONING
303 .It Li " " Ta -nocloned Ta ~RTF_CLONED Ta deny removal with RTF_CLONING
304 .It Li D Ta "" Ta " RTF_DYNAMIC" Ta created dynamically (redirect)
305 .It Li G Ta "" Ta " RTF_GATEWAY" Ta forwarded to dest by intermediary
306 .It Li H Ta "" Ta " RTF_HOST" Ta host entry (net otherwise)
307 .It Li L Ta -llinfo Ta " RTF_LLINFO" Ta translate proto to link addr
308 .It Li l Ta "" Ta " RTF_LOCAL" Ta Route represents a local address
309 .It Li M Ta "" Ta " RTF_MODIFIED" Ta modified dynamically (redirect)
310 .It Li p Ta -proxy Ta " RTF_ANNOUNCE" Ta make entry a link level proxy
311 .It Li R Ta -reject Ta " RTF_REJECT" Ta send ICMP unreachable on match
312 .It Li " " Ta -noreject Ta ~RTF_REJECT Ta clear reject flag
313 .It Li S Ta -static Ta " RTF_STATIC" Ta manually added route
314 .It Li " " Ta -nostatic Ta ~RTF_STATIC Ta pretend route added automatically
315 .It Li U Ta "" Ta " RTF_UP" Ta route usable
316 .It Li X Ta -xresolve Ta " RTF_XRESOLVE" Ta emit mesg on use (for ext lookup)
319 The optional modifiers
329 provide initial values to quantities maintained in the routing entry
330 by transport level protocols, such as TCP or TP4.
331 These may be individually locked by preceding each such modifier to
335 meta-modifier, or one can
336 specify that all ensuing metrics may be locked by the
344 command where the destination and gateway are not sufficient to specify
349 modifiers may be used to determine the interface or interface address.
351 All symbolic names specified for a
355 are looked up first as a host name using
356 .Xr gethostbyname 3 .
357 If this lookup fails,
359 is then used to interpret the name as that of a network.
362 uses a routing socket and the new message types
368 As such, only the super-user may modify
373 utility exits 0 on success, and \*[Gt]0 if an error occurs.
374 This includes the use of the
376 command to look up a route that is incomplete.
378 This sets the default route to 192.168.0.1:
379 .Dl route add default 192.168.0.1
380 This shows all routes, without DNS resolution (this is useful if the
381 DNS is not available):
383 To install a static route through 10.200.0.1 to reach the network
384 192.168.1.0/28, use this:
385 .Dl route add -net 192.168.1.0 -netmask 255.255.255.240 10.200.0.1
388 .It Sy "add [host \&| network ] %s: gateway %s flags %x"
389 The specified route is being added to the tables.
390 The values printed are from the routing table entry supplied in the
393 If the gateway address used was not the primary address of the gateway
394 (the first one returned by
395 .Xr gethostbyname 3 ) ,
396 the gateway address is printed numerically as well as symbolically.
397 .It Sy "delete [ host \&| network ] %s: gateway %s flags %x"
398 As above, but when deleting an entry.
402 command is specified, each routing table entry deleted
403 is indicated with a message of this form.
404 .It Sy "Network is unreachable"
405 An attempt to add a route failed because the gateway listed was not
406 on a directly-connected network.
407 The next-hop gateway must be given.
408 .It Sy "not in table"
409 A delete operation was attempted for an entry which
410 wasn't present in the tables.
411 .It Sy "routing table overflow"
412 An add operation was attempted, but the system was
413 low on resources and was unable to allocate memory
414 to create the new entry.
415 .It Sy "Permission denied"
416 The attempted operation is privileged.
417 Only root may modify the routing tables.
418 These privileges are enforced by the kernel.
432 IPv6 support was added by WIDE/KAME project.
434 The first paragraph may have slightly exaggerated
442 modifiers with the add command will incorrectly fail with a
443 .Dq Network is unreachable
444 message if there is no default route.
448 .Pa sys/net/rtsock.c:route_output