ROUTE(4) BSD Programmer's Manual ROUTE(4)NAMEroute - forwarding information database and routing socket
SYNOPSIS
#include <sys/socket.h>
#include <net/if.h>
#include <net/route.h>
int
socket(PF_ROUTE, SOCK_RAW, int family);
DESCRIPTION
The operating system provides packet forwarding facilities by maintaining
a ``forwarding information database'', or ``forwarding table''. This
database is used in selecting the appropriate network interface when
transmitting packets.
One or more co-operating user processes (see gated(8)and routed(8))
maintain this database by sending messages over a special type of socket,
the ``routing socket''. This supplants the fixed size ioctl(2) calls
(SIOCADDRT and SIOCDELRT) used in earlier releases.
The term ``routing'' technically refers to the use of routing protocols
to discover ``routes'' to remote networks and hosts. The term
``forwarding'' refers to the process of sending a packet on towards its
eventual destination. An entry in the operating system's forwarding
table can be referred to as a ``forwarding table entry'' or a ``route''.
The ability to change the forwarding table is restricted to the super us-
er.
The operating system may spontaneously emit routing socket messages in
response to external events, such as receipt of a re-direct, failure to
locate a suitable route when attempting to send or forward a packet, or
interface status or address changes. The message types are described in
greater detail below.
Forwarding 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 a ``wildcard'' or ``default'' route
may be achieved by using a mask of all zeros, and there may be hierarchi-
cal routes.
When the system is booted and addresses are assigned to the network in-
terfaces, each protocol family installs a forwarding 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 desti-
nation 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 forwarding entry (i.e. the
packet is forwarded).
When forwarding a packet, the operating system will attempt to find the
most specific route matching the destination. If no entry is found, the
destination is declared to be unreachable, and a routing-miss (RTM_MISS)
message is generated if there are any listeners on the routing socket as
described below. 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.
A wildcard (or ``default'') routing entry is specified with a zero desti-
nation address value, and a mask of all zeroes. Wild card routes will be
used when the system fails to find other routes matching the destination.
The combination of wildcard routes and routing redirects can provide an
economical mechanism for routing traffic.
A process opens the routing socket for passing control messages by using
the socket(2) system call shown in the synopsis. Multiple routing sock-
ets can be open simultaneously. Messages will be restricted to the ad-
dress family provided via the family parameter unless AF_UNSPEC is used
to request messages from all address families.
Messages are formed by a header followed by a small number of struct
sockaddr entries. (now variable length particularly in the ISO case),
interpreted by position, and delimited by the new length entry in the
struct sockaddr (rounded up to the size of a long). Network masks should
have a family of AF_UNSPEC. The interpretation of which address are pre-
sent 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 operating system are returned, and copies are
sent to all interested listeners. The operating system will provide the
process ID for the sender, and the sender may use an additional sequence
field to distinguish between outstanding messages. However, message
replies may be lost when operating system buffers are exhausted.
The operating system may reject certain messages, and will indicate this
by filling in the rtm_errno field as described below. In the current im-
plementation, all routing process run locally, 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 to dis-
allow further input.
If a route is in use when it is deleted, the forwarding table entry will
be marked down and removed from the 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 forwarding table entry
used to forward to a specific destination by using a RTM_GET message, or
by issuing a sysctl(3) system call.
Forwarding table maintenance messages
The following message types are defined for forwarding table maintenance:
RTM_ADD Add a route to the forwarding table.
RTM_CHANGE Change an existing route in the forwarding table.
RTM_DELETE Remove a route from the forwarding table.
RTM_GET Look up and returns the characteristics of a route in the
forwarding table. The route returned is the (longest
match) route for the specified destination.
RTM_LOCK Used by user processes to set the ``lock'' bits for certain
metrics. When the metrics are locked, the operating system
will not update them.
RTM_LOSING The operating system detects packet loss.
RTM_MISS No entry in the forwarding table was found for the speci-
fied address.
RTM_REDIRECT The operating system has received and processed a redirect.
RTM_RESOLVE A request from the operating system for a user process to
resolve the specified destination to a link level address.
A routing related message header consists of:
struct rt_msghdr {
u_short rtm_msglen; /* to skip over non-understood messages */
u_char rtm_version; /* Set to RTM_VERSION */
u_char rtm_type; /* message type */
u_short rtm_index; /* index for associated ifp */
int rtm_flags; /* flags, incl kern & message, e.g. DONE */
int rtm_addrs; /* bitmask identifying sockaddrs in msg */
pid_t rtm_pid; /* identify sender */
int rtm_seq; /* for sender to identify action */
int rtm_errno; /* why failed */
int rtm_use; /* from rtentry */
u_long rtm_inits; /* which values we are initializing */
struct rt_metrics rtm_rmx; /* metrics themselves */
};
rtm_addrs Description of addresses included as defined below.
rtm_errno Indication of success (when 0) or reason for failure to pro-
cess message.
rtm_flags Route flags as defined below.
rtm_index Index of associated interface. Only used in messages gener-
ated by the operating system.
rtm_inits Indication of which fields of rtm_rmx are being set.
rtm_msglen Total length of message, including struct sockaddr entries.
rtm_pid Process ID of the sender, set by the operating system.
rtm_rmx Route metrics from struct rtentry as described below.
rtm_seq Sequence number assigned by the sender.
rtm_type Message type as defined above.
rtm_use Value of rt_use from struct rtentry.
rtm_version Version of the message format in use, should be set to
RTM_VERSION.
Route metrics are defined as:
struct rt_metrics {
u_long rmx_locks; /* Kernel must leave these values alone */
u_long rmx_mtu; /* MTU for this path */
u_long rmx_hopcount; /* max hops expected */
u_long rmx_expire; /* lifetime for route, e.g. redirect */
u_long rmx_recvpipe; /* inbound delay-bandwith product */
u_long rmx_sendpipe; /* outbound delay-bandwith product */
u_long rmx_ssthresh; /* outbound gateway buffer limit */
u_long rmx_rtt; /* estimated round trip time */
u_long rmx_rttvar; /* estimated rtt variance */
};
Values for rtm_flags include the values:
RTF_BLACKHOLE Packets using this route will be silently dropped.
RTF_CLONED This route was cloned dynamically from a more general
route.
RTF_CLONING References to this route should generate a more specific
route with the specified cloning mask.
RTF_DONE Indicates that processing of this message has been com-
pleted. The preferred method of detecting if a
RTF_DYNAMIC Created dynamically, usually by a redirect.
RTF_GATEWAY The route points to a ``gateway'' which will forward the
packet on to it's final destination.
RTF_HOST The destination references a host, no netmask is present.
RTF_LLINFO Indicates that this route contains link level information,
used by routes installed by arp(4) and esis(4).
RTF_MODIFIED Modified dynamically, usually by a redirect. RTM_REDIRECT
message was processed by the operating system is to exam-
ine rtm_errno.
RTF_PROTO1
RTF_PROTO2 Protocol specific routing flags.
RTF_REJECT Packets using this route will be dropped and EHOSTUNREACH
or ENETUNREACH errors to be returned.
RTF_STATIC Indicates that this route was manually added by the system
administrator with the route(8) command. This provides a
indication to user-level routing daemons (e.g.
gated(8)routed(8)) that this route should be retained.
RTF_UP The route is usable.
RTF_XRESOLVE References to this route should generate RTM_RESOLVE rout-
ing socket messages to request a more specific route be
installed by a user process.
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 _hopcount */
#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 */
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_GENMASK 0x8 /* cloning mask 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, broadcast or p-p dest addr */
Interface status messages
Messages describing interfaces and interface status changes are:
RTM_DELADDR Generated whenever an existing address is deleted from an
interface.
RTM_IFINFO Generated whenever the status of an interface changes.
RTM_NEWADDR Generated whenever a new address is added to an interface,
or the characteristics of an existing address are changed.
The RTM_IFINFO message uses the following message header:
struct if_msghdr {
u_short ifm_msglen; /* to skip over non-understood messages */
u_char ifm_version; /* future binary compatability */
u_char ifm_type; /* message type */
int ifm_addrs; /* like rtm_addrs */
int ifm_flags; /* value of if_flags */
u_short ifm_index; /* index for associated ifp */
struct if_data ifm_data; /* statistics and other data about if */
};
ifm_msglen Total length of message, including struct sockaddr entries.
ifm_addrs Description of addresses included as defined above.
ifm_data Interface statistics as defined in struct if_data found in
<net/if.h>.
ifm_flags Interface flags as defined in <net/if.h>.
ifm_index Index of associated interface.
ifm_type Message type as defined above.
ifm_version Version of the message format in use, should be set to
RTM_VERSION.
Messages describing the addition or deletion of addresses on an interface
use the following message header:
struct ifa_msghdr {
u_short ifam_msglen; /* to skip over non-understood messages */
u_char ifam_version; /* future binary compatability */
u_char ifam_type; /* message type */
int ifam_addrs; /* like rtm_addrs */
int ifam_flags; /* value of ifa_flags */
u_short ifam_index; /* index for associated ifp */
int ifam_metric; /* value of ifa_metric */
};
ifam_msglen Total length of message, including struct sockaddr entries.
ifam_addrs Description of addresses included as defined above.
ifam_flags Interface address flags from struct ifaddr.
ifam_index Interface index of associated interface.
ifam_metric Interface address metric from struct ifaddr.
ifam_type Message type as defined above.
ifam_version Version of the message format in use, should be set to
RTM_VERSION.
ERRORS
The routing code returns the following errors in the global variable
errno and as rtm_errno.
[EEXIST]
The entry being added would duplicate an existing entry.
[ESRCH] The entry being deleted does not exist.
[ENOBUFS]
Insufficient resources were available to install a new route.
SEE ALSOioctl(2), shutdown(2), socket(2), sysctl(3), arp(4), esis(4),
inet(4), intro(4), iso(4), localdomain(4), netintro(4), ns(4),
config(8), gated(8), ifconfig(8), routed(8)BSDI BSD/OS April 19, 1994 6