diff options
Diffstat (limited to 'share/man/man4/route.4')
| -rw-r--r-- | share/man/man4/route.4 | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/share/man/man4/route.4 b/share/man/man4/route.4 new file mode 100644 index 00000000000..382dc323615 --- /dev/null +++ b/share/man/man4/route.4 @@ -0,0 +1,272 @@ +.\" $NetBSD: route.4,v 1.3 1994/11/30 16:22:31 jtc 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 <sys/socket.h> +.Fd #include <net/if.h> +.Fd #include <net/route.h> +.Ft int +.Fn socket PF_ROUTE SOCK_RAW "int family" +.Sh DESCRIPTION +.Tn UNIX +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 +listers 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 sockadders (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 process 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 issuing a +.Xr getkerninfo 2 +system call. +.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_LOOSING 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 */ +.Ed +.Pp +A message header consists of: +.Bd -literal +struct rt_msghdr { + u_short rmt_msglen; /* to skip over non-understood messages */ + u_char rtm_version; /* future binary compatibility */ + u_char rtm_type; /* message type */ + u_short rmt_index; /* index for associated ifp */ + pid_t rmt_pid; /* identify sender */ + int rtm_addrs; /* bitmask identifying sockaddrs in msg */ + int rtm_seq; /* for sender to identify action */ + int rtm_errno; /* why failed */ + int rtm_flags; /* flags, incl kern & message, e.g. DONE */ + int rtm_use; /* from rtentry */ + u_long rtm_inits; /* which values we are initializing */ + struct rt_metrics rtm_rmx; /* metrics themselves */ +}; +.Ed +.Pp +where +.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-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 */ +}; +.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_PROTO2 0x4000 /* protocol specific routing flag #1 */ +#define RTF_PROTO1 0x8000 /* protocol specific routing flag #2 */ +.Ed +.Pp +Specifiers for metric values in rmx_locks and rtm_inits are: +.Bd -literal +#define RTV_SSTHRESH 0x1 /* init or lock _ssthresh */ +#define RTV_RPIPE 0x2 /* init or lock _recvpipe */ +#define RTV_SPIPE 0x4 /* init or lock _sendpipe */ +#define RTV_HOPCOUNT 0x8 /* init or lock _hopcount */ +#define RTV_RTT 0x10 /* init or lock _rtt */ +#define RTV_RTTVAR 0x20 /* init or lock _rttvar */ +#define RTV_MTU 0x40 /* init or lock _mtu */ +.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 */ +.Ed |