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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)ip.4        8.2 (Berkeley) 11/30/93
  29 .\" $FreeBSD: src/share/man/man4/ip.4,v 1.13.2.9 2002/05/02 02:40:26 silby Exp $
  30 .\" $DragonFly: src/share/man/man4/ip.4,v 1.7 2007/12/15 10:23:58 swildner Exp $
  31 .\"
  32 .Dd March 3, 2001
  33 .Dt IP 4
  34 .Os
  35 .Sh NAME
  36 .Nm ip
  37 .Nd Internet Protocol
  38 .Sh SYNOPSIS
  39 .In sys/types.h
  40 .In sys/socket.h
  41 .In netinet/in.h
  42 .Ft int
  43 .Fn socket AF_INET SOCK_RAW proto
  44 .Sh DESCRIPTION
  45 .Tn IP
  46 is the transport layer protocol used
  47 by the Internet protocol family.
  48 Options may be set at the
  49 .Tn IP
  50 level
  51 when using higher-level protocols that are based on
  52 .Tn IP
  53 (such as
  54 .Tn TCP
  55 and
  56 .Tn UDP ) .
  57 It may also be accessed
  58 through a
  59 .Dq raw socket
  60 when developing new protocols, or
  61 special-purpose applications.
  62 .Pp
  63 There are several
  64 .Tn IP-level
  65 .Xr setsockopt 2
  66 and
  67 .Xr getsockopt 2
  68 options.
  69 .Dv IP_OPTIONS
  70 may be used to provide
  71 .Tn IP
  72 options to be transmitted in the
  73 .Tn IP
  74 header of each outgoing packet
  75 or to examine the header options on incoming packets.
  76 .Tn IP
  77 options may be used with any socket type in the Internet family.
  78 The format of
  79 .Tn IP
  80 options to be sent is that specified by the
  81 .Tn IP
  82 protocol specification (RFC 791), with one exception:
  83 the list of addresses for Source Route options must include the first-hop
  84 gateway at the beginning of the list of gateways.
  85 The first-hop gateway address will be extracted from the option list
  86 and the size adjusted accordingly before use.
  87 To disable previously specified options,
  88 use a zero-length buffer:
  89 .Bd -literal
  90 setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0);
  91 .Ed
  92 .Pp
  93 .Dv IP_TOS
  94 and
  95 .Dv IP_TTL
  96 may be used to set the type-of-service and time-to-live
  97 fields in the
  98 .Tn IP
  99 header for
 100 .Dv SOCK_STREAM , SOCK_DGRAM ,
 101 and certain types of
 102 .Dv SOCK_RAW
 103 sockets.
 104 For example,
 105 .Bd -literal
 106 int tos = IPTOS_LOWDELAY;       /* see <netinet/ip.h> */
 107 setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos));
 108
 109 int ttl = 60;                   /* max = 255 */
 110 setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl));
 111 .Ed
 112 .Pp
 113 .Dv IP_MINTTL
 114 may be used to set the minimum acceptable TTL a packet must have when
 115 received on a socket.
 116 All packets with a lower TTL are silently dropped.
 117 Works on already connected/connecting and listening sockets for RAW/UDP/TCP.
 118 It allows to implement security mechanisms described in RFC 3682 (GTSM).
 119 .Pp
 120 If the
 121 .Dv IP_RECVDSTADDR
 122 option is enabled on a
 123 .Dv SOCK_DGRAM
 124 socket,
 125 the
 126 .Xr recvmsg 2
 127 call will return the destination
 128 .Tn IP
 129 address for a
 130 .Tn UDP
 131 datagram.
 132 The msg_control field in the msghdr structure points to a buffer
 133 that contains a cmsghdr structure followed by the
 134 .Tn IP
 135 address.
 136 The cmsghdr fields have the following values:
 137 .Bd -literal
 138 cmsg_len = sizeof(struct in_addr)
 139 cmsg_level = IPPROTO_IP
 140 cmsg_type = IP_RECVDSTADDR
 141 .Ed
 142 .Pp
 143 If the
 144 .Dv IP_RECVTTL
 145 option is enabled on a
 146 .Dv SOCK_DGRAM
 147 socket, the
 148 .Xr recvmsg 2
 149 call will return the
 150 .Tn IP
 151 .Tn TTL
 152 (time to live) field for a
 153 .Tn UDP
 154 datagram.
 155 The msg_control field in the msghdr structure points to a buffer
 156 that contains a cmsghdr structure followed by the
 157 .Tn TTL .
 158 The cmsghdr fields have the following values:
 159 .Bd -literal
 160 cmsg_len = sizeof(u_char)
 161 cmsg_level = IPPROTO_IP
 162 cmsg_type = IP_RECVTTL
 163 .Ed
 164 .Pp
 165 .Dv IP_PORTRANGE
 166 may be used to set the port range used for selecting a local port number
 167 on a socket with an unspecified (zero) port number.
 168 It has the following
 169 possible values:
 170 .Bl -tag -width IP_PORTRANGE_DEFAULT
 171 .It Dv IP_PORTRANGE_DEFAULT
 172 use the default range of values, normally
 173 .Dv IPPORT_RESERVED
 174 through
 175 .Dv IPPORT_USERRESERVED .
 176 This is adjustable through the sysctl setting:
 177 .Va net.inet.ip.portrange.first
 178 and
 179 .Va net.inet.ip.portrange.last .
 180 .It Dv IP_PORTRANGE_HIGH
 181 use a high range of values, normally
 182 .Dv IPPORT_HIFIRSTAUTO
 183 and
 184 .Dv IPPORT_HILASTAUTO .
 185 This is adjustable through the sysctl setting:
 186 .Va net.inet.ip.portrange.hifirst
 187 and
 188 .Va net.inet.ip.portrange.hilast .
 189 .It Dv IP_PORTRANGE_LOW
 190 use a low range of ports, which are normally restricted to
 191 privileged processes on
 192 .Ux
 193 systems.  The range is normally from
 194 .Dv IPPORT_RESERVED - 1
 195 down to
 196 .Li IPPORT_RESERVEDSTART
 197 in descending order.
 198 This is adjustable through the sysctl setting:
 199 .Va net.inet.ip.portrange.lowfirst
 200 and
 201 .Va net.inet.ip.portrange.lowlast .
 202 .El
 203 .Ss "Multicast Options"
 204 .Tn IP
 205 multicasting is supported only on
 206 .Dv AF_INET
 207 sockets of type
 208 .Dv SOCK_DGRAM
 209 and
 210 .Dv SOCK_RAW ,
 211 and only on networks where the interface
 212 driver supports multicasting.
 213 .Pp
 214 The
 215 .Dv IP_MULTICAST_TTL
 216 option changes the time-to-live (TTL)
 217 for outgoing multicast datagrams
 218 in order to control the scope of the multicasts:
 219 .Bd -literal
 220 u_char ttl;     /* range: 0 to 255, default = 1 */
 221 setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl));
 222 .Ed
 223 .Pp
 224 Datagrams with a TTL of 1 are not forwarded beyond the local network.
 225 Multicast datagrams with a TTL of 0 will not be transmitted on any network,
 226 but may be delivered locally if the sending host belongs to the destination
 227 group and if multicast loopback has not been disabled on the sending socket
 228 (see below).  Multicast datagrams with TTL greater than 1 may be forwarded
 229 to other networks if a multicast router is attached to the local network.
 230 .Pp
 231 For hosts with multiple interfaces, each multicast transmission is
 232 sent from the primary network interface.
 233 The
 234 .Dv IP_MULTICAST_IF
 235 option overrides the default for
 236 subsequent transmissions from a given socket:
 237 .Bd -literal
 238 struct in_addr addr;
 239 setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr));
 240 .Ed
 241 .Pp
 242 where "addr" is the local
 243 .Tn IP
 244 address of the desired interface or
 245 .Dv INADDR_ANY
 246 to specify the default interface.
 247 An interface's local IP address and multicast capability can
 248 be obtained via the
 249 .Dv SIOCGIFCONF
 250 and
 251 .Dv SIOCGIFFLAGS
 252 ioctls.
 253 Normal applications should not need to use this option.
 254 .Pp
 255 If a multicast datagram is sent to a group to which the sending host itself
 256 belongs (on the outgoing interface), a copy of the datagram is, by default,
 257 looped back by the IP layer for local delivery.
 258 The
 259 .Dv IP_MULTICAST_LOOP
 260 option gives the sender explicit control
 261 over whether or not subsequent datagrams are looped back:
 262 .Bd -literal
 263 u_char loop;    /* 0 = disable, 1 = enable (default) */
 264 setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop));
 265 .Ed
 266 .Pp
 267 This option
 268 improves performance for applications that may have no more than one
 269 instance on a single host (such as a router daemon), by eliminating
 270 the overhead of receiving their own transmissions.  It should generally not
 271 be used by applications for which there may be more than one instance on a
 272 single host (such as a conferencing program) or for which the sender does
 273 not belong to the destination group (such as a time querying program).
 274 .Pp
 275 A multicast datagram sent with an initial TTL greater than 1 may be delivered
 276 to the sending host on a different interface from that on which it was sent,
 277 if the host belongs to the destination group on that other interface.  The
 278 loopback control option has no effect on such delivery.
 279 .Pp
 280 A host must become a member of a multicast group before it can receive
 281 datagrams sent to the group.  To join a multicast group, use the
 282 .Dv IP_ADD_MEMBERSHIP
 283 option:
 284 .Bd -literal
 285 struct ip_mreq mreq;
 286 setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq));
 287 .Ed
 288 .Pp
 289 where
 290 .Fa mreq
 291 is the following structure:
 292 .Bd -literal
 293 struct ip_mreq {
 294     struct in_addr imr_multiaddr; /* IP multicast address of group */
 295     struct in_addr imr_interface; /* local IP address of interface */
 296 }
 297 .Ed
 298 .Pp
 299 .Fa imr_interface
 300 should
 301 be
 302 .Dv INADDR_ANY
 303 to choose the default multicast interface,
 304 or the
 305 .Tn IP
 306 address of a particular multicast-capable interface if
 307 the host is multihomed.
 308 Membership is associated with a single interface;
 309 programs running on multihomed hosts may need to
 310 join the same group on more than one interface.
 311 Up to
 312 .Dv IP_MAX_MEMBERSHIPS
 313 (currently 20) memberships may be added on a
 314 single socket.
 315 .Pp
 316 To drop a membership, use:
 317 .Bd -literal
 318 struct ip_mreq mreq;
 319 setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq));
 320 .Ed
 321 .Pp
 322 where
 323 .Fa mreq
 324 contains the same values as used to add the membership.
 325 Memberships are dropped when the socket is closed or the process exits.
 326 .\"-----------------------
 327 .Ss "Raw IP Sockets"
 328 Raw
 329 .Tn IP
 330 sockets are connectionless,
 331 and are normally used with the
 332 .Xr sendto 2
 333 and
 334 .Xr recvfrom 2
 335 calls, though the
 336 .Xr connect 2
 337 call may also be used to fix the destination for future
 338 packets (in which case the
 339 .Xr read 2
 340 or
 341 .Xr recv 2
 342 and
 343 .Xr write 2
 344 or
 345 .Xr send 2
 346 system calls may be used).
 347 .Pp
 348 If
 349 .Fa proto
 350 is 0, the default protocol
 351 .Dv IPPROTO_RAW
 352 is used for outgoing
 353 packets, and only incoming packets destined for that protocol
 354 are received.
 355 If
 356 .Fa proto
 357 is non-zero, that protocol number will be used on outgoing packets
 358 and to filter incoming packets.
 359 .Pp
 360 Outgoing packets automatically have an
 361 .Tn IP
 362 header prepended to
 363 them (based on the destination address and the protocol
 364 number the socket is created with),
 365 unless the
 366 .Dv IP_HDRINCL
 367 option has been set.
 368 Incoming packets are received with
 369 .Tn IP
 370 header and options intact.
 371 .Pp
 372 .Dv IP_HDRINCL
 373 indicates the complete IP header is included with the data
 374 and may be used only with the
 375 .Dv SOCK_RAW
 376 type.
 377 .Bd -literal
 378 #include <netinet/in_systm.h>
 379 #include <netinet/ip.h>
 380
 381 int hincl = 1;                  /* 1 = on, 0 = off */
 382 setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl));
 383 .Ed
 384 .Pp
 385 Unlike previous
 386 .Bx
 387 releases, the program must set all
 388 the fields of the IP header, including the following:
 389 .Bd -literal
 390 ip->ip_v = IPVERSION;
 391 ip->ip_hl = hlen >> 2;
 392 ip->ip_id = 0;  /* 0 means kernel set appropriate value */
 393 ip->ip_off = offset;
 394 .Ed
 395 .Pp
 396 If the header source address is set to
 397 .Dv INADDR_ANY ,
 398 the kernel will choose an appropriate address.
 399 .Sh ERRORS
 400 A socket operation may fail with one of the following errors returned:
 401 .Bl -tag -width Er
 402 .It Bq Er EISCONN
 403 when trying to establish a connection on a socket which
 404 already has one, or when trying to send a datagram with the destination
 405 address specified and the socket is already connected;
 406 .It Bq Er ENOTCONN
 407 when trying to send a datagram, but
 408 no destination address is specified, and the socket hasn't been
 409 connected;
 410 .It Bq Er ENOBUFS
 411 when the system runs out of memory for
 412 an internal data structure;
 413 .It Bq Er EADDRNOTAVAIL
 414 when an attempt is made to create a
 415 socket with a network address for which no network interface
 416 exists.
 417 .It Bq Er EACCES
 418 when an attempt is made to create
 419 a raw IP socket by a non-privileged process.
 420 .El
 421 .Pp
 422 The following errors specific to
 423 .Tn IP
 424 may occur when setting or getting
 425 .Tn IP
 426 options:
 427 .Bl -tag -width EADDRNOTAVAILxx
 428 .It Bq Er EINVAL
 429 An unknown socket option name was given.
 430 .It Bq Er EINVAL
 431 The IP option field was improperly formed;
 432 an option field was shorter than the minimum value
 433 or longer than the option buffer provided.
 434 .El
 435 .Sh SEE ALSO
 436 .Xr getsockopt 2 ,
 437 .Xr recv 2 ,
 438 .Xr send 2 ,
 439 .Xr icmp 4 ,
 440 .Xr inet 4 ,
 441 .Xr intro 4
 442 .Sh HISTORY
 443 The
 444 .Nm
 445 protocol appeared in
 446 .Bx 4.2 .