333 lines
13 KiB
Groff
333 lines
13 KiB
Groff
.\" $NetBSD: route.4,v 1.13 2003/01/18 00:01:18 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 1990, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)route.4 8.6 (Berkeley) 4/19/94
|
|
.\"
|
|
.Dd April 19, 1994
|
|
.Dt ROUTE 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm route
|
|
.Nd kernel packet forwarding database
|
|
.Sh SYNOPSIS
|
|
.Fd #include \*[Lt]sys/socket.h\*[Gt]
|
|
.Fd #include \*[Lt]net/if.h\*[Gt]
|
|
.Fd #include \*[Lt]net/route.h\*[Gt]
|
|
.Ft int
|
|
.Fn socket PF_ROUTE SOCK_RAW "int family"
|
|
.Sh DESCRIPTION
|
|
.Ux
|
|
provides some packet routing facilities.
|
|
The kernel maintains a routing information database, which
|
|
is used in selecting the appropriate network interface when
|
|
transmitting packets.
|
|
.Pp
|
|
A user process (or possibly multiple co-operating processes)
|
|
maintains this database by sending messages over a special kind
|
|
of socket.
|
|
This supplants fixed size
|
|
.Xr ioctl 2 Ns 's
|
|
used in earlier releases.
|
|
Routing table changes may only be carried out by the super user.
|
|
.Pp
|
|
The operating system may spontaneously emit routing messages in response
|
|
to external events, such as receipt of a redirect, or failure to
|
|
locate a suitable route for a request.
|
|
The message types are described in greater detail below.
|
|
.Pp
|
|
Routing 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 wildcard or default route may be achieved by using
|
|
a mask of all zeros, and there may be hierarchical routes.
|
|
.Pp
|
|
When the system is booted and addresses are assigned
|
|
to the network interfaces, each protocol family
|
|
installs a routing table entry for each interface when it is ready for traffic.
|
|
Normally the protocol specifies the route
|
|
through each interface as a
|
|
.Dq direct
|
|
connection to the destination 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 address the packet to the gateway listed in the routing entry
|
|
(i.e. the packet is forwarded).
|
|
.Pp
|
|
When routing a packet,
|
|
the kernel will attempt to find
|
|
the most specific route matching the destination.
|
|
(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).
|
|
If no entry is found, the destination is declared to be unreachable,
|
|
and a routing\-miss message is generated if there are any
|
|
listeners on the routing control socket described below.
|
|
.Pp
|
|
A wildcard routing entry is specified with a zero
|
|
destination address value, and a mask of all zeroes.
|
|
Wildcard 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.
|
|
.Pp
|
|
One opens the channel for passing routing control messages
|
|
by using the socket call shown in the synopsis above:
|
|
.Pp
|
|
The
|
|
.Fa family
|
|
parameter may be
|
|
.Dv AF_UNSPEC
|
|
which will provide
|
|
routing information for all address families, or can be restricted
|
|
to a specific address family by specifying which one is desired.
|
|
There can be more than one routing socket open per system.
|
|
.Pp
|
|
Messages are formed by a header followed by a small
|
|
number of sockaddrs (now variable length particularly
|
|
in the
|
|
.Tn ISO
|
|
case), interpreted by position, and delimited
|
|
by the new length entry in the sockaddr.
|
|
An example of a message with four addresses might be an
|
|
.Tn ISO
|
|
redirect:
|
|
Destination, Netmask, Gateway, and Author of the redirect.
|
|
The interpretation of which address are present is given by a
|
|
bit mask within the header, and the sequence is least significant
|
|
to most significant bit within the vector.
|
|
.Pp
|
|
Any messages sent to the kernel are returned, and copies are sent
|
|
to all interested listeners. The kernel 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 kernel buffers are exhausted.
|
|
.Pp
|
|
The kernel may reject certain messages, and will indicate this
|
|
by filling in the
|
|
.Ar rtm_errno
|
|
field.
|
|
The routing code returns
|
|
.Dv EEXIST
|
|
if
|
|
requested to duplicate an existing entry,
|
|
.Dv ESRCH
|
|
if
|
|
requested to delete a non-existent entry,
|
|
or
|
|
.Dv ENOBUFS
|
|
if insufficient resources were available
|
|
to install a new route.
|
|
In the current implementation, all routing processes run locally,
|
|
and the values for
|
|
.Ar rtm_errno
|
|
are available through the normal
|
|
.Em errno
|
|
mechanism, even if the routing reply message is lost.
|
|
.Pp
|
|
A process may avoid the expense of reading replies to
|
|
its own messages by issuing a
|
|
.Xr setsockopt 2
|
|
call indicating that the
|
|
.Dv SO_USELOOPBACK
|
|
option
|
|
at the
|
|
.Dv SOL_SOCKET
|
|
level is to be turned off.
|
|
A process may ignore all messages from the routing socket
|
|
by doing a
|
|
.Xr shutdown 2
|
|
system call for further input.
|
|
.Pp
|
|
If a route is in use when it is deleted,
|
|
the routing entry will be marked down and removed from the routing 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 routing
|
|
entry to a specific destination by using a
|
|
.Dv RTM_GET
|
|
message,
|
|
or by reading the
|
|
.Pa /dev/kmem
|
|
device, or by calling
|
|
.Xr sysctl 3 .
|
|
.Pp
|
|
The messages are:
|
|
.Bd -literal
|
|
#define RTM_ADD 0x1 /* Add Route */
|
|
#define RTM_DELETE 0x2 /* Delete Route */
|
|
#define RTM_CHANGE 0x3 /* Change Metrics, Flags, or Gateway */
|
|
#define RTM_GET 0x4 /* Report Information */
|
|
#define RTM_LOSING 0x5 /* Kernel Suspects Partitioning */
|
|
#define RTM_REDIRECT 0x6 /* Told to use different route */
|
|
#define RTM_MISS 0x7 /* Lookup failed on this address */
|
|
#define RTM_RESOLVE 0xb /* request to resolve dst to LL addr */
|
|
#define RTM_NEWADDR 0xc /* address being added to iface */
|
|
#define RTM_DELADDR 0xd /* address being removed from iface */
|
|
#define RTM_OIFINFO 0xe /* Old (pre-1.5) RTM_IFINFO message */
|
|
#define RTM_IFINFO 0xf /* iface/link going up/down etc. */
|
|
#define RTM_IFANNOUNCE 0x10 /* iface arrival/departure */
|
|
.Ed
|
|
.Pp
|
|
A message header consists of one of the following:
|
|
.Bd -literal
|
|
struct rt_msghdr {
|
|
u_short rtm_msglen; /* to skip over non-understood messages */
|
|
u_char rtm_version; /* future binary compatibility */
|
|
u_char rtm_type; /* message type */
|
|
u_short rtm_index; /* index for associated ifp */
|
|
int rtm_flags; /* flags, incl kern \*[Am] 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 metrics we are initializing */
|
|
struct rt_metrics rtm_rmx; /* metrics themselves */
|
|
};
|
|
|
|
struct if_msghdr {
|
|
u_short ifm_msglen; /* to skip over non-understood messages */
|
|
u_char ifm_version; /* future binary compatibility */
|
|
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 */
|
|
};
|
|
|
|
struct ifa_msghdr {
|
|
u_short ifam_msglen; /* to skip over non-understood messages */
|
|
u_char ifam_version; /* future binary compatibility */
|
|
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 */
|
|
};
|
|
|
|
struct if_announcemsghdr {
|
|
u_short ifan_msglen; /* to skip over non-understood messages */
|
|
u_char ifan_version; /* future binary compatibility */
|
|
u_char ifan_type; /* message type */
|
|
u_short ifan_index; /* index for associated ifp */
|
|
char ifan_name[IFNAMSIZ]; /* if name, e.g. "en0" */
|
|
u_short ifan_what; /* what type of announcement */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Dv RTM_IFINFO
|
|
message uses a
|
|
.Ar if_msghdr
|
|
header, the
|
|
.Dv RTM_NEWADDR
|
|
and
|
|
.Dv RTM_DELADDR
|
|
messages use a
|
|
.Ar ifa_msghdr
|
|
header,
|
|
the
|
|
.Dv RTM_IFANNOUNCE
|
|
message uses a
|
|
.Ar if_announcemsghdr
|
|
header,
|
|
and all other messages use the
|
|
.Ar rt_msghdr
|
|
header.
|
|
.Pp
|
|
The metrics structure is:
|
|
.Bd -literal
|
|
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-bandwidth product */
|
|
u_long rmx_sendpipe; /* outbound delay-bandwidth product */
|
|
u_long rmx_ssthresh; /* outbound gateway buffer limit */
|
|
u_long rmx_rtt; /* estimated round trip time */
|
|
u_long rmx_rttvar; /* estimated rtt variance */
|
|
u_long rmx_pksent; /* packets sent using this route */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
Flags include the values:
|
|
.Bd -literal
|
|
#define RTF_UP 0x1 /* route usable */
|
|
#define RTF_GATEWAY 0x2 /* destination is a gateway */
|
|
#define RTF_HOST 0x4 /* host entry (net otherwise) */
|
|
#define RTF_REJECT 0x8 /* host or net unreachable */
|
|
#define RTF_DYNAMIC 0x10 /* created dynamically (by redirect) */
|
|
#define RTF_MODIFIED 0x20 /* modified dynamically (by redirect) */
|
|
#define RTF_DONE 0x40 /* message confirmed */
|
|
#define RTF_MASK 0x80 /* subnet mask present */
|
|
#define RTF_CLONING 0x100 /* generate new routes on use */
|
|
#define RTF_XRESOLVE 0x200 /* external daemon resolves name */
|
|
#define RTF_LLINFO 0x400 /* generated by ARP or ESIS */
|
|
#define RTF_STATIC 0x800 /* manually added */
|
|
#define RTF_BLACKHOLE 0x1000 /* just discard pkts (during updates) */
|
|
#define RTF_CLONED 0x2000 /* this is a cloned route */
|
|
#define RTF_PROTO2 0x4000 /* protocol specific routing flag */
|
|
#define RTF_PROTO1 0x8000 /* protocol specific routing flag */
|
|
.Ed
|
|
.Pp
|
|
Specifiers for metric values in rmx_locks and rtm_inits are:
|
|
.Bd -literal
|
|
#define RTV_MTU 0x1 /* init or lock _mtu */
|
|
#define RTV_HOPCOUNT 0x2 /* init or lock _hopcount */
|
|
#define RTV_EXPIRE 0x4 /* init or lock _expire */
|
|
#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 */
|
|
.Ed
|
|
.Pp
|
|
Specifiers for which addresses are present in the messages are:
|
|
.Bd -literal
|
|
#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 */
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr socket 2 ,
|
|
.Xr sysctl 3
|