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