1.\" $OpenBSD: ip.4,v 1.43 2021/01/08 23:33:12 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: January 8 2021 $ 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 either of the following structures: 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 421struct ip_mreqn { 422 struct in_addr imr_multiaddr; /* multicast group to join */ 423 struct in_addr imr_address; /* local IP address of interface */ 424 int imr_ifindex; /* interface index to join */ 425}; 426.Ed 427.Pp 428.Va imr_interface 429should 430be 431.Dv INADDR_ANY 432to choose the default multicast interface, 433or the 434.Tn IP 435address of a particular multicast-capable interface if 436the host is multihomed. 437The 438.Va imr_ifindex 439element of 440.Va struct ip_mreqn 441can be set to the interface index instead of specifying the 442.Tn IP 443address of a particular multicast-capable interface. 444Membership is associated with a single interface; 445programs running on multihomed hosts may need to 446join the same group on more than one interface. 447Up to 448.Dv IP_MAX_MEMBERSHIPS 449(currently 4095) memberships may be added on a 450single socket. 451.Pp 452To drop a membership, use: 453.Bd -literal -offset indent 454struct ip_mreq mreq; 455setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); 456.Ed 457.Pp 458where 459.Fa mreq 460contains the same values as used to add the membership. 461Memberships are dropped when the socket is closed or the process exits. 462.\"----------------------- 463.Ss "Raw IP Sockets" 464Raw 465.Tn IP 466sockets are connectionless, 467and are normally used with the 468.Xr sendto 2 469and 470.Xr recvfrom 2 471calls, though the 472.Xr connect 2 473call may also be used to fix the destination for future 474packets (in which case the 475.Xr read 2 476or 477.Xr recv 2 478and 479.Xr write 2 480or 481.Xr send 2 482system calls may be used). 483.Pp 484If 485.Fa proto 486is 0, the default protocol 487.Dv IPPROTO_RAW 488is used for outgoing 489packets, and only incoming packets destined for that protocol 490are received. 491If 492.Fa proto 493is non-zero, that protocol number will be used on outgoing packets 494and to filter incoming packets. 495.Pp 496Outgoing packets automatically have an 497.Tn IP 498header prepended to 499them (based on the destination address and the protocol 500number the socket is created with), 501unless the 502.Dv IP_HDRINCL 503option has been set. 504Incoming packets are received with 505.Tn IP 506header and options intact. 507.Pp 508.Dv IP_HDRINCL 509indicates the complete IP header is included with the data 510and may be used only with the 511.Dv SOCK_RAW 512type. 513.Bd -literal -offset indent 514#include <netinet/ip.h> 515 516int hincl = 1; /* 1 = on, 0 = off */ 517setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); 518.Ed 519.Pp 520Unlike previous 521.Bx 522releases, the program must set all 523the fields of the IP header, including the following: 524.Bd -literal -offset indent 525ip->ip_v = IPVERSION; 526ip->ip_hl = hlen >> 2; 527ip->ip_id = 0; /* 0 means kernel set appropriate value */ 528ip->ip_off = htons(offset); 529ip->ip_len = htons(len); 530.Ed 531.Pp 532Additionally note that starting with 533.Ox 2.1 , 534the 535.Va ip_off 536and 537.Va ip_len 538fields are in network byte order. 539If the header source address is set to 540.Dv INADDR_ANY , 541the kernel will choose an appropriate address. 542.Sh DIAGNOSTICS 543A socket operation may fail with one of the following errors returned: 544.Bl -tag -width [EADDRNOTAVAIL] 545.It Bq Er EISCONN 546when trying to establish a connection on a socket which 547already has one, or when trying to send a datagram with the destination 548address specified and the socket is already connected; 549.It Bq Er ENOTCONN 550when trying to send a datagram, but 551no destination address is specified, and the socket hasn't been 552connected; 553.It Bq Er ENOBUFS 554when the system runs out of memory for 555an internal data structure; 556.It Bq Er EADDRNOTAVAIL 557when an attempt is made to create a 558socket with a network address for which no network interface 559exists. 560.It Bq Er EACCES 561when an attempt is made to create 562a raw IP socket by a non-privileged process. 563.El 564.Pp 565The following errors specific to 566.Tn IP 567may occur when setting or getting 568.Tn IP 569options: 570.Bl -tag -width EADDRNOTAVAILxx 571.It Bq Er EINVAL 572An unknown socket option name was given. 573.It Bq Er EINVAL 574The IP option field was improperly formed; 575an option field was shorter than the minimum value 576or longer than the option buffer provided. 577.El 578.Sh SEE ALSO 579.Xr getsockopt 2 , 580.Xr ioctl 2 , 581.Xr recv 2 , 582.Xr send 2 , 583.Xr icmp 4 , 584.Xr inet 4 , 585.Xr netintro 4 586.Sh HISTORY 587The 588.Nm 589protocol appeared in 590.Bx 4.2 . 591