1.\" $OpenBSD: ip.4,v 1.41 2016/08/18 11:45:18 jmc Exp $ 2.\" $NetBSD: ip.4,v 1.3 1994/11/30 16:22:19 jtc Exp $ 3.\" 4.\" Copyright (c) 1983, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)ip.4 8.2 (Berkeley) 11/30/93 32.\" 33.Dd $Mdocdate: August 18 2016 $ 34.Dt IP 4 35.Os 36.Sh NAME 37.Nm ip 38.Nd Internet Protocol 39.Sh SYNOPSIS 40.In sys/types.h 41.In sys/socket.h 42.In netinet/in.h 43.Ft int 44.Fn socket AF_INET SOCK_RAW proto 45.Sh DESCRIPTION 46.Tn IP 47is the network layer protocol used 48by the Internet protocol family. 49Options may be set at the 50.Tn IP 51level 52when using higher-level protocols that are based on 53.Tn IP 54(such as 55.Tn TCP 56and 57.Tn UDP ) . 58It may also be accessed 59through a 60.Dq raw socket 61when developing new protocols, or 62special-purpose applications. 63.Pp 64There are several 65.Tn IP-level 66.Xr setsockopt 2 Ns / Ns Xr getsockopt 2 67options. 68.Dv IP_OPTIONS 69may be used to provide 70.Tn IP 71options to be transmitted in the 72.Tn IP 73header of each outgoing packet 74or to examine the header options on incoming packets. 75.Tn IP 76options may be used with any socket type in the Internet family. 77The format of 78.Tn IP 79options to be sent is that specified by the 80.Tn IP 81protocol specification (RFC 791), with one exception: 82the list of addresses for Source Route options must include the first-hop 83gateway at the beginning of the list of gateways. 84The first-hop gateway address will be extracted from the option list 85and the size adjusted accordingly before use. 86To disable previously specified options, 87use a zero-length buffer: 88.Bd -literal -offset indent 89setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0); 90.Ed 91.Pp 92.Dv IP_TOS 93and 94.Dv IP_TTL 95may be used to set the type-of-service and time-to-live 96fields in the 97.Tn IP 98header for 99.Dv SOCK_STREAM , 100.Dv SOCK_DGRAM 101and 102.Dv SOCK_RAW 103sockets. 104For example, 105.Bd -literal -offset indent 106int tos = IPTOS_LOWDELAY; /* see <netinet/ip.h> */ 107setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); 108 109int ttl = 60; /* max = 255 */ 110setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl)); 111.Ed 112.Pp 113.Dv IP_IPDEFTTL 114can be used to retrieve the system wide default TTL. 115.Pp 116If the 117.Dv IP_RECVDSTADDR 118option is enabled on a 119.Dv SOCK_DGRAM 120socket, 121the 122.Xr recvmsg 2 123call will return the destination 124.Tn IP 125address for a 126.Tn UDP 127datagram. 128The 129.Va msg_control 130field in the 131.Vt msghdr 132structure points to a buffer that contains a 133.Vt cmsghdr 134structure followed by the 135.Tn IP 136address. 137The 138.Vt cmsghdr 139fields have the following values: 140.Bd -literal -offset indent 141cmsg_len = CMSG_LEN(sizeof(struct in_addr)) 142cmsg_level = IPPROTO_IP 143cmsg_type = IP_RECVDSTADDR 144.Ed 145.Pp 146If the 147.Dv IP_RECVDSTPORT 148option is enabled on a 149.Dv SOCK_DGRAM 150socket, 151the 152.Xr recvmsg 2 153call will return the destination 154port for a 155.Tn UDP 156datagram. 157The 158.Va msg_control 159field in the 160.Vt msghdr 161structure points to a buffer that contains a 162.Vt cmsghdr 163structure followed by the port in 16-bit network byte order. 164The 165.Vt cmsghdr 166fields have the following values: 167.Bd -literal -offset indent 168cmsg_len = CMSG_LEN(sizeof(u_int16_t)) 169cmsg_level = IPPROTO_IP 170cmsg_type = IP_RECVDSTPORT 171.Ed 172.Pp 173If the 174.Dv IP_RECVTTL 175option is enabled on a 176.Dv SOCK_DGRAM 177or 178.Dv SOCK_RAW 179socket, the 180.Xr recvmsg 2 181call will return the 182.Tn TTL 183of the received datagram. 184The 185.Va msg_control 186field in the 187.Vt msghdr 188structure points to a buffer that contains a 189.Vt cmsghdr 190structure followed by the 191.Tn TTL 192value. 193The 194.Vt cmsghdr 195fields have the following values: 196.Bd -literal -offset indent 197cmsg_len = CMSG_LEN(sizeof(u_int8_t)) 198cmsg_level = IPPROTO_IP 199cmsg_type = IP_RECVTTL 200.Ed 201.Pp 202The 203.Dv IP_MINTTL 204option may be used on TCP and UDP sockets to discard packets with a TTL 205lower than the option value. 206This can be used to implement the 207.Em Generalized TTL Security Mechanism (GTSM) 208according to RFC 5082. 209To discard all packets with a TTL lower than 255: 210.Bd -literal -offset indent 211int minttl = 255; 212setsockopt(s, IPPROTO_IP, IP_MINTTL, &minttl, sizeof(minttl)); 213.Ed 214.Pp 215If the 216.Dv IP_IPSECFLOWINFO 217option is enabled on a 218.Dv SOCK_DGRAM 219socket, 220the 221.Xr recvmsg 2 222call will return information identifying the incoming 223IPsec SA for a 224.Tn UDP 225datagram. 226The 227.Va msg_control 228field in the 229.Vt msghdr 230structure points to a buffer that contains a 231.Vt cmsghdr 232structure followed by flow information in 32-bit network byte order. 233When this information is passed to a 234.Xr sendmsg 2 235call the ID of the incoming SA will be used for looking up the 236outgoing SA for the 237.Tn UDP 238datagram. 239The 240.Vt cmsghdr 241fields for 242.Xr recvmsg 2 243and 244.Xr sendmsg 2 245have the following values: 246.Bd -literal -offset indent 247cmsg_len = CMSG_LEN(sizeof(u_int32_t)) 248cmsg_level = IPPROTO_IP 249cmsg_type = IP_IPSECFLOWINFO 250.Ed 251.Pp 252The 253.Dv IP_PORTRANGE 254option causes the default allocation policy for when the kernel is asked 255to choose a free port number. 256Three choices are available: 257.Pp 258.Bl -tag -width IP_PORTRANGE_DEFAULT -compact -offset indent 259.It Dv IP_PORTRANGE_DEFAULT 260The regular range of non-reserved ports. 261.It Dv IP_PORTRANGE_HIGH 262A high range, for fun. 263.It Dv IP_PORTRANGE_LOW 264Reserved ports; between 600 and 1023. 265.El 266.Pp 267If the 268.Dv IP_RECVRTABLE 269option is enabled on a 270.Dv SOCK_DGRAM 271socket, 272the 273.Xr recvmsg 2 274call will return the source routing domain for a 275.Tn UDP 276datagram. 277The 278.Va msg_control 279field in the 280.Vt msghdr 281structure points to a buffer that contains a 282.Vt cmsghdr 283structure followed by the routing table ID. 284The 285.Vt cmsghdr 286fields have the following values: 287.Bd -literal -offset indent 288cmsg_len = CMSG_LEN(sizeof(u_int)) 289cmsg_level = IPPROTO_IP 290cmsg_type = IP_RECVRTABLE 291.Ed 292.Pp 293When sending on a 294.Dv SOCK_DGRAM 295socket with 296.Xr sendmsg 2 , 297the source address to be used can be passed as ancillary data 298with a type code of 299.Dv IP_SENDSRCADDR . 300The 301.Va msg_control 302field in the 303.Vt msghdr 304structure should point to a buffer that contains a 305.Vt cmsghdr 306structure followed by the requested source address. 307The 308.Vt cmsghdr 309fields should have the following values: 310.Bd -literal -offset indent 311cmsg_len = CMSG_LEN(sizeof(struct in_addr)) 312cmsg_level = IPPROTO_IP 313cmsg_type = IP_SENDSRCADDR 314.Ed 315.Pp 316The same checks and restrictions as for 317.Xr bind 2 318apply, unless the socket is bound to 319.Dv INADDR_ANY . 320In this case, there is no source address overlap check. 321.Ss "Multicast Options" 322.Tn IP 323multicasting is supported only on 324.Dv AF_INET 325sockets of type 326.Dv SOCK_DGRAM 327and 328.Dv SOCK_RAW , 329and only on networks where the interface 330driver supports multicasting. 331.Pp 332The 333.Dv IP_MULTICAST_TTL 334option changes the time-to-live (TTL) 335for outgoing multicast datagrams 336in order to control the scope of the multicasts: 337.Bd -literal -offset indent 338u_char ttl; /* range: 0 to 255, default = 1 */ 339setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); 340.Ed 341.Pp 342Datagrams with a TTL of 1 are not forwarded beyond the local network. 343Multicast datagrams with a TTL of 0 will not be transmitted on any network, 344but may be delivered locally if the sending host belongs to the destination 345group and if multicast loopback has not been disabled on the sending socket 346(see below). 347Multicast datagrams with TTL greater than 1 may be forwarded 348to other networks if a multicast router is attached to the local network. 349.Pp 350For hosts with multiple interfaces, each multicast transmission is 351sent from the primary network interface. 352The 353.Dv IP_MULTICAST_IF 354option overrides the default for 355subsequent transmissions from a given socket: 356.Bd -literal -offset indent 357struct in_addr addr; 358setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); 359.Ed 360.Pp 361where 362.Va addr 363is the local 364.Tn IP 365address of the desired interface or 366.Dv INADDR_ANY 367to specify the default interface. 368An interface's local IP address and multicast capability can 369be obtained via the 370.Dv SIOCGIFCONF 371and 372.Dv SIOCGIFFLAGS 373.Xr ioctl 2 Ns 's . 374Normal applications should not need to use this option. 375.Pp 376If a multicast datagram is sent to a group to which the sending host itself 377belongs (on the outgoing interface), a copy of the datagram is, by default, 378looped back by the IP layer for local delivery. 379The 380.Dv IP_MULTICAST_LOOP 381option gives the sender explicit control 382over whether or not subsequent datagrams are looped back: 383.Bd -literal -offset indent 384u_char loop; /* 0 = disable, 1 = enable (default) */ 385setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); 386.Ed 387.Pp 388This option 389improves performance for applications that may have no more than one 390instance on a single host (such as a router daemon), by eliminating 391the overhead of receiving their own transmissions. 392It should generally not 393be used by applications for which there may be more than one instance on a 394single host (such as a conferencing program) or for which the sender does 395not belong to the destination group (such as a time querying program). 396.Pp 397A multicast datagram sent with an initial TTL greater than 1 may be delivered 398to the sending host on a different interface from that on which it was sent, 399if the host belongs to the destination group on that other interface. 400The loopback control option has no effect on such delivery. 401.Pp 402A host must become a member of a multicast group before it can receive 403datagrams sent to the group. 404To join a multicast group, use the 405.Dv IP_ADD_MEMBERSHIP 406option: 407.Bd -literal -offset indent 408struct ip_mreq mreq; 409setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq)); 410.Ed 411.Pp 412where 413.Fa mreq 414is the following structure: 415.Bd -literal -offset indent 416struct ip_mreq { 417 struct in_addr imr_multiaddr; /* multicast group to join */ 418 struct in_addr imr_interface; /* interface to join on */ 419} 420.Ed 421.Pp 422.Va imr_interface 423should 424be 425.Dv INADDR_ANY 426to choose the default multicast interface, 427or the 428.Tn IP 429address of a particular multicast-capable interface if 430the host is multihomed. 431Membership is associated with a single interface; 432programs running on multihomed hosts may need to 433join the same group on more than one interface. 434Up to 435.Dv IP_MAX_MEMBERSHIPS 436(currently 4095) memberships may be added on a 437single socket. 438.Pp 439To drop a membership, use: 440.Bd -literal -offset indent 441struct ip_mreq mreq; 442setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); 443.Ed 444.Pp 445where 446.Fa mreq 447contains the same values as used to add the membership. 448Memberships are dropped when the socket is closed or the process exits. 449.\"----------------------- 450.Ss "Raw IP Sockets" 451Raw 452.Tn IP 453sockets are connectionless, 454and are normally used with the 455.Xr sendto 2 456and 457.Xr recvfrom 2 458calls, though the 459.Xr connect 2 460call may also be used to fix the destination for future 461packets (in which case the 462.Xr read 2 463or 464.Xr recv 2 465and 466.Xr write 2 467or 468.Xr send 2 469system calls may be used). 470.Pp 471If 472.Fa proto 473is 0, the default protocol 474.Dv IPPROTO_RAW 475is used for outgoing 476packets, and only incoming packets destined for that protocol 477are received. 478If 479.Fa proto 480is non-zero, that protocol number will be used on outgoing packets 481and to filter incoming packets. 482.Pp 483Outgoing packets automatically have an 484.Tn IP 485header prepended to 486them (based on the destination address and the protocol 487number the socket is created with), 488unless the 489.Dv IP_HDRINCL 490option has been set. 491Incoming packets are received with 492.Tn IP 493header and options intact. 494.Pp 495.Dv IP_HDRINCL 496indicates the complete IP header is included with the data 497and may be used only with the 498.Dv SOCK_RAW 499type. 500.Bd -literal -offset indent 501#include <netinet/ip.h> 502 503int hincl = 1; /* 1 = on, 0 = off */ 504setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); 505.Ed 506.Pp 507Unlike previous 508.Bx 509releases, the program must set all 510the fields of the IP header, including the following: 511.Bd -literal -offset indent 512ip->ip_v = IPVERSION; 513ip->ip_hl = hlen >> 2; 514ip->ip_id = 0; /* 0 means kernel set appropriate value */ 515ip->ip_off = htons(offset); 516ip->ip_len = htons(len); 517.Ed 518.Pp 519Additionally note that starting with 520.Ox 2.1 , 521the 522.Va ip_off 523and 524.Va ip_len 525fields are in network byte order. 526If the header source address is set to 527.Dv INADDR_ANY , 528the kernel will choose an appropriate address. 529.Sh DIAGNOSTICS 530A socket operation may fail with one of the following errors returned: 531.Bl -tag -width [EADDRNOTAVAIL] 532.It Bq Er EISCONN 533when trying to establish a connection on a socket which 534already has one, or when trying to send a datagram with the destination 535address specified and the socket is already connected; 536.It Bq Er ENOTCONN 537when trying to send a datagram, but 538no destination address is specified, and the socket hasn't been 539connected; 540.It Bq Er ENOBUFS 541when the system runs out of memory for 542an internal data structure; 543.It Bq Er EADDRNOTAVAIL 544when an attempt is made to create a 545socket with a network address for which no network interface 546exists. 547.It Bq Er EACCES 548when an attempt is made to create 549a raw IP socket by a non-privileged process. 550.El 551.Pp 552The following errors specific to 553.Tn IP 554may occur when setting or getting 555.Tn IP 556options: 557.Bl -tag -width EADDRNOTAVAILxx 558.It Bq Er EINVAL 559An unknown socket option name was given. 560.It Bq Er EINVAL 561The IP option field was improperly formed; 562an option field was shorter than the minimum value 563or longer than the option buffer provided. 564.El 565.Sh SEE ALSO 566.Xr getsockopt 2 , 567.Xr ioctl 2 , 568.Xr recv 2 , 569.Xr send 2 , 570.Xr icmp 4 , 571.Xr inet 4 , 572.Xr netintro 4 573.Sh HISTORY 574The 575.Nm 576protocol appeared in 577.Bx 4.2 . 578