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

FreeBSD Manual Pages


home | help
ROUTE(4)	       FreeBSD Kernel Interfaces Manual		      ROUTE(4)

     route -- kernel packet forwarding database

     #include <sys/socket.h>
     #include <net/if.h>
     #include <net/route.h>

     socket(AF_ROUTE, SOCK_RAW,	family);

     OpenBSD provides some packet routing facilities.  The kernel maintains a
     routing information database, which is used in selecting the appropriate
     network interface when transmitting packets.

     A user process (or	possibly multiple co-operating processes) maintains
     this database by sending messages over a special kind of socket.  This
     supplants fixed size ioctl(2)'s used in earlier releases.	Routing	table
     changes may only be carried out by	the super user.

     The operating system may spontaneously emit routing messages in response
     to	external events, such as receipt of a redirect,	or failure to locate a
     suitable route for	a request.  The	message	types are described in greater
     detail below.

     Routing database entries come in two flavors: for a specific host,	or for
     all hosts on a generic subnetwork (as specified by	a bit mask and value
     under the mask).  The effect of wildcard or default route may be achieved
     by	using a	mask of	all zeros, and there may be hierarchical routes.

     When the system is	booted and addresses are assigned to the network in-
     terfaces, each protocol family installs a routing table entry for each
     interface when it is ready	for traffic.  Normally the protocol specifies
     the route through each interface as a "direct" connection to the destina-
     tion host or network.  If the route is direct, the	transport layer	of a
     protocol family usually requests the packet be sent to the	same host
     specified in the packet.  Otherwise, the interface	is requested to	ad-
     dress the packet to the gateway listed in the routing entry (i.e.,	the
     packet is forwarded).

     When routing a packet, the	kernel will attempt to find the	most specific
     route matching the	destination.  (If there	are two	different mask and
     value-under-the-mask pairs	that match, the	more specific is the one with
     more bits in the mask.  A route to	a host is regarded as being supplied
     with a mask of as many ones as there are bits in the destination.)	 If no
     entry is found, the destination is	declared to be unreachable, and	a
     routing-miss message is generated if there	are any	listeners on the rout-
     ing control socket	described below.

     If	there are two identical	destinations, the route	priority acts as a
     tie-breaker.  If there are	multiple routes	to the same destination, the
     one with the lowest priority wins.	 The kernel assigns certain default
     priorities	based on the type of route, as given in	the table below.  For
     connected and static routes, this default priority	is added to the	inter-
     face's priority.

     A wildcard	routing	entry is specified with	a zero destination address
     value and a mask of all zeroes.  Wildcard routes will be used when	the
     system fails to find other	routes matching	the destination.  The combina-
     tion of wildcard routes and routing redirects can provide an economical
     mechanism for routing traffic.  Routes created by redirects from wildcard
     routes and	other routes will be marked cloned, until their	"parent" from
     which they	were created has disappeared.

     Route labels can be attached to routes and	may contain arbitrary informa-
     tion about	the route.  Labels are sent over the routing socket (see be-
     low) as sockaddr_rtlabel structures.

   The Routing Socket
     One opens the channel for passing routing control messages	by using the
     socket(2) call shown in the SYNOPSIS above.

     The family	parameter may be AF_UNSPEC, which will provide routing infor-
     mation for	all address families, or can be	restricted to a	specific ad-
     dress family by specifying	which one is desired.  There can be more than
     one routing socket	open per system.

     Messages are formed by a header followed by a small number	of sockaddr
     structures	(which are variable length), interpreted by position, and de-
     limited by	the length entry in the	sockaddr.  An example of a message
     with four addresses might be an IPv4 route	addition: the destination,
     netmask, gateway, and label, since	both netmasks and labels are sent over
     the routing socket	as sockaddr structures.	 The interpretation of which
     addresses are present is given by a bit mask within the header, and the
     sequence is least significant to most significant bit within the vector.

     Any messages sent to the kernel are returned, and copies are sent to all
     interested	listeners.  The	kernel will provide the	process	ID of the
     sender, and the sender may	use an additional sequence field to distin-
     guish between outstanding messages.  However, message replies may be lost
     when kernel buffers are exhausted.

     The kernel	may reject certain messages, and will indicate this by filling
     in	the rtm_errno field.  The routing code returns EEXIST if requested to
     duplicate an existing entry, ESRCH	if requested to	delete a non-existent
     entry, or ENOBUFS if insufficient resources were available	to install a
     new route.	 In the	current	implementation,	all routing processes run lo-
     cally, and	the values for rtm_errno are available through the normal
     errno mechanism, even if the routing reply	message	is lost.

     A process may avoid the expense of	reading	replies	to its own messages by
     issuing a setsockopt(2) call indicating that the SO_USELOOPBACK option at
     the SOL_SOCKET level is to	be turned off.	A process may ignore all mes-
     sages from	the routing socket by doing a shutdown(2) system call for fur-
     ther input.

     There are three filter options that can be	used to	restrict the received
     route messages to a subset	of all the route messages processed by the


     A process can specify an alternate	routing	table by using the
     ROUTE_TABLEFILTER setsockopt(2).  A value of RTABLE_ANY specifies all
     routing tables.  For example, to receive messages for routing table 5:

	   unsigned int	rdomain	= 5;

	   if (setsockopt(routefd, AF_ROUTE, ROUTE_TABLEFILTER,
	       &rdomain, sizeof(rdomain)) == -1)
		   err(1, "setsockopt(ROUTE_TABLEFILTER)");

     A process can specify which route message types it's interested in	by us-
     ing ROUTE_FILTER(int type)	and issuing a setsockopt call with the
     ROUTE_MSGFILTER option at the AF_ROUTE level.  For	example, to only get
     interface specific	messages:

	   unsigned int	rtfilter;

	   rtfilter = ROUTE_FILTER(RTM_IFINFO) |

	   if (setsockopt(routefd, AF_ROUTE, ROUTE_MSGFILTER,
	       &rtfilter, sizeof(rtfilter)) == -1)
		   err(1, "setsockopt(ROUTE_MSGFILTER)");

     Similarly,	a process can specify that it is only interested in messages
     relating to routes	where the priority is no more than a certain value by
     issuing a setsockopt call with the	ROUTE_PRIOFILTER option.  For example,
     to	select only local, directly connected and static routes:

	   unsigned int	maxprio	= RTP_STATIC;

	   if (setsockopt(routefd, AF_ROUTE, ROUTE_PRIOFILTER,
	       &maxprio, sizeof(maxprio)) == -1)
		   err(1, "setsockopt(ROUTE_PRIOFILTER)");

     The ROUTE_FLAGFILTER socket option	can be used to exclude a subset	of
     rtm_flags flags from the received route messages:

	   int rtfilter	= RTF_LLINFO | RTF_BROADCAST;

	   if (setsockopt(routefd, AF_ROUTE, ROUTE_FLAGFILTER, &rtfilter,
	       sizeof(rtfilter)) == -1)
		   err(1, "setsockopt(ROUTE_FLAGFILTER)");

     The predefined constants for the routing priorities are:

     #define RTP_NONE	     0	     /*	unset priority use sane	default	*/
     #define RTP_LOCAL	     1	     /*	local address routes (must be the highest) */
     #define RTP_CONNECTED   4	     /*	directly connected routes */
     #define RTP_STATIC	     8	     /*	static routes base priority */
     #define RTP_EIGRP	     28	     /*	EIGRP routes */
     #define RTP_OSPF	     32	     /*	OSPF routes */
     #define RTP_ISIS	     36	     /*	IS-IS routes */
     #define RTP_RIP	     40	     /*	RIP routes */
     #define RTP_BGP	     48	     /*	BGP routes */
     #define RTP_DEFAULT     56	     /*	routes that have nothing set */
     #define RTP_PROPOSAL_STATIC     57
     #define RTP_PROPOSAL_DHCLIENT   58
     #define RTP_PROPOSAL_SLAAC	     59
     #define RTP_PROPOSAL_UMB	     60
     #define RTP_PROPOSAL_SOLICIT    61	     /*	request	reply of all RTM_PROPOSAL */
     #define RTP_MAX	     63	     /*	maximum	priority */
     #define RTP_ANY	     64	     /*	any of the above */
     #define RTP_MASK	     0x7f
     #define RTP_DOWN	     0x80    /*	route/link is down */

     If	a route	is in use when it is deleted, the routing entry	will be	marked
     down and removed from the routing table, but the resources	associated
     with it will not be reclaimed until all references	to it are released.
     User processes can	obtain information about the routing entry to a	spe-
     cific destination by using	a RTM_GET message or via the PF_ROUTE

     Messages include:

     #define RTM_ADD	     0x1     /*	Add Route */
     #define RTM_DELETE	     0x2     /*	Delete Route */
     #define RTM_CHANGE	     0x3     /*	Change Metrics or flags	*/
     #define RTM_GET	     0x4     /*	Report Metrics */
     #define RTM_LOSING	     0x5     /*	Kernel Suspects	Partitioning */
     #define RTM_REDIRECT    0x6     /*	Told to	use different route */
     #define RTM_MISS	     0x7     /*	Lookup failed on this address */
     #define RTM_RESOLVE     0xb     /*	req to resolve dst to LL addr */
     #define RTM_NEWADDR     0xc     /*	address	being added to iface */
     #define RTM_DELADDR     0xd     /*	address	being removed from iface */
     #define RTM_IFINFO	     0xe     /*	iface going up/down etc. */
     #define RTM_IFANNOUNCE  0xf     /*	iface arrival/departure	*/
     #define RTM_DESYNC	     0x10    /*	route socket buffer overflow */
     #define RTM_INVALIDATE  0x11    /*	Invalidate cache of L2 route */

     A message header consists of one of the following:

     struct rt_msghdr {
	     u_short rtm_msglen;     /*	to skip	over non-understood messages */
	     u_char  rtm_version;    /*	future binary compatibility */
	     u_char  rtm_type;	     /*	message	type */
	     u_short rtm_hdrlen;     /*	sizeof(rt_msghdr) to skip over the header */
	     u_short rtm_index;	     /*	index for associated ifp */
	     u_short rtm_tableid;    /*	routing	table id */
	     u_char  rtm_priority;   /*	routing	priority */
	     u_char  rtm_mpls;	     /*	MPLS additional	infos */
	     int     rtm_addrs;	     /*	bitmask	identifying sockaddrs in msg */
	     int     rtm_flags;	     /*	flags, incl. kern & message, e.g. DONE */
	     int     rtm_fmask;	     /*	bitmask	used in	RTM_CHANGE message */
	     pid_t   rtm_pid;	     /*	identify sender	*/
	     int     rtm_seq;	     /*	for sender to identify action */
	     int     rtm_errno;	     /*	why failed */
	     u_int   rtm_inits;	     /*	which metrics we are initializing */
	     struct  rt_metrics	rtm_rmx; /* metrics themselves */

     struct if_msghdr {
	     u_short ifm_msglen;     /*	to skip	over non-understood messages */
	     u_char  ifm_version;    /*	future binary compatibility */
	     u_char  ifm_type;	     /*	message	type */
	     u_short ifm_hdrlen;     /*	sizeof(if_msghdr) to skip over the header */
	     u_short ifm_index;	     /*	index for associated ifp */
	     u_short ifm_tableid;    /*	routing	table id */
	     u_char  ifm_pad1;
	     u_char  ifm_pad2;
	     int     ifm_addrs;	     /*	like rtm_addrs */
	     int     ifm_flags;	     /*	value of if_flags */
	     int     ifm_xflags;
	     struct  if_data ifm_data;/* statistics and	other data about if */

     struct ifa_msghdr {
	     u_short ifam_msglen;    /*	to skip	over non-understood messages */
	     u_char  ifam_version;   /*	future binary compatibility */
	     u_char  ifam_type;	     /*	message	type */
	     u_short ifam_hdrlen;    /*	sizeof(ifa_msghdr) to skip over	the header */
	     u_short ifam_index;     /*	index for associated ifp */
	     u_short ifam_tableid;   /*	routing	table id */
	     u_char  ifam_pad1;
	     u_char  ifam_pad2;
	     int     ifam_addrs;     /*	like rtm_addrs */
	     int     ifam_flags;     /*	value of ifa_flags */
	     int     ifam_metric;    /*	value of ifa_metric */

     struct if_announcemsghdr {
	     u_short ifan_msglen;    /*	to skip	over non-understood messages */
	     u_char  ifan_version;   /*	future binary compatibility */
	     u_char  ifan_type;	     /*	message	type */
	     u_short ifan_hdrlen;    /*	sizeof(ifa_msghdr) to skip over	the header */
	     u_short ifan_index;     /*	index for associated ifp */
	     u_short ifan_what;	     /*	what type of announcement */
	     char    ifan_name[IFNAMSIZ];    /*	if name, e.g. "en0" */

     The RTM_IFINFO message uses an if_msghdr header, the RTM_NEWADDR and
     RTM_DELADDR messages use an ifa_msghdr header, the	RTM_IFANNOUNCE message
     uses an if_announcemsghdr header, RTM_INVALIDATE is used only internally
     in	the kernel and should never appear in a	route message, and all other
     messages use the rt_msghdr	header.

     The metrics structure is:

     struct rt_metrics {
	     u_int64_t	     rmx_pksent;     /*	packets	sent using this	route */
	     int64_t	     rmx_expire;     /*	lifetime for route, e.g. redirect */
	     u_int	     rmx_locks;	     /*	Kernel must leave these	values */
	     u_int	     rmx_mtu;	     /*	MTU for	this path */
	     u_int	     rmx_refcnt;     /*	# references hold */
	     u_int	     rmx_hopcount;   /*	max hops expected */
	     u_int	     rmx_recvpipe;   /*	inbound	delay-bandwidth	product	*/
	     u_int	     rmx_sendpipe;   /*	outbound delay-bandwidth product */
	     u_int	     rmx_ssthresh;   /*	outbound gateway buffer	limit */
	     u_int	     rmx_rtt;	     /*	estimated round	trip time */
	     u_int	     rmx_rttvar;     /*	estimated rtt variance */
	     u_int	     rmx_pad;

     Only rmx_mtu, rmx_expire, rmx_pksent, and rmx_locks are used by the ker-
     nel routing table.	 All other values will be ignored when inserting them
     into the kernel and are set to zero in routing messages sent by the ker-
     nel.  They	are left for compatibility reasons with	other systems.

     Flags include the values:

     #define RTF_UP	   0x1	     /*	route usable */
     #define RTF_GATEWAY   0x2	     /*	destination is a gateway */
     #define RTF_HOST	   0x4	     /*	host entry (net	otherwise) */
     #define RTF_REJECT	   0x8	     /*	host or	net unreachable	*/
     #define RTF_DYNAMIC   0x10	     /*	created	dynamically (by	redirect) */
     #define RTF_MODIFIED  0x20	     /*	modified dynamically (by redirect) */
     #define RTF_DONE	   0x40	     /*	message	confirmed */
     #define RTF_CLONING   0x100     /*	generate new routes on use */
     #define RTF_MULTICAST 0x200     /*	route associated to a mcast addr.  */
     #define RTF_LLINFO	   0x400     /*	generated by ARP or NDP	*/
     #define RTF_STATIC	   0x800     /*	manually added */
     #define RTF_BLACKHOLE 0x1000    /*	just discard pkts (during updates) */
     #define RTF_PROTO3	   0x2000    /*	protocol specific routing flag */
     #define RTF_PROTO2	   0x4000    /*	protocol specific routing flag */
     #define RTF_PROTO1	   0x8000    /*	protocol specific routing flag */
     #define RTF_CLONED	   0x10000   /*	this is	a cloned route */
     #define RTF_MPATH	   0x40000   /*	multipath route	or operation */
     #define RTF_MPLS	   0x100000  /*	MPLS additional	infos */
     #define RTF_LOCAL	   0x200000  /*	route to a local address */
     #define RTF_BROADCAST 0x400000  /*	route associated to a bcast addr. */
     #define RTF_CONNECTED 0x800000  /*	interface route	*/

     The following flags (defined as RTF_FMASK)	can be changed by an

     Specifiers	for metric values in rmx_locks and rtm_inits are:

     #define RTV_MTU	     0x1     /*	init or	lock _mtu */
     #define RTV_HOPCOUNT    0x2     /*	init or	lock _hopcount */
     #define RTV_EXPIRE	     0x4     /*	init or	lock _expire */
     #define RTV_RPIPE	     0x8     /*	init or	lock _recvpipe */
     #define RTV_SPIPE	     0x10    /*	init or	lock _sendpipe */
     #define RTV_SSTHRESH    0x20    /*	init or	lock _ssthresh */
     #define RTV_RTT	     0x40    /*	init or	lock _rtt */
     #define RTV_RTTVAR	     0x80    /*	init or	lock _rttvar */

     Only RTV_MTU and RTV_EXPIRE should	be used; all other flags are ignored.

     Specifiers	for which addresses are	present	in the messages	are:

     #define RTA_DST	     0x1     /*	destination sockaddr present */
     #define RTA_GATEWAY     0x2     /*	gateway	sockaddr present */
     #define RTA_NETMASK     0x4     /*	netmask	sockaddr present */
     #define RTA_IFP	     0x10    /*	interface name sockaddr	present	*/
     #define RTA_IFA	     0x20    /*	interface addr sockaddr	present	*/
     #define RTA_AUTHOR	     0x40    /*	sockaddr for author of redirect	*/
     #define RTA_BRD	     0x80    /*	for NEWADDR, bcast or p-p dest addr */
     #define RTA_SRC	     0x100   /*	source sockaddr	present	*/
     #define RTA_SRCMASK     0x200   /*	source netmask present */
     #define RTA_LABEL	     0x400   /*	route label present */

     netstat(1), socket(2), sysctl(2), rtable(4), mygate(5), route(8),

     A PF_ROUTE	protocol family	first appeared in 4.3BSD-Reno.

FreeBSD	13.0			August 21, 2020			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help