Begin documenting the soup sandwich that is the kernel routing code.

Much handholding jmc@

ok jmc@ sthen@ claudio@

2 files changed, 366 insertions, 3 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 489772acfd4..2721d564a58 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.168 2011/07/29 12:59:28 blambert Exp $
+#	$OpenBSD: Makefile,v 1.169 2011/12/08 20:58:49 blambert Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -21,8 +21,8 @@ MAN=	altq.9 aml_evalnode.9 atomic.9 audio.9 autoconf.9 bio_register.9 \
 	mountroothook_establish.9 mutex.9 namei.9 \
 	panic.9 pci_conf_read.9 pci_intr_map.9 pfind.9 physio.9 pmap.9 \
 	pool.9 powerhook_establish.9 ppsratecheck.9 printf.9 psignal.9 \
-	radio.9 arc4random.9 rasops.9 ratecheck.9 resettodr.9 rssadapt.9 rwlock.9 \
-	sensor_attach.9 \
+	radio.9 arc4random.9 rasops.9 ratecheck.9 resettodr.9 rssadapt.9 \
+	route.9 rwlock.9 sensor_attach.9 \
 	shutdownhook_establish.9 tsleep.9 spl.9 startuphook_establish.9 \
 	socreate.9 sosplice.9 style.9 syscall.9 systrace.9 sysctl_int.9 \
 	tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 vfs_busy.9 \
@@ -266,6 +266,18 @@ MLINKS+=rssadapt.9 ieee80211_rssadapt_choose.9 \
 	rssadapt.9 ieee80211_rssadapt_lower_rate.9 \
 	rssadapt.9 ieee80211_rssadapt_raise_rate.9 \
 	rssadapt.9 ieee80211_rssadapt_updatestats.9
+MLINKS+=route.9 rt_lookup.9 route.9 rtalloc.9 \
+	route.9 rtalloc_noclone.9 route.9 rtalloc1.9 \
+	route.9 rtfree.9 route.9 rtrequest1.9 \
+	route.9 rt_setgate.9 route.9 rtredirect.9 \
+	route.9 rtdeletemsg.9 route.9 rtable_exists.9 \
+	route.9 rtable_add.9 route.9 rtable_l2.9 \
+	route.9 rtable_l2set.9 route.9 rt_gettable.9 \
+	route.9 rt_timer_queue_create.9 route.9 rt_timer_add.9 \
+	route.9 rt_timer_queue_change.9 route.9 rt_timer_queue_destroy.9 \
+	route.9 rt_timer_count.9 route.9 rt_timer_remove_all.9 \
+	route.9 rtlabel_name2id.9 route.9 rtlabel_id2name.9 \
+	route.9 rtlabel_id2sa.9 route.9 rtlabel_unref.9
 MLINKS+=rwlock.9 rw_init.9 rwlock.9 rw_enter.9 rwlock.9 rw_exit.9 \
 	rwlock.9 rw_enter_read.9 rwlock.9 rw_enter_write.9 \
 	rwlock.9 rw_exit_read.9 rwlock.9 rw_exit_write.9 \
diff --git a/share/man/man9/route.9 b/share/man/man9/route.9
new file mode 100644
index 00000000000..01b42bfb40f
--- /dev/null
+++ b/share/man/man9/route.9
@@ -0,0 +1,351 @@
+.\"     $OpenBSD: route.9,v 1.1 2011/12/08 20:58:49 blambert 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: December 8 2011 $
+.Dt ROUTE 9
+.Os
+.Sh NAME
+.Nm route
+.Nd kernel routing interface
+.Sh SYNOPSIS
+.Fd #include <net/route.h>
+.Ft struct radix_node *
+.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_GENMASK	3	/* cloning mask 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 (as a radix_node) 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 timout 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 .
+.Bl -tag -width Ds
+.It Fn rtlabel_name2id "char *name"
+Return numerical ID of routing 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 routing 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 routing 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 conficts 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 routing 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.