original/man7/ip.7

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