| blob | d670e336774a5efb3f8e9399cb2cfd2272c9c2de |
1 .\" $NetBSD: ip.4,v 1.29 2009/07/19 23:17:33 minskim Exp $
2 .\"
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)ip.4 8.2 (Berkeley) 11/30/93
31 .\"
32 .Dd July 19, 2009
33 .Dt IP 4
34 .Os
35 .Sh NAME
36 .Nm ip
37 .Nd Internet Protocol
38 .Sh SYNOPSIS
39 .In sys/socket.h
40 .In netinet/in.h
41 .Ft int
42 .Fn socket AF_INET SOCK_RAW proto
43 .Sh DESCRIPTION
44 .Tn IP
45 is the network layer protocol used by the Internet protocol family.
46 Options may be set at the
47 .Tn IP
48 level when using higher-level protocols that are based on
49 .Tn IP
50 (such as
51 .Tn TCP
52 and
53 .Tn UDP ) .
54 It may also be accessed through a
55 .Dq raw socket
56 when developing new protocols, or special-purpose applications.
57 .Pp
58 There are several
59 .Tn IP-level
60 .Xr setsockopt 2 Ns / Ns Xr getsockopt 2
61 options.
62 .Dv IP_OPTIONS
63 may be used to provide
64 .Tn IP
65 options to be transmitted in the
66 .Tn IP
67 header of each outgoing packet
68 or to examine the header options on incoming packets.
69 .Tn IP
70 options may be used with any socket type in the Internet family.
71 The format of
72 .Tn IP
73 options to be sent is that specified by the
74 .Tn IP
75 protocol specification (RFC 791), with one exception:
76 the list of addresses for Source Route options must include the first-hop
77 gateway at the beginning of the list of gateways.
78 The first-hop gateway address will be extracted from the option list
79 and the size adjusted accordingly before use.
80 To disable previously specified options, use a zero-length buffer:
81 .Bd -literal
82 setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0);
83 .Ed
84 .Pp
85 .Dv IP_TOS
86 and
87 .Dv IP_TTL
88 may be used to set the type-of-service and time-to-live fields in the
89 .Tn IP
90 header for
91 .Dv SOCK_STREAM
92 and
93 .Dv SOCK_DGRAM
94 sockets.
95 For example,
96 .Bd -literal
97 int tos = IPTOS_LOWDELAY; /* see \*[Lt]netinet/ip.h\*[Gt] */
98 setsockopt(s, IPPROTO_IP, IP_TOS, \*[Am]tos, sizeof(tos));
100 int ttl = 60; /* max = 255 */
101 setsockopt(s, IPPROTO_IP, IP_TTL, \*[Am]ttl, sizeof(ttl));
102 .Ed
103 .Pp
104 .Dv IP_IPSEC_POLICY
105 controls IPSec policy for sockets.
106 For example,
107 .Bd -literal
108 const char *policy = "in ipsec ah/transport//require";
109 char *buf = ipsec_set_policy(policy, strlen(policy));
110 setsockopt(s, IPPROTO_IP, IP_IPSEC_POLICY, buf, ipsec_get_policylen(buf));
111 .Ed
112 .Pp
113 .Dv IP_PORTRANGE
114 controls how ephemeral ports are allocated for
115 .Dv SOCK_STREAM
116 and
117 .Dv SOCK_DGRAM
118 sockets.
119 For example,
120 .Bd -literal
121 int range = IP_PORTRANGE_LOW; /* see \*[Lt]netinet/in.h\*[Gt] */
122 setsockopt(s, IPPROTO_IP, IP_PORTRANGE, \*[Am]range, sizeof(range));
123 .Ed
124 .Pp
125 If the
126 .Dv IP_RECVDSTADDR
127 option is enabled on a
128 .Dv SOCK_DGRAM
129 or
130 .Dv SOCK_RAW
131 socket,
132 the
133 .Xr recvmsg 2
134 call will return the destination
135 .Tn IP
136 address for a
137 .Tn UDP
138 datagram.
139 The msg_control field in the msghdr structure points to a buffer
140 that contains a cmsghdr structure followed by the
141 .Tn IP
142 address.
143 The cmsghdr fields have the following values:
144 .Bd -literal
145 cmsg_len = sizeof(struct in_addr)
146 cmsg_level = IPPROTO_IP
147 cmsg_type = IP_RECVDSTADDR
148 .Ed
149 .Pp
150 If the
151 .Dv IP_RECVIF
152 option is enabled on a
153 .Dv SOCK_DGRAM
154 or
155 .Dv SOCK_RAW
156 socket,
157 the
158 .Xr recvmsg 2
159 call will return a struct sockaddr_dl corresponding to
160 the interface on which the packet was received.
161 the msg_control field in the msghdr structure points to a buffer
162 that contains a cmsghdr structure followed by the struct sockaddr_dl.
163 The cmsghdr fields have the following values:
164 .Bd -literal
165 cmsg_len = sizeof(struct sockaddr_dl)
166 cmsg_level = IPPROTO_IP
167 cmsg_type = IP_RECVIF
168 .Ed
169 .Pp
170 If the
171 .Dv IP_RECVTTL
172 option is enabled on a
173 .Dv SOCK_DGRAM
174 socket, the
175 .Xr recvmsg 2
176 call will return the
177 .Tn TTL
178 of the received datagram.
179 The msg_control field in the msghdr structure points to a buffer
180 that contains a cmsghdr structure followed by the
181 .Tn TTL
182 value.
183 The cmsghdr fields have the following values:
184 .Bd -literal
185 cmsg_len = sizeof(uint8_t)
186 cmsg_level = IPPROTO_IP
187 cmsg_type = IP_RECVTTL
188 .Ed
189 .Pp
190 The
191 .Dv IP_MINTTL
192 option may be used on
193 .Dv SOCK_DGRAM
194 or
195 .Dv SOCK_STREAM
196 sockets to discard packets with a TTL lower than the option value.
197 This can be used to implement the
198 .Em Generalized TTL Security Mechanism (GTSM)
199 according to RFC 3682.
200 To discard all packets with a TTL lower than 255:
201 .Bd -literal -offset indent
202 int minttl = 255;
203 setsockopt(s, IPPROTO_IP, IP_MINTTL, \*[Am]minttl, sizeof(minttl));
204 .Ed
205 .Ss MULTICAST OPTIONS
206 .Tn IP
207 multicasting is supported only on
208 .Dv AF_INET
209 sockets of type
210 .Dv SOCK_DGRAM
211 and
212 .Dv SOCK_RAW ,
213 and only on networks where the interface driver supports multicasting.
214 .Pp
215 The
216 .Dv IP_MULTICAST_TTL
217 option changes the time-to-live (TTL) for outgoing multicast datagrams
218 in order to control the scope of the multicasts:
219 .Bd -literal
220 u_char ttl; /* range: 0 to 255, default = 1 */
221 setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, \*[Am]ttl, sizeof(ttl));
222 .Ed
223 .Pp
224 Datagrams with a TTL of 1 are not forwarded beyond the local network.
225 Multicast datagrams with a TTL of 0 will not be transmitted on any network,
226 but may be delivered locally if the sending host belongs to the destination
227 group and if multicast loopback has not been disabled on the sending socket
228 (see below).
229 Multicast datagrams with TTL greater than 1 may be forwarded
230 to other networks if a multicast router is attached to the local network.
231 .Pp
232 For hosts with multiple interfaces, each multicast transmission is
233 sent from the primary network interface.
234 The
235 .Dv IP_MULTICAST_IF
236 option overrides the default for
237 subsequent transmissions from a given socket:
238 .Bd -literal
239 struct in_addr addr;
240 setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]addr, sizeof(addr));
241 .Ed
242 .Pp
243 where "addr" is the local
244 .Tn IP
245 address of the desired interface or
246 .Dv INADDR_ANY
247 to specify the default interface.
248 An interface's local IP address and multicast capability can
249 be obtained via the
250 .Dv SIOCGIFCONF
251 and
252 .Dv SIOCGIFFLAGS
253 ioctls.
254 An application may also specify an alternative to the default network interface
255 by index:
256 .Bd -literal
257 struct uint32_t idx = htonl(ifindex);
258 setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]idx, sizeof(idx));
259 .Ed
260 .Pp
261 where "ifindex" is an interface index as returned by
262 .Xr if_nametoindex 3 .
263 .Pp
264 Normal applications should not need to use
265 .Dv IP_MULTICAST_IF .
266 .Pp
267 If a multicast datagram is sent to a group to which the sending host itself
268 belongs (on the outgoing interface), a copy of the datagram is, by default,
269 looped back by the IP layer for local delivery.
270 The
271 .Dv IP_MULTICAST_LOOP
272 option gives the sender explicit control
273 over whether or not subsequent datagrams are looped back:
274 .Bd -literal
275 u_char loop; /* 0 = disable, 1 = enable (default) */
276 setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, \*[Am]loop, sizeof(loop));
277 .Ed
278 .Pp
279 This option
280 improves performance for applications that may have no more than one
281 instance on a single host (such as a router demon), by eliminating
282 the overhead of receiving their own transmissions.
283 It should generally not be used by applications for which there
284 may be more than one instance on a single host (such as a conferencing
285 program) or for which the sender does not belong to the destination
286 group (such as a time querying program).
287 .Pp
288 A multicast datagram sent with an initial TTL greater than 1 may be delivered
289 to the sending host on a different interface from that on which it was sent,
290 if the host belongs to the destination group on that other interface.
291 The loopback control option has no effect on such delivery.
292 .Pp
293 A host must become a member of a multicast group before it can receive
294 datagrams sent to the group.
295 To join a multicast group, use the
296 .Dv IP_ADD_MEMBERSHIP
297 option:
298 .Bd -literal
299 struct ip_mreq mreq;
300 setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, \*[Am]mreq, sizeof(mreq));
301 .Ed
302 .Pp
303 where
304 .Fa mreq
305 is the following structure:
306 .Bd -literal
307 struct ip_mreq {
308 struct in_addr imr_multiaddr; /* multicast group to join */
309 struct in_addr imr_interface; /* interface to join on */
310 }
311 .Ed
312 .Pp
313 .Dv imr_interface
314 should be
315 .Dv INADDR_ANY
316 to choose the default multicast interface, or the
317 .Tn IP
318 address of a particular multicast-capable interface if
319 the host is multihomed.
320 Membership is associated with a single interface;
321 programs running on multihomed hosts may need to
322 join the same group on more than one interface.
323 Up to
324 .Dv IP_MAX_MEMBERSHIPS
325 (currently 20) memberships may be added on a single socket.
326 .Pp
327 To drop a membership, use:
328 .Bd -literal
329 struct ip_mreq mreq;
330 setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, \*[Am]mreq, sizeof(mreq));
331 .Ed
332 .Pp
333 where
334 .Fa mreq
335 contains the same values as used to add the membership.
336 Memberships are dropped when the socket is closed or the process exits.
337 .\"-----------------------
338 .Ss RAW IP SOCKETS
339 Raw
340 .Tn IP
341 sockets are connectionless, and are normally used with the
342 .Xr sendto 2
343 and
344 .Xr recvfrom 2
345 calls, though the
346 .Xr connect 2
347 call may also be used to fix the destination for future
348 packets (in which case the
349 .Xr read 2
350 or
351 .Xr recv 2
352 and
353 .Xr write 2
354 or
355 .Xr send 2
356 system calls may be used).
357 .Pp
358 If
359 .Fa proto
360 is 0, the default protocol
361 .Dv IPPROTO_RAW
362 is used for outgoing packets, and only incoming packets destined
363 for that protocol are received.
364 If
365 .Fa proto
366 is non-zero, that protocol number will be used on outgoing packets
367 and to filter incoming packets.
368 .Pp
369 Outgoing packets automatically have an
370 .Tn IP
371 header prepended to them (based on the destination address and the
372 protocol number the socket is created with), unless the
373 .Dv IP_HDRINCL
374 option has been set.
375 Incoming packets are received with
376 .Tn IP
377 header and options intact.
378 .Pp
379 .Dv IP_HDRINCL
380 indicates the complete IP header is included with the data and may
381 be used only with the
382 .Dv SOCK_RAW
383 type.
384 .Bd -literal
385 #include \*[Lt]netinet/ip.h\*[Gt]
387 int hincl = 1; /* 1 = on, 0 = off */
388 setsockopt(s, IPPROTO_IP, IP_HDRINCL, \*[Am]hincl, sizeof(hincl));
389 .Ed
390 .Pp
391 Unlike previous
392 .Bx
393 releases, the program must set all
394 the fields of the IP header, including the following:
395 .Bd -literal
396 ip-\*[Gt]ip_v = IPVERSION;
397 ip-\*[Gt]ip_hl = hlen \*[Gt]\*[Gt] 2;
398 ip-\*[Gt]ip_id = 0; /* 0 means kernel set appropriate value */
399 ip-\*[Gt]ip_off = offset;
400 .Ed
401 .Pp
402 If the header source address is set to
403 .Dv INADDR_ANY ,
404 the kernel will choose an appropriate address.
405 .Sh DIAGNOSTICS
406 A socket operation may fail with one of the following errors returned:
407 .Bl -tag -width [EADDRNOTAVAIL]
408 .It Bq Er EISCONN
409 when trying to establish a connection on a socket which already
410 has one, or when trying to send a datagram with the destination
411 address specified and the socket is already connected;
412 .It Bq Er ENOTCONN
413 when trying to send a datagram, but no destination address is
414 specified, and the socket hasn't been connected;
415 .It Bq Er ENOBUFS
416 when the system runs out of memory for an internal data structure;
417 .It Bq Er EADDRNOTAVAIL
418 when an attempt is made to create a socket with a network address
419 for which no network interface exists.
420 .It Bq Er EACCES
421 when an attempt is made to create a raw IP socket by a non-privileged process.
422 .El
423 .Pp
424 The following errors specific to
425 .Tn IP
426 may occur when setting or getting
427 .Tn IP
428 options:
429 .Bl -tag -width EADDRNOTAVAILxx
430 .It Bq Er EINVAL
431 An unknown socket option name was given.
432 .It Bq Er EINVAL
433 The IP option field was improperly formed; an option field was
434 shorter than the minimum value or longer than the option buffer provided.
435 .El
436 .Sh SEE ALSO
437 .Xr getsockopt 2 ,
438 .Xr recv 2 ,
439 .Xr send 2 ,
440 .Xr ipsec_set_policy 3 ,
441 .Xr icmp 4 ,
442 .Xr inet 4 ,
443 .Xr intro 4
444 .Rs
445 .%R RFC
446 .%N 791
447 .%D September 1981
448 .%T "Internet Protocol"
449 .Re
450 .Rs
451 .%R RFC
452 .%N 1112
453 .%D August 1989
454 .%T "Host Extensions for IP Multicasting"
455 .Re
456 .Rs
457 .%R RFC
458 .%N 1122
459 .%D October 1989
460 .%T "Requirements for Internet Hosts -- Communication Layers"
461 .Re
462 .Sh HISTORY
463 The
464 .Nm
465 protocol appeared in
466 .Bx 4.2 .