1.\" $NetBSD: ip.4,v 1.33 2012/06/25 14:47:55 christos 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 June 25, 2012 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 113The 114.Dv IP_PORTALGO 115can be used to randomize the port selection. 116Valid algorithms are described in 117.Xr rfc6056 7 118and their respective constants are in 119.In netinet/portalgo.h . 120For example, 121.Bd -literal 122int algo = PORTALGO_ALGO_RANDOM_PICK; /* see \*[Lt]netinet/portalgo.h\*[Gt] */ 123setsockopt(s, IPPROTO_IP, IP_PORTALGO, \*[Am]algo, sizeof(algo)); 124.Ed 125.Pp 126The port selection can be also viewed and controlled at a global level for all 127.Tn IP 128sockets using the following 129.Xr sysctl 7 130variables: 131.Dv net.inet.ip.anonportalgo.available 132and 133.Dv net.inet.ip.anonportalgo.selected . 134.Pp 135.Dv IP_PORTRANGE 136controls how ephemeral ports are allocated for 137.Dv SOCK_STREAM 138and 139.Dv SOCK_DGRAM 140sockets. 141For example, 142.Bd -literal 143int range = IP_PORTRANGE_LOW; /* see \*[Lt]netinet/in.h\*[Gt] */ 144setsockopt(s, IPPROTO_IP, IP_PORTRANGE, \*[Am]range, sizeof(range)); 145.Ed 146.Pp 147If the 148.Dv IP_RECVDSTADDR 149option is enabled on a 150.Dv SOCK_DGRAM 151or 152.Dv SOCK_RAW 153socket, 154the 155.Xr recvmsg 2 156call will return the destination 157.Tn IP 158address for a 159.Tn UDP 160datagram. 161The msg_control field in the msghdr structure points to a buffer 162that contains a cmsghdr structure followed by the 163.Tn IP 164address. 165The cmsghdr fields have the following values: 166.Bd -literal 167cmsg_len = CMSG_LEN(sizeof(struct in_addr)) 168cmsg_level = IPPROTO_IP 169cmsg_type = IP_RECVDSTADDR 170.Ed 171.Pp 172If the 173.Dv IP_RECVIF 174option is enabled on a 175.Dv SOCK_DGRAM 176or 177.Dv SOCK_RAW 178socket, 179the 180.Xr recvmsg 2 181call will return a struct sockaddr_dl corresponding to 182the interface on which the packet was received. 183the msg_control field in the msghdr structure points to a buffer 184that contains a cmsghdr structure followed by the struct sockaddr_dl. 185The cmsghdr fields have the following values: 186.Bd -literal 187cmsg_len = CMSG_LEN(sizeof(struct sockaddr_dl)) 188cmsg_level = IPPROTO_IP 189cmsg_type = IP_RECVIF 190.Ed 191.Pp 192If the 193.Dv IP_RECVTTL 194option is enabled on a 195.Dv SOCK_DGRAM 196socket, the 197.Xr recvmsg 2 198call will return the 199.Tn TTL 200of the received datagram. 201The msg_control field in the msghdr structure points to a buffer 202that contains a cmsghdr structure followed by the 203.Tn TTL 204value. 205The cmsghdr fields have the following values: 206.Bd -literal 207cmsg_len = CMSG_LEN(sizeof(uint8_t)) 208cmsg_level = IPPROTO_IP 209cmsg_type = IP_RECVTTL 210.Ed 211.Pp 212The 213.Dv IP_MINTTL 214option may be used on 215.Dv SOCK_DGRAM 216or 217.Dv SOCK_STREAM 218sockets to discard packets with a TTL lower than the option value. 219This can be used to implement the 220.Em Generalized TTL Security Mechanism (GTSM) 221according to RFC 3682. 222To discard all packets with a TTL lower than 255: 223.Bd -literal -offset indent 224int minttl = 255; 225setsockopt(s, IPPROTO_IP, IP_MINTTL, \*[Am]minttl, sizeof(minttl)); 226.Ed 227.Ss MULTICAST OPTIONS 228.Tn IP 229multicasting is supported only on 230.Dv AF_INET 231sockets of type 232.Dv SOCK_DGRAM 233and 234.Dv SOCK_RAW , 235and only on networks where the interface driver supports multicasting. 236.Pp 237The 238.Dv IP_MULTICAST_TTL 239option changes the time-to-live (TTL) for outgoing multicast datagrams 240in order to control the scope of the multicasts: 241.Bd -literal 242u_char ttl; /* range: 0 to 255, default = 1 */ 243setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, \*[Am]ttl, sizeof(ttl)); 244.Ed 245.Pp 246Datagrams with a TTL of 1 are not forwarded beyond the local network. 247Multicast datagrams with a TTL of 0 will not be transmitted on any network, 248but may be delivered locally if the sending host belongs to the destination 249group and if multicast loopback has not been disabled on the sending socket 250(see below). 251Multicast datagrams with TTL greater than 1 may be forwarded 252to other networks if a multicast router is attached to the local network. 253.Pp 254For hosts with multiple interfaces, each multicast transmission is 255sent from the primary network interface. 256The 257.Dv IP_MULTICAST_IF 258option overrides the default for 259subsequent transmissions from a given socket: 260.Bd -literal 261struct in_addr addr; 262setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]addr, sizeof(addr)); 263.Ed 264.Pp 265where "addr" is the local 266.Tn IP 267address of the desired interface or 268.Dv INADDR_ANY 269to specify the default interface. 270An interface's local IP address and multicast capability can 271be obtained via the 272.Dv SIOCGIFCONF 273and 274.Dv SIOCGIFFLAGS 275ioctls. 276An application may also specify an alternative to the default network interface 277by index: 278.Bd -literal 279struct uint32_t idx = htonl(ifindex); 280setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]idx, sizeof(idx)); 281.Ed 282.Pp 283where "ifindex" is an interface index as returned by 284.Xr if_nametoindex 3 . 285.Pp 286Normal applications should not need to use 287.Dv IP_MULTICAST_IF . 288.Pp 289If a multicast datagram is sent to a group to which the sending host itself 290belongs (on the outgoing interface), a copy of the datagram is, by default, 291looped back by the IP layer for local delivery. 292The 293.Dv IP_MULTICAST_LOOP 294option gives the sender explicit control 295over whether or not subsequent datagrams are looped back: 296.Bd -literal 297u_char loop; /* 0 = disable, 1 = enable (default) */ 298setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, \*[Am]loop, sizeof(loop)); 299.Ed 300.Pp 301This option 302improves performance for applications that may have no more than one 303instance on a single host (such as a router demon), by eliminating 304the overhead of receiving their own transmissions. 305It should generally not be used by applications for which there 306may be more than one instance on a single host (such as a conferencing 307program) or for which the sender does not belong to the destination 308group (such as a time querying program). 309.Pp 310A multicast datagram sent with an initial TTL greater than 1 may be delivered 311to the sending host on a different interface from that on which it was sent, 312if the host belongs to the destination group on that other interface. 313The loopback control option has no effect on such delivery. 314.Pp 315A host must become a member of a multicast group before it can receive 316datagrams sent to the group. 317To join a multicast group, use the 318.Dv IP_ADD_MEMBERSHIP 319option: 320.Bd -literal 321struct ip_mreq mreq; 322setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, \*[Am]mreq, sizeof(mreq)); 323.Ed 324.Pp 325where 326.Fa mreq 327is the following structure: 328.Bd -literal 329struct ip_mreq { 330 struct in_addr imr_multiaddr; /* multicast group to join */ 331 struct in_addr imr_interface; /* interface to join on */ 332} 333.Ed 334.Pp 335.Dv imr_interface 336should be 337.Dv INADDR_ANY 338to choose the default multicast interface, or the 339.Tn IP 340address of a particular multicast-capable interface if 341the host is multihomed. 342Membership is associated with a single interface; 343programs running on multihomed hosts may need to 344join the same group on more than one interface. 345Up to 346.Dv IP_MAX_MEMBERSHIPS 347(currently 20) memberships may be added on a single socket. 348.Pp 349To drop a membership, use: 350.Bd -literal 351struct ip_mreq mreq; 352setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, \*[Am]mreq, sizeof(mreq)); 353.Ed 354.Pp 355where 356.Fa mreq 357contains the same values as used to add the membership. 358Memberships are dropped when the socket is closed or the process exits. 359.\"----------------------- 360.Ss RAW IP SOCKETS 361Raw 362.Tn IP 363sockets are connectionless, and are normally used with the 364.Xr sendto 2 365and 366.Xr recvfrom 2 367calls, though the 368.Xr connect 2 369call may also be used to fix the destination for future 370packets (in which case the 371.Xr read 2 372or 373.Xr recv 2 374and 375.Xr write 2 376or 377.Xr send 2 378system calls may be used). 379.Pp 380If 381.Fa proto 382is 0, the default protocol 383.Dv IPPROTO_RAW 384is used for outgoing packets, and only incoming packets destined 385for that protocol are received. 386If 387.Fa proto 388is non-zero, that protocol number will be used on outgoing packets 389and to filter incoming packets. 390.Pp 391Outgoing packets automatically have an 392.Tn IP 393header prepended to them (based on the destination address and the 394protocol number the socket is created with), unless the 395.Dv IP_HDRINCL 396option has been set. 397Incoming packets are received with 398.Tn IP 399header and options intact. 400.Pp 401.Dv IP_HDRINCL 402indicates the complete IP header is included with the data and may 403be used only with the 404.Dv SOCK_RAW 405type. 406.Bd -literal 407#include \*[Lt]netinet/ip.h\*[Gt] 408 409int hincl = 1; /* 1 = on, 0 = off */ 410setsockopt(s, IPPROTO_IP, IP_HDRINCL, \*[Am]hincl, sizeof(hincl)); 411.Ed 412.Pp 413Unlike previous 414.Bx 415releases, the program must set all 416the fields of the IP header, including the following: 417.Bd -literal 418ip-\*[Gt]ip_v = IPVERSION; 419ip-\*[Gt]ip_hl = hlen \*[Gt]\*[Gt] 2; 420ip-\*[Gt]ip_id = 0; /* 0 means kernel set appropriate value */ 421ip-\*[Gt]ip_off = offset; 422.Ed 423.Pp 424If the header source address is set to 425.Dv INADDR_ANY , 426the kernel will choose an appropriate address. 427.Sh DIAGNOSTICS 428A socket operation may fail with one of the following errors returned: 429.Bl -tag -width [EADDRNOTAVAIL] 430.It Bq Er EISCONN 431when trying to establish a connection on a socket which already 432has one, or when trying to send a datagram with the destination 433address specified and the socket is already connected; 434.It Bq Er ENOTCONN 435when trying to send a datagram, but no destination address is 436specified, and the socket hasn't been connected; 437.It Bq Er ENOBUFS 438when the system runs out of memory for an internal data structure; 439.It Bq Er EADDRNOTAVAIL 440when an attempt is made to create a socket with a network address 441for which no network interface exists. 442.It Bq Er EACCES 443when an attempt is made to create a raw IP socket by a non-privileged process. 444.El 445.Pp 446The following errors specific to 447.Tn IP 448may occur when setting or getting 449.Tn IP 450options: 451.Bl -tag -width EADDRNOTAVAILxx 452.It Bq Er EINVAL 453An unknown socket option name was given. 454.It Bq Er EINVAL 455The IP option field was improperly formed; an option field was 456shorter than the minimum value or longer than the option buffer provided. 457.El 458.Sh SEE ALSO 459.Xr getsockopt 2 , 460.Xr recv 2 , 461.Xr send 2 , 462.Xr CMSG_DATA 3 , 463.Xr ipsec_set_policy 3 , 464.Xr icmp 4 , 465.Xr inet 4 , 466.Xr intro 4 467.Rs 468.%R RFC 469.%N 791 470.%D September 1981 471.%T "Internet Protocol" 472.Re 473.Rs 474.%R RFC 475.%N 1112 476.%D August 1989 477.%T "Host Extensions for IP Multicasting" 478.Re 479.Rs 480.%R RFC 481.%N 1122 482.%D October 1989 483.%T "Requirements for Internet Hosts -- Communication Layers" 484.Re 485.Sh HISTORY 486The 487.Nm 488protocol appeared in 489.Bx 4.2 . 490