.\"
.\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $
.\"
-.\" FIXME: The following socket options are yet to be documented
+.\" FIXME The following socket options are yet to be documented
.\" IP_XFRM_POLICY (2.5.48)
.\" Needs CAP_NET_ADMIN
.\" IP_IPSEC_POLICY (2.5.47)
.\" MCAST_JOIN_SOURCE_GROUP (2.4.22 / 2.6)
.\" MCAST_LEAVE_SOURCE_GROUP (2.4.22 / 2.6)
.\" MCAST_MSFILTER (2.4.22 / 2.6)
-.\" IP_MULTICAST_ALL (2.6.31)
-.\" commit f771bef98004d9d141b085d987a77d06669d4f4f
-.\" Author: Nivedita Singhvi <niv@us.ibm.com>
.\" IP_UNICAST_IF (3.4)
.\" commit 76e21053b5bf33a07c76f99d27a74238310e3c71
.\" Author: Erich E. Hoover <ehoover@mines.edu>
.\"
-.TH IP 7 2013-02-12 "Linux" "Linux Programmer's Manual"
+.TH IP 7 2014-05-10 "Linux" "Linux Programmer's Manual"
.SH NAME
ip \- Linux IPv4 protocol implementation
.SH SYNOPSIS
.B ip
contains a level 2 multicasting implementation conforming to RFC\ 1112.
It also contains an IP router including a packet filter.
-.\" FIXME has someone verified that 2.1 is really 1812 compliant?
+.\" FIXME . has someone verified that 2.1 is really 1812 compliant?
.PP
The programming interface is BSD-sockets compatible.
For more information on sockets, see
.BR bind (2)
to these sockets.
Note that the raw IPv4 protocol as such has no concept of a
-port, they are only implemented by higher protocols like
+port, they are implemented only by higher protocols like
.BR tcp (7)
and
.BR udp (7).
Unicast addresses specify a single interface of a host,
broadcast addresses specify all hosts on a network and multicast
addresses address all hosts in a multicast group.
-Datagrams to broadcast addresses can be only sent or received when the
+Datagrams to broadcast addresses can be sent or received only when the
.B SO_BROADCAST
socket flag is set.
-In the current implementation, connection-oriented sockets are only allowed
-to use unicast addresses.
+In the current implementation, connection-oriented sockets are allowed
+to use only unicast addresses.
.\" Leave a loophole for XTP @)
Note that the address and the port are always stored in
.I imr_address
is the address of the local interface with which the system
should join the multicast group; if it is equal to
-.B INADDR_ANY
+.BR INADDR_ANY ,
an appropriate interface is chosen by the system.
.I imr_ifindex
is the interface index of the interface that should join/leave the
.BR IP_MTU " (since Linux 2.2)"
.\" Precisely: 2.1.124
Retrieve the current known path MTU of the current socket.
-Only valid when the socket has been connected.
+Valid only when the socket has been connected.
Returns an integer.
Only valid as a
.BR getsockopt (2).
To bootstrap the path MTU discovery process on unconnected sockets, it
is possible to start with a big datagram size
(up to 64K-headers bytes long) and let it shrink by updates of the path MTU.
-.\" FIXME this is an ugly hack
+.\" FIXME . this is an ugly hack
To get an initial estimate of the
path MTU, connect a datagram socket to the destination address using
that wish to deliberately send probe packets larger than
the observed Path MTU.
.TP
+.BR IP_MULTICAST_ALL " (since Linux 2.6.31)"
+This option can be used to modify the delivery policy of multicast messages
+to sockets bound to the wildcard
+.B INADDR_ANY
+address.
+The argument is a boolean integer (defaults to 1).
+If set to 1,
+the socket will receive messages from all the groups that have been joined
+globally on the whole system.
+Otherwise, it will deliver messages only from
+the groups that have been explicitly joined (for example via the
+.B IP_ADD_MEMBERSHIP
+option) on this particular socket.
+.TP
.BR IP_MULTICAST_IF " (since Linux 1.2)"
Set the local device for a multicast socket.
Argument is an
.I ip_mreqn
or
.I ip_mreq
+.\" net: IP_MULTICAST_IF setsockopt now recognizes struct mreq
+.\" Commit: 3a084ddb4bf299a6e898a9a07c89f3917f0713f7
+(since Linux 3.5)
structure similar to
.BR IP_ADD_MEMBERSHIP .
.IP
.BR IP_NODEFRAG " (since Linux 2.6.36)"
If enabled (argument is nonzero),
the reassembly of outgoing packets is disabled in the netfilter layer.
-This option is only valid for
+This option is valid only for
.B SOCK_RAW
sockets.
The argument is an integer.
.fi
.in
.IP
-.\" FIXME elaborate on that.
+.\" FIXME . elaborate on that.
.I ipi_ifindex
is the unique index of the interface the packet was received on.
.I ipi_spec_dst
.TP
.BR IP_RECVTOS " (since Linux 2.2)"
.\" Precisely: 2.1.68
-If enabled the
+If enabled, the
.B IP_TOS
ancillary message is passed with incoming packets.
It contains a byte which specifies the Type of Service/Precedence
the calling application to bind to a nonlocal IP address and operate
both as a client and a server with the foreign address as the local endpoint.
NOTE: this requires that routing be set up in a way that
-packets going to the foreign address are routed through the TProxy box.
+packets going to the foreign address are routed through the TProxy box
+(i.e., the system hosting the application that employs the
+.B IP_TRANSPARENT
+socket option).
Enabling this socket option requires superuser privileges
(the
.BR CAP_NET_ADMIN
Only enable if running either a firewall that is the sole link
to your network or a transparent proxy; never ever use it for a
normal router or host.
-Otherwise fragmented communication can be disturbed
+Otherwise, fragmented communication can be disturbed
if the fragments travel over different links.
Defragmentation also has a large memory and CPU time cost.
.TP
.IR ip_local_port_range " (since Linux 2.2)"
.\" Precisely: since 2.1.68
-Contains two integers that define the default local port range
-allocated to sockets.
-Allocation starts with the first number and ends with the second number.
-Note that these should not conflict with the ports used by masquerading
+This file contains two integers that define the default local port range
+allocated to sockets that are not explicitly bound to a port number\(emthat
+is, the range used for
+.IR "ephemeral ports" .
+An ephemeral port is allocated to a socket in the following circumstances:
+.RS
+.IP * 3
+the port number in a socket address is specified as 0 when calling
+.BR bind (2);
+.IP *
+.BR listen (2)
+is called on a stream socket that was not previously bound;
+.IP *
+.BR connect (2)
+was called on a socket that was not previously bound;
+.IP *
+.BR sendto (2)
+is called on a datagram socket that was not previously bound.
+.RE
+.IP
+Allocation of ephemeral ports starts with the first number in
+.IR ip_local_port_range
+and ends with the second number.
+If the range of ephemeral ports is exhausted,
+then the relevant system call returns an error (but see BUGS).
+.IP
+Note that the port range in
+.IR ip_local_port_range
+should not conflict with the ports used by masquerading
(although the case is handled).
-Also arbitrary choices may cause problems with some firewall packet
+Also, arbitrary choices may cause problems with some firewall packet
filters that make assumptions about the local ports in use.
-First number should be at least greater than 1024,
+The first number should be at least greater than 1024,
or better, greater than 4096, to avoid clashes
with well known ports and to minimize firewall problems.
.\"
See
.BR arp (7).
.\" FIXME Document the conf/*/* interfaces
+.\"
.\" FIXME Document the route/* interfaces
-.\" FIXME document them all
.SS Ioctls
All ioctls described in
.BR socket (7)
Invalid socket option passed.
.TP
.B ENOTCONN
-The operation is only defined on a connected socket, but the socket wasn't
+The operation is defined only on a connected socket, but the socket wasn't
connected.
.TP
.B EPERM
Other errors may be generated by the overlaying protocols; see
.BR tcp (7),
.BR raw (7),
-.BR udp (7)
+.BR udp (7),
and
.BR socket (7).
.SH NOTES
.SH BUGS
There are too many inconsistent error values.
.PP
+The error used to diagnose exhaustion of the ephemeral port range differs
+across the various system calls
+.RB ( connect (2),
+.BR bind (2),
+.BR listen (2),
+.BR sendto (2))
+that can assign ephemeral ports.
+.PP
The ioctls to configure IP-specific interface options and ARP tables are
not described.
-.PP
-Some versions of glibc forget to declare
-.IR in_pktinfo .
-Workaround currently is to copy it into your program from this man page.
+.\" .PP
+.\" Some versions of glibc forget to declare
+.\" .IR in_pktinfo .
+.\" Workaround currently is to copy it into your program from this man page.
.PP
Receiving the original destination address with
.B MSG_ERRQUEUE
RFC\ 791 for the original IP specification.
RFC\ 1122 for the IPv4 host requirements.
RFC\ 1812 for the IPv4 router requirements.
-.\" FIXME autobind INADDR REUSEADDR
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.