diff options
Diffstat (limited to 'share/man/man9')
| -rw-r--r-- | share/man/man9/Makefile | 18 | ||||
| -rw-r--r-- | share/man/man9/route.9 | 351 |
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. |