Commit | Line | Data |
---|---|---|
9903e566 | 1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
41bf08ba KS |
2 | .\" All rights reserved. |
3 | .\" | |
4 | .\" %sccs.include.redist.man% | |
5 | .\" | |
5ebe7d4b | 6 | .\" @(#)route.4 8.1 (Berkeley) %G% |
41bf08ba | 7 | .\" |
9903e566 CL |
8 | .Dd |
9 | .Dt ROUTE 4 | |
10 | .Os | |
11 | .Sh NAME | |
12 | .Nm route | |
13 | .Nd kernel packet forwarding database | |
14 | .Sh SYNOPSIS | |
15 | .Fd #include <sys/socket.h> | |
16 | .Fd #include <net/if.h> | |
17 | .Fd #include <net/route.h> | |
18 | .Ft int | |
19 | .Fn socket PF_ROUTE SOCK_RAW "int family" | |
20 | .Sh DESCRIPTION | |
21 | .Tn UNIX | |
41bf08ba KS |
22 | provides some packet routing facilities. |
23 | The kernel maintains a routing information database, which | |
24 | is used in selecting the appropriate network interface when | |
25 | transmitting packets. | |
9903e566 | 26 | .Pp |
41bf08ba KS |
27 | A user process (or possibly multiple co-operating processes) |
28 | maintains this database by sending messages over a special kind | |
29 | of socket. | |
30 | This supplants fixed size | |
9903e566 | 31 | .Xr ioctl 2 Ns 's |
41bf08ba KS |
32 | used in earlier releases. |
33 | Routing table changes may only be carried out by the super user. | |
9903e566 | 34 | .Pp |
41bf08ba KS |
35 | The operating system may spontaneously emit routing messages in response |
36 | to external events, such as recipt of a re-direct, or failure to | |
37 | locate a suitable route for a request. | |
38 | The message types are described in greater detail below. | |
9903e566 | 39 | .Pp |
a553c1d1 KS |
40 | Routing database entries come in two flavors: for a specific |
41 | host, or for all hosts on a generic subnetwork (as specified | |
42 | by a bit mask and value under the mask. | |
43 | The effect of wildcard or default route may be achieved by using | |
44 | a mask of all zeros, and there may be hierarchical routes. | |
9903e566 | 45 | .Pp |
41bf08ba KS |
46 | When the system is booted and addresses are assigned |
47 | to the network interfaces, each protocol family | |
48 | installs a routing table entry for each interface when it is ready for traffic. | |
49 | Normally the protocol specifies the route | |
9903e566 CL |
50 | through each interface as a |
51 | .Dq direct | |
52 | connection to the destination host | |
41bf08ba KS |
53 | or network. If the route is direct, the transport layer of |
54 | a protocol family usually requests the packet be sent to the | |
55 | same host specified in the packet. Otherwise, the interface | |
56 | is requested to address the packet to the gateway listed in the routing entry | |
57 | (i.e. the packet is forwarded). | |
9903e566 | 58 | .Pp |
41bf08ba KS |
59 | When routing a packet, |
60 | the kernel will first attempt to find a route to the destination host. | |
61 | Failing that, a search is made for a route to the network of the destination. | |
9903e566 CL |
62 | Finally, any route to a default |
63 | .Pq Dq wildcard | |
64 | gateway is chosen. | |
41bf08ba KS |
65 | If no entry is found, the destination is declared to be unreachable, |
66 | and a routing\-miss message is generated if there are any | |
67 | listers on the routing control socket described below. | |
9903e566 | 68 | .Pp |
41bf08ba KS |
69 | A wildcard routing entry is specified with a zero |
70 | destination address value. Wildcard routes are used | |
71 | only when the system fails to find a route to the | |
72 | destination host and network. The combination of wildcard | |
73 | routes and routing redirects can provide an economical | |
74 | mechanism for routing traffic. | |
9903e566 | 75 | .Pp |
41bf08ba KS |
76 | One opens the channel for passing routing control messasges |
77 | by using the socket call shown in the synopsis above: | |
9903e566 CL |
78 | .Pp |
79 | The | |
80 | .Fa family | |
81 | paramter may be | |
82 | .Dv AF_UNSPEC | |
83 | which will provide | |
41bf08ba KS |
84 | routing information for all address families, or can be restricted |
85 | to a specific address family by specifying which one is desired. | |
86 | There can be more than one routing socket open per system. | |
9903e566 | 87 | .Pp |
41bf08ba KS |
88 | Messages are formed by a header followed by a small |
89 | number of sockadders (now variable length particularly | |
9903e566 CL |
90 | in the |
91 | .Tn ISO | |
92 | case), interpreted by position, and delimited | |
41bf08ba | 93 | by the new length entry in the sockaddr. |
9903e566 CL |
94 | An example of a message with four addresses might be an |
95 | .Tn ISO | |
96 | redirect: | |
41bf08ba KS |
97 | Destination, Netmask, Gateway, and Author of the redirect. |
98 | The interpretation of which address are present is given by a | |
99 | bit mask within the header, and the sequence is least significant | |
100 | to most significant bit within the vector. | |
9903e566 | 101 | .Pp |
41bf08ba KS |
102 | Any messages sent to the kernel are returned, and copies are sent |
103 | to all interested listeners. The kernel will provide the process | |
104 | id. for the sender, and the sender may use an additional sequence | |
105 | field to distinguish between outstanding messages. However, | |
106 | message replies may be lost when kernel buffers are exhausted. | |
9903e566 | 107 | .Pp |
41bf08ba | 108 | The kernel may reject certain messages, and will indicate this |
9903e566 CL |
109 | by filling in the |
110 | .Ar rtm_errno | |
111 | field. | |
112 | The routing code returns | |
113 | .Dv EEXIST | |
114 | if | |
115 | requested to duplicate an existing entry, | |
116 | .Dv ESRCH | |
117 | if | |
41bf08ba | 118 | requested to delete a non-existent entry, |
9903e566 CL |
119 | or |
120 | .Dv ENOBUFS | |
121 | if insufficient resources were available | |
41bf08ba KS |
122 | to install a new route. |
123 | In the current implementation, all routing process run locally, | |
9903e566 CL |
124 | and the values for |
125 | .Ar rtm_errno | |
126 | are available through the normal | |
127 | .Em errno | |
128 | mechanism, even if the routing reply message is lost. | |
129 | .Pp | |
41bf08ba KS |
130 | A process may avoid the expense of reading replies to |
131 | its own messages by issuing a | |
9903e566 CL |
132 | .Xr setsockopt 2 |
133 | call indicating that the | |
134 | .Dv SO_USELOOPBACK | |
135 | option | |
136 | at the | |
137 | .Dv SOL_SOCKET | |
138 | level is to be turned off. | |
41bf08ba KS |
139 | A process may ignore all messages from the routing socket |
140 | by doing a | |
9903e566 | 141 | .Xr shutdown 2 |
41bf08ba | 142 | system call for further input. |
9903e566 | 143 | .Pp |
41bf08ba KS |
144 | If a route is in use when it is deleted, |
145 | the routing entry will be marked down and removed from the routing table, | |
146 | but the resources associated with it will not | |
147 | be reclaimed until all references to it are released. | |
148 | User processes can obtain information about the routing | |
9903e566 CL |
149 | entry to a specific destination by using a |
150 | .Dv RTM_GET | |
151 | message, | |
41bf08ba | 152 | or by reading the |
9903e566 | 153 | .Pa /dev/kmem |
41bf08ba | 154 | device, or by issuing a |
9903e566 | 155 | .Xr getkerninfo 2 |
41bf08ba | 156 | system call. |
9903e566 | 157 | .Pp |
41bf08ba | 158 | Messages include: |
9903e566 CL |
159 | .Bd -literal |
160 | #define RTM_ADD 0x1 /* Add Route */ | |
161 | #define RTM_DELETE 0x2 /* Delete Route */ | |
162 | #define RTM_CHANGE 0x3 /* Change Metrics, Flags, or Gateway */ | |
163 | #define RTM_GET 0x4 /* Report Information */ | |
164 | #define RTM_LOOSING 0x5 /* Kernel Suspects Partitioning */ | |
165 | #define RTM_REDIRECT 0x6 /* Told to use different route */ | |
166 | #define RTM_MISS 0x7 /* Lookup failed on this address */ | |
167 | #define RTM_RESOLVE 0xb /* request to resolve dst to LL addr */ | |
168 | .Ed | |
169 | .Pp | |
41bf08ba | 170 | A message header consists of: |
9903e566 | 171 | .Bd -literal |
41bf08ba | 172 | struct rt_msghdr { |
9903e566 CL |
173 | u_short rmt_msglen; /* to skip over non-understood messages */ |
174 | u_char rtm_version; /* future binary compatability */ | |
175 | u_char rtm_type; /* message type */ | |
176 | u_short rmt_index; /* index for associated ifp */ | |
177 | pid_t rmt_pid; /* identify sender */ | |
178 | int rtm_addrs; /* bitmask identifying sockaddrs in msg */ | |
179 | int rtm_seq; /* for sender to identify action */ | |
180 | int rtm_errno; /* why failed */ | |
181 | int rtm_flags; /* flags, incl kern & message, e.g. DONE */ | |
182 | int rtm_use; /* from rtentry */ | |
183 | u_long rtm_inits; /* which values we are initializing */ | |
184 | struct rt_metrics rtm_rmx; /* metrics themselves */ | |
41bf08ba | 185 | }; |
9903e566 CL |
186 | .Ed |
187 | .Pp | |
41bf08ba | 188 | where |
9903e566 | 189 | .Bd -literal |
41bf08ba | 190 | struct rt_metrics { |
9903e566 CL |
191 | u_long rmx_locks; /* Kernel must leave these values alone */ |
192 | u_long rmx_mtu; /* MTU for this path */ | |
193 | u_long rmx_hopcount; /* max hops expected */ | |
194 | u_long rmx_expire; /* lifetime for route, e.g. redirect */ | |
195 | u_long rmx_recvpipe; /* inbound delay-bandwith product */ | |
196 | u_long rmx_sendpipe; /* outbound delay-bandwith product */ | |
197 | u_long rmx_ssthresh; /* outbound gateway buffer limit */ | |
198 | u_long rmx_rtt; /* estimated round trip time */ | |
199 | u_long rmx_rttvar; /* estimated rtt variance */ | |
41bf08ba | 200 | }; |
9903e566 CL |
201 | .Ed |
202 | .Pp | |
41bf08ba | 203 | Flags include the values: |
9903e566 CL |
204 | .Bd -literal |
205 | #define RTF_UP 0x1 /* route useable */ | |
206 | #define RTF_GATEWAY 0x2 /* destination is a gateway */ | |
207 | #define RTF_HOST 0x4 /* host entry (net otherwise) */ | |
208 | #define RTF_NORMAL 0x8 /* subnet mask is cannonical */ | |
209 | #define RTF_DYNAMIC 0x10 /* created dynamically (by redirect) */ | |
210 | #define RTF_MODIFIED 0x20 /* modified dynamically (by redirect) */ | |
211 | #define RTF_DONE 0x40 /* message confirmed */ | |
212 | #define RTF_MASK 0x80 /* subnet mask present */ | |
213 | .Ed | |
214 | .Pp | |
41bf08ba | 215 | Specfiers for metric values in rmx_locks and rtm_inits are: |
9903e566 CL |
216 | .Bd -literal |
217 | #define RTV_SSTHRESH 0x1 /* init or lock _ssthresh */ | |
218 | #define RTV_RPIPE 0x2 /* init or lock _recvpipe */ | |
219 | #define RTV_SPIPE 0x4 /* init or lock _sendpipe */ | |
220 | #define RTV_HOPCOUNT 0x8 /* init or lock _hopcount */ | |
221 | #define RTV_RTT 0x10 /* init or lock _rtt */ | |
222 | #define RTV_RTTVAR 0x20 /* init or lock _rttvar */ | |
223 | #define RTV_MTU 0x40 /* init or lock _mtu */ | |
224 | .Ed | |
225 | .Pp | |
41bf08ba | 226 | Specifiers for which addresses are present in the messages are: |
9903e566 CL |
227 | .Bd -literal |
228 | #define RTA_DST 0x1 /* destination sockaddr present */ | |
229 | #define RTA_GATEWAY 0x2 /* gateway sockaddr present */ | |
230 | #define RTA_NETMASK 0x4 /* netmask sockaddr present */ | |
231 | #define RTA_GENMASK 0x8 /* cloning mask sockaddr present */ | |
232 | #define RTA_IFP 0x10 /* interface name sockaddr present */ | |
233 | #define RTA_IFA 0x20 /* interface addr sockaddr present */ | |
234 | #define RTA_AUTHOR 0x40 /* sockaddr for author of redirect */ | |
235 | .Ed | |
236 | .Sh HISTORY | |
237 | The | |
238 | .Nm | |
239 | forwarding database | |
240 | .Ud |