share/man/man4/ip.4

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