1.\" $OpenBSD: route.9,v 1.4 2011/12/12 14:59:38 blambert Exp $ 2.\" 3.\" Copyright (c) 2011 Bret S. Lambert <blambert@openbsd.org> 4.\" All rights reserved. 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: December 12 2011 $ 19.Dt ROUTE 9 20.Os 21.Sh NAME 22.Nm route 23.Nd kernel routing interface 24.Sh SYNOPSIS 25.Fd #include <net/route.h> 26.Ft struct radix_node * 27.Fn rt_lookup "struct sockaddr *dst" "struct sockaddr *mask" "u_int tableid" 28.Ft void 29.Fn rtalloc "struct route *ro" 30.Ft void 31.Fn rtalloc_noclone "struct route *ro" 32.Ft struct rtentry * 33.Fn rtalloc1 "struct sockaddr *dst" "int flags" "u_int tableid" 34.Ft void 35.Fn rtfree "struct rtentry *rt" 36.Fn RTFREE "struct rtentry *rt" 37.Ft int 38.Fn rtrequest1 "int req" "struct rt_addrinfo *info" "u_int8_t prio" \ 39"struct rtentry **ret_nrt" "u_int tableid" 40.Ft int 41.Fn rt_setgate "struct rtentry *rt0" "struct sockaddr *dst" \ 42"struct sockaddr *gate" "u_int tableid" 43.Ft void 44.Fn rtredirect "struct sockaddr *dst" "struct sockaddr *gateway" \ 45"struct sockaddr *netmask" "int flags" "struct sockaddr *src" \ 46"struct rtentry **rtp" "u_int rdomain" 47.Ft int 48.Fn rtdeletemsg "struct rtentry *rt" "u_int tableid" 49.Ft int 50.Fn rtable_exists "u_int id" 51.Ft int 52.Fn rtable_add "u_int id" 53.Ft u_int 54.Fn rtable_l2 "u_int id" 55.Ft void 56.Fn rtable_l2set "u_int id" "u_int parent" 57.Ft struct radix_node_head * 58.Fn rt_gettable "sa_family_t af" "u_int id" 59.Ft struct rttimer_queue * 60.Fn rt_timer_queue_create "u_int timeout" 61.Ft int 62.Fn rt_timer_add "struct rtentry *rt" \ 63"void (*func)(struct rtentry *, struct rttimer *)" \ 64"struct rttimer_queue *queue" "u_int rtableid" 65.Ft void 66.Fn rt_timer_queue_change "struct rttimer_queue *rtq" "long timeout" 67.Ft void 68.Fn rt_timer_queue_destroy "struct rttimer_queue *rtq" "int destroy" 69.Ft unsigned long 70.Fn rt_timer_count "struct rttimer_queue *rtq" 71.Ft void 72.Fn rt_timer_remove_all "struct rtentry *rt" 73.Ft u_int16_t 74.Fn rtlabel_name2id "char *name" 75.Ft const char * 76.Fn rtlabel_id2name "u_int16_t id" 77.Ft struct sockaddr * 78.Fn rtlabel_id2sa "u_int16_t labelid" "struct sockaddr_rtlabel *sa_rl" 79.Ft void 80.Fn rtlabel_unref "u_int16_t id" 81.Bd -literal 82struct rt_addrinfo { 83 int rti_addrs; 84 struct sockaddr *rti_info[RTAX_MAX]; 85 int rti_flags; 86 struct ifaddr *rti_ifa; 87 struct ifnet *rti_ifp; 88 struct rt_msghdr *rti_rtm; 89 u_char rti_mpls; 90}; 91 92#define RTAX_DST 0 /* destination sockaddr present */ 93#define RTAX_GATEWAY 1 /* gateway sockaddr present */ 94#define RTAX_NETMASK 2 /* netmask sockaddr present */ 95#define RTAX_GENMASK 3 /* cloning mask sockaddr present */ 96#define RTAX_IFP 4 /* interface name sockaddr present */ 97#define RTAX_IFA 5 /* interface addr sockaddr present */ 98#define RTAX_AUTHOR 6 /* sockaddr for author of redirect */ 99#define RTAX_BRD 7 /* for NEWADDR, broadcast or p-p dest */ 100#define RTAX_SRC 8 /* source sockaddr present */ 101#define RTAX_SRCMASK 9 /* source netmask present */ 102#define RTAX_LABEL 10 /* route label present */ 103#define RTAX_MAX 11 /* size of array to allocate */ 104.Ed 105.Sh DESCRIPTION 106.Ss Route Entries 107Routing entries describe the routes to be taken by packets in a router. 108.Bl -tag -width Ds 109.It Fn rt_lookup "struct sockaddr *dst" "struct sockaddr *mask" "u_int tableid" 110Return pointer to routing entry (as a radix_node) corresponding to address 111.Fa dst 112with a mask of 113.Fa mask 114from table 115.Fa tableid . 116.It Fn rtrequest1 "int req" "struct rt_addrinfo *info" "u_int8_t prio" \ 117"struct rtentry **ret_nrt" "u_int tableid" 118Perform the action specified in 119.Fa req 120on table 121.Fa tableid . 122.Fa req 123can be any of the following: 124.Bl -tag -width "RTM_RESOLVEXXX" -offset indent 125.It RTM_ADD 126.\" XXX Describe adding an entry. 127.It RTM_RESOLVE 128.\" XXX Describe resolving an entry. 129.It RTM_DELETE 130.\" XXX Describe deleting an entry. 131.El 132.Pp 133If 134.Fa ret_nrt 135is non-NULL, a pointer to the routing entry which satisfied the request is 136placed there. 137If 138.Fa prio 139is 0, a default priority based on the egress interface is used. 140.It Fn rt_setgate "struct rtentry *rt0" "struct sockaddr *dst" \ 141"struct sockaddr *gate" "u_int tableid" 142Set the address of the gateway for routes described by 143.Fa rt0 144to 145.Fa gateway . 146If memory must be allocated to hold the gateway address, 147the address for which 148.Fa rt0 149describes routes will be copied from 150.Fa dst . 151.It Fn rtredirect "struct sockaddr *dst" "struct sockaddr *gateway" \ 152"struct sockaddr *netmask" "int flags" "struct sockaddr *src" \ 153"struct rtentry **rtp" "u_int rdomain" 154Redirect routes to 155.Fa dst 156through 157.Fa gateway , 158such as in response to an ICMP redirect message. 159.Fa src 160should be the address from which the redirect message was received. 161If 162.Fa rtp 163is not NULL, 164it will be populated by the routing entry corresponding to 165.Fa dst . 166.It Fn rtdeletemsg "struct rtentry *rt" "u_int tableid" 167Delete routing table entry 168.Fa rt 169from table 170.Fa tableid 171and forward a notification message to all 172.Fa AF_ROUTE 173sockets. 174.It Fn rtfree "struct rtentry *rt" 175Release a reference to 176.Fa rt , 177freeing it if the reference count drops to 0. 178.It Fn RTFREE 179A macro which calls 180.Fn rtfree . 181.El 182.Ss Routing Tables and Domains 183Routing tables contain layer 2 and 3 forwarding information. 184Each address family in use will have its own routing table. 185Routing domains are a way of logically segmenting a router among multiple 186networks and may contain more than one routing table. 187.Bl -tag -width Ds 188.It Fn rtable_exists "u_int id" 189Return 190.Fa 1 191if table with ID 192.Fa id 193exists, 194.Fa 0 195otherwise. 196.It Fn rtable_add "u_int id" 197Add table with ID of 198.Fa id 199to routing domain 200.Fa 0 . 201.It Fn rtable_l2 "u_int id" 202Get the routing domain of table with ID of 203.Fa id . 204.It Fn rtable_l2set "u_int id" "u_int parent" 205Place table with ID of 206.Fa id 207under the routing domain with ID of 208.Fa parent . 209.El 210.Ss Route Timer Queues 211Route timer queues provide a method of queueing routing-related actions to be 212triggered once per second. 213.Bl -tag -width Ds 214.It Fn rt_timer_queue_create "u_int timeout" 215Create a timer queue with a timeout of 216.Fa timeout 217seconds. 218.It Fn rt_timer_add "struct rtentry *rt" \ 219"void (*func)(struct rtentry *, struct rttimer *)" \ 220"struct rttimer_queue *queue" "u_int rtableid" 221Schedule 222.Fa func 223to be called on 224.Fa rt 225using the timeout of 226.Fa queue . 227If 228.Fa rt 229already has a call to 230.Fa func 231scheduled on any timer queue, it will be replaced with the new invocation. 232.It Fn rt_timer_queue_change "struct rttimer_queue *rtq" "long timeout" 233Set timeout for 234.Fa rtq 235to 236.Fa timeout 237seconds. 238.It Fn rt_timer_remove_all "struct rtentry *rt" 239Remove all timeouts associated with 240.Fa rt 241from all routing timer queues. 242.El 243.Ss Route Labels 244Route labels are arbitrary data appended to routes and can be acted upon by 245.Xr pf . 246.Bl -tag -width Ds 247.It Fn rtlabel_name2id "char *name" 248Return numerical ID of the route label named 249.Fa name , 250creating the label if it does not already exist. 251.It Fn rtlabel_id2name "u_int16_t id" 252Return the string name of the route label with ID 253.Fa id . 254.It Fn rtlabel_id2sa "u_int16_t labelid" "struct sockaddr_rtlabel *sa_rl" 255Populate 256.Fa sa_rl 257with the data from the route label specified by 258.Fa labelid . 259.It Fn rtlabel_unref "u_int16_t id" 260Remove a reference to the route label with ID 261.Fa id , 262freeing the label if the reference count drops to 0. 263.El 264.Sh RETURN VALUES 265.Fn rtrequest1 266may fail with: 267.Pp 268.Bl -tag -width Er -compact 269.It Bq Er EAFNOSUPPORT 270The protocol used by 271.Fa info 272is not supported in table with ID of 273.Fa tableid . 274.It Bq Er ESEARCH 275No routing entry corresponding to 276.Fa info 277could be found. 278.It Bq Er ESEARCH 279Multipath route with no gateway provided in 280.Fa info . 281.It Bq Er ESEARCH 282The routing entry could not be found in the routing table. 283.It Bq Er EINVAL 284.Fa req 285specified 286.Fa RTM_RESOLVE 287with a 288.Fa ret_nrt 289argument which does not point to a cloneable routing entry. 290.It Bq Er EEXIST 291Multipath route conflicts with existing multipath route. 292.It Bq Er EEXIST 293The route could not be entered into the routing table. 294.It Bq Er ENOMEM 295Space for MPLS protocol data could not be allocated. 296.It Bq Er ENOBUFS 297Space for a new routing entry could not be allocated. 298.It Bq Er ENETUNREACH 299An interface address corresponding to the route described by 300.Fa info 301could not be found. 302.El 303.Pp 304.Fn rt_setgate 305returns non-0 if it cannot allocate memory. 306.Pp 307.Fn rtdeletemsg 308may fail with: 309.Pp 310.Bl -tag -width Er -compact 311.It Bq Er EAFNOSUPPORT 312The protocol used by 313.Fa rt 314is not supported by table with ID 315.Fa tableid . 316.It Bq Er ESRCH 317No routing entry for 318.Fa rt 319could be found. 320.It Bq Er ESRCH 321.Fa rt 322is a multipath route that conflicts with existing multipath route. 323.El 324.Pp 325.Fn rtable_add 326may fail with: 327.Pp 328.Bl -tag -width Er -compact 329.It Bq Er EEXIST 330A table with ID of 331.Fa id 332already exists. 333.It Bq Er ENOMEM 334Memory could not be allocated to extend the list of routing domains. 335.El 336.Pp 337.Fn rt_timer_add 338may fail with 339.Er ENOBUFS 340if memory could not be allocated for the timeout. 341.Pp 342.Fn rtlabel_name2id 343returns 344.Fa 0 345if it was unable to create a route label. 346.Sh SEE ALSO 347.Xr route 4 , 348.Xr route 8 349.Sh BUGS 350The current route entry reference counting code, while not incorrect, is also 351likely not correct either. 352