View Source: ip(7) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
IP
!!!IP
NAME
SYNOPSIS
DESCRIPTION
ADDRESS FORMAT
SOCKET OPTIONS
SYSCTLS
IOCTLS
NOTES
ERRORS
VERSIONS
COMPATIBILITY
BUGS
AUTHORS
SEE ALSO
----
!!NAME


ip - Linux IPv4 protocol implementation
!!SYNOPSIS


__#include __
#include __


''tcp_socket'' __= socket(PF_INET, SOCK_STREAM,
0);__''
raw_socket'' __= socket(PF_INET, SOCK_RAW,__
''protocol''__);__''
udp_socket'' __= socket(PF_INET, SOCK_DGRAM,__
''protocol''__);__
!!DESCRIPTION


Linux implements the Internet Protocol, version 4, described
in RFC791 and RFC1122. __ip__ contains a level 2
multicasting implementation conforming to RFC1112. It also
contains an IP router including a packet
filter.


The programmer's interface is BSD sockets compatible. For
more information on sockets, see
socket(7).


An IP socket is created by calling the socket(2)
function as __socket(PF_INET, socket_type, protocol)__.
Valid socket types are __SOCK_STREAM__ to open a
tcp(7) socket, __SOCK_DGRAM__ to open a
udp(7) socket, or __SOCK_RAW__ to open a
raw(7) socket to access the IP protocol directly.
''protocol'' is the IP protocol in the IP header to be
received or sent. The only valid values for ''protocol''
are __0__ and __IPPROTO_TCP__ for TCP sockets and
__0__ and __IPPROTO_UDP__ for UDP sockets. For
__SOCK_RAW__ you may specify a valid IANA IP protocol
defined in RFC1700 assigned numbers.


When a process wants to receive new incoming packets or
connections, it should bind a socket to a local interface
address using bind(2). Only one IP socket may be
bound to any given local (address, port) pair. When
__INADDR_ANY__ is specified in the bind call the socket
will be bound to ''all'' local interfaces. When
listen(2) or connect(2) are called on a
unbound socket the socket is automatically bound to a random
free port with the local address set to
__INADDR_ANY__.


A TCP local socket address that has been bound is
unavailable for some time after closing, unless the
__SO_REUSEADDR__ flag has been set. Care should be taken
when using this flag as it makes TCP less
reliable.
!!ADDRESS FORMAT


An IP socket address is defined as a combination of an IP
interface address and a port number. The basic IP protocol
does not supply port numbers, they are implemented by higher
level protocols like udp(7) and tcp(7). On raw
sockets __sin_port__ is set to the IP
protocol.


 struct sockaddr_in {
     sa_family_t    sin_family; /* address family: AF_INET */
     u_int16_t      sin_port;   /* port in network byte order */
     struct in_addr  sin_addr;  /* internet address */
 };
 /* Internet address. */
 struct in_addr {
     u_int32_t      s_addr;     /* address in network byte order */
 };


''sin_family'' is always set to __AF_INET__. This is
required; in Linux 2.2 most networking functions return
__EINVAL__ when this setting is missing. ''sin_port''
contains the port in network byte order. The port numbers
below 1024 are called ''reserved ports''. Only processes
with effective user id 0 or the __CAP_NET_BIND_SERVICE__
capability may 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 tcp(7)
and udp(7).


''sin_addr'' is the IP host address. The ''addr''
member of __struct in_addr__ contains the host interface
address in network order. __in_addr__ should be only
accessed using the inet_aton(3), __inet_addr__(3),
inet_makeaddr(3) library functions or directly with
the name resolver (see gethostbyname(3)). IPv4
addresses are divided into unicast, broadcast and multicast
addresses. 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 __SO_BROADCAST__ socket flag is set. In
the current implementation connection oriented sockets are
only allowed to use unicast addresses.


Note that the address and the port are always stored in
network order. In particular, this means that you need to
call htons(3) on the number that is assigned to a
port. All address/port manipulation functions in the
standard library work in network order.


There are several special addresses: __INADDR_LOOPBACK__
(127.0.0.1) always refers to the local host via the loopback
device; __INADDR_ANY__ (0.0.0.0) means any address for
binding; __INADDR_BROADCAST__ (255.255.255.255) means any
host and has the same effect on bind as __INADDR_ANY__
for historical reasons.
!!SOCKET OPTIONS


IP supports some protocol specific socket options that can
be set with setsockopt(2) and read with
getsockopt(2). The socket option level for IP is
__SOL_IP__. A boolean integer flag is zero when it is
false, otherwise true.


__IP_OPTIONS__


Sets or get the IP options to be sent with every packet from
this socket. The arguments are a pointer to a memory buffer
containing the options and the option length. The
setsockopt(2) call sets the IP options associated
with a socket. The maximum option size for IPv4 is 40 bytes.
See RFC791 for the allowed options. When the initial
connection request packet for a __SOCK_STREAM__ socket
contains IP options, the IP options will be set
automatically to the options from the initial packet with
routing headers reversed. Incoming packets are not allowed
to change options after the connection is established. The
processing of all incoming source routing options is
disabled by default and can be enabled by using the
__accept_source_route__ sysctl. Other options like
timestamps are still handled. For datagram sockets, IP
options can be only set by the local user. Calling
getsockopt(2) with ''IP_OPTIONS'' puts the current
IP options used for sending into the supplied
buffer.


__IP_PKTINFO__


Pass an ''IP_PKTINFO'' ancillary message that contains a
__pktinfo__ structure that supplies some information
about the incoming packet. This only works for datagram
oriented sockets. The argument is a flag that tells the
socket whether the IP_PKTINFO message should be passed or
not. The message itself can only be sent/retrieved as
control message with a packet using recvmsg(2) or
sendmsg(2).


 struct in_pktinfo {
     unsigned int   ipi_ifindex;  /* Interface index */
     struct in_addr ipi_spec_dst; /* Local address */
     struct in_addr ipi_addr;     /* Header Destination address */
 };


__ipi_ifindex__ is the unique index of the interface the
packet was received on. __ipi_spec_dst__ is the local
address of the packet and __ipi_addr__ is the destination
address in the packet header. If ''IP_PKTINFO'' is passed
to sendmsg(2) then the outgoing packet will be sent
over the interface specified in __ipi_ifindex__ with the
destination address set to __ipi_spec_dst__


__IP_RECVTOS__


If enabled the ''IP_TOS'' ancillary message is passed
with incoming packets. It contains a byte which specifies
the Type of Service/Precedence field of the packet header.
Expects a boolean integer flag.


__IP_RECVTTL__


When this flag is set pass a ''IP_RECVTTL'' control
message with the time to live field of the received packet
as a byte. Not supported for __SOCK_STREAM__
sockets.


__IP_RECVOPTS__


Pass all incoming IP options to the user in a
''IP_OPTIONS'' control message. The routing header and
other options are already filled in for the local host. Not
supported for ''SOCK_STREAM'' sockets.


__IP_RETOPTS__


Identical to ''IP_RECVOPTS'' but returns raw unprocessed
options with timestamp and route record options not filled
in for this hop.


__IP_TOS__


Set or receive the Type-Of-Service (TOS) field that is sent
with every IP packet originating from this socket. It is
used to prioritize packets on the network. TOS is a byte.
There are some standard TOS flags defined:
__IPTOS_LOWDELAY__ to minimize delays for interactive
traffic, __IPTOS_THROUGHPUT__ to optimize throughput,
__IPTOS_RELIABILITY__ to optimize for reliability,
__IPTOS_MINCOST__ should be used for
__IPTOS_LOWDELAY__ datagrams first by default, but the
exact behaviour depends on the configured queueing
discipline. Some high priority levels may require an
effective user id of 0 or the __CAP_NET_ADMIN__
capability. The priority can also be set in a protocol
independent way by the ( __SOL_SOCKET, SO_PRIORITY__ )
socket option (see socket(7) ).


__IP_TTL__


Set or retrieve the current time to live field that is send
in every packet send from this socket.


__IP_HDRINCL__


If enabled the user supplies an ip header in front of the
user data. Only valid for __SOCK_RAW__ sockets. See
raw(7) for more information. When this flag is
enabled the values set by ''IP_OPTIONS'', ''IP_TTL''
and ''IP_TOS'' are ignored.


__IP_RECVERR__ (defined in
__


Enable extended reliable error message passing. When enabled
on a datagram socket all generated errors will be queued in
a per-socket error queue. When the user receives an error
from a socket operation the errors can be received by
calling recvmsg(2) with the __MSG_ERRQUEUE__ flag
set. The __sock_extended_err__ structure describing the
error will be passed in a ancillary message with the type
''IP_RECVERR'' and the level __SOL_IP__. This is
useful for reliable error handling on unconnected sockets.
The received data portion of the error queue contains the
error packet.


The ''IP_RECVERR'' control message contains a
__sock_extended_err__ structure:


#define SO_EE_ORIGIN_NONE       0
#define SO_EE_ORIGIN_LOCAL      1
#define SO_EE_ORIGIN_ICMP       2
#define SO_EE_ORIGIN_ICMP6      3
struct sock_extended_err {
u_int32_t       ee_errno;   /* error number */
u_int8_t        ee_origin;  /* where the error originated */
u_int8_t        ee_type;    /* type */
u_int8_t        ee_code;    /* code */
u_int8_t        ee_pad;
u_int32_t       ee_info;    /* additional information */
u_int32_t       ee_data;    /* other data */
/* More data may follow */
};
struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);


__ee_errno__ contains the errno number of the queued
error. __ee_origin__ is the origin code of where the
error originated. The other fields are protocol specific.
The macro __SO_EE_OFFENDER__ returns a pointer to the
address of the network object where the error originated
from given a pointer to the ancillary message. If this
address is not known, the ''sa_family'' member of the
__sockaddr__ contains __AF_UNSPEC__ and the other
fields of the __sockaddr__ are undefined.


IP uses the __sock_extended_err__ structure as follows:
''ee_origin'' is set to __SO_EE_ORIGIN_ICMP__ for
errors received as an ICMP packet, or
__SO_EE_ORIGIN_LOCAL__ for locally generated errors.
Unknown values should be ignored. ''ee_type'' and
''ee_code'' are set from the type and code fields of the
ICMP header. ''ee_info'' contains the discovered MTU for
__EMSGSIZE__ errors. The message also contains the
''sockaddr_in of the node'' caused the error, which can
be accessed with the __SO_EE_OFFENDER__ macro. The
''sin_family'' field of the SO_EE_OFFENDER address is
''AF_UNSPEC'' when the source was unknown. When the error
originated from the network, all IP options
(''IP_OPTIONS'', ''IP_TTL'', etc.) enabled on the
socket and contained in the error packet are passed as
control messages. The payload of the packet causing the
error is returned as normal payload. Note that TCP has no
error queue; __MSG_ERRQUEUE__ is illegal on
__SOCK_STREAM__ sockets. Thus all errors are returned by
socket function return or __SO_ERROR__ only.


For raw sockets, ''IP_RECVERR'' enables passing of all
received ICMP errors to the application, otherwise errors
are only reported on connected sockets


It sets or retrieves an integer boolean flag.
''IP_RECVERR'' defaults to off.


__IP_PMTU_DISCOVER__


Sets or receives the Path MTU Discovery setting for a
socket. When enabled, Linux will perform Path MTU Discovery
as defined in RFC1191 on this socket. The don't fragment
flag is set on all outgoing datagrams. The system-wide
default is controlled by the __ip_no_pmtu_disc__ sysctl
for __SOCK_STREAM__ sockets, and disabled on all others.
For non __SOCK_STREAM__ sockets it is the user's
responsibility to packetize the data in MTU sized chunks and
to do the retransmits if necessary. The kernel will reject
packets that are bigger than the known path MTU if this flag
is set (with __EMSGSIZE__ ).


When PMTU discovery is enabled the kernel automatically keeps track of the path MTU per destination host. When it is connected to a specific peer with connect(2) the currently known path MTU can be retrieved conveniently using the __IP_MTU__ socket option (e.g. after a __EMSGSIZE__ error occurred). It may change over time. For connectionless sockets with many destinations the new also MTU for a given destination can also be accessed using the error queue (see __IP_RECVERR__). A new error will be queued for every incoming MTU update.


While MTU discovery is in progress initial packets from
datagram sockets may be dropped. Applications using UDP
should be aware of this and not take it into account for
their packet retransmit strategy.


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.


To get an initial estimate of the path MTU connect a
datagram socket to the destination address using
connect(2) and retrieve the MTU by calling
getsockopt(2) with the __IP_MTU__
option.


__IP_MTU__


Retrieve the current known path MTU of the current socket.
Only valid when the socket has been connected. Returns an
integer. Only valid as a getsockopt(2).


__IP_ROUTER_ALERT__


Pass all to-be forwarded packets with the IP Router Alert
option set to this socket. Only valid for raw sockets. This
is useful, for instance, for user space RSVP daemons. The
tapped packets are not forwarded by the kernel, it is the
users responsibility to send them out again. Socket binding
is ignored, such packets are only filtered by protocol.
Expects an integer flag.


__IP_MULTICAST_TTL__


Set or reads the time-to-live value of outgoing multicast
packets for this socket. It is very important for multicast
packets to set the smallest TTL possible. The default is 1
which means that multicast packets don't leave the local
network unless the user program explicitly requests it.
Argument is an integer.


__IP_MULTICAST_LOOP__


Sets or reads a boolean integer argument whether sent
multicast packets should be looped back to the local
sockets.


__IP_ADD_MEMBERSHIP__


Join a multicast group. Argument is a __struct ip_mreqn__
structure.


 struct ip_mreqn {
     struct in_addr imr_multiaddr; /* IP multicast group address */
     struct in_addr imr_address;   /* IP address of local interface */
     int            imr_ifindex;   /* interface index */
 };


''imr_multiaddr'' contains the address of the multicast
group the application wants to join or leave. It must be a
valid multicast address. ''imr_address'' is the address
of the local interface with which the system should join the
multicast group; if it is equal to __INADDR_ANY__ an
appropriate interface is chosen by the system.
''imr_ifindex'' is the interface index of the interface
that should join/leave the ''imr_multiaddr'' group, or 0
to indicate any interface.


For compatibility, the old __ip_mreq__ structure is still
supported. It differs from __ip_mreqn__ only by not
including the ''imr_ifindex'' field. Only valid as a
setsockopt(2).


__IP_DROP_MEMBERSHIP__


Leave a multicast group. Argument is an __ip_mreqn__ or
__ip_mreq__ structure similar to
''IP_ADD_MEMBERSHIP''.


__IP_MULTICAST_IF__


Set the local device for a multicast socket. Argument is an
__ip_mreqn__ or __ip_mreq__ structure similar to
''IP_ADD_MEMBERSHIP''.


When an invalid socket option is passed, __ENOPROTOOPT__
is returned.
!!SYSCTLS


The IP protocol supports the sysctl interface to configure
some global options. The sysctls can be accessed by reading
or writing the __/proc/sys/net/ipv4/*__ files or using
the sysctl(2) interface.


__ip_default_ttl__


Set the default time-to-live value of outgoing packets. This
can be changed per socket with the ''IP_TTL''
option.


__ip_forward__


Enable IP forwarding with a boolean flag. IP forwarding can
be also set on a per interface basis.


__ip_dynaddr__


Enable dynamic socket address and masquerading entry
rewriting on interface address change. This is useful for
dialup interface with changing IP addresses. 0 means no
rewriting, 1 turns it on and 2 enables verbose
mode.


__ip_autoconfig__


Not documented.


__ip_local_port_range__


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
(although the case is handled). Also arbitary choices may
cause problems with some firewall packet filters that make
assumptions about the local ports in use. First number
should be at least


__ip_no_pmtu_disc__


If enabled, don't do Path MTU Discovery for TCP sockets by
default. Path MTU discovery may fail if misconfigured
firewalls (that drop all ICMP packets) or misconfigured
interfaces (e.g., a point-to-point link where the both ends
don't agree on the MTU) are on the path. It is better to fix
the broken routers on the path than to turn off Path MTU
Discovery globally, because not doing it incurs a high cost
to the network.


__ipfrag_high_thresh, ipfrag_low_thresh__


If the amount of queued IP fragments reaches
__ipfrag_high_thresh ,__ the queue is pruned down to
__ipfrag_low_thresh .__ Contains an integer with the
number of bytes.


__ip_always_defrag__


[[New with Kernel 2.2.13; in earlier kernel version the
feature was controlled at compile time by the
__CONFIG_IP_ALWAYS_DEFRAG__ option]


When this boolean frag is enabled (not equal 0) incoming
fragments (parts of IP packets that arose when some host
between origin and destination decided that the packets were
too large and cut them into pieces) will be reassembled
(defragmented) before being processed, even if they are
about to be forwarded.


Only enable if running either a firewall that is the sole
link to your network or a transparent proxy; never ever turn
on here for a normal router or host. Otherwise fragmented
communication may me disturbed when the fragments would
travel over different links. Defragmentation also has a
large memory and CPU time cost.


This is automagically turned on when masquerading or
transparent proxying are configured.


__neigh/*__


See arp(7).
!!IOCTLS


All ioctls described in socket(7) apply to
ip.


The ioctls to configure firewalling are documented in
ipfw(7) from the __ipchains__
package.


Ioctls to configure generic device parameters are described
in netdevice(7).
!!NOTES


Be very careful with the __SO_BROADCAST__ option - it is
not privileged in Linux. It is easy to overload the network
with careless broadcasts. For new application protocols it
is better to use a multicast group instead of broadcasting.
Broadcasting is discouraged.


Some other BSD sockets implementations provide
''IP_RCVDSTADDR'' and ''IP_RECVIF'' socket options to
get the destination address and the interface of received
datagrams. Linux has the more general ''IP_PKTINFO'' for
the same task.
!!ERRORS


__ENOTCONN__


The operation is only defined on a connected socket, but the
socket wasn't connected.


__EINVAL__


Invalid argument passed. For send operations this can be
caused by sending to a ''blackhole'' route.


__EMSGSIZE__


Datagram is bigger than an MTU on the path and it cannot be
fragmented.


__EACCES__


The user tried to execute an operation without the necessary
permissions. These include: Sending a packet to a broadcast
address without having the __SO_BROADCAST__ flag set.
Sending a packet via a ''prohibit'' route. Modifying
firewall settings without __CAP_NET_ADMIN__ or effective
user id 0. Binding to a reserved port without the
__CAP_NET_BIND_SERVICE__ capacibility or effective user
id 0.


__EADDRINUSE__


Tried to bind to an address already in use.


__ENOPROTOOPT__ and __EOPNOTSUPP__


Invalid socket option passed.


__EPERM__


User doesn't have permission to set high priority, change
configuration, or send signals to the requested process or
group,


__EADDRNOTAVAIL__


A non-existent interface was requested or the requested
source address was not local.


__EAGAIN__


Operation on a non-blocking socket would block.


__ESOCKTNOSUPPORT__


The socket is not configured or an unknown socket type was
requested.


__EISCONN__


connect(2) was called on an already connected
socket.


__EALREADY__


An connection operation on a non-blocking socket is already
in progress.


__ECONNABORTED__


A connection was closed during an
accept(2).


__EPIPE__


The connection was unexpectedly closed or shut down by the
other end.


__ENOENT__


__SIOCGSTAMP__ was called on a socket where no packet
arrived.


__EHOSTUNREACH__


No valid routing table entry matches the destination
address. This error can be caused by a ICMP message from a
remote router or for the local routing table.


__ENODEV__


Network device not available or not capable of sending
IP.


__ENOPKG__


A kernel subsystem was not configured.


__ENOBUFS, ENOMEM__


Not enough free memory. This often means that the memory
allocation is limited by the socket buffer limits, not by
the system memory, but this is not 100%
consistent.


Other errors may be generated by the overlaying protocols;
see tcp(7), raw(7), udp(7) and
socket(7).
!!VERSIONS


''IP_PKTINFO'', ''IP_MTU'', ''IP_PMTU_DISCOVER'',
''IP_PKTINFO'', ''IP_RECVERR'' and
''IP_ROUTER_ALERT'' are new options in Linux 2.2. They
are also all Linux specific and should not be used in
programs intended to be portable.


__struct ip_mreqn__ is new in Linux 2.2. Linux 2.0 only
supported __ip_mreq__.


The sysctls were introduced with Linux 2.2.
!!COMPATIBILITY


For compatibility with Linux 2.0, the obsolete
__socket(PF_INET, SOCK_RAW,__ ''protocol''__)__
syntax is still supported to open a packet(7) socket.
This is deprecated and should be replaced by
__socket(PF_PACKET, SOCK_RAW,__ ''protocol''__)__
instead. The main difference is the new __sockaddr_ll__
address structure for generic link layer information instead
of the old __sockaddr_pkt__.
!!BUGS


There are too many inconsistent error values.


The ioctls to configure IP-specific interface options and
ARP tables are not described.


Some versions of glibc forget to declare ''in_pktinfo.''
Workaround currently is to copy it into your program from
this man page.


Receiving the original destination address with
__MSG_ERRQUEUE__ in ''msg_name'' by recvmsg(2)
does not work in some 2.2 kernels.
!!AUTHORS


This man page was written by Andi Kleen.
!!SEE ALSO


sendmsg(2), recvmsg(2), socket(7),
netlink(7), tcp(7), udp(7),
raw(7), ipfw(7)


RFC791 for the original IP specification.
RFC1122 for the IPv4 host requirements.
RFC1812 for the IPv4 router requirements.
----
22 pages link to ip(7):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Monday, September 5, 2005 2:01:13 pm by "ScottLamb"
Edit PageHistory Diff Info LikePages