1.\" $NetBSD: ip.4,v 1.44 2020/08/28 16:07:49 fcambus 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 December 31, 2017 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 44IP is the network layer protocol used by the Internet protocol family. 45Options may be set at the 46IP level when using higher-level protocols that are based on 47IP (such as TCP and UDP). 48It may also be accessed through a 49.Dq raw socket 50when developing new protocols, or special-purpose applications. 51.Pp 52There are several IP-level 53.Xr setsockopt 2 Ns / Ns Xr getsockopt 2 54options. 55.Dv IP_OPTIONS 56may be used to provide IP options to be transmitted in the 57IP header of each outgoing packet 58or to examine the header options on incoming packets. 59IP options may be used with any socket type in the Internet family. 60The format of IP options to be sent is that specified by the 61IP protocol specification (RFC 791), with one exception: 62the list of addresses for Source Route options must include the first-hop 63gateway at the beginning of the list of gateways. 64The first-hop gateway address will be extracted from the option list 65and the size adjusted accordingly before use. 66To disable previously specified options, use a zero-length buffer: 67.Bd -literal 68setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0); 69.Ed 70.Pp 71.Dv IP_TOS 72and 73.Dv IP_TTL 74may be used to set the type-of-service and time-to-live fields in the 75IP header for 76.Dv SOCK_STREAM 77and 78.Dv SOCK_DGRAM 79sockets. 80For example, 81.Bd -literal 82int tos = IPTOS_LOWDELAY; /* see <netinet/ip.h> */ 83setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); 84 85int ttl = 60; /* max = 255 */ 86setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl)); 87.Ed 88.Pp 89.Dv IP_IPSEC_POLICY 90controls IPSec policy for sockets. 91For example, 92.Bd -literal 93const char *policy = "in ipsec ah/transport//require"; 94char *buf = ipsec_set_policy(policy, strlen(policy)); 95setsockopt(s, IPPROTO_IP, IP_IPSEC_POLICY, buf, ipsec_get_policylen(buf)); 96.Ed 97.Pp 98The 99.Dv IP_RECVPKTINFO 100option can be used to turn on receiving of information about the destination 101address of the packet, and the interface index. 102The information is passed in a 103.Vt struct in_pktinfo 104structure, which contains 105.Bd -literal 106 struct in_addr ipi_addr; /* the source or destination address */ 107 unsigned int ipi_ifindex; /* the interface index */ 108.Ed 109.Pp 110and added to the control portion of the message: 111The cmsghdr fields have the following values: 112.Bd -literal 113cmsg_len = CMSG_LEN(sizeof(struct in_pktinfo)) 114cmsg_level = IPPROTO_IP 115cmsg_type = IP_PKTINFO 116.Ed 117.Pp 118For 119.Xr sendmsg 2 , 120the source address or output interface can be specified by adding an 121.Dv IP_PKTINFO 122message to the control part of the message on a 123.Dv SOCK_DGRAM 124or 125.Dv SOCK_RAW 126socket. 127Setting ipi_ifindex will cause the primary address of that interface 128to be used; setting ipi_addr will directly choose that address. 129The 130.Dv IP_PKTINFO 131cmsghdr structure from a received message may be 132used unchanged, in which case the outgoing message will be sent 133from the address the incoming message was received on. 134.Pp 135Setting the 136.Dv IP_PKTINFO 137option on a socket, with the same 138.Vt struct in_pktinfo 139structure, will set the default source address to be used until set 140again, unless explicitly overridden on a per-packet basis, as above. 141.Pp 142The 143.Dv IP_PORTALGO 144can be used to randomize the port selection. 145Valid algorithms are described in 146.Xr rfc6056 7 147and their respective constants are in 148.In netinet/portalgo.h . 149For example, 150.Bd -literal 151int algo = PORTALGO_ALGO_RANDOM_PICK; /* see <netinet/portalgo.h> */ 152setsockopt(s, IPPROTO_IP, IP_PORTALGO, &algo, sizeof(algo)); 153.Ed 154.Pp 155The port selection can be also viewed and controlled at a global level for all 156IP sockets using the following 157.Xr sysctl 7 158variables: 159.Dv net.inet.ip.anonportalgo.available 160and 161.Dv net.inet.ip.anonportalgo.selected . 162.Pp 163.Dv IP_PORTRANGE 164controls how ephemeral ports are allocated for 165.Dv SOCK_STREAM 166and 167.Dv SOCK_DGRAM 168sockets. 169For example, 170.Bd -literal 171int range = IP_PORTRANGE_LOW; /* see <netinet/in.h> */ 172setsockopt(s, IPPROTO_IP, IP_PORTRANGE, &range, sizeof(range)); 173.Ed 174.Pp 175If the 176.Dv IP_RECVDSTADDR 177option is enabled on a 178.Dv SOCK_DGRAM 179or 180.Dv SOCK_RAW 181socket, 182the 183.Xr recvmsg 2 184call will return the destination IP address for a UDP datagram. 185The msg_control field in the msghdr structure points to a buffer 186that contains a cmsghdr structure followed by the IP address. 187The cmsghdr fields have the following values: 188.Bd -literal 189cmsg_len = CMSG_LEN(sizeof(struct in_addr)) 190cmsg_level = IPPROTO_IP 191cmsg_type = IP_RECVDSTADDR 192.Ed 193.Pp 194For 195.Xr sendmsg 2 , 196the source address can be specified by adding 197.Dv IP_SENDSRCADDR 198to the control part of the message on a 199.Dv SOCK_DGRAM 200or 201.Dv SOCK_RAW 202socket. 203The 204.Dv IP_RECVDSTADDR 205cmsghdr structure from a received message may 206be used unchanged, in which case the outgoing message will be sent 207from the address the incoming message was received on. 208.Pp 209If the 210.Dv IP_RECVIF 211option is enabled on a 212.Dv SOCK_DGRAM 213or 214.Dv SOCK_RAW 215socket, 216the 217.Xr recvmsg 2 218call will return a struct sockaddr_dl corresponding to 219the interface on which the packet was received. 220the msg_control field in the msghdr structure points to a buffer 221that contains a cmsghdr structure followed by the struct sockaddr_dl. 222The cmsghdr fields have the following values: 223.Bd -literal 224cmsg_len = CMSG_LEN(sizeof(struct sockaddr_dl)) 225cmsg_level = IPPROTO_IP 226cmsg_type = IP_RECVIF 227.Ed 228.Pp 229If the 230.Dv IP_RECVTTL 231option is enabled on a 232.Dv SOCK_DGRAM 233socket, the 234.Xr recvmsg 2 235call will return the TTL of the received datagram. 236The msg_control field in the msghdr structure points to a buffer 237that contains a cmsghdr structure followed by the TTL value. 238The cmsghdr fields have the following values: 239.Bd -literal 240cmsg_len = CMSG_LEN(sizeof(uint8_t)) 241cmsg_level = IPPROTO_IP 242cmsg_type = IP_RECVTTL 243.Ed 244.Pp 245The 246.Dv IP_MINTTL 247option may be used on 248.Dv SOCK_DGRAM 249or 250.Dv SOCK_STREAM 251sockets to discard packets with a TTL lower than the option value. 252This can be used to implement the 253.Em Generalized TTL Security Mechanism (GTSM) 254according to RFC 3682. 255To discard all packets with a TTL lower than 255: 256.Bd -literal -offset indent 257int minttl = 255; 258setsockopt(s, IPPROTO_IP, IP_MINTTL, &minttl, sizeof(minttl)); 259.Ed 260.Ss MULTICAST OPTIONS 261IP multicasting is supported only on 262.Dv AF_INET 263sockets of type 264.Dv SOCK_DGRAM 265and 266.Dv SOCK_RAW , 267and only on networks where the interface driver supports multicasting. 268.Pp 269The 270.Dv IP_MULTICAST_TTL 271option changes the time-to-live (TTL) for outgoing multicast datagrams 272in order to control the scope of the multicasts: 273.Bd -literal 274u_char ttl; /* range: 0 to 255, default = 1 */ 275setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); 276.Ed 277.Pp 278Datagrams with a TTL of 1 are not forwarded beyond the local network. 279Multicast datagrams with a TTL of 0 will not be transmitted on any network, 280but may be delivered locally if the sending host belongs to the destination 281group and if multicast loopback has not been disabled on the sending socket 282(see below). 283Multicast datagrams with TTL greater than 1 may be forwarded 284to other networks if a multicast router is attached to the local network. 285.Pp 286For hosts with multiple interfaces, each multicast transmission is 287sent from the primary network interface. 288The 289.Dv IP_MULTICAST_IF 290option overrides the default for 291subsequent transmissions from a given socket: 292.Bd -literal 293struct in_addr addr; 294setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); 295.Ed 296.Pp 297where "addr" is the local IP address of the desired interface or 298.Dv INADDR_ANY 299to specify the default interface. 300An interface's local IP address and multicast capability can 301be obtained via the 302.Dv SIOCGIFCONF 303and 304.Dv SIOCGIFFLAGS 305ioctls. 306An application may also specify an alternative to the default network interface 307by index: 308.Bd -literal 309struct uint32_t idx = htonl(ifindex); 310setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &idx, sizeof(idx)); 311.Ed 312.Pp 313where "ifindex" is an interface index as returned by 314.Xr if_nametoindex 3 . 315.Pp 316Normal applications should not need to use 317.Dv IP_MULTICAST_IF . 318.Pp 319If a multicast datagram is sent to a group to which the sending host itself 320belongs (on the outgoing interface), a copy of the datagram is, by default, 321looped back by the IP layer for local delivery. 322The 323.Dv IP_MULTICAST_LOOP 324option gives the sender explicit control 325over whether or not subsequent datagrams are looped back: 326.Bd -literal 327u_char loop; /* 0 = disable, 1 = enable (default) */ 328setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); 329.Ed 330.Pp 331This option 332improves performance for applications that may have no more than one 333instance on a single host (such as a router demon), by eliminating 334the overhead of receiving their own transmissions. 335It should generally not be used by applications for which there 336may be more than one instance on a single host (such as a conferencing 337program) or for which the sender does not belong to the destination 338group (such as a time querying program). 339.Pp 340A multicast datagram sent with an initial TTL greater than 1 may be delivered 341to the sending host on a different interface from that on which it was sent, 342if the host belongs to the destination group on that other interface. 343The loopback control option has no effect on such delivery. 344.Pp 345A host must become a member of a multicast group before it can receive 346datagrams sent to the group. 347To join a multicast group, use the 348.Dv IP_ADD_MEMBERSHIP 349option: 350.Bd -literal 351struct ip_mreq mreq; 352setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq)); 353.Ed 354.Pp 355where 356.Fa mreq 357is the following structure: 358.Bd -literal 359struct ip_mreq { 360 struct in_addr imr_multiaddr; /* multicast group to join */ 361 struct in_addr imr_interface; /* interface to join on */ 362} 363.Ed 364.Pp 365.Dv imr_interface 366should be 367.Dv INADDR_ANY 368to choose the default multicast interface, or the IP 369address of a particular multicast-capable interface if 370the host is multihomed. 371Membership is associated with a single interface; 372programs running on multihomed hosts may need to 373join the same group on more than one interface. 374Up to 375.Dv IP_MAX_MEMBERSHIPS 376(currently 20) memberships may be added on a single socket. 377.Pp 378To drop a membership, use: 379.Bd -literal 380struct ip_mreq mreq; 381setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); 382.Ed 383.Pp 384where 385.Fa mreq 386contains the same values as used to add the membership. 387Memberships are dropped when the socket is closed or the process exits. 388.\"----------------------- 389.Ss RAW IP SOCKETS 390Raw IP sockets are connectionless, and are normally used with the 391.Xr sendto 2 392and 393.Xr recvfrom 2 394calls, though the 395.Xr connect 2 396call may also be used to fix the destination for future 397packets (in which case the 398.Xr read 2 399or 400.Xr recv 2 401and 402.Xr write 2 403or 404.Xr send 2 405system calls may be used). 406.Pp 407If 408.Fa proto 409is 0, the default protocol 410.Dv IPPROTO_RAW 411is used for outgoing packets, and only incoming packets destined 412for that protocol are received. 413If 414.Fa proto 415is non-zero, that protocol number will be used on outgoing packets 416and to filter incoming packets. 417.Pp 418Outgoing packets automatically have an IP 419header prepended to them (based on the destination address and the 420protocol number the socket is created with), unless the 421.Dv IP_HDRINCL 422option has been set. 423Incoming packets are received with IP header and options intact. 424.Pp 425.Dv IP_HDRINCL 426indicates the complete IP header is included with the data and may 427be used only with the 428.Dv SOCK_RAW 429type. 430.Bd -literal 431#include <netinet/ip.h> 432 433int hincl = 1; /* 1 = on, 0 = off */ 434setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); 435.Ed 436.Pp 437Unlike previous 438.Bx 439releases, the program must set all 440the fields of the IP header, including the following: 441.Bd -literal 442ip->ip_v = IPVERSION; 443ip->ip_hl = hlen >> 2; 444ip->ip_id = 0; /* 0 means kernel set appropriate value */ 445ip->ip_off = offset; 446.Ed 447.Pp 448If the header source address is set to 449.Dv INADDR_ANY , 450the kernel will choose an appropriate address. 451.Sh DIAGNOSTICS 452A socket operation may fail with one of the following errors returned: 453.Bl -tag -width [EADDRNOTAVAIL] 454.It Bq Er EACCES 455when an attempt is made to create a raw IP socket by a non-privileged process. 456.It Bq Er EADDRNOTAVAIL 457when an attempt is made to create a socket with a network address 458for which no network interface exists. 459.It Bq Er EISCONN 460when trying to establish a connection on a socket which already 461has one, or when trying to send a datagram with the destination 462address specified and the socket is already connected; 463.It Bq Er ENOBUFS 464when the system runs out of memory for an internal data structure; 465.It Bq Er ENOTCONN 466when trying to send a datagram, but no destination address is 467specified, and the socket hasn't been connected; 468.El 469.Pp 470The following errors specific to IP may occur when setting or getting 471IP options: 472.Bl -tag -width EADDRNOTAVAILxx 473.It Bq Er EINVAL 474An unknown socket option name was given; or 475the IP option field was improperly formed; an option field was 476shorter than the minimum value or longer than the option buffer provided. 477.El 478.Sh COMPATIBILITY 479The 480.Dv IP_RECVPKTINFO 481option is used because it is directly compatible with Solaris, AIX, etc., 482and the 483.Dv IP_PKTINFO 484option is intended to be used in their manner, to set the default source 485address for outgoing packets on a 486.Dv SOCK_DGRAM 487or 488.Dv SOCK_RAW 489socket. 490For compatibility with Linux, however, if you attempt to set the 491.Dv IP_PKTINFO 492option, using an integer parameter as a boolean value, this will 493transparently manipulate the 494.Dv IP_RECVPKTINFO 495option instead. 496Source code compatibility with both environments is thus maintained. 497.Sh SEE ALSO 498.Xr getsockopt 2 , 499.Xr recv 2 , 500.Xr send 2 , 501.Xr CMSG_DATA 3 , 502.Xr ipsec_set_policy 3 , 503.Xr icmp 4 , 504.Xr inet 4 , 505.Xr intro 4 506.Rs 507.%R RFC 508.%N 791 509.%D September 1981 510.%T "Internet Protocol" 511.Re 512.Rs 513.%R RFC 514.%N 1112 515.%D August 1989 516.%T "Host Extensions for IP Multicasting" 517.Re 518.Rs 519.%R RFC 520.%N 1122 521.%D October 1989 522.%T "Requirements for Internet Hosts -- Communication Layers" 523.Re 524.Sh HISTORY 525The 526.Nm 527protocol appeared in 528.Bx 4.2 . 529