1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)ip.4 8.2 (Berkeley) 11/30/93 33.\" $FreeBSD$ 34.\" 35.Dd August 22, 2005 36.Dt IP 4 37.Os 38.Sh NAME 39.Nm ip 40.Nd Internet Protocol 41.Sh SYNOPSIS 42.In sys/types.h 43.In sys/socket.h 44.In netinet/in.h 45.Ft int 46.Fn socket AF_INET SOCK_RAW proto 47.Sh DESCRIPTION 48.Tn IP 49is the transport layer protocol used 50by the Internet protocol family. 51Options may be set at the 52.Tn IP 53level 54when using higher-level protocols that are based on 55.Tn IP 56(such as 57.Tn TCP 58and 59.Tn UDP ) . 60It may also be accessed 61through a 62.Dq raw socket 63when developing new protocols, or 64special-purpose applications. 65.Pp 66There are several 67.Tn IP-level 68.Xr setsockopt 2 69and 70.Xr getsockopt 2 71options. 72.Dv IP_OPTIONS 73may be used to provide 74.Tn IP 75options to be transmitted in the 76.Tn IP 77header of each outgoing packet 78or to examine the header options on incoming packets. 79.Tn IP 80options may be used with any socket type in the Internet family. 81The format of 82.Tn IP 83options to be sent is that specified by the 84.Tn IP 85protocol specification (RFC-791), with one exception: 86the list of addresses for Source Route options must include the first-hop 87gateway at the beginning of the list of gateways. 88The first-hop gateway address will be extracted from the option list 89and the size adjusted accordingly before use. 90To disable previously specified options, 91use a zero-length buffer: 92.Bd -literal 93setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0); 94.Ed 95.Pp 96.Dv IP_TOS 97and 98.Dv IP_TTL 99may be used to set the type-of-service and time-to-live 100fields in the 101.Tn IP 102header for 103.Dv SOCK_STREAM , SOCK_DGRAM , 104and certain types of 105.Dv SOCK_RAW 106sockets. 107For example, 108.Bd -literal 109int tos = IPTOS_LOWDELAY; /* see <netinet/ip.h> */ 110setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); 111 112int ttl = 60; /* max = 255 */ 113setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl)); 114.Ed 115.Pp 116.Dv IP_MINTTL 117may be used to set the minimum acceptable TTL a packet must have when 118received on a socket. 119All packets with a lower TTL are silently dropped. 120This option is only really useful when set to 255 preventing packets 121from outside the directly connected networks reaching local listeners 122on sockets. 123.Pp 124If the 125.Dv IP_RECVDSTADDR 126option is enabled on a 127.Dv SOCK_DGRAM 128socket, 129the 130.Xr recvmsg 2 131call will return the destination 132.Tn IP 133address for a 134.Tn UDP 135datagram. 136The 137.Vt msg_control 138field in the 139.Vt msghdr 140structure points to a buffer 141that contains a 142.Vt cmsghdr 143structure followed by the 144.Tn IP 145address. 146The 147.Vt cmsghdr 148fields have the following values: 149.Bd -literal 150cmsg_len = sizeof(struct in_addr) 151cmsg_level = IPPROTO_IP 152cmsg_type = IP_RECVDSTADDR 153.Ed 154.Pp 155The source address to be used for outgoing 156.Tn UDP 157datagrams on a socket that is not bound to a specific 158.Tn IP 159address can be specified as ancillary data with a type code of 160.Dv IP_SENDSRCADDR . 161The msg_control field in the msghdr structure should point to a buffer 162that contains a 163.Vt cmsghdr 164structure followed by the 165.Tn IP 166address. 167The cmsghdr fields should have the following values: 168.Bd -literal 169cmsg_len = sizeof(struct in_addr) 170cmsg_level = IPPROTO_IP 171cmsg_type = IP_SENDSRCADDR 172.Ed 173.Pp 174For convenience, 175.Dv IP_SENDSRCADDR 176is defined to have the same value as 177.Dv IP_RECVDSTADDR , 178so the 179.Dv IP_RECVDSTADDR 180control message from 181.Xr recvmsg 2 182can be used directly as a control message for 183.Xr sendmsg 2 . 184.Pp 185If the 186.Dv IP_ONESBCAST 187option is enabled on a 188.Dv SOCK_DGRAM 189or a 190.Dv SOCK_RAW 191socket, the destination address of outgoing 192broadcast datagrams on that socket will be forced 193to the undirected broadcast address, 194.Dv INADDR_BROADCAST , 195before transmission. 196This is in contrast to the default behavior of the 197system, which is to transmit undirected broadcasts 198via the first network interface with the 199.Dv IFF_BROADCAST flag set. 200.Pp 201This option allows applications to choose which 202interface is used to transmit an undirected broadcast 203datagram. 204For example, the following code would force an 205undirected broadcast to be transmitted via the interface 206configured with the broadcast address 192.168.2.255: 207.Bd -literal 208char msg[512]; 209struct sockaddr_in sin; 210u_char onesbcast = 1; /* 0 = disable (default), 1 = enable */ 211 212setsockopt(s, IPPROTO_IP, IP_ONESBCAST, &onesbcast, sizeof(onesbcast)); 213sin.sin_addr.s_addr = inet_addr("192.168.2.255"); 214sin.sin_port = htons(1234); 215sendto(s, msg, sizeof(msg), 0, &sin, sizeof(sin)); 216.Ed 217.Pp 218It is the application's responsibility to set the 219.Dv IP_TTL option 220to an appropriate value in order to prevent broadcast storms. 221The application must have sufficient credentials to set the 222.Dv SO_BROADCAST 223socket level option, otherwise the 224.Dv IP_ONESBCAST option has no effect. 225.Pp 226If the 227.Dv IP_RECVTTL 228option is enabled on a 229.Dv SOCK_DGRAM 230socket, the 231.Xr recvmsg 2 232call will return the 233.Tn IP 234.Tn TTL 235(time to live) field for a 236.Tn UDP 237datagram. 238The msg_control field in the msghdr structure points to a buffer 239that contains a cmsghdr structure followed by the 240.Tn TTL . 241The cmsghdr fields have the following values: 242.Bd -literal 243cmsg_len = sizeof(u_char) 244cmsg_level = IPPROTO_IP 245cmsg_type = IP_RECVTTL 246.Ed 247.Pp 248If the 249.Dv IP_RECVIF 250option is enabled on a 251.Dv SOCK_DGRAM 252socket, the 253.Xr recvmsg 2 254call returns a 255.Vt "struct sockaddr_dl" 256corresponding to the interface on which the 257packet was received. 258The 259.Va msg_control 260field in the 261.Vt msghdr 262structure points to a buffer that contains a 263.Vt cmsghdr 264structure followed by the 265.Vt "struct sockaddr_dl" . 266The 267.Vt cmsghdr 268fields have the following values: 269.Bd -literal 270cmsg_len = sizeof(struct sockaddr_dl) 271cmsg_level = IPPROTO_IP 272cmsg_type = IP_RECVIF 273.Ed 274.Pp 275.Dv IP_PORTRANGE 276may be used to set the port range used for selecting a local port number 277on a socket with an unspecified (zero) port number. 278It has the following 279possible values: 280.Bl -tag -width IP_PORTRANGE_DEFAULT 281.It Dv IP_PORTRANGE_DEFAULT 282use the default range of values, normally 283.Dv IPPORT_HIFIRSTAUTO 284through 285.Dv IPPORT_HILASTAUTO . 286This is adjustable through the sysctl setting: 287.Va net.inet.ip.portrange.first 288and 289.Va net.inet.ip.portrange.last . 290.It Dv IP_PORTRANGE_HIGH 291use a high range of values, normally 292.Dv IPPORT_HIFIRSTAUTO 293and 294.Dv IPPORT_HILASTAUTO . 295This is adjustable through the sysctl setting: 296.Va net.inet.ip.portrange.hifirst 297and 298.Va net.inet.ip.portrange.hilast . 299.It Dv IP_PORTRANGE_LOW 300use a low range of ports, which are normally restricted to 301privileged processes on 302.Ux 303systems. 304The range is normally from 305.Dv IPPORT_RESERVED 306\- 1 down to 307.Li IPPORT_RESERVEDSTART 308in descending order. 309This is adjustable through the sysctl setting: 310.Va net.inet.ip.portrange.lowfirst 311and 312.Va net.inet.ip.portrange.lowlast . 313.El 314.Pp 315The range of privileged ports which only may be opened by 316root-owned processes may be modified by the 317.Va net.inet.ip.portrange.reservedlow 318and 319.Va net.inet.ip.portrange.reservedhigh 320sysctl settings. 321The values default to the traditional range, 3220 through 323.Dv IPPORT_RESERVED 324\- 1 325(0 through 1023), respectively. 326Note that these settings do not affect and are not accounted for in the 327use or calculation of the other 328.Va net.inet.ip.portrange 329values above. 330Changing these values departs from 331.Ux 332tradition and has security 333consequences that the administrator should carefully evaluate before 334modifying these settings. 335.Pp 336Ports are allocated at random within the specified port range in order 337to increase the difficulty of random spoofing attacks. 338In scenarios such as benchmarking, this behavior may be undesirable. 339In these cases, 340.Va net.inet.ip.portrange.randomized 341can be used to toggle randomization off. 342If more than 343.Va net.inet.ip.portrange.randomcps 344ports have been allocated in the last second, then return to sequential 345port allocation. 346Return to random allocation only once the current port allocation rate 347drops below 348.Va net.inet.ip.portrange.randomcps 349for at least 350.Va net.inet.ip.portrange.randomtime 351seconds. 352The default values for 353.Va net.inet.ip.portrange.randomcps 354and 355.Va net.inet.ip.portrange.randomtime 356are 10 port allocations per second and 45 seconds correspondingly. 357.Ss "Multicast Options" 358.Pp 359.Tn IP 360multicasting is supported only on 361.Dv AF_INET 362sockets of type 363.Dv SOCK_DGRAM 364and 365.Dv SOCK_RAW , 366and only on networks where the interface 367driver supports multicasting. 368.Pp 369The 370.Dv IP_MULTICAST_TTL 371option changes the time-to-live (TTL) 372for outgoing multicast datagrams 373in order to control the scope of the multicasts: 374.Bd -literal 375u_char ttl; /* range: 0 to 255, default = 1 */ 376setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); 377.Ed 378.Pp 379Datagrams with a TTL of 1 are not forwarded beyond the local network. 380Multicast datagrams with a TTL of 0 will not be transmitted on any network, 381but may be delivered locally if the sending host belongs to the destination 382group and if multicast loopback has not been disabled on the sending socket 383(see below). 384Multicast datagrams with TTL greater than 1 may be forwarded 385to other networks if a multicast router is attached to the local network. 386.Pp 387For hosts with multiple interfaces, each multicast transmission is 388sent from the primary network interface. 389The 390.Dv IP_MULTICAST_IF 391option overrides the default for 392subsequent transmissions from a given socket: 393.Bd -literal 394struct in_addr addr; 395setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); 396.Ed 397.Pp 398where "addr" is the local 399.Tn IP 400address of the desired interface or 401.Dv INADDR_ANY 402to specify the default interface. 403An interface's local IP address and multicast capability can 404be obtained via the 405.Dv SIOCGIFCONF 406and 407.Dv SIOCGIFFLAGS 408ioctls. 409Normal applications should not need to use this option. 410.Pp 411If a multicast datagram is sent to a group to which the sending host itself 412belongs (on the outgoing interface), a copy of the datagram is, by default, 413looped back by the IP layer for local delivery. 414The 415.Dv IP_MULTICAST_LOOP 416option gives the sender explicit control 417over whether or not subsequent datagrams are looped back: 418.Bd -literal 419u_char loop; /* 0 = disable, 1 = enable (default) */ 420setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); 421.Ed 422.Pp 423This option 424improves performance for applications that may have no more than one 425instance on a single host (such as a router daemon), by eliminating 426the overhead of receiving their own transmissions. 427It should generally not 428be used by applications for which there may be more than one instance on a 429single host (such as a conferencing program) or for which the sender does 430not belong to the destination group (such as a time querying program). 431.Pp 432A multicast datagram sent with an initial TTL greater than 1 may be delivered 433to the sending host on a different interface from that on which it was sent, 434if the host belongs to the destination group on that other interface. 435The loopback control option has no effect on such delivery. 436.Pp 437A host must become a member of a multicast group before it can receive 438datagrams sent to the group. 439To join a multicast group, use the 440.Dv IP_ADD_MEMBERSHIP 441option: 442.Bd -literal 443struct ip_mreq mreq; 444setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq)); 445.Ed 446.Pp 447where 448.Fa mreq 449is the following structure: 450.Bd -literal 451struct ip_mreq { 452 struct in_addr imr_multiaddr; /* IP multicast address of group */ 453 struct in_addr imr_interface; /* local IP address of interface */ 454} 455.Ed 456.Pp 457.Va imr_interface 458should be set to 459.Dv INADDR_ANY 460to choose the default multicast interface, 461or the 462.Tn IP 463address of a particular multicast-capable interface if 464the host is multihomed. 465Since 466.Fx 4.4 , 467if the 468.Va imr_interface 469member is within the network range 470.Li 0.0.0.0/8 , 471it is treated as an interface index in the system interface MIB, 472as per the RIP Version 2 MIB Extension (RFC-1724). 473.Pp 474Membership is associated with a single interface; 475programs running on multihomed hosts may need to 476join the same group on more than one interface. 477Up to 478.Dv IP_MAX_MEMBERSHIPS 479(currently 20) memberships may be added on a 480single socket. 481.Pp 482To drop a membership, use: 483.Bd -literal 484struct ip_mreq mreq; 485setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); 486.Ed 487.Pp 488where 489.Fa mreq 490contains the same values as used to add the membership. 491Memberships are dropped when the socket is closed or the process exits. 492.\"----------------------- 493.Ss "Raw IP Sockets" 494.Pp 495Raw 496.Tn IP 497sockets are connectionless, 498and are normally used with the 499.Xr sendto 2 500and 501.Xr recvfrom 2 502calls, though the 503.Xr connect 2 504call may also be used to fix the destination for future 505packets (in which case the 506.Xr read 2 507or 508.Xr recv 2 509and 510.Xr write 2 511or 512.Xr send 2 513system calls may be used). 514.Pp 515If 516.Fa proto 517is 0, the default protocol 518.Dv IPPROTO_RAW 519is used for outgoing 520packets, and only incoming packets destined for that protocol 521are received. 522If 523.Fa proto 524is non-zero, that protocol number will be used on outgoing packets 525and to filter incoming packets. 526.Pp 527Outgoing packets automatically have an 528.Tn IP 529header prepended to 530them (based on the destination address and the protocol 531number the socket is created with), 532unless the 533.Dv IP_HDRINCL 534option has been set. 535Incoming packets are received with 536.Tn IP 537header and options intact. 538.Pp 539.Dv IP_HDRINCL 540indicates the complete IP header is included with the data 541and may be used only with the 542.Dv SOCK_RAW 543type. 544.Bd -literal 545#include <netinet/in_systm.h> 546#include <netinet/ip.h> 547 548int hincl = 1; /* 1 = on, 0 = off */ 549setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); 550.Ed 551.Pp 552Unlike previous 553.Bx 554releases, the program must set all 555the fields of the IP header, including the following: 556.Bd -literal 557ip->ip_v = IPVERSION; 558ip->ip_hl = hlen >> 2; 559ip->ip_id = 0; /* 0 means kernel set appropriate value */ 560ip->ip_off = offset; 561.Ed 562.Pp 563The 564.Va ip_len 565and 566.Va ip_off 567fields 568.Em must 569be provided in host byte order . 570All other fields must be provided in network byte order. 571See 572.Xr byteorder 3 573for more information on network byte order. 574If the 575.Va ip_id 576field is set to 0 then the kernel will choose an 577appropriate value. 578If the header source address is set to 579.Dv INADDR_ANY , 580the kernel will choose an appropriate address. 581.Sh ERRORS 582A socket operation may fail with one of the following errors returned: 583.Bl -tag -width Er 584.It Bq Er EISCONN 585when trying to establish a connection on a socket which 586already has one, or when trying to send a datagram with the destination 587address specified and the socket is already connected; 588.It Bq Er ENOTCONN 589when trying to send a datagram, but 590no destination address is specified, and the socket has not been 591connected; 592.It Bq Er ENOBUFS 593when the system runs out of memory for 594an internal data structure; 595.It Bq Er EADDRNOTAVAIL 596when an attempt is made to create a 597socket with a network address for which no network interface 598exists. 599.It Bq Er EACCES 600when an attempt is made to create 601a raw IP socket by a non-privileged process. 602.El 603.Pp 604The following errors specific to 605.Tn IP 606may occur when setting or getting 607.Tn IP 608options: 609.Bl -tag -width Er 610.It Bq Er EINVAL 611An unknown socket option name was given. 612.It Bq Er EINVAL 613The IP option field was improperly formed; 614an option field was shorter than the minimum value 615or longer than the option buffer provided. 616.El 617.Pp 618The following errors may occur when attempting to send 619.Tn IP 620datagrams via a 621.Dq raw socket 622with the 623.Dv IP_HDRINCL 624option set: 625.Bl -tag -width Er 626.It Bq Er EINVAL 627The user-supplied 628.Va ip_len 629field was not equal to the length of the datagram written to the socket. 630.El 631.Sh SEE ALSO 632.Xr getsockopt 2 , 633.Xr recv 2 , 634.Xr send 2 , 635.Xr byteorder 3 , 636.Xr icmp 4 , 637.Xr inet 4 , 638.Xr intro 4 639.Sh HISTORY 640The 641.Nm 642protocol appeared in 643.Bx 4.2 . 644