1.\" $NetBSD: ip.4,v 1.30 2009/07/20 07:58:54 wiz 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 45is the network layer protocol used by the Internet protocol family. 46Options may be set at the 47.Tn IP 48level when using higher-level protocols that are based on 49.Tn IP 50(such as 51.Tn TCP 52and 53.Tn UDP ) . 54It may also be accessed through a 55.Dq raw socket 56when developing new protocols, or special-purpose applications. 57.Pp 58There are several 59.Tn IP-level 60.Xr setsockopt 2 Ns / Ns Xr getsockopt 2 61options. 62.Dv IP_OPTIONS 63may be used to provide 64.Tn IP 65options to be transmitted in the 66.Tn IP 67header of each outgoing packet 68or to examine the header options on incoming packets. 69.Tn IP 70options may be used with any socket type in the Internet family. 71The format of 72.Tn IP 73options to be sent is that specified by the 74.Tn IP 75protocol specification (RFC 791), with one exception: 76the list of addresses for Source Route options must include the first-hop 77gateway at the beginning of the list of gateways. 78The first-hop gateway address will be extracted from the option list 79and the size adjusted accordingly before use. 80To disable previously specified options, use a zero-length buffer: 81.Bd -literal 82setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0); 83.Ed 84.Pp 85.Dv IP_TOS 86and 87.Dv IP_TTL 88may be used to set the type-of-service and time-to-live fields in the 89.Tn IP 90header for 91.Dv SOCK_STREAM 92and 93.Dv SOCK_DGRAM 94sockets. 95For example, 96.Bd -literal 97int tos = IPTOS_LOWDELAY; /* see \*[Lt]netinet/ip.h\*[Gt] */ 98setsockopt(s, IPPROTO_IP, IP_TOS, \*[Am]tos, sizeof(tos)); 99 100int ttl = 60; /* max = 255 */ 101setsockopt(s, IPPROTO_IP, IP_TTL, \*[Am]ttl, sizeof(ttl)); 102.Ed 103.Pp 104.Dv IP_IPSEC_POLICY 105controls IPSec policy for sockets. 106For example, 107.Bd -literal 108const char *policy = "in ipsec ah/transport//require"; 109char *buf = ipsec_set_policy(policy, strlen(policy)); 110setsockopt(s, IPPROTO_IP, IP_IPSEC_POLICY, buf, ipsec_get_policylen(buf)); 111.Ed 112.Pp 113.Dv IP_PORTRANGE 114controls how ephemeral ports are allocated for 115.Dv SOCK_STREAM 116and 117.Dv SOCK_DGRAM 118sockets. 119For example, 120.Bd -literal 121int range = IP_PORTRANGE_LOW; /* see \*[Lt]netinet/in.h\*[Gt] */ 122setsockopt(s, IPPROTO_IP, IP_PORTRANGE, \*[Am]range, sizeof(range)); 123.Ed 124.Pp 125If the 126.Dv IP_RECVDSTADDR 127option is enabled on a 128.Dv SOCK_DGRAM 129or 130.Dv SOCK_RAW 131socket, 132the 133.Xr recvmsg 2 134call will return the destination 135.Tn IP 136address for a 137.Tn UDP 138datagram. 139The msg_control field in the msghdr structure points to a buffer 140that contains a cmsghdr structure followed by the 141.Tn IP 142address. 143The cmsghdr fields have the following values: 144.Bd -literal 145cmsg_len = sizeof(struct in_addr) 146cmsg_level = IPPROTO_IP 147cmsg_type = IP_RECVDSTADDR 148.Ed 149.Pp 150If the 151.Dv IP_RECVIF 152option is enabled on a 153.Dv SOCK_DGRAM 154or 155.Dv SOCK_RAW 156socket, 157the 158.Xr recvmsg 2 159call will return a struct sockaddr_dl corresponding to 160the interface on which the packet was received. 161the msg_control field in the msghdr structure points to a buffer 162that contains a cmsghdr structure followed by the struct sockaddr_dl. 163The cmsghdr fields have the following values: 164.Bd -literal 165cmsg_len = sizeof(struct sockaddr_dl) 166cmsg_level = IPPROTO_IP 167cmsg_type = IP_RECVIF 168.Ed 169.Pp 170If the 171.Dv IP_RECVTTL 172option is enabled on a 173.Dv SOCK_DGRAM 174socket, the 175.Xr recvmsg 2 176call will return the 177.Tn TTL 178of the received datagram. 179The msg_control field in the msghdr structure points to a buffer 180that contains a cmsghdr structure followed by the 181.Tn TTL 182value. 183The cmsghdr fields have the following values: 184.Bd -literal 185cmsg_len = sizeof(uint8_t) 186cmsg_level = IPPROTO_IP 187cmsg_type = IP_RECVTTL 188.Ed 189.Pp 190The 191.Dv IP_MINTTL 192option may be used on 193.Dv SOCK_DGRAM 194or 195.Dv SOCK_STREAM 196sockets to discard packets with a TTL lower than the option value. 197This can be used to implement the 198.Em Generalized TTL Security Mechanism (GTSM) 199according to RFC 3682. 200To discard all packets with a TTL lower than 255: 201.Bd -literal -offset indent 202int minttl = 255; 203setsockopt(s, IPPROTO_IP, IP_MINTTL, \*[Am]minttl, sizeof(minttl)); 204.Ed 205.Ss MULTICAST OPTIONS 206.Tn IP 207multicasting is supported only on 208.Dv AF_INET 209sockets of type 210.Dv SOCK_DGRAM 211and 212.Dv SOCK_RAW , 213and only on networks where the interface driver supports multicasting. 214.Pp 215The 216.Dv IP_MULTICAST_TTL 217option changes the time-to-live (TTL) for outgoing multicast datagrams 218in order to control the scope of the multicasts: 219.Bd -literal 220u_char ttl; /* range: 0 to 255, default = 1 */ 221setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, \*[Am]ttl, sizeof(ttl)); 222.Ed 223.Pp 224Datagrams with a TTL of 1 are not forwarded beyond the local network. 225Multicast datagrams with a TTL of 0 will not be transmitted on any network, 226but may be delivered locally if the sending host belongs to the destination 227group and if multicast loopback has not been disabled on the sending socket 228(see below). 229Multicast datagrams with TTL greater than 1 may be forwarded 230to other networks if a multicast router is attached to the local network. 231.Pp 232For hosts with multiple interfaces, each multicast transmission is 233sent from the primary network interface. 234The 235.Dv IP_MULTICAST_IF 236option overrides the default for 237subsequent transmissions from a given socket: 238.Bd -literal 239struct in_addr addr; 240setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]addr, sizeof(addr)); 241.Ed 242.Pp 243where "addr" is the local 244.Tn IP 245address of the desired interface or 246.Dv INADDR_ANY 247to specify the default interface. 248An interface's local IP address and multicast capability can 249be obtained via the 250.Dv SIOCGIFCONF 251and 252.Dv SIOCGIFFLAGS 253ioctls. 254An application may also specify an alternative to the default network interface 255by index: 256.Bd -literal 257struct uint32_t idx = htonl(ifindex); 258setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]idx, sizeof(idx)); 259.Ed 260.Pp 261where "ifindex" is an interface index as returned by 262.Xr if_nametoindex 3 . 263.Pp 264Normal applications should not need to use 265.Dv IP_MULTICAST_IF . 266.Pp 267If a multicast datagram is sent to a group to which the sending host itself 268belongs (on the outgoing interface), a copy of the datagram is, by default, 269looped back by the IP layer for local delivery. 270The 271.Dv IP_MULTICAST_LOOP 272option gives the sender explicit control 273over whether or not subsequent datagrams are looped back: 274.Bd -literal 275u_char loop; /* 0 = disable, 1 = enable (default) */ 276setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, \*[Am]loop, sizeof(loop)); 277.Ed 278.Pp 279This option 280improves performance for applications that may have no more than one 281instance on a single host (such as a router demon), by eliminating 282the overhead of receiving their own transmissions. 283It should generally not be used by applications for which there 284may be more than one instance on a single host (such as a conferencing 285program) or for which the sender does not belong to the destination 286group (such as a time querying program). 287.Pp 288A multicast datagram sent with an initial TTL greater than 1 may be delivered 289to the sending host on a different interface from that on which it was sent, 290if the host belongs to the destination group on that other interface. 291The loopback control option has no effect on such delivery. 292.Pp 293A host must become a member of a multicast group before it can receive 294datagrams sent to the group. 295To join a multicast group, use the 296.Dv IP_ADD_MEMBERSHIP 297option: 298.Bd -literal 299struct ip_mreq mreq; 300setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, \*[Am]mreq, sizeof(mreq)); 301.Ed 302.Pp 303where 304.Fa mreq 305is the following structure: 306.Bd -literal 307struct 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 314should be 315.Dv INADDR_ANY 316to choose the default multicast interface, or the 317.Tn IP 318address of a particular multicast-capable interface if 319the host is multihomed. 320Membership is associated with a single interface; 321programs running on multihomed hosts may need to 322join the same group on more than one interface. 323Up to 324.Dv IP_MAX_MEMBERSHIPS 325(currently 20) memberships may be added on a single socket. 326.Pp 327To drop a membership, use: 328.Bd -literal 329struct ip_mreq mreq; 330setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, \*[Am]mreq, sizeof(mreq)); 331.Ed 332.Pp 333where 334.Fa mreq 335contains the same values as used to add the membership. 336Memberships are dropped when the socket is closed or the process exits. 337.\"----------------------- 338.Ss RAW IP SOCKETS 339Raw 340.Tn IP 341sockets are connectionless, and are normally used with the 342.Xr sendto 2 343and 344.Xr recvfrom 2 345calls, though the 346.Xr connect 2 347call may also be used to fix the destination for future 348packets (in which case the 349.Xr read 2 350or 351.Xr recv 2 352and 353.Xr write 2 354or 355.Xr send 2 356system calls may be used). 357.Pp 358If 359.Fa proto 360is 0, the default protocol 361.Dv IPPROTO_RAW 362is used for outgoing packets, and only incoming packets destined 363for that protocol are received. 364If 365.Fa proto 366is non-zero, that protocol number will be used on outgoing packets 367and to filter incoming packets. 368.Pp 369Outgoing packets automatically have an 370.Tn IP 371header prepended to them (based on the destination address and the 372protocol number the socket is created with), unless the 373.Dv IP_HDRINCL 374option has been set. 375Incoming packets are received with 376.Tn IP 377header and options intact. 378.Pp 379.Dv IP_HDRINCL 380indicates the complete IP header is included with the data and may 381be used only with the 382.Dv SOCK_RAW 383type. 384.Bd -literal 385#include \*[Lt]netinet/ip.h\*[Gt] 386 387int hincl = 1; /* 1 = on, 0 = off */ 388setsockopt(s, IPPROTO_IP, IP_HDRINCL, \*[Am]hincl, sizeof(hincl)); 389.Ed 390.Pp 391Unlike previous 392.Bx 393releases, the program must set all 394the fields of the IP header, including the following: 395.Bd -literal 396ip-\*[Gt]ip_v = IPVERSION; 397ip-\*[Gt]ip_hl = hlen \*[Gt]\*[Gt] 2; 398ip-\*[Gt]ip_id = 0; /* 0 means kernel set appropriate value */ 399ip-\*[Gt]ip_off = offset; 400.Ed 401.Pp 402If the header source address is set to 403.Dv INADDR_ANY , 404the kernel will choose an appropriate address. 405.Sh DIAGNOSTICS 406A socket operation may fail with one of the following errors returned: 407.Bl -tag -width [EADDRNOTAVAIL] 408.It Bq Er EISCONN 409when trying to establish a connection on a socket which already 410has one, or when trying to send a datagram with the destination 411address specified and the socket is already connected; 412.It Bq Er ENOTCONN 413when trying to send a datagram, but no destination address is 414specified, and the socket hasn't been connected; 415.It Bq Er ENOBUFS 416when the system runs out of memory for an internal data structure; 417.It Bq Er EADDRNOTAVAIL 418when an attempt is made to create a socket with a network address 419for which no network interface exists. 420.It Bq Er EACCES 421when an attempt is made to create a raw IP socket by a non-privileged process. 422.El 423.Pp 424The following errors specific to 425.Tn IP 426may occur when setting or getting 427.Tn IP 428options: 429.Bl -tag -width EADDRNOTAVAILxx 430.It Bq Er EINVAL 431An unknown socket option name was given. 432.It Bq Er EINVAL 433The IP option field was improperly formed; an option field was 434shorter 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 463The 464.Nm 465protocol appeared in 466.Bx 4.2 . 467