1.\" $OpenBSD: ip.4,v 1.35 2012/08/24 20:13:03 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 24 2012 $ 34.Dt IP 4 35.Os 36.Sh NAME 37.Nm ip 38.Nd Internet Protocol 39.Sh SYNOPSIS 40.Fd #include <sys/types.h> 41.Fd #include <sys/socket.h> 42.Fd #include <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 100and 101.Dv SOCK_DGRAM 102sockets. 103For example, 104.Bd -literal -offset indent 105int tos = IPTOS_LOWDELAY; /* see <netinet/ip.h> */ 106setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); 107 108int ttl = 60; /* max = 255 */ 109setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl)); 110.Ed 111.Pp 112If the 113.Dv IP_RECVDSTADDR 114option is enabled on a 115.Dv SOCK_DGRAM 116socket, 117the 118.Xr recvmsg 2 119call will return the destination 120.Tn IP 121address for a 122.Tn UDP 123datagram. 124The 125.Va msg_control 126field in the 127.Vt msghdr 128structure points to a buffer that contains a 129.Vt cmsghdr 130structure followed by the 131.Tn IP 132address. 133The 134.Vt cmsghdr 135fields have the following values: 136.Bd -literal -offset indent 137cmsg_len = CMSG_LEN(sizeof(struct in_addr)) 138cmsg_level = IPPROTO_IP 139cmsg_type = IP_RECVDSTADDR 140.Ed 141.Pp 142If the 143.Dv IP_RECVDSTPORT 144option is enabled on a 145.Dv SOCK_DGRAM 146socket, 147the 148.Xr recvmsg 2 149call will return the destination 150port for a 151.Tn UDP 152datagram. 153The 154.Va msg_control 155field in the 156.Vt msghdr 157structure points to a buffer that contains a 158.Vt cmsghdr 159structure followed by the port in 16-bit network byte order. 160The 161.Vt cmsghdr 162fields have the following values: 163.Bd -literal -offset indent 164cmsg_len = CMSG_LEN(sizeof(u_int16_t)) 165cmsg_level = IPPROTO_IP 166cmsg_type = IP_RECVDSTPORT 167.Ed 168.Pp 169If the 170.Dv IP_RECVTTL 171option is enabled on a 172.Dv SOCK_DGRAM 173or 174.Dv SOCK_RAW 175socket, the 176.Xr recvmsg 2 177call will return the 178.Tn TTL 179of the received datagram. 180The 181.Va msg_control 182field in the 183.Vt msghdr 184structure points to a buffer that contains a 185.Vt cmsghdr 186structure followed by the 187.Tn TTL 188value. 189The 190.Vt cmsghdr 191fields have the following values: 192.Bd -literal -offset indent 193cmsg_len = CMSG_LEN(sizeof(u_int8_t)) 194cmsg_level = IPPROTO_IP 195cmsg_type = IP_RECVTTL 196.Ed 197.Pp 198The 199.Dv IP_MINTTL 200option may be used on 201.Dv SOCK_STREAM 202sockets to discard packets with a TTL lower than the option value. 203This can be used to implement the 204.Em Generalized TTL Security Mechanism (GTSM) 205according to RFC 5082. 206To discard all packets with a TTL lower than 255: 207.Bd -literal -offset indent 208int minttl = 255; 209setsockopt(s, IPPROTO_IP, IP_MINTTL, &minttl, sizeof(minttl)); 210.Ed 211.Pp 212If the 213.Dv IP_IPSECFLOWINFO 214option is enabled on a 215.Dv SOCK_DGRAM 216socket, 217the 218.Xr recvmsg 2 219call will return information identifying the incoming 220IPsec SA for a 221.Tn UDP 222datagram. 223The 224.Va msg_control 225field in the 226.Vt msghdr 227structure points to a buffer that contains a 228.Vt cmsghdr 229structure followed by flow information in 32-bit network byte order. 230When this information is passed to a 231.Xr sendmsg 2 232call the ID of the incoming SA will be used for looking up the 233outgoing SA for the 234.Tn UDP 235datagram. 236The 237.Vt cmsghdr 238fields for 239.Xr recvmsg 2 240and 241.Xr sendmsg 2 242have the following values: 243.Bd -literal -offset indent 244cmsg_len = CMSG_LEN(sizeof(u_int32_t)) 245cmsg_level = IPPROTO_IP 246cmsg_type = IP_IPSECFLOWINFO 247.Ed 248.Pp 249The 250.Dv IP_PORTRANGE 251option causes the default allocation policy for when the kernel is asked 252to choose a free port number. 253Three choices are available: 254.Pp 255.Bl -tag -width IP_PORTRANGE_DEFAULT -compact -offset indent 256.It Dv IP_PORTRANGE_DEFAULT 257The regular range of non-reserved ports. 258.It Dv IP_PORTRANGE_HIGH 259A high range, for fun. 260.It Dv IP_PORTRANGE_LOW 261Reserved ports; between 600 and 1023. 262.El 263.Pp 264If the 265.Dv IP_RECVRTABLE 266option is enabled on a 267.Dv SOCK_DGRAM 268socket, 269the 270.Xr recvmsg 2 271call will return the source routing domain for a 272.Tn UDP 273datagram. 274The 275.Va msg_control 276field in the 277.Vt msghdr 278structure points to a buffer that contains a 279.Vt cmsghdr 280structure followed by the routing table ID. 281The 282.Vt cmsghdr 283fields have the following values: 284.Bd -literal -offset indent 285cmsg_len = CMSG_LEN(sizeof(u_int)) 286cmsg_level = IPPROTO_IP 287cmsg_type = IP_RECVRTABLE 288.Ed 289.Ss "Multicast Options" 290.Tn IP 291multicasting is supported only on 292.Dv AF_INET 293sockets of type 294.Dv SOCK_DGRAM 295and 296.Dv SOCK_RAW , 297and only on networks where the interface 298driver supports multicasting. 299.Pp 300The 301.Dv IP_MULTICAST_TTL 302option changes the time-to-live (TTL) 303for outgoing multicast datagrams 304in order to control the scope of the multicasts: 305.Bd -literal -offset indent 306u_char ttl; /* range: 0 to 255, default = 1 */ 307setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); 308.Ed 309.Pp 310Datagrams with a TTL of 1 are not forwarded beyond the local network. 311Multicast datagrams with a TTL of 0 will not be transmitted on any network, 312but may be delivered locally if the sending host belongs to the destination 313group and if multicast loopback has not been disabled on the sending socket 314(see below). 315Multicast datagrams with TTL greater than 1 may be forwarded 316to other networks if a multicast router is attached to the local network. 317.Pp 318For hosts with multiple interfaces, each multicast transmission is 319sent from the primary network interface. 320The 321.Dv IP_MULTICAST_IF 322option overrides the default for 323subsequent transmissions from a given socket: 324.Bd -literal -offset indent 325struct in_addr addr; 326setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); 327.Ed 328.Pp 329where 330.Va addr 331is the local 332.Tn IP 333address of the desired interface or 334.Dv INADDR_ANY 335to specify the default interface. 336An interface's local IP address and multicast capability can 337be obtained via the 338.Dv SIOCGIFCONF 339and 340.Dv SIOCGIFFLAGS 341.Xr ioctl 2 Ns 's . 342Normal applications should not need to use this option. 343.Pp 344If a multicast datagram is sent to a group to which the sending host itself 345belongs (on the outgoing interface), a copy of the datagram is, by default, 346looped back by the IP layer for local delivery. 347The 348.Dv IP_MULTICAST_LOOP 349option gives the sender explicit control 350over whether or not subsequent datagrams are looped back: 351.Bd -literal -offset indent 352u_char loop; /* 0 = disable, 1 = enable (default) */ 353setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); 354.Ed 355.Pp 356This option 357improves performance for applications that may have no more than one 358instance on a single host (such as a router daemon), by eliminating 359the overhead of receiving their own transmissions. 360It should generally not 361be used by applications for which there may be more than one instance on a 362single host (such as a conferencing program) or for which the sender does 363not belong to the destination group (such as a time querying program). 364.Pp 365A multicast datagram sent with an initial TTL greater than 1 may be delivered 366to the sending host on a different interface from that on which it was sent, 367if the host belongs to the destination group on that other interface. 368The loopback control option has no effect on such delivery. 369.Pp 370A host must become a member of a multicast group before it can receive 371datagrams sent to the group. 372To join a multicast group, use the 373.Dv IP_ADD_MEMBERSHIP 374option: 375.Bd -literal -offset indent 376struct ip_mreq mreq; 377setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq)); 378.Ed 379.Pp 380where 381.Fa mreq 382is the following structure: 383.Bd -literal -offset indent 384struct ip_mreq { 385 struct in_addr imr_multiaddr; /* multicast group to join */ 386 struct in_addr imr_interface; /* interface to join on */ 387} 388.Ed 389.Pp 390.Va imr_interface 391should 392be 393.Dv INADDR_ANY 394to choose the default multicast interface, 395or the 396.Tn IP 397address of a particular multicast-capable interface if 398the host is multihomed. 399Membership is associated with a single interface; 400programs running on multihomed hosts may need to 401join the same group on more than one interface. 402Up to 403.Dv IP_MAX_MEMBERSHIPS 404(currently 4095) memberships may be added on a 405single socket. 406.Pp 407To drop a membership, use: 408.Bd -literal -offset indent 409struct ip_mreq mreq; 410setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); 411.Ed 412.Pp 413where 414.Fa mreq 415contains the same values as used to add the membership. 416Memberships are dropped when the socket is closed or the process exits. 417.\"----------------------- 418.Ss "Raw IP Sockets" 419Raw 420.Tn IP 421sockets are connectionless, 422and are normally used with the 423.Xr sendto 2 424and 425.Xr recvfrom 2 426calls, though the 427.Xr connect 2 428call may also be used to fix the destination for future 429packets (in which case the 430.Xr read 2 431or 432.Xr recv 2 433and 434.Xr write 2 435or 436.Xr send 2 437system calls may be used). 438.Pp 439If 440.Fa proto 441is 0, the default protocol 442.Dv IPPROTO_RAW 443is used for outgoing 444packets, and only incoming packets destined for that protocol 445are received. 446If 447.Fa proto 448is non-zero, that protocol number will be used on outgoing packets 449and to filter incoming packets. 450.Pp 451Outgoing packets automatically have an 452.Tn IP 453header prepended to 454them (based on the destination address and the protocol 455number the socket is created with), 456unless the 457.Dv IP_HDRINCL 458option has been set. 459Incoming packets are received with 460.Tn IP 461header and options intact. 462.Pp 463.Dv IP_HDRINCL 464indicates the complete IP header is included with the data 465and may be used only with the 466.Dv SOCK_RAW 467type. 468.Bd -literal -offset indent 469#include <netinet/ip.h> 470 471int hincl = 1; /* 1 = on, 0 = off */ 472setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); 473.Ed 474.Pp 475Unlike previous 476.Bx 477releases, the program must set all 478the fields of the IP header, including the following: 479.Bd -literal -offset indent 480ip->ip_v = IPVERSION; 481ip->ip_hl = hlen >> 2; 482ip->ip_id = 0; /* 0 means kernel set appropriate value */ 483ip->ip_off = htons(offset); 484ip->ip_len = htons(len); 485.Ed 486.Pp 487Additionally note that starting with 488.Ox 2.1 , 489the 490.Va ip_off 491and 492.Va ip_len 493fields are in network byte order. 494If the header source address is set to 495.Dv INADDR_ANY , 496the kernel will choose an appropriate address. 497.Sh DIAGNOSTICS 498A socket operation may fail with one of the following errors returned: 499.Bl -tag -width [EADDRNOTAVAIL] 500.It Bq Er EISCONN 501when trying to establish a connection on a socket which 502already has one, or when trying to send a datagram with the destination 503address specified and the socket is already connected; 504.It Bq Er ENOTCONN 505when trying to send a datagram, but 506no destination address is specified, and the socket hasn't been 507connected; 508.It Bq Er ENOBUFS 509when the system runs out of memory for 510an internal data structure; 511.It Bq Er EADDRNOTAVAIL 512when an attempt is made to create a 513socket with a network address for which no network interface 514exists. 515.It Bq Er EACCES 516when an attempt is made to create 517a raw IP socket by a non-privileged process. 518.El 519.Pp 520The following errors specific to 521.Tn IP 522may occur when setting or getting 523.Tn IP 524options: 525.Bl -tag -width EADDRNOTAVAILxx 526.It Bq Er EINVAL 527An unknown socket option name was given. 528.It Bq Er EINVAL 529The IP option field was improperly formed; 530an option field was shorter than the minimum value 531or longer than the option buffer provided. 532.El 533.Sh SEE ALSO 534.Xr getsockopt 2 , 535.Xr ioctl 2 , 536.Xr recv 2 , 537.Xr send 2 , 538.Xr icmp 4 , 539.Xr inet 4 , 540.Xr netintro 4 541.Sh HISTORY 542The 543.Nm 544protocol appeared in 545.Bx 4.2 . 546