.\"     $OpenBSD: route.9,v 1.8 2014/01/22 06:25:52 claudio Exp $
.\"
.\" Copyright (c) 2011 Bret S. Lambert <blambert@openbsd.org>
.\" All rights reserved.
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: January 22 2014 $
.Dt ROUTE 9
.Os
.Sh NAME
.Nm route
.Nd kernel routing interface
.Sh SYNOPSIS
.In net/route.h
.Ft struct rtentry *
.Fn rt_lookup "struct sockaddr *dst" "struct sockaddr *mask" "u_int tableid"
.Ft void
.Fn rtalloc "struct route *ro"
.Ft void
.Fn rtalloc_noclone "struct route *ro"
.Ft struct rtentry *
.Fn rtalloc1 "struct sockaddr *dst" "int flags" "u_int tableid"
.Ft void
.Fn rtfree "struct rtentry *rt"
.Fn RTFREE "struct rtentry *rt"
.Ft int
.Fn rtrequest1 "int req" "struct rt_addrinfo *info" "u_int8_t prio" \
"struct rtentry **ret_nrt" "u_int tableid"
.Ft int
.Fn rt_setgate "struct rtentry *rt0" "struct sockaddr *dst" \
"struct sockaddr *gate" "u_int tableid"
.Ft void
.Fn rtredirect "struct sockaddr *dst" "struct sockaddr *gateway" \
"struct sockaddr *netmask" "int flags" "struct sockaddr *src" \
"struct rtentry **rtp" "u_int rdomain"
.Ft int
.Fn rtdeletemsg "struct rtentry *rt" "u_int tableid"
.Ft int
.Fn rtable_exists "u_int id"
.Ft int
.Fn rtable_add "u_int id"
.Ft u_int
.Fn rtable_l2 "u_int id"
.Ft void
.Fn rtable_l2set "u_int id" "u_int parent"
.Ft struct radix_node_head *
.Fn rt_gettable "sa_family_t af" "u_int id"
.Ft struct rttimer_queue *
.Fn rt_timer_queue_create "u_int timeout"
.Ft int
.Fn rt_timer_add "struct rtentry *rt" \
"void (*func)(struct rtentry *, struct rttimer *)" \
"struct rttimer_queue *queue" "u_int rtableid"
.Ft void
.Fn rt_timer_queue_change "struct rttimer_queue *rtq" "long timeout"
.Ft void
.Fn rt_timer_queue_destroy "struct rttimer_queue *rtq" "int destroy"
.Ft unsigned long
.Fn rt_timer_count "struct rttimer_queue *rtq"
.Ft void
.Fn rt_timer_remove_all "struct rtentry *rt"
.Ft u_int16_t
.Fn rtlabel_name2id "char *name"
.Ft const char *
.Fn rtlabel_id2name "u_int16_t id"
.Ft struct sockaddr *
.Fn rtlabel_id2sa "u_int16_t labelid" "struct sockaddr_rtlabel *sa_rl"
.Ft void
.Fn rtlabel_unref "u_int16_t id"
.Bd -literal
struct rt_addrinfo {
	int	rti_addrs;
	struct	sockaddr *rti_info[RTAX_MAX];
	int	rti_flags;
	struct	ifaddr *rti_ifa;
	struct	ifnet *rti_ifp;
	struct	rt_msghdr *rti_rtm;
	u_char	rti_mpls;
};

#define RTAX_DST	0	/* destination sockaddr present */
#define RTAX_GATEWAY	1	/* gateway sockaddr present */
#define RTAX_NETMASK	2	/* netmask sockaddr present */
#define RTAX_IFP	4	/* interface name sockaddr present */
#define RTAX_IFA	5	/* interface addr sockaddr present */
#define RTAX_AUTHOR	6	/* sockaddr for author of redirect */
#define RTAX_BRD	7	/* for NEWADDR, broadcast or p-p dest */
#define RTAX_SRC	8	/* source sockaddr present */
#define RTAX_SRCMASK	9	/* source netmask present */
#define RTAX_LABEL	10	/* route label present */
#define RTAX_MAX	11	/* size of array to allocate */
.Ed
.Sh DESCRIPTION
.Ss Route Entries
Routing entries describe the routes to be taken by packets in a router.
.Bl -tag -width Ds
.It Fn rt_lookup "struct sockaddr *dst" "struct sockaddr *mask" "u_int tableid"
Return pointer to routing entry corresponding to address
.Fa dst
with a mask of
.Fa mask
from table
.Fa tableid .
.It Fn rtrequest1 "int req" "struct rt_addrinfo *info" "u_int8_t prio" \
"struct rtentry **ret_nrt" "u_int tableid"
Perform the action specified in
.Fa req
on table
.Fa tableid .
.Fa req
can be any of the following:
.Bl -tag -width "RTM_RESOLVEXXX" -offset indent
.It RTM_ADD
.\" XXX Describe adding an entry.
.It RTM_RESOLVE
.\" XXX Describe resolving an entry.
.It RTM_DELETE
.\" XXX Describe deleting an entry.
.El
.Pp
If
.Fa ret_nrt
is non-NULL, a pointer to the routing entry which satisfied the request is
placed there.
If
.Fa prio
is 0, a default priority based on the egress interface is used.
.It Fn rt_setgate "struct rtentry *rt0" "struct sockaddr *dst" \
"struct sockaddr *gate" "u_int tableid"
Set the address of the gateway for routes described by
.Fa rt0
to
.Fa gateway .
If memory must be allocated to hold the gateway address,
the address for which
.Fa rt0
describes routes will be copied from
.Fa dst .
.It Fn rtredirect "struct sockaddr *dst" "struct sockaddr *gateway" \
"struct sockaddr *netmask" "int flags" "struct sockaddr *src" \
"struct rtentry **rtp" "u_int rdomain"
Redirect routes to
.Fa dst
through
.Fa gateway ,
such as in response to an ICMP redirect message.
.Fa src
should be the address from which the redirect message was received.
If
.Fa rtp
is not NULL,
it will be populated by the routing entry corresponding to
.Fa dst .
.It Fn rtdeletemsg "struct rtentry *rt" "u_int tableid"
Delete routing table entry
.Fa rt
from table
.Fa tableid
and forward a notification message to all
.Fa AF_ROUTE
sockets.
.It Fn rtfree "struct rtentry *rt"
Release a reference to
.Fa rt ,
freeing it if the reference count drops to 0.
.It Fn RTFREE
A macro which calls
.Fn rtfree .
.El
.Ss Routing Tables and Domains
Routing tables contain layer 2 and 3 forwarding information.
Each address family in use will have its own routing table.
Routing domains are a way of logically segmenting a router among multiple
networks and may contain more than one routing table.
.Bl -tag -width Ds
.It Fn rtable_exists "u_int id"
Return
.Fa 1
if table with ID
.Fa id
exists,
.Fa 0
otherwise.
.It Fn rtable_add "u_int id"
Add table with ID of
.Fa id
to routing domain
.Fa 0 .
.It Fn rtable_l2 "u_int id"
Get the routing domain of table with ID of
.Fa id .
.It Fn rtable_l2set "u_int id" "u_int parent"
Place table with ID of
.Fa id
under the routing domain with ID of
.Fa parent .
.El
.Ss Route Timer Queues
Route timer queues provide a method of queueing routing-related actions to be
triggered once per second.
.Bl -tag -width Ds
.It Fn rt_timer_queue_create "u_int timeout"
Create a timer queue with a timeout of
.Fa timeout
seconds.
.It Fn rt_timer_add "struct rtentry *rt" \
"void (*func)(struct rtentry *, struct rttimer *)" \
"struct rttimer_queue *queue" "u_int rtableid"
Schedule
.Fa func
to be called on
.Fa rt
using the timeout of
.Fa queue .
If
.Fa rt
already has a call to
.Fa func
scheduled on any timer queue, it will be replaced with the new invocation.
.It Fn rt_timer_queue_change "struct rttimer_queue *rtq" "long timeout"
Set timeout for
.Fa rtq
to
.Fa timeout
seconds.
.It Fn rt_timer_remove_all "struct rtentry *rt"
Remove all timeouts associated with
.Fa rt
from all routing timer queues.
.El
.Ss Route Labels
Route labels are arbitrary data appended to routes and can be acted upon by
.Xr pf 4 .
.Bl -tag -width Ds
.It Fn rtlabel_name2id "char *name"
Return numerical ID of the route label named
.Fa name ,
creating the label if it does not already exist.
.It Fn rtlabel_id2name "u_int16_t id"
Return the string name of the route label with ID
.Fa id .
.It Fn rtlabel_id2sa "u_int16_t labelid" "struct sockaddr_rtlabel *sa_rl"
Populate
.Fa sa_rl
with the data from the route label specified by
.Fa labelid .
.It Fn rtlabel_unref "u_int16_t id"
Remove a reference to the route label with ID
.Fa id ,
freeing the label if the reference count drops to 0.
.El
.Sh RETURN VALUES
.Fn rtrequest1
may fail with:
.Pp
.Bl -tag -width Er -compact
.It Bq Er EAFNOSUPPORT
The protocol used by
.Fa info
is not supported in table with ID of
.Fa tableid .
.It Bq Er ESEARCH
No routing entry corresponding to
.Fa info
could be found.
.It Bq Er ESEARCH
Multipath route with no gateway provided in
.Fa info .
.It Bq Er ESEARCH
The routing entry could not be found in the routing table.
.It Bq Er EINVAL
.Fa req
specified
.Fa RTM_RESOLVE
with a
.Fa ret_nrt
argument which does not point to a cloneable routing entry.
.It Bq Er EEXIST
Multipath route conflicts with existing multipath route.
.It Bq Er EEXIST
The route could not be entered into the routing table.
.It Bq Er ENOMEM
Space for MPLS protocol data could not be allocated.
.It Bq Er ENOBUFS
Space for a new routing entry could not be allocated.
.It Bq Er ENETUNREACH
An interface address corresponding to the route described by
.Fa info
could not be found.
.El
.Pp
.Fn rt_setgate
returns non-0 if it cannot allocate memory.
.Pp
.Fn rtdeletemsg
may fail with:
.Pp
.Bl -tag -width Er -compact
.It Bq Er EAFNOSUPPORT
The protocol used by
.Fa rt
is not supported by table with ID
.Fa tableid .
.It Bq Er ESRCH
No routing entry for
.Fa rt
could be found.
.It Bq Er ESRCH
.Fa rt
is a multipath route that conflicts with existing multipath route.
.El
.Pp
.Fn rtable_add
may fail with:
.Pp
.Bl -tag -width Er -compact
.It Bq Er EEXIST
A table with ID of
.Fa id
already exists.
.It Bq Er ENOMEM
Memory could not be allocated to extend the list of routing domains.
.El
.Pp
.Fn rt_timer_add
may fail with
.Er ENOBUFS
if memory could not be allocated for the timeout.
.Pp
.Fn rtlabel_name2id
returns
.Fa 0
if it was unable to create a route label.
.Sh SEE ALSO
.Xr route 4 ,
.Xr route 8
.Sh BUGS
The current route entry reference counting code, while not incorrect, is also
likely not correct either.