diff options
Diffstat (limited to 'share/man/man4/route.4')
| -rw-r--r-- | share/man/man4/route.4 | 335 |
1 files changed, 335 insertions, 0 deletions
diff --git a/share/man/man4/route.4 b/share/man/man4/route.4 new file mode 100644 index 000000000000..b85b41cbe5a1 --- /dev/null +++ b/share/man/man4/route.4 @@ -0,0 +1,335 @@ +.\" 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. +.\" +.\" From: @(#)route.4 8.6 (Berkeley) 4/19/94 +.\" $FreeBSD$ +.\" +.Dd November 4, 2004 +.Dt ROUTE 4 +.Os +.Sh NAME +.Nm route +.Nd kernel packet forwarding database +.Sh SYNOPSIS +.In sys/types.h +.In sys/time.h +.In sys/socket.h +.In net/if.h +.In net/route.h +.Ft int +.Fn socket PF_ROUTE SOCK_RAW "int family" +.Sh DESCRIPTION +.Fx +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 re-direct, 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 +.Er EEXIST +if +requested to duplicate an existing entry, +.Er ESRCH +if +requested to delete a non-existent entry, +or +.Er 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 calling +.Xr sysctl 3 . +.Pp +Messages include: +.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_LOCK 0x8 /* fix specified metrics */ +#define RTM_OLDADD 0x9 /* caused by SIOCADDRT */ +#define RTM_OLDDEL 0xa /* caused by SIOCDELRT */ +#define RTM_RESOLVE 0xb /* request to resolve dst to LL addr - unused */ +#define RTM_NEWADDR 0xc /* address being added to iface */ +#define RTM_DELADDR 0xd /* address being removed from iface */ +#define RTM_IFINFO 0xe /* iface going up/down etc. */ +#define RTM_NEWMADDR 0xf /* mcast group membership being added to if */ +#define RTM_DELMADDR 0x10 /* mcast group membership being deleted */ +#define RTM_IFANNOUNCE 0x11 /* iface arrival/departure */ +#define RTM_IEEE80211 0x12 /* IEEE80211 wireless event */ +.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 & 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_fmask; /* bitmask used in RTM_CHANGE message */ + 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 ifma_msghdr { + u_short ifmam_msglen; /* to skip over non-understood messages */ + u_char ifmam_version; /* future binary compatibility */ + u_char ifmam_type; /* message type */ + int ifmam_addrs; /* like rtm_addrs */ + int ifmam_flags; /* value of ifa_flags */ + u_short ifmam_index; /* index for associated ifp */ +}; + +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_NEWMADDR +and +.Dv RTM_DELMADDR +messages use a +.Vt ifma_msghdr +header, the +.Dv RTM_IFANNOUNCE +message uses a +.Vt if_announcemsghdr +header, +and all other messages use the +.Ar rt_msghdr +header. +.Pp +The +.Dq Li "struct rt_metrics" +and the flag bits are as defined in +.Xr rtentry 9 . +.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 */ +#define RTV_WEIGHT 0x100 /* init or lock _weight */ +.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 - unused */ +#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 sysctl 3 , +.Xr route 8 , +.Xr rtentry 9 +.Pp +The constants for the +.Va rtm_flags +field are documented in the manual page for the +.Xr route 8 +utility. +.Sh HISTORY +A +.Dv PF_ROUTE +protocol family first appeared in +.Bx 4.3 reno . |