original/man7/ip.7

   1 '\" t
   2 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM_ONE_PARA)
   5 .\" Permission is granted to distribute possibly modified copies
   6 .\" of this page provided the header is included verbatim,
   7 .\" and in case of nontrivial modification author and date
   8 .\" of the modification is added to the header.
   9 .\" %%%LICENSE_END
  10 .\"
  11 .\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $
  12 .\"
  13 .\" FIXME: The following socket options are yet to be documented
  14 .\"     IP_XFRM_POLICY (2.5.48)
  15 .\"         Needs CAP_NET_ADMIN
  16 .\"     IP_IPSEC_POLICY (2.5.47)
  17 .\"         Needs CAP_NET_ADMIN
  18 .\"     IP_PASSSEC (2.6.17)
  19 .\"         Boolean
  20 .\"         commit 2c7946a7bf45ae86736ab3b43d0085e43947945c
  21 .\"         Author: Catherine Zhang <cxzhang@watson.ibm.com>
  22 .\"     IP_MINTTL (2.6.34)
  23 .\"         commit d218d11133d888f9745802146a50255a4781d37a
  24 .\"         Author: Stephen Hemminger <shemminger@vyatta.com>
  25 .\"     MCAST_JOIN_GROUP (2.4.22 / 2.6)
  26 .\"     MCAST_BLOCK_SOURCE (2.4.22 / 2.6)
  27 .\"     MCAST_UNBLOCK_SOURCE (2.4.22 / 2.6)
  28 .\"     MCAST_LEAVE_GROUP (2.4.22 / 2.6)
  29 .\"     MCAST_JOIN_SOURCE_GROUP (2.4.22 / 2.6)
  30 .\"     MCAST_LEAVE_SOURCE_GROUP (2.4.22 / 2.6)
  31 .\"     MCAST_MSFILTER (2.4.22 / 2.6)
  32 .\"     IP_UNICAST_IF (3.4)
  33 .\"         commit 76e21053b5bf33a07c76f99d27a74238310e3c71
  34 .\"         Author: Erich E. Hoover <ehoover@mines.edu>
  35 .\"
  36 .TH IP  7 2013-04-16 "Linux" "Linux Programmer's Manual"
  37 .SH NAME
  38 ip \- Linux IPv4 protocol implementation
  39 .SH SYNOPSIS
  40 .B #include <sys/socket.h>
  41 .br
  42 .\" .B #include <net/netinet.h> -- does not exist anymore
  43 .\" .B #include <linux/errqueue.h> -- never include <linux/foo.h>
  44 .B #include <netinet/in.h>
  45 .br
  46 .B #include <netinet/ip.h>        \fR/* superset of previous */
  47 .sp
  48 .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);"
  49 .br
  50 .IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);"
  51 .br
  52 .IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");"
  53 .SH DESCRIPTION
  54 Linux implements the Internet Protocol, version 4,
  55 described in RFC\ 791 and RFC\ 1122.
  56 .B ip
  57 contains a level 2 multicasting implementation conforming to RFC\ 1112.
  58 It also contains an IP router including a packet filter.
  59 .\" FIXME has someone verified that 2.1 is really 1812 compliant?
  60 .PP
  61 The programming interface is BSD-sockets compatible.
  62 For more information on sockets, see
  63 .BR socket (7).
  64 .PP
  65 An IP socket is created by calling the
  66 .BR socket (2)
  67 function as
  68 .BI "socket(AF_INET, " socket_type ", " protocol ) \fR.
  69 Valid socket types are
  70 .B SOCK_STREAM
  71 to open a
  72 .BR tcp (7)
  73 socket,
  74 .B SOCK_DGRAM
  75 to open a
  76 .BR udp (7)
  77 socket, or
  78 .B SOCK_RAW
  79 to open a
  80 .BR raw (7)
  81 socket to access the IP protocol directly.
  82 .I protocol
  83 is the IP protocol in the IP header to be received or sent.
  84 The only valid values for
  85 .I protocol
  86 are 0 and
  87 .B IPPROTO_TCP
  88 for TCP sockets, and 0 and
  89 .B IPPROTO_UDP
  90 for UDP sockets.
  91 For
  92 .B SOCK_RAW
  93 you may specify a valid IANA IP protocol defined in
  94 RFC\ 1700 assigned numbers.
  95 .PP
  96 When a process wants to receive new incoming packets or connections, it
  97 should bind a socket to a local interface address using
  98 .BR bind (2).
  99 In this case, only one IP socket may be bound to any given local
 100 (address, port) pair.
 101 When
 102 .B INADDR_ANY
 103 is specified in the bind call, the socket will be bound to
 104 .I all
 105 local interfaces.
 106 When
 107 .BR listen (2)
 108 is called on an unbound socket, the socket is automatically bound
 109 to a random free port with the local address set to
 110 .BR INADDR_ANY .
 111 When
 112 .BR connect (2)
 113 is called on an unbound socket, the socket is automatically bound
 114 to a random free port or to a usable shared port with the local address
 115 set to
 116 .BR INADDR_ANY .
 117
 118 A TCP local socket address that has been bound is unavailable for
 119 some time after closing, unless the
 120 .B SO_REUSEADDR
 121 flag has been set.
 122 Care should be taken when using this flag as it makes TCP less reliable.
 123 .SS Address format
 124 An IP socket address is defined as a combination of an IP interface
 125 address and a 16-bit port number.
 126 The basic IP protocol does not supply port numbers, they
 127 are implemented by higher level protocols like
 128 .BR udp (7)
 129 and
 130 .BR tcp (7).
 131 On raw sockets
 132 .I sin_port
 133 is set to the IP protocol.
 134 .PP
 135 .in +4n
 136 .nf
 137 struct sockaddr_in {
 138     sa_family_t    sin_family; /* address family: AF_INET */
 139     in_port_t      sin_port;   /* port in network byte order */
 140     struct in_addr sin_addr;   /* internet address */
 141 };
 142
 143 /* Internet address. */
 144 struct in_addr {
 145     uint32_t       s_addr;     /* address in network byte order */
 146 };
 147 .fi
 148 .in
 149 .PP
 150 .I sin_family
 151 is always set to
 152 .BR AF_INET .
 153 This is required; in Linux 2.2 most networking functions return
 154 .B EINVAL
 155 when this setting is missing.
 156 .I sin_port
 157 contains the port in network byte order.
 158 The port numbers below 1024 are called
 159 .IR "privileged ports"
 160 (or sometimes:
 161 .IR "reserved ports" ).
 162 Only privileged processes (i.e., those having the
 163 .B CAP_NET_BIND_SERVICE
 164 capability) may
 165 .BR bind (2)
 166 to these sockets.
 167 Note that the raw IPv4 protocol as such has no concept of a
 168 port, they are implemented only by higher protocols like
 169 .BR tcp (7)
 170 and
 171 .BR udp (7).
 172 .PP
 173 .I sin_addr
 174 is the IP host address.
 175 The
 176 .I s_addr
 177 member of
 178 .I struct in_addr
 179 contains the host interface address in network byte order.
 180 .I in_addr
 181 should be assigned one of the
 182 .BR INADDR_*
 183 values (e.g.,
 184 .BR INADDR_ANY )
 185 or set using the
 186 .BR inet_aton (3),
 187 .BR inet_addr (3),
 188 .BR inet_makeaddr (3)
 189 library functions or directly with the name resolver (see
 190 .BR gethostbyname (3)).
 191
 192 IPv4 addresses are divided into unicast, broadcast
 193 and multicast addresses.
 194 Unicast addresses specify a single interface of a host,
 195 broadcast addresses specify all hosts on a network and multicast
 196 addresses address all hosts in a multicast group.
 197 Datagrams to broadcast addresses can be sent or received only when the
 198 .B SO_BROADCAST
 199 socket flag is set.
 200 In the current implementation, connection-oriented sockets are allowed
 201 to use only unicast addresses.
 202 .\" Leave a loophole for XTP @)
 203
 204 Note that the address and the port are always stored in
 205 network byte order.
 206 In particular, this means that you need to call
 207 .BR htons (3)
 208 on the number that is assigned to a port.
 209 All address/port manipulation
 210 functions in the standard library work in network byte order.
 211
 212 There are several special addresses:
 213 .B INADDR_LOOPBACK
 214 (127.0.0.1)
 215 always refers to the local host via the loopback device;
 216 .B INADDR_ANY
 217 (0.0.0.0)
 218 means any address for binding;
 219 .B INADDR_BROADCAST
 220 (255.255.255.255)
 221 means any host and has the same effect on bind as
 222 .B INADDR_ANY
 223 for historical reasons.
 224 .SS Socket options
 225 IP supports some protocol-specific socket options that can be set with
 226 .BR setsockopt (2)
 227 and read with
 228 .BR getsockopt (2).
 229 The socket option level for IP is
 230 .BR IPPROTO_IP .
 231 .\" or SOL_IP on Linux
 232 A boolean integer flag is zero when it is false, otherwise true.
 233 .TP
 234 .BR IP_ADD_MEMBERSHIP " (since Linux 1.2)"
 235 Join a multicast group.
 236 Argument is an
 237 .I ip_mreqn
 238 structure.
 239 .sp
 240 .in +4n
 241 .nf
 242 struct ip_mreqn {
 243     struct in_addr imr_multiaddr; /* IP multicast group
 244                                      address */
 245     struct in_addr imr_address;   /* IP address of local
 246                                      interface */
 247     int            imr_ifindex;   /* interface index */
 248 };
 249 .fi
 250 .in
 251 .sp
 252 .I imr_multiaddr
 253 contains the address of the multicast group the application
 254 wants to join or leave.
 255 It must be a valid multicast address
 256 .\" (i.e., within the 224.0.0.0-239.255.255.255 range)
 257 (or
 258 .BR setsockopt (2)
 259 fails with the error
 260 .BR EINVAL ).
 261 .I imr_address
 262 is the address of the local interface with which the system
 263 should join the multicast group; if it is equal to
 264 .B INADDR_ANY
 265 an appropriate interface is chosen by the system.
 266 .I imr_ifindex
 267 is the interface index of the interface that should join/leave the
 268 .I imr_multiaddr
 269 group, or 0 to indicate any interface.
 270 .IP
 271 The
 272 .I ip_mreqn
 273 structure is available only since Linux 2.2.
 274 For compatibility, the old
 275 .I ip_mreq
 276 structure (present since Linux 1.2) is still supported;
 277 it differs from
 278 .I ip_mreqn
 279 only by not including the
 280 .I imr_ifindex
 281 field.
 282 Only valid as a
 283 .BR setsockopt (2).
 284 .\"
 285 .TP
 286 .BR IP_ADD_SOURCE_MEMBERSHIP " (since Linux 2.4.22 / 2.5.68)"
 287 Join a multicast group and allow receiving data only
 288 from a specified source.
 289 Argument is an
 290 .I ip_mreq_source
 291 structure.
 292 .sp
 293 .in +4n
 294 .nf
 295 struct ip_mreq_source {
 296     struct in_addr imr_multiaddr;  /* IP multicast group
 297                                       address */
 298     struct in_addr imr_interface;  /* IP address of local
 299                                       interface */
 300     struct in_addr imr_sourceaddr; /* IP address of
 301                                       multicast source */
 302 };
 303 .fi
 304 .in
 305 .sp
 306 The
 307 .I ip_mreq_source
 308 structure is similar to
 309 .I ip_mreqn
 310 described under
 311 .BR IP_ADD_MEMBERSIP .
 312 The
 313 .I imr_multiaddr
 314 field contains the address of the multicast group the application
 315 wants to join or leave.
 316 The
 317 .I imr_interface
 318 field is the address of the local interface with which
 319 the system should join the multicast group.
 320 Finally, the
 321 .I imr_sourceaddr
 322 field contains the address of the source the
 323 application wants to receive data from.
 324 .IP
 325 This option can be used multiple times to allow
 326 receiving data from more than one source.
 327 .TP
 328 .BR IP_BLOCK_SOURCE " (since Linux 2.4.22 / 2.5.68)"
 329 Stop receiving multicast data from a specific source in a given group.
 330 This is valid only after the application has subscribed
 331 to the multicast group using either
 332 .BR IP_ADD_MEMBERSHIP
 333 or
 334 .BR IP_ADD_SOURCE_MEMBERSHIP .
 335 .IP
 336 Argument is an
 337 .I ip_mreq_source
 338 structure as described under
 339 .BR IP_ADD_SOURCE_MEMBERSHIP .
 340 .TP
 341 .BR IP_DROP_MEMBERSHIP " (since Linux 1.2)"
 342 Leave a multicast group.
 343 Argument is an
 344 .I ip_mreqn
 345 or
 346 .I ip_mreq
 347 structure similar to
 348 .BR IP_ADD_MEMBERSHIP .
 349 .TP
 350 .BR IP_DROP_SOURCE_MEMBERSHIP " (since Linux 2.4.22 / 2.5.68)"
 351 Leave a source-specific group\(emthat is, stop receiving data from
 352 a given multicast group that come from a given source.
 353 If the application has subscribed to multiple sources within
 354 the same group, data from the remaining sources will still be delivered.
 355 To stop receiving data from all sources at once, use
 356 .BR IP_LEAVE_GROUP .
 357 .IP
 358 Argument is an
 359 .I ip_mreq_source
 360 structure as described under
 361 .BR IP_ADD_SOURCE_MEMBERSHIP .
 362 .TP
 363 .BR IP_FREEBIND " (since Linux 2.4)"
 364 .\" Precisely: 2.4.0-test10
 365 If enabled, this boolean option allows binding to an IP address
 366 that is nonlocal or does not (yet) exist.
 367 This permits listening on a socket,
 368 without requiring the underlying network interface or the
 369 specified dynamic IP address to be up at the time that
 370 the application is trying to bind to it.
 371 This option is the per-socket equivalent of the
 372 .IR ip_nonlocal_bind
 373 .I /proc
 374 interface described below.
 375 .TP
 376 .BR IP_HDRINCL " (since Linux 2.0)"
 377 If enabled,
 378 the user supplies an IP header in front of the user data.
 379 Only valid for
 380 .B SOCK_RAW
 381 sockets.
 382 See
 383 .BR raw (7)
 384 for more information.
 385 When this flag is enabled the values set by
 386 .BR IP_OPTIONS ,
 387 .B IP_TTL
 388 and
 389 .B IP_TOS
 390 are ignored.
 391 .TP
 392 .BR IP_MSFILTER " (since Linux 2.4.22 / 2.5.68)"
 393 This option provides access to the advanced full-state filtering API.
 394 Argument is an
 395 .I ip_msfilter
 396 structure.
 397 .sp
 398 .in +4n
 399 .nf
 400 struct ip_msfilter {
 401     struct in_addr imsf_multiaddr; /* IP multicast group
 402                                       address */
 403     struct in_addr imsf_interface; /* IP address of local
 404                                       interface */
 405     uint32_t       imsf_fmode;     /* Filter-mode */
 406
 407     uint32_t       imsf_numsrc;    /* Number of sources in
 408                                       the following array */
 409     struct in_addr imsf_slist[1];  /* Array of source
 410                                       addresses */
 411 };
 412 .fi
 413 .in
 414 .sp
 415 There are two macros,
 416 .BR MCAST_INCLUDE
 417 and
 418 .BR MCAST_EXCLUDE ,
 419 which can be used to specify the filtering mode.
 420 Additionally, the
 421 .BR IP_MSFILTER_SIZE (n)
 422 macro exists to determine how much memory is needed to store
 423 .I ip_msfilter
 424 structure with
 425 .I n
 426 sources in the source list.
 427 .IP
 428 For the full description of multicast source filtering
 429 refer to RFC 3376.
 430 .TP
 431 .BR IP_MTU " (since Linux 2.2)"
 432 .\" Precisely: 2.1.124
 433 Retrieve the current known path MTU of the current socket.
 434 Valid only when the socket has been connected.
 435 Returns an integer.
 436 Only valid as a
 437 .BR getsockopt (2).
 438 .TP
 439 .BR IP_MTU_DISCOVER " (since Linux 2.2)"
 440 .\" Precisely: 2.1.124
 441 Set or receive the Path MTU Discovery setting for a socket.
 442 When enabled, Linux will perform Path MTU Discovery
 443 as defined in RFC\ 1191 on
 444 .B SOCK_STREAM
 445 sockets.
 446 For
 447 .RB non- SOCK_STREAM
 448 sockets,
 449 .B IP_PMTUDISC_DO
 450 forces the don't-fragment flag to be set on all outgoing packets.
 451 It is the user's responsibility to packetize the data
 452 in MTU-sized chunks and to do the retransmits if necessary.
 453 The kernel will reject (with
 454 .BR EMSGSIZE )
 455 datagrams that are bigger than the known path MTU.
 456 .B IP_PMTUDISC_WANT
 457 will fragment a datagram if needed according to the path MTU,
 458 or will set the don't-fragment flag otherwise.
 459
 460 The system-wide default can be toggled between
 461 .B IP_PMTUDISC_WANT
 462 and
 463 .B IP_PMTUDISC_DONT
 464 by writing (respectively, zero and nonzero values) to the
 465 .I /proc/sys/net/ipv4/ip_no_pmtu_disc
 466 file.
 467 .TS
 468 tab(:);
 469 c l
 470 l l.
 471 Path MTU discovery value:Meaning
 472 IP_PMTUDISC_WANT:Use per-route settings.
 473 IP_PMTUDISC_DONT:Never do Path MTU Discovery.
 474 IP_PMTUDISC_DO:Always do Path MTU Discovery.
 475 IP_PMTUDISC_PROBE:Set DF but ignore Path MTU.
 476 .TE
 477
 478 When PMTU discovery is enabled, the kernel automatically keeps track of
 479 the path MTU per destination host.
 480 When it is connected to a specific peer with
 481 .BR connect (2),
 482 the currently known path MTU can be retrieved conveniently using the
 483 .B IP_MTU
 484 socket option (e.g., after an
 485 .B EMSGSIZE
 486 error occurred).
 487 The path MTU may change over time.
 488 For connectionless sockets with many destinations,
 489 the new MTU for a given destination can also be accessed using the
 490 error queue (see
 491 .BR IP_RECVERR ).
 492 A new error will be queued for every incoming MTU update.
 493
 494 While MTU discovery is in progress, initial packets from datagram sockets
 495 may be dropped.
 496 Applications using UDP should be aware of this and not
 497 take it into account for their packet retransmit strategy.
 498
 499 To bootstrap the path MTU discovery process on unconnected sockets, it
 500 is possible to start with a big datagram size
 501 (up to 64K-headers bytes long) and let it shrink by updates of the path MTU.
 502 .\" FIXME this is an ugly hack
 503
 504 To get an initial estimate of the
 505 path MTU, connect a datagram socket to the destination address using
 506 .BR connect (2)
 507 and retrieve the MTU by calling
 508 .BR getsockopt (2)
 509 with the
 510 .B IP_MTU
 511 option.
 512
 513 It is possible to implement RFC 4821 MTU probing with
 514 .B SOCK_DGRAM
 515 or
 516 .B SOCK_RAW
 517 sockets by setting a value of
 518 .BR IP_PMTUDISC_PROBE
 519 (available since Linux 2.6.22).
 520 This is also particularly useful for diagnostic tools such as
 521 .BR tracepath (8)
 522 that wish to deliberately send probe packets larger than
 523 the observed Path MTU.
 524 .TP
 525 .BR IP_MULTICAST_ALL " (since Linux 2.6.31)"
 526 This option can be used to modify the delivery policy of multicast messages
 527 to sockets bound to the wildcard
 528 .B INADDR_ANY
 529 address.
 530 The argument is a boolean integer (defaults to 1).
 531 If set to 1,
 532 the socket will receive messages from all the groups that have been joined
 533 globally on the whole system.
 534 Otherwise, it will deliver messages only from
 535 the groups that have been explicitly joined (for example via the
 536 .B IP_ADD_MEMBERSHIP
 537 option) on this particular socket.
 538 .TP
 539 .BR IP_MULTICAST_IF " (since Linux 1.2)"
 540 Set the local device for a multicast socket.
 541 Argument is an
 542 .I ip_mreqn
 543 or
 544 .I ip_mreq
 545 structure similar to
 546 .BR IP_ADD_MEMBERSHIP .
 547 .IP
 548 When an invalid socket option is passed,
 549 .B ENOPROTOOPT
 550 is returned.
 551 .TP
 552 .BR IP_MULTICAST_LOOP " (since Linux 1.2)"
 553 Set or read a boolean integer argument that determines whether
 554 sent multicast packets should be looped back to the local sockets.
 555 .TP
 556 .BR IP_MULTICAST_TTL " (since Linux 1.2)"
 557 Set or read the time-to-live value of outgoing multicast packets for this
 558 socket.
 559 It is very important for multicast packets to set the smallest TTL possible.
 560 The default is 1 which means that multicast packets don't leave the local
 561 network unless the user program explicitly requests it.
 562 Argument is an integer.
 563 .TP
 564 .BR IP_NODEFRAG " (since Linux 2.6.36)"
 565 If enabled (argument is nonzero),
 566 the reassembly of outgoing packets is disabled in the netfilter layer.
 567 This option is valid only for
 568 .B SOCK_RAW
 569 sockets.
 570 The argument is an integer.
 571 .TP
 572 .BR IP_OPTIONS " (since Linux 2.0)"
 573 .\" Precisely: 1.3.30
 574 Set or get the IP options to be sent with every packet from this socket.
 575 The arguments are a pointer to a memory buffer containing the options
 576 and the option length.
 577 The
 578 .BR setsockopt (2)
 579 call sets the IP options associated with a socket.
 580 The maximum option size for IPv4 is 40 bytes.
 581 See RFC\ 791 for the allowed options.
 582 When the initial connection request packet for a
 583 .B SOCK_STREAM
 584 socket contains IP options, the IP options will be set automatically
 585 to the options from the initial packet with routing headers reversed.
 586 Incoming packets are not allowed to change options after the connection
 587 is established.
 588 The processing of all incoming source routing options
 589 is disabled by default and can be enabled by using the
 590 .I accept_source_route
 591 .I /proc
 592 interface.
 593 Other options like timestamps are still handled.
 594 For datagram sockets, IP options can be only set by the local user.
 595 Calling
 596 .BR getsockopt (2)
 597 with
 598 .B IP_OPTIONS
 599 puts the current IP options used for sending into the supplied buffer.
 600 .TP
 601 .BR IP_PKTINFO " (since Linux 2.2)"
 602 .\" Precisely: 2.1.68
 603 Pass an
 604 .B IP_PKTINFO
 605 ancillary message that contains a
 606 .I pktinfo
 607 structure that supplies some information about the incoming packet.
 608 This only works for datagram oriented sockets.
 609 The argument is a flag that tells the socket whether the
 610 .B IP_PKTINFO
 611 message should be passed or not.
 612 The message itself can only be sent/retrieved
 613 as control message with a packet using
 614 .BR recvmsg (2)
 615 or
 616 .BR sendmsg (2).
 617 .IP
 618 .in +4n
 619 .nf
 620 struct in_pktinfo {
 621     unsigned int   ipi_ifindex;  /* Interface index */
 622     struct in_addr ipi_spec_dst; /* Local address */
 623     struct in_addr ipi_addr;     /* Header Destination
 624                                     address */
 625 };
 626 .fi
 627 .in
 628 .IP
 629 .\" FIXME elaborate on that.
 630 .I ipi_ifindex
 631 is the unique index of the interface the packet was received on.
 632 .I ipi_spec_dst
 633 is the local address of the packet and
 634 .I ipi_addr
 635 is the destination address in the packet header.
 636 If
 637 .B IP_PKTINFO
 638 is passed to
 639 .BR sendmsg (2)
 640 and
 641 .\" This field is grossly misnamed
 642 .I ipi_spec_dst
 643 is not zero, then it is used as the local source address for the routing
 644 table lookup and for setting up IP source route options.
 645 When
 646 .I ipi_ifindex
 647 is not zero, the primary local address of the interface specified by the
 648 index overwrites
 649 .I ipi_spec_dst
 650 for the routing table lookup.
 651 .TP
 652 .BR IP_RECVERR " (since Linux 2.2)"
 653 .\" Precisely: 2.1.15
 654 Enable extended reliable error message passing.
 655 When enabled on a datagram socket, all
 656 generated errors will be queued in a per-socket error queue.
 657 When the user receives an error from a socket operation,
 658 the errors can be received by calling
 659 .BR recvmsg (2)
 660 with the
 661 .B MSG_ERRQUEUE
 662 flag set.
 663 The
 664 .I sock_extended_err
 665 structure describing the error will be passed in an ancillary message with
 666 the type
 667 .B IP_RECVERR
 668 and the level
 669 .BR IPPROTO_IP .
 670 .\" or SOL_IP on Linux
 671 This is useful for reliable error handling on unconnected sockets.
 672 The received data portion of the error queue contains the error packet.
 673 .IP
 674 The
 675 .B IP_RECVERR
 676 control message contains a
 677 .I sock_extended_err
 678 structure:
 679 .IP
 680 .in +4n
 681 .ne 18
 682 .nf
 683 #define SO_EE_ORIGIN_NONE    0
 684 #define SO_EE_ORIGIN_LOCAL   1
 685 #define SO_EE_ORIGIN_ICMP    2
 686 #define SO_EE_ORIGIN_ICMP6   3
 687
 688 struct sock_extended_err {
 689     uint32_t ee_errno;   /* error number */
 690     uint8_t  ee_origin;  /* where the error originated */
 691     uint8_t  ee_type;    /* type */
 692     uint8_t  ee_code;    /* code */
 693     uint8_t  ee_pad;
 694     uint32_t ee_info;    /* additional information */
 695     uint32_t ee_data;    /* other data */
 696     /* More data may follow */
 697 };
 698
 699 struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
 700 .fi
 701 .in
 702 .IP
 703 .I ee_errno
 704 contains the
 705 .I errno
 706 number of the queued error.
 707 .I ee_origin
 708 is the origin code of where the error originated.
 709 The other fields are protocol-specific.
 710 The macro
 711 .B SO_EE_OFFENDER
 712 returns a pointer to the address of the network object
 713 where the error originated from given a pointer to the ancillary message.
 714 If this address is not known, the
 715 .I sa_family
 716 member of the
 717 .I sockaddr
 718 contains
 719 .B AF_UNSPEC
 720 and the other fields of the
 721 .I sockaddr
 722 are undefined.
 723 .IP
 724 IP uses the
 725 .I sock_extended_err
 726 structure as follows:
 727 .I ee_origin
 728 is set to
 729 .B SO_EE_ORIGIN_ICMP
 730 for errors received as an ICMP packet, or
 731 .B SO_EE_ORIGIN_LOCAL
 732 for locally generated errors.
 733 Unknown values should be ignored.
 734 .I ee_type
 735 and
 736 .I ee_code
 737 are set from the type and code fields of the ICMP header.
 738 .I ee_info
 739 contains the discovered MTU for
 740 .B EMSGSIZE
 741 errors.
 742 The message also contains the
 743 .I sockaddr_in of the node
 744 caused the error, which can be accessed with the
 745 .B SO_EE_OFFENDER
 746 macro.
 747 The
 748 .I sin_family
 749 field of the
 750 .B SO_EE_OFFENDER
 751 address is
 752 .B AF_UNSPEC
 753 when the source was unknown.
 754 When the error originated from the network, all IP options
 755 .RB ( IP_OPTIONS ", " IP_TTL ", "
 756 etc.) enabled on the socket and contained in the
 757 error packet are passed as control messages.
 758 The payload of the packet causing the error is returned as normal payload.
 759 .\" FIXME . Is it a good idea to document that? It is a dubious feature.
 760 .\" On
 761 .\" .B SOCK_STREAM
 762 .\" sockets,
 763 .\" .B IP_RECVERR
 764 .\" has slightly different semantics. Instead of
 765 .\" saving the errors for the next timeout, it passes all incoming
 766 .\" errors immediately to the user.
 767 .\" This might be useful for very short-lived TCP connections which
 768 .\" need fast error handling. Use this option with care:
 769 .\" it makes TCP unreliable
 770 .\" by not allowing it to recover properly from routing
 771 .\" shifts and other normal
 772 .\" conditions and breaks the protocol specification.
 773 Note that TCP has no error queue;
 774 .B MSG_ERRQUEUE
 775 is not permitted on
 776 .B SOCK_STREAM
 777 sockets.
 778 .B IP_RECVERR
 779 is valid for TCP, but all errors are returned by socket function return or
 780 .B SO_ERROR
 781 only.
 782 .IP
 783 For raw sockets,
 784 .B IP_RECVERR
 785 enables passing of all received ICMP errors to the
 786 application, otherwise errors are only reported on connected sockets
 787 .IP
 788 It sets or retrieves an integer boolean flag.
 789 .B IP_RECVERR
 790 defaults to off.
 791 .TP
 792 .BR IP_RECVOPTS " (since Linux 2.2)"
 793 .\" Precisely: 2.1.15
 794 Pass all incoming IP options to the user in a
 795 .B IP_OPTIONS
 796 control message.
 797 The routing header and other options are already filled in
 798 for the local host.
 799 Not supported for
 800 .B SOCK_STREAM
 801 sockets.
 802 .TP
 803 .BR IP_RECVORIGDSTADDR " (since Linux 2.6.29)"
 804 .\" commit e8b2dfe9b4501ed0047459b2756ba26e5a940a69
 805 This boolean option enables the
 806 .B IP_ORIGDSTADDR
 807 ancillary message in
 808 .BR recvmsg (2),
 809 in which the kernel returns the original destination address
 810 of the datagram being received.
 811 The ancillary message contains a
 812 .IR "struct sockaddr_in" .
 813 .TP
 814 .BR IP_RECVTOS " (since Linux 2.2)"
 815 .\" Precisely: 2.1.68
 816 If enabled the
 817 .B IP_TOS
 818 ancillary message is passed with incoming packets.
 819 It contains a byte which specifies the Type of Service/Precedence
 820 field of the packet header.
 821 Expects a boolean integer flag.
 822 .TP
 823 .BR IP_RECVTTL " (since Linux 2.2)"
 824 .\" Precisely: 2.1.68
 825 When this flag is set, pass a
 826 .B IP_TTL
 827 control message with the time to live
 828 field of the received packet as a byte.
 829 Not supported for
 830 .B SOCK_STREAM
 831 sockets.
 832 .TP
 833 .BR IP_RETOPTS " (since Linux 2.2)"
 834 .\" Precisely: 2.1.15
 835 Identical to
 836 .BR IP_RECVOPTS ,
 837 but returns raw unprocessed options with timestamp and route record
 838 options not filled in for this hop.
 839 .TP
 840 .BR IP_ROUTER_ALERT " (since Linux 2.2)"
 841 .\" Precisely: 2.1.68
 842 Pass all to-be forwarded packets with the
 843 IP Router Alert option set to this socket.
 844 Only valid for raw sockets.
 845 This is useful, for instance, for user-space RSVP daemons.
 846 The tapped packets are not forwarded by the kernel; it is
 847 the user's responsibility to send them out again.
 848 Socket binding is ignored,
 849 such packets are only filtered by protocol.
 850 Expects an integer flag.
 851 .TP
 852 .BR IP_TOS " (since Linux 1.0)"
 853 Set or receive the Type-Of-Service (TOS) field that is sent
 854 with every IP packet originating from this socket.
 855 It is used to prioritize packets on the network.
 856 TOS is a byte.
 857 There are some standard TOS flags defined:
 858 .B IPTOS_LOWDELAY
 859 to minimize delays for interactive traffic,
 860 .B IPTOS_THROUGHPUT
 861 to optimize throughput,
 862 .B IPTOS_RELIABILITY
 863 to optimize for reliability,
 864 .B IPTOS_MINCOST
 865 should be used for "filler data" where slow transmission doesn't matter.
 866 At most one of these TOS values can be specified.
 867 Other bits are invalid and shall be cleared.
 868 Linux sends
 869 .B IPTOS_LOWDELAY
 870 datagrams first by default,
 871 but the exact behavior depends on the configured queueing discipline.
 872 .\" FIXME elaborate on this
 873 Some high priority levels may require superuser privileges (the
 874 .B CAP_NET_ADMIN
 875 capability).
 876 The priority can also be set in a protocol independent way by the
 877 .RB ( SOL_SOCKET ", " SO_PRIORITY )
 878 socket option (see
 879 .BR socket (7)).
 880 .\" Needs CAP_NET_ADMIN
 881 .\" Boolean
 882 .\" Since Linux 2.6.27
 883 .\" Author: KOVACS Krisztian <hidden@sch.bme.hu>
 884 .\" http://lwn.net/Articles/252545/
 885 .TP
 886 .BR IP_TRANSPARENT " (since Linux 2.6.24)"
 887 .\" commit f5715aea4564f233767ea1d944b2637a5fd7cd2e
 888 .\"     This patch introduces the IP_TRANSPARENT socket option: enabling that
 889 .\"     will make the IPv4 routing omit the non-local source address check on
 890 .\"     output. Setting IP_TRANSPARENT requires NET_ADMIN capability.
 891 .\" http://lwn.net/Articles/252545/
 892 Setting this boolean option enables transparent proxying on this socket.
 893 This socket option allows
 894 the calling application to bind to a nonlocal IP address and operate
 895 both as a client and a server with the foreign address as the local endpoint.
 896 NOTE: this requires that routing be set up in a way that
 897 packets going to the foreign address are routed through the TProxy box.
 898 Enabling this socket option requires superuser privileges
 899 (the
 900 .BR CAP_NET_ADMIN
 901 capability).
 902 .IP
 903 TProxy redirection with the iptables TPROXY target also requires that
 904 this option be set on the redirected socket.
 905 .TP
 906 .BR IP_TTL " (since Linux 1.0)"
 907 Set or retrieve the current time-to-live field that is used in every packet
 908 sent from this socket.
 909 .TP
 910 .BR IP_UNBLOCK_SOURCE " (since Linux 2.4.22 / 2.5.68)"
 911 Unblock previously blocked multicast source.
 912 Returns
 913 .BR EADDRNOTAVAIL
 914 when given source is not being blocked.
 915 .IP
 916 Argument is an
 917 .I ip_mreq_source
 918 structure as described under
 919 .BR IP_ADD_SOURCE_MEMBERSHIP .
 920 .SS /proc interfaces
 921 The IP protocol
 922 supports a set of
 923 .I /proc
 924 interfaces to configure some global parameters.
 925 The parameters can be accessed by reading or writing files in the directory
 926 .IR /proc/sys/net/ipv4/ .
 927 .\" FIXME As at 2.6.12, 14 Jun 2005, the following are undocumented:
 928 .\"     ip_queue_maxlen
 929 .\"     ip_conntrack_max
 930 Interfaces described as
 931 .I Boolean
 932 take an integer value, with a nonzero value ("true") meaning that
 933 the corresponding option is enabled, and a zero value ("false")
 934 meaning that the option is disabled.
 935 .\"
 936 .TP
 937 .IR ip_always_defrag " (Boolean; since Linux 2.2.13)"
 938 [New with kernel 2.2.13; in earlier kernel versions this feature
 939 was controlled at compile time by the
 940 .B CONFIG_IP_ALWAYS_DEFRAG
 941 option; this option is not present in 2.4.x and later]
 942
 943 When this boolean flag is enabled (not equal 0), incoming fragments
 944 (parts of IP packets
 945 that arose when some host between origin and destination decided
 946 that the packets were too large and cut them into pieces) will be
 947 reassembled (defragmented) before being processed, even if they are
 948 about to be forwarded.
 949
 950 Only enable if running either a firewall that is the sole link
 951 to your network or a transparent proxy; never ever use it for a
 952 normal router or host.
 953 Otherwise fragmented communication can be disturbed
 954 if the fragments travel over different links.
 955 Defragmentation also has a large memory and CPU time cost.
 956
 957 This is automagically turned on when masquerading or transparent
 958 proxying are configured.
 959 .\"
 960 .TP
 961 .IR ip_autoconfig " (since Linux 2.2 to 2.6.17)"
 962 .\" Precisely: since 2.1.68
 963 .\" FIXME document ip_autoconfig
 964 Not documented.
 965 .\"
 966 .TP
 967 .IR ip_default_ttl " (integer; default: 64; since Linux 2.2)"
 968 .\" Precisely: 2.1.15
 969 Set the default time-to-live value of outgoing packets.
 970 This can be changed per socket with the
 971 .B IP_TTL
 972 option.
 973 .\"
 974 .TP
 975 .IR ip_dynaddr " (Boolean; default: disabled; since Linux 2.0.31)"
 976 Enable dynamic socket address and masquerading entry rewriting on interface
 977 address change.
 978 This is useful for dialup interface with changing IP addresses.
 979 0 means no rewriting, 1 turns it on and 2 enables verbose mode.
 980 .\"
 981 .TP
 982 .IR ip_forward " (Boolean; default: disabled; since Linux 1.2)"
 983 Enable IP forwarding with a boolean flag.
 984 IP forwarding can be also set on a per-interface basis.
 985 .\"
 986 .TP
 987 .IR ip_local_port_range " (since Linux 2.2)"
 988 .\" Precisely: since 2.1.68
 989 Contains two integers that define the default local port range
 990 allocated to sockets.
 991 Allocation starts with the first number and ends with the second number.
 992 Note that these should not conflict with the ports used by masquerading
 993 (although the case is handled).
 994 Also arbitrary choices may cause problems with some firewall packet
 995 filters that make assumptions about the local ports in use.
 996 First number should be at least greater than 1024,
 997 or better, greater than 4096, to avoid clashes
 998 with well known ports and to minimize firewall problems.
 999 .\"
1000 .TP
1001 .IR ip_no_pmtu_disc " (Boolean; default: disabled; since Linux 2.2)"
1002 .\" Precisely: 2.1.15
1003 If enabled, don't do Path MTU Discovery for TCP sockets by default.
1004 Path MTU discovery may fail if misconfigured firewalls (that drop
1005 all ICMP packets) or misconfigured interfaces (e.g., a point-to-point
1006 link where the both ends don't agree on the MTU) are on the path.
1007 It is better to fix the broken routers on the path than to turn off
1008 Path MTU Discovery globally, because not doing it incurs a high cost
1009 to the network.
1010 .\"
1011 .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt
1012 .TP
1013 .IR ip_nonlocal_bind " (Boolean; default: disabled; since Linux 2.4)"
1014 .\" Precisely: patch-2.4.0-test10
1015 If set, allows processes to
1016 .BR bind (2)
1017 to nonlocal IP addresses,
1018 which can be quite useful, but may break some applications.
1019 .\"
1020 .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt
1021 .TP
1022 .IR ip6frag_time " (integer; default: 30)"
1023 Time in seconds to keep an IPv6 fragment in memory.
1024 .\"
1025 .\" The following is from 2.6.12: Documentation/networking/ip-sysctl.txt
1026 .TP
1027 .IR ip6frag_secret_interval " (integer; default: 600)"
1028 Regeneration interval (in seconds) of the hash secret (or lifetime
1029 for the hash secret) for IPv6 fragments.
1030 .TP
1031 .IR ipfrag_high_thresh " (integer), " ipfrag_low_thresh " (integer)"
1032 If the amount of queued IP fragments reaches
1033 .IR ipfrag_high_thresh ,
1034 the queue is pruned down to
1035 .IR ipfrag_low_thresh .
1036 Contains an integer with the number of bytes.
1037 .TP
1038 .I neigh/*
1039 See
1040 .BR arp (7).
1041 .\" FIXME Document the conf/*/* interfaces
1042 .\" FIXME Document the route/* interfaces
1043 .\" FIXME document them all
1044 .SS Ioctls
1045 All ioctls described in
1046 .BR socket (7)
1047 apply to
1048 .BR ip .
1049 .\" 2006-04-02, mtk
1050 .\" commented out the following because ipchains is obsolete
1051 .\" .PP
1052 .\" The ioctls to configure firewalling are documented in
1053 .\" .BR ipfw (4)
1054 .\" from the
1055 .\" .B ipchains
1056 .\" package.
1057 .PP
1058 Ioctls to configure generic device parameters are described in
1059 .BR netdevice (7).
1060 .\" FIXME Add a discussion of multicasting
1061 .SH ERRORS
1062 .\" FIXME document all errors.
1063 .\"     We should really fix the kernels to give more uniform
1064 .\"     error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.)
1065 .TP
1066 .B EACCES
1067 The user tried to execute an operation without the necessary permissions.
1068 These include:
1069 sending a packet to a broadcast address without having the
1070 .B SO_BROADCAST
1071 flag set;
1072 sending a packet via a
1073 .I prohibit
1074 route;
1075 modifying firewall settings without superuser privileges (the
1076 .B CAP_NET_ADMIN
1077 capability);
1078 binding to a privileged port without superuser privileges (the
1079 .B CAP_NET_BIND_SERVICE
1080 capability).
1081 .TP
1082 .B EADDRINUSE
1083 Tried to bind to an address already in use.
1084 .TP
1085 .B EADDRNOTAVAIL
1086 A nonexistent interface was requested or the requested source
1087 address was not local.
1088 .TP
1089 .B EAGAIN
1090 Operation on a nonblocking socket would block.
1091 .TP
1092 .B EALREADY
1093 An connection operation on a nonblocking socket is already in progress.
1094 .TP
1095 .B ECONNABORTED
1096 A connection was closed during an
1097 .BR accept (2).
1098 .TP
1099 .B EHOSTUNREACH
1100 No valid routing table entry matches the destination address.
1101 This error can be caused by a ICMP message from a remote router or
1102 for the local routing table.
1103 .TP
1104 .B EINVAL
1105 Invalid argument passed.
1106 For send operations this can be caused by sending to a
1107 .I blackhole
1108 route.
1109 .TP
1110 .B EISCONN
1111 .BR connect (2)
1112 was called on an already connected socket.
1113 .TP
1114 .B EMSGSIZE
1115 Datagram is bigger than an MTU on the path and it cannot be fragmented.
1116 .TP
1117 .BR ENOBUFS ", " ENOMEM
1118 Not enough free memory.
1119 This often means that the memory allocation is limited by the socket
1120 buffer limits, not by the system memory, but this is not 100% consistent.
1121 .TP
1122 .B ENOENT
1123 .B SIOCGSTAMP
1124 was called on a socket where no packet arrived.
1125 .TP
1126 .B ENOPKG
1127 A kernel subsystem was not configured.
1128 .TP
1129 .BR ENOPROTOOPT " and " EOPNOTSUPP
1130 Invalid socket option passed.
1131 .TP
1132 .B ENOTCONN
1133 The operation is defined only on a connected socket, but the socket wasn't
1134 connected.
1135 .TP
1136 .B EPERM
1137 User doesn't have permission to set high priority, change configuration,
1138 or send signals to the requested process or group.
1139 .TP
1140 .B EPIPE
1141 The connection was unexpectedly closed or shut down by the other end.
1142 .TP
1143 .B ESOCKTNOSUPPORT
1144 The socket is not configured or an unknown socket type was requested.
1145 .PP
1146 Other errors may be generated by the overlaying protocols; see
1147 .BR tcp (7),
1148 .BR raw (7),
1149 .BR udp (7)
1150 and
1151 .BR socket (7).
1152 .SH NOTES
1153 .BR IP_FREEBIND ,
1154 .BR IP_MSFILTER ,
1155 .BR IP_MTU ,
1156 .BR IP_MTU_DISCOVER ,
1157 .BR IP_RECVORIGDSTADDR ,
1158 .BR IP_PKTINFO ,
1159 .BR IP_RECVERR ,
1160 .BR IP_ROUTER_ALERT ,
1161 and
1162 .BR IP_TRANSPARENT
1163 are Linux-specific.
1164 .\" IP_PASSSEC is Linux-specific
1165 .\" IP_XFRM_POLICY is Linux-specific
1166 .\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs
1167
1168 Be very careful with the
1169 .B SO_BROADCAST
1170 option \- it is not privileged in Linux.
1171 It is easy to overload the network
1172 with careless broadcasts.
1173 For new application protocols
1174 it is better to use a multicast group instead of broadcasting.
1175 Broadcasting is discouraged.
1176 .PP
1177 Some other BSD sockets implementations provide
1178 .B IP_RCVDSTADDR
1179 and
1180 .B IP_RECVIF
1181 socket options to get the destination address and the interface of
1182 received datagrams.
1183 Linux has the more general
1184 .B IP_PKTINFO
1185 for the same task.
1186 .PP
1187 Some BSD sockets implementations also provide an
1188 .B IP_RECVTTL
1189 option, but an ancillary message with type
1190 .B IP_RECVTTL
1191 is passed with the incoming packet.
1192 This is different from the
1193 .B IP_TTL
1194 option used in Linux.
1195 .PP
1196 Using
1197 .B SOL_IP
1198 socket options level isn't portable, BSD-based stacks use
1199 .B IPPROTO_IP
1200 level.
1201 .SS Compatibility
1202 For compatibility with Linux 2.0, the obsolete
1203 .BI "socket(AF_INET, SOCK_PACKET, " protocol )
1204 syntax is still supported to open a
1205 .BR packet (7)
1206 socket.
1207 This is deprecated and should be replaced by
1208 .BI "socket(AF_PACKET, SOCK_RAW, " protocol )
1209 instead.
1210 The main difference is the new
1211 .I sockaddr_ll
1212 address structure for generic link layer information instead of the old
1213 .BR sockaddr_pkt .
1214 .SH BUGS
1215 There are too many inconsistent error values.
1216 .PP
1217 The ioctls to configure IP-specific interface options and ARP tables are
1218 not described.
1219 .PP
1220 Some versions of glibc forget to declare
1221 .IR in_pktinfo .
1222 Workaround currently is to copy it into your program from this man page.
1223 .PP
1224 Receiving the original destination address with
1225 .B MSG_ERRQUEUE
1226 in
1227 .I msg_name
1228 by
1229 .BR recvmsg (2)
1230 does not work in some 2.2 kernels.
1231 .\" .SH AUTHORS
1232 .\" This man page was written by Andi Kleen.
1233 .SH SEE ALSO
1234 .BR recvmsg (2),
1235 .BR sendmsg (2),
1236 .BR byteorder (3),
1237 .BR ipfw (4),
1238 .BR capabilities (7),
1239 .BR icmp (7),
1240 .BR ipv6 (7),
1241 .BR netlink (7),
1242 .BR raw (7),
1243 .BR socket (7),
1244 .BR tcp (7),
1245 .BR udp (7)
1246 .PP
1247 RFC\ 791 for the original IP specification.
1248 RFC\ 1122 for the IPv4 host requirements.
1249 RFC\ 1812 for the IPv4 router requirements.
1250 .\" FIXME autobind INADDR REUSEADDR