1.\" $NetBSD: ip.4,v 1.47 2020/09/08 17:30:44 wiz 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 September 8, 2020 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_BINDANY 231option is enabled on a 232.Dv SOCK_STREAM , 233.Dv SOCK_DGRAM , 234or a 235.Dv SOCK_RAW 236socket, one can 237.Xr bind 2 238to any address, even one not bound to any available network interface in the 239system. 240This functionality (in conjunction with special firewall rules) can be used for 241implementing a transparent proxy. 242The 243.Dv KAUTH_REQ_NETWORK_BIND_ANYADDR 244privilege is needed to set this option. 245.Pp 246If the 247.Dv IP_RECVTTL 248option is enabled on a 249.Dv SOCK_DGRAM 250socket, the 251.Xr recvmsg 2 252call will return the TTL of the received datagram. 253The msg_control field in the msghdr structure points to a buffer 254that contains a cmsghdr structure followed by the TTL value. 255The cmsghdr fields have the following values: 256.Bd -literal 257cmsg_len = CMSG_LEN(sizeof(uint8_t)) 258cmsg_level = IPPROTO_IP 259cmsg_type = IP_RECVTTL 260.Ed 261.Pp 262The 263.Dv IP_MINTTL 264option may be used on 265.Dv SOCK_DGRAM 266or 267.Dv SOCK_STREAM 268sockets to discard packets with a TTL lower than the option value. 269This can be used to implement the 270.Em Generalized TTL Security Mechanism (GTSM) 271according to RFC 3682. 272To discard all packets with a TTL lower than 255: 273.Bd -literal -offset indent 274int minttl = 255; 275setsockopt(s, IPPROTO_IP, IP_MINTTL, &minttl, sizeof(minttl)); 276.Ed 277.Ss MULTICAST OPTIONS 278IP multicasting is supported only on 279.Dv AF_INET 280sockets of type 281.Dv SOCK_DGRAM 282and 283.Dv SOCK_RAW , 284and only on networks where the interface driver supports multicasting. 285.Pp 286The 287.Dv IP_MULTICAST_TTL 288option changes the time-to-live (TTL) for outgoing multicast datagrams 289in order to control the scope of the multicasts: 290.Bd -literal 291u_char ttl; /* range: 0 to 255, default = 1 */ 292setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); 293.Ed 294.Pp 295Datagrams with a TTL of 1 are not forwarded beyond the local network. 296Multicast datagrams with a TTL of 0 will not be transmitted on any network, 297but may be delivered locally if the sending host belongs to the destination 298group and if multicast loopback has not been disabled on the sending socket 299(see below). 300Multicast datagrams with TTL greater than 1 may be forwarded 301to other networks if a multicast router is attached to the local network. 302.Pp 303For hosts with multiple interfaces, each multicast transmission is 304sent from the primary network interface. 305The 306.Dv IP_MULTICAST_IF 307option overrides the default for 308subsequent transmissions from a given socket: 309.Bd -literal 310struct in_addr addr; 311setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); 312.Ed 313.Pp 314where "addr" is the local IP address of the desired interface or 315.Dv INADDR_ANY 316to specify the default interface. 317An interface's local IP address and multicast capability can 318be obtained via the 319.Dv SIOCGIFCONF 320and 321.Dv SIOCGIFFLAGS 322ioctls. 323An application may also specify an alternative to the default network interface 324by index: 325.Bd -literal 326struct uint32_t idx = htonl(ifindex); 327setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &idx, sizeof(idx)); 328.Ed 329.Pp 330where "ifindex" is an interface index as returned by 331.Xr if_nametoindex 3 . 332.Pp 333Normal applications should not need to use 334.Dv IP_MULTICAST_IF . 335.Pp 336If a multicast datagram is sent to a group to which the sending host itself 337belongs (on the outgoing interface), a copy of the datagram is, by default, 338looped back by the IP layer for local delivery. 339The 340.Dv IP_MULTICAST_LOOP 341option gives the sender explicit control 342over whether or not subsequent datagrams are looped back: 343.Bd -literal 344u_char loop; /* 0 = disable, 1 = enable (default) */ 345setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); 346.Ed 347.Pp 348This option 349improves performance for applications that may have no more than one 350instance on a single host (such as a router demon), by eliminating 351the overhead of receiving their own transmissions. 352It should generally not be used by applications for which there 353may be more than one instance on a single host (such as a conferencing 354program) or for which the sender does not belong to the destination 355group (such as a time querying program). 356.Pp 357A multicast datagram sent with an initial TTL greater than 1 may be delivered 358to the sending host on a different interface from that on which it was sent, 359if the host belongs to the destination group on that other interface. 360The loopback control option has no effect on such delivery. 361.Pp 362A host must become a member of a multicast group before it can receive 363datagrams sent to the group. 364To join a multicast group, use the 365.Dv IP_ADD_MEMBERSHIP 366option: 367.Bd -literal 368struct ip_mreq mreq; 369setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq)); 370.Ed 371.Pp 372where 373.Fa mreq 374is the following structure: 375.Bd -literal 376struct ip_mreq { 377 struct in_addr imr_multiaddr; /* multicast group to join */ 378 struct in_addr imr_interface; /* interface to join on */ 379} 380.Ed 381.Pp 382.Dv imr_interface 383should be 384.Dv INADDR_ANY 385to choose the default multicast interface, or the IP 386address of a particular multicast-capable interface if 387the host is multihomed. 388Membership is associated with a single interface; 389programs running on multihomed hosts may need to 390join the same group on more than one interface. 391Up to 392.Dv IP_MAX_MEMBERSHIPS 393(currently 20) memberships may be added on a single socket. 394.Pp 395To drop a membership, use: 396.Bd -literal 397struct ip_mreq mreq; 398setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); 399.Ed 400.Pp 401where 402.Fa mreq 403contains the same values as used to add the membership. 404Memberships are dropped when the socket is closed or the process exits. 405.\"----------------------- 406.Ss RAW IP SOCKETS 407Raw IP sockets are connectionless, and are normally used with the 408.Xr sendto 2 409and 410.Xr recvfrom 2 411calls, though the 412.Xr connect 2 413call may also be used to fix the destination for future 414packets (in which case the 415.Xr read 2 416or 417.Xr recv 2 418and 419.Xr write 2 420or 421.Xr send 2 422system calls may be used). 423.Pp 424If 425.Fa proto 426is 0, the default protocol 427.Dv IPPROTO_RAW 428is used for outgoing packets, and only incoming packets destined 429for that protocol are received. 430If 431.Fa proto 432is non-zero, that protocol number will be used on outgoing packets 433and to filter incoming packets. 434.Pp 435Outgoing packets automatically have an IP 436header prepended to them (based on the destination address and the 437protocol number the socket is created with), unless the 438.Dv IP_HDRINCL 439option has been set. 440Incoming packets are received with IP header and options intact. 441.Pp 442.Dv IP_HDRINCL 443indicates the complete IP header is included with the data and may 444be used only with the 445.Dv SOCK_RAW 446type. 447.Bd -literal 448#include <netinet/ip.h> 449 450int hincl = 1; /* 1 = on, 0 = off */ 451setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); 452.Ed 453.Pp 454Unlike previous 455.Bx 456releases, the program must set all 457the fields of the IP header, including the following: 458.Bd -literal 459ip->ip_v = IPVERSION; 460ip->ip_hl = hlen >> 2; 461ip->ip_id = 0; /* 0 means kernel set appropriate value */ 462ip->ip_off = offset; 463.Ed 464.Pp 465If the header source address is set to 466.Dv INADDR_ANY , 467the kernel will choose an appropriate address. 468.Sh DIAGNOSTICS 469A socket operation may fail with one of the following errors returned: 470.Bl -tag -width [EADDRNOTAVAIL] 471.It Bq Er EACCES 472when an attempt is made to create a raw IP socket by a non-privileged process. 473.It Bq Er EADDRNOTAVAIL 474when an attempt is made to create a socket with a network address 475for which no network interface exists. 476.It Bq Er EISCONN 477when trying to establish a connection on a socket which already 478has one, or when trying to send a datagram with the destination 479address specified and the socket is already connected; 480.It Bq Er ENOBUFS 481when the system runs out of memory for an internal data structure; 482.It Bq Er ENOTCONN 483when trying to send a datagram, but no destination address is 484specified, and the socket hasn't been connected; 485.El 486.Pp 487The following errors specific to IP may occur when setting or getting 488IP options: 489.Bl -tag -width EADDRNOTAVAILxx 490.It Bq Er EINVAL 491An unknown socket option name was given; or 492the IP option field was improperly formed; an option field was 493shorter than the minimum value or longer than the option buffer provided. 494.El 495.Sh COMPATIBILITY 496The 497.Dv IP_RECVPKTINFO 498option is used because it is directly compatible with Solaris, AIX, etc., 499and the 500.Dv IP_PKTINFO 501option is intended to be used in their manner, to set the default source 502address for outgoing packets on a 503.Dv SOCK_DGRAM 504or 505.Dv SOCK_RAW 506socket. 507For compatibility with Linux, however, if you attempt to set the 508.Dv IP_PKTINFO 509option, using an integer parameter as a boolean value, this will 510transparently manipulate the 511.Dv IP_RECVPKTINFO 512option instead. 513Source code compatibility with both environments is thus maintained. 514.Sh SEE ALSO 515.Xr getsockopt 2 , 516.Xr recv 2 , 517.Xr send 2 , 518.Xr CMSG_DATA 3 , 519.Xr ipsec_set_policy 3 , 520.Xr icmp 4 , 521.Xr inet 4 , 522.Xr intro 4 523.Rs 524.%R RFC 525.%N 791 526.%D September 1981 527.%T "Internet Protocol" 528.Re 529.Rs 530.%R RFC 531.%N 1112 532.%D August 1989 533.%T "Host Extensions for IP Multicasting" 534.Re 535.Rs 536.%R RFC 537.%N 1122 538.%D October 1989 539.%T "Requirements for Internet Hosts \(em Communication Layers" 540.Re 541.Sh HISTORY 542The 543.Nm 544protocol appeared in 545.Bx 4.2 . 546