Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ROUTE(8)		FreeBSD	System Manager's Manual		      ROUTE(8)

NAME
     route -- manually manipulate the routing tables

SYNOPSIS
     route [-dnqtv] [-T	rtable]	command	[[modifiers] args]

DESCRIPTION
     route is a	utility	used to	manually view and manipulate the network rout-
     ing tables.  route	can be used to modify nearly any aspect	of the routing
     policy, except packet forwarding, which can be manipulated	through	the
     sysctl(8) command.

     The route utility supports	a limited number of general options, but a
     rich command language enables the user to specify any arbitrary request
     that could	be delivered via the programmatic interface discussed in
     route(4).

     The options are as	follows:

     -d	     Run in debug-only mode, i.e., don't actually modify the routing
	     table.

     -n	     Bypass attempts to	print host and network names symbolically when
	     reporting actions.	 (The process of translating between symbolic
	     names and numerical equivalents can be quite time consuming, and
	     may require correct operation of the network; thus	it may be ex-
	     pedient to	forgo this, especially when attempting to repair net-
	     working operations.)

     -q	     Suppress all output.

     -T	rtable
	     Select an alternate routing table to modify or query.  The	de-
	     fault is to use the current routing table.

     -t	     Write routing messages to a fake device (/dev/null) instead of a
	     real routing socket to test route manipulation.

     -v	     (verbose) Print additional	details.

     The route utility provides	the following simple commands:

     route [-T rtable] exec [command ...]
		 Execute a command forcing the process and its children	to use
		 the routing table and appropriate routing domain as specified
		 with the -T rtable option.

     route [-nqv] [-T rtable] flush [modifiers]
		 Delete	all gateway entries from the routing table.  When the
		 address family	is specified by	any one	of the family modi-
		 fiers (listed below), only routes having destinations with
		 addresses in the delineated family will be deleted.  Also,
		 only routes matching a	specific interface or priority can be
		 flushed by using the -iface or	-priority modifiers.

     route [-nv] [-T rtable] get [modifiers] address
		 Extract a routing entry from the kernel.  If -gateway is
		 specified, only routes	whose gateway are in the same address
		 family	as the destination are shown.

     route [-n]	[-T rtable] monitor [modifiers]
		 Continuously report any changes to the	routing	information
		 base, routing lookup misses, or suspected network partition-
		 ings.

		 When the address family is specified by any one of the	family
		 modifiers (listed below), only	routes having destinations
		 with addresses	in the delineated family will be shown.	 If
		 the -iface modifier is	used only interface specific messages
		 (link state changes) are shown.  If a routing table is	sup-
		 plied with -T,	only changes in	that routing table will	be
		 displayed.

     route [-nv] [-T rtable] show [family] [-gateway] [-label label]
		 [-priority priority]
		 Print out the routing table, in a fashion similar to "netstat
		 -r".  The output is documented	in more	detail towards the end
		 of the	netstat(1) manual.

		 If -gateway is	specified, only	routes whose gateway are in
		 the same address family as the	destination are	shown.

		 If -label is specified, only routes with the specified	label
		 are shown.

		 If -priority is specified, only routes	with the specified
		 priority are shown.  It may be	specified by number or one of
		 local,	connected, static, ospf, rip, or bgp.  If the priority
		 is negative, then routes that do not match the	numeric	prior-
		 ity are shown.

     route [-T rtable] sourceaddr [-inet|-inet6] [address]
     route [-T rtable] sourceaddr [-inet|-inet6] -ifp interface

		 Set the preferred source address.  If address is the word
		 "default", 0.0.0.0 or ::, source address will be chosen by
		 the kernel for	the matching address family.  When address is
		 omitted, preferred source address is printed if set.  If -ifp
		 is used, source will use IP assigned to interface.  The pre-
		 ferred	source will not	be used	when:

		 +o   destination is on-link
		 +o   source address is assigned	to a disabled interface

     The other commands	relating to adding, changing, or deleting routes have
     the syntax:

     route [-dnqtv] [-T	rtable]	add [modifiers]	destination gateway
     route [-dnqtv] [-T	rtable]	change [modifiers] destination gateway
     route [-dnqtv] [-T	rtable]	del[ete] [modifiers] destination gateway

     destination is the	destination host or network; gateway is	the next-hop
     intermediary via which packets should be routed.  Routes to a particular
     host may be distinguished from those to a network by interpreting the In-
     ternet address specified as the destination argument.  The	optional modi-
     fiers -net	and -host cause	the destination	to be interpreted as a network
     or	a host,	respectively.  Otherwise, type is chosen based on the follow-
     ing rules:

     The route is assumed to be	to a network if	any of the following apply to
     destination:

     +o	 it is the word	"default", equivalent to 0/0
     +o	 it is an IPv4 address with less than 3	dots
     +o	 it is an IPv4 address with a "/XX" suffix (where XX is	the number of
	 bits in the network portion of	the address and	is less	than 32)
     +o	 it is an IPv6 address with a "/XX" suffix (where XX is	the number of
	 bits in the network portion of	the address and	is less	than 128)
     +o	 it is the symbolic name of a network.

     If	destination is a valid IP address or host name,	it is presumed to be a
     route to a	host.

     For example, 192.168.1.1 is interpreted as	-host 192.168.1.1 and
     192.168.1 is interpreted as -net 192.168.1.  Note,	however, that
     192.168.2.0 will be interpreted as	-host 192.168.2.0 since	it is a	com-
     plete IP address with 3 dots.  In this case the number of bits in the
     network portion of	the address must be explicitly listed, for example
     192.168.2.0/24, 192.168.2/24, or alternately 192.168.2.

     If	the destination	is directly reachable via an interface requiring no
     intermediary system to act	as a gateway, the -iface modifier should be
     specified;	the gateway given is the address of this host on the common
     network, indicating the interface to be used for transmission.

     To	allow addresses	to be interpreted as belonging to a particular address
     family (as	well as	for use	in the family arguments	to some	commands), the
     following modifiers may be	used:

     -inet   Internet Protocol version 4 (IPv4)	addresses (see ip(4))
     -inet6  Internet Protocol version 6 (IPv6)	addresses (see ip6(4))
     -link   Hardware (link-level) addresses
     -mpls   MPLS addresses
     -sa     Actual sockaddr data, in hexadecimal format

     In	the absence of modifiers, an address is	assumed	to be IPv4, unless
     containing	a `:' character, when it is treated as IPv6.

     The optional modifier -link specifies that	all subsequent addresses are
     specified as link-level addresses,	and the	names must be numeric specifi-
     cations rather than symbolic names.

     The optional -netmask qualifier is	intended to manually add subnet	routes
     with netmasks different from that of the implied network interface	(as
     would otherwise be	communicated using a routing protocol).	 One specifies
     an	additional ensuing address parameter (to be interpreted	as a network
     mask).  The implicit network mask generated in the	AF_INET	case can be
     overridden	by making sure this option follows the destination parameter.
     -prefixlen	is also	available for a	similar	purpose, for IPv6/v4.

     A specific	routing	priority can be	specified with the optional -priority
     qualifier.	 If no priority	is specified the kernel	will set a priority
     depending on the RTF_STATIC flag to either	RTP_STATIC or RTP_DEFAULT.
     Note that priority	1 is reserved for kernel use.

     The optional -mpath modifier needs	to be specified	with the add command
     to	be able	to enter multiple gateways for the same	destination address
     (multipath).  When	multiple routes	exist for a destination, one route is
     selected based on the source address of the packet.  The sysctl(8)	vari-
     ables net.inet.ip.multipath and net.inet6.ip6.multipath are used to con-
     trol multipath routing.  If set to	1, multiple routes with	the same pri-
     ority are used equally; if	set to 0, the first route selected will	be
     used for subsequent packets to that destination regardless	of source.

     When inserting MPLS routes, particular modifiers must be used.  The
     -mplslabel	modifier needs to be specified in an ingress LSR to associate
     a particular label	to an IPv4/IPv6	route.	The MPLS traffic -in and -out
     modifiers are intended to identify	the ingress label and, optionally, the
     outgoing one.  Additionally, one of the following operations must be
     used: -push, -pop and -swap.  Route's nexthop can be specified with the
     modifier -inet.

     Routes have associated flags which	influence operation of the protocols
     when sending to destinations matched by the routes.  These	flags may be
     set (or sometimes cleared)	by indicating the following corresponding mod-
     ifiers:

     -blackhole	   RTF_BLACKHOLE    silently discard pkts (during updates)
     -cloning	   RTF_CLONING	    generates a	new route on use
     -iface	   ~RTF_GATEWAY	    destination	is directly reachable
     -llinfo	   RTF_LLINFO	    validly translates proto addr to link addr
     -mpath	   RTF_MPATH	    multiple gateways for a destination	exist
     -nostatic	   ~RTF_STATIC	    pretend route added	by kernel or daemon
     -proto1	   RTF_PROTO1	    set	protocol specific routing flag #1
     -proto2	   RTF_PROTO2	    set	protocol specific routing flag #2
     -reject	   RTF_REJECT	    emit an ICMP unreachable when matched
     -static	   RTF_STATIC	    manually added route

     The optional modifiers -expire and	-mtu provide initial values to quanti-
     ties maintained in	the routing entry by transport level protocols,	such
     as	TCP (see tcp(4)).  They	have the following meanings:

     -expire n	  Lifetime for route (e.g., if generated by a redirect).
     -mtu n	  Maximum transmission unit (MTU) size for this	path.

     These may be individually locked by preceding each	such modifier to be
     locked by the -lock meta-modifier,	or one can specify that	all ensuing
     metrics may be locked by the -lockrest meta-modifier.

     In	a change or add	command	where the destination and gateway are not suf-
     ficient to	specify	the route, the -ifp or -ifa modifiers may be used to
     determine the interface name or interface address.

     The optional -label modifier specifies on route addition or modification
     that the route should have	the given label	associated with	it.  Route la-
     bels can be used to attach	arbitrary information to a route.

     All symbolic names	specified for a	destination or gateway are looked up
     using gethostbyname(3).

     route uses	a routing socket (see route(4))	and the	message	types RTM_ADD,
     RTM_DELETE, RTM_GET, and RTM_CHANGE.  As such, only the superuser may
     modify the	routing	tables.

FILES
     /etc/hosts	  host and network name	database
     /etc/mygate  default gateway address

EXAMPLES
     Add a static inet(4) route	to the 192.168.5.0/24 network via the
     192.168.0.1 gateway:

	   # route add -inet 192.168.5.0/24 192.168.0.1

     Amend the inet(4) route to	the 192.168.5.0/24 network to use the
     192.168.0.2 gateway:

	   # route change -inet	192.168.5.0/24 192.168.0.2

     Delete the	inet(4)	route to the 192.168.5.0/24 network:

	   # route delete -inet	192.168.5.0/24

DIAGNOSTICS
     %s: gateway %s flags %x  The specified route is being added to or deleted
     from the tables.  If the gateway address used was not the primary address
     of	the gateway (the first one returned by gethostbyname(3)), the gateway
     address is	printed	numerically as well as symbolically.

     %s	%s done	 When the flush	command	is specified, each routing table entry
     deleted is	indicated with a message of this form.

     Network is	unreachable  An	attempt	to add a route failed because the
     gateway listed was	not on a directly connected network.  The next-hop
     gateway must be given.

     not in table  A delete operation was attempted for	an entry which wasn't
     present in	the tables.

     routing table overflow  An	add operation was attempted, but the system
     was low on	resources and was unable to allocate memory to create the new
     entry.

SEE ALSO
     netstat(1), gethostbyname(3), netintro(4),	route(4), tcp(4), hosts(5),
     mygate(5),	bgpd(8), ospfd(8), ripd(8), sysctl(8)

HISTORY
     The route command appeared	in 4.2BSD.  IPv6 support was added by
     WIDE/KAME project.

     The -recvpipe, -hopcount, -sendpipe, -ssthres, -rtt, and -rttvar modi-
     fiers used	to be used to initialize various quantities in routing table
     entries.  The routing system no longer uses these values and the modi-
     fiers exist now only for compatibility with other operating systems.

BUGS
     Some uses of the -ifa or -ifp modifiers with the add command will incor-
     rectly fail with a	"Network is unreachable" message if there is no	de-
     fault route.  See case RTM_ADD in route_output() from sys/net/rtsock.c
     for details.

FreeBSD	13.0			January	2, 2021			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | FILES | EXAMPLES | DIAGNOSTICS | SEE ALSO | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=route&sektion=8&manpath=OpenBSD+6.9>

home | help