IP(4) | Device Drivers Manual | IP(4) |
NAME¶
ip — Internet ProtocolSYNOPSIS¶
#include <sys/types.h>#include <sys/socket.h>
#include <netinet/in.h> int
socket(AF_INET, SOCK_RAW, proto);
DESCRIPTION¶
IP is the transport layer protocol used by the Internet protocol family. Options may be set at the IP level when using higher-level protocols that are based on IP (such as TCP and UDP). It may also be accessed through a “raw socket” when developing new protocols, or special-purpose applications. There are several IP-level setsockopt(2) and getsockopt(2) options.IP_OPTIONS
may be used to provide IP options to be transmitted in the IP header of each
outgoing packet or to examine the header options on incoming packets. IP
options may be used with any socket type in the Internet family. The format of
IP options to be sent is that specified by the IP protocol specification
(RFC-791), with one exception: the list of addresses for Source Route options
must include the first-hop gateway at the beginning of the list of gateways.
The first-hop gateway address will be extracted from the option list and the
size adjusted accordingly before use. To disable previously specified options,
use a zero-length buffer:
setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0);
IP_TOS
and IP_TTL
may be used to
set the type-of-service and time-to-live fields in the IP header for
SOCK_STREAM
, SOCK_DGRAM
, and
certain types of SOCK_RAW
sockets. For example,
int tos = IPTOS_LOWDELAY; /* see <netinet/ip.h> */ setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); int ttl = 60; /* max = 255 */ setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl));
IP_MINTTL
may be used to set the minimum acceptable TTL
a packet must have when received on a socket. All packets with a lower TTL are
silently dropped. This option is only really useful when set to 255,
preventing packets from outside the directly connected networks reaching local
listeners on sockets.
IP_DONTFRAG
may be used to set the Don't Fragment flag
on IP packets. Currently this option is respected only on
udp(4) and raw ip(4) sockets, unless the
IP_HDRINCL
option has been set. On
tcp(4) sockets, the Don't Fragment flag is controlled by the
Path MTU Discovery option. Sending a packet larger than the MTU size of the
egress interface, determined by the destination address, returns an
EMSGSIZE
error.
If the IP_RECVDSTADDR
option is enabled on a
SOCK_DGRAM
socket, the recvmsg(2)
call will return the destination IP address for a UDP datagram. The
msg_control field in the msghdr
structure points to a buffer that contains a cmsghdr
structure followed by the IP address. The cmsghdr fields
have the following values:
cmsg_len = sizeof(struct in_addr) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVDSTADDR
IP_SENDSRCADDR
. The msg_control field in the
msghdr structure should point to a buffer that contains a
cmsghdr structure followed by the IP address. The
cmsghdr fields should have the following values:
cmsg_len = sizeof(struct in_addr) cmsg_level = IPPROTO_IP cmsg_type = IP_SENDSRCADDR
IP_SENDSRCADDR
is defined to have the
same value as IP_RECVDSTADDR
, so the
IP_RECVDSTADDR
control message from
recvmsg(2) can be used directly as a control message for
sendmsg(2).
If the IP_ONESBCAST
option is enabled on a
SOCK_DGRAM
or a SOCK_RAW
socket, the destination address of outgoing broadcast datagrams on that socket
will be forced to the undirected broadcast address,
INADDR_BROADCAST
, before transmission. This is in
contrast to the default behavior of the system, which is to transmit
undirected broadcasts via the first network interface with the
IFF_BROADCAST flag set.
This option allows applications to choose which interface is used to transmit an
undirected broadcast datagram. For example, the following code would force an
undirected broadcast to be transmitted via the interface configured with the
broadcast address 192.168.2.255:
char msg[512]; struct sockaddr_in sin; u_char onesbcast = 1; /* 0 = disable (default), 1 = enable */ setsockopt(s, IPPROTO_IP, IP_ONESBCAST, &onesbcast, sizeof(onesbcast)); sin.sin_addr.s_addr = inet_addr("192.168.2.255"); sin.sin_port = htons(1234); sendto(s, msg, sizeof(msg), 0, &sin, sizeof(sin));
IP_TTL
option
to an appropriate value in order to prevent broadcast storms.
The application must have sufficient credentials to set the
SO_BROADCAST
socket level option, otherwise the
IP_ONESBCAST option has no effect.
If the IP_BINDANY
option is enabled on a
SOCK_STREAM
, SOCK_DGRAM
or a
SOCK_RAW
socket, one can bind(2) to
any address, even one not bound to any available network interface in the
system. This functionality (in conjunction with special firewall rules) can be
used for implementing a transparent proxy. The
PRIV_NETINET_BINDANY
privilege is needed to set this
option.
If the IP_RECVTTL
option is enabled on a
SOCK_DGRAM
socket, the recvmsg(2)
call will return the IP TTL (time to live) field for a UDP datagram. The
msg_control field in the msghdr structure points to a buffer that contains a
cmsghdr structure followed by the TTL. The cmsghdr fields have the following
values:
cmsg_len = sizeof(u_char) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVTTL
IP_RECVIF
option is enabled on a
SOCK_DGRAM
socket, the recvmsg(2)
call returns a struct sockaddr_dl corresponding to the
interface on which the packet was received. The
msg_control field in the msghdr
structure points to a buffer that contains a cmsghdr
structure followed by the struct sockaddr_dl. The
cmsghdr fields have the following values:
cmsg_len = sizeof(struct sockaddr_dl) cmsg_level = IPPROTO_IP cmsg_type = IP_RECVIF
IP_PORTRANGE
may be used to set the port range used for
selecting a local port number on a socket with an unspecified (zero) port
number. It has the following possible values:
IP_PORTRANGE_DEFAULT
- use the default range of values, normally
IPPORT_HIFIRSTAUTO
throughIPPORT_HILASTAUTO
. This is adjustable through the sysctl setting: net.inet.ip.portrange.first and net.inet.ip.portrange.last. IP_PORTRANGE_HIGH
- use a high range of values, normally
IPPORT_HIFIRSTAUTO
andIPPORT_HILASTAUTO
. This is adjustable through the sysctl setting: net.inet.ip.portrange.hifirst and net.inet.ip.portrange.hilast. IP_PORTRANGE_LOW
- use a low range of ports, which are normally restricted to
privileged processes on UNIX systems. The range is
normally from
IPPORT_RESERVED
- 1 down toIPPORT_RESERVEDSTART
in descending order. This is adjustable through the sysctl setting: net.inet.ip.portrange.lowfirst and net.inet.ip.portrange.lowlast.
IPPORT_RESERVED
- 1 (0 through 1023), respectively.
Note that these settings do not affect and are not accounted for in the use or
calculation of the other net.inet.ip.portrange values
above. Changing these values departs from UNIX
tradition and has security consequences that the administrator should
carefully evaluate before modifying these settings.
Ports are allocated at random within the specified port range in order to
increase the difficulty of random spoofing attacks. In scenarios such as
benchmarking, this behavior may be undesirable. In these cases,
net.inet.ip.portrange.randomized can be used to toggle
randomization off. If more than
net.inet.ip.portrange.randomcps ports have been
allocated in the last second, then return to sequential port allocation.
Return to random allocation only once the current port allocation rate drops
below net.inet.ip.portrange.randomcps for at least
net.inet.ip.portrange.randomtime seconds. The default
values for net.inet.ip.portrange.randomcps and
net.inet.ip.portrange.randomtime are 10 port allocations
per second and 45 seconds correspondingly.
Multicast Options¶
IP multicasting is supported only onAF_INET
sockets of
type SOCK_DGRAM
and SOCK_RAW
,
and only on networks where the interface driver supports multicasting.
The IP_MULTICAST_TTL
option changes the time-to-live
(TTL) for outgoing multicast datagrams in order to control the scope of the
multicasts:
u_char ttl; /* range: 0 to 255, default = 1 */ setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl));
IP_MULTICAST_IF
option
overrides the default for subsequent transmissions from a given socket:
struct in_addr addr; setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr));
INADDR_ANY
to specify the default interface.
To specify an interface by index, an instance of ip_mreqn
may be passed instead. The imr_ifindex member should be
set to the index of the desired interface, or 0 to specify the default
interface. The kernel differentiates between these two structures by their
size.
The use of IP_MULTICAST_IF is not
recommended, as multicast memberships are scoped to each individual
interface. It is supported for legacy use only by applications, such as
routing daemons, which expect to be able to transmit link-local IPv4 multicast
datagrams (224.0.0.0/24) on multiple interfaces, without requesting an
individual membership for each interface.
An interface's local IP address and multicast capability can be obtained via the
SIOCGIFCONF
and SIOCGIFFLAGS
ioctls. Normal applications should not need to use this option.
If a multicast datagram is sent to a group to which the sending host itself
belongs (on the outgoing interface), a copy of the datagram is, by default,
looped back by the IP layer for local delivery. The
IP_MULTICAST_LOOP
option gives the sender explicit
control over whether or not subsequent datagrams are looped back:
u_char loop; /* 0 = disable, 1 = enable (default) */ setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop));
IP_MULTICAST_LOOP
socket option
for new sockets.
A multicast datagram sent with an initial TTL greater than 1 may be delivered to
the sending host on a different interface from that on which it was sent, if
the host belongs to the destination group on that other interface. The
loopback control option has no effect on such delivery.
A host must become a member of a multicast group before it can receive datagrams
sent to the group. To join a multicast group, use the
IP_ADD_MEMBERSHIP
option:
struct ip_mreq mreq; setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq));
struct ip_mreq { struct in_addr imr_multiaddr; /* IP multicast address of group */ struct in_addr imr_interface; /* local IP address of interface */ }
INADDR_ANY
to choose the default interface,
although this is not recommended; this is considered to be the first interface
corresponding to the default route. Otherwise, the first multicast-capable
interface configured in the system will be used.
Prior to FreeBSD 7.0, if the
imr_interface member is within the network range
0.0.0.0/8
, it is treated as an interface index in the
system interface MIB, as per the RIP Version 2 MIB Extension (RFC-1724). In
versions of FreeBSD since 7.0, this behavior is no
longer supported. Developers should instead use the RFC 3678 multicast source
filter APIs; in particular, MCAST_JOIN_GROUP
.
Up to IP_MAX_MEMBERSHIPS
memberships may be added on a
single socket. Membership is associated with a single interface; programs
running on multihomed hosts may need to join the same group on more than one
interface.
To drop a membership, use:
struct ip_mreq mreq; setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq));
Source-Specific Multicast Options¶
Since FreeBSD 8.0, the use of Source-Specific Multicast (SSM) is supported. These extensions require an IGMPv3 multicast router in order to make best use of them. If a legacy multicast router is present on the link, FreeBSD will simply downgrade to the version of IGMP spoken by the router, and the benefits of source filtering on the upstream link will not be present, although the kernel will continue to squelch transmissions from blocked sources. Each group membership on a socket now has a filter mode:MCAST_EXCLUDE
- Datagrams sent to this group are accepted, unless the source is in a list of blocked source addresses.
MCAST_INCLUDE
- Datagrams sent to this group are accepted only if the source is in a list of accepted source addresses.
IP_ADD_MEMBERSHIP
option
are placed in exclusive-mode, and are able to request that certain sources are
blocked or allowed. This is known as the delta-based API.
To block a multicast source on an existing group membership:
struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_BLOCK_SOURCE, &mreqs, sizeof(mreqs));
struct ip_mreq_source { struct in_addr imr_multiaddr; /* IP multicast address of group */ struct in_addr imr_sourceaddr; /* IP address of source */ struct in_addr imr_interface; /* local IP address of interface */ }
struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_UNBLOCK_SOURCE, &mreqs, sizeof(mreqs));
IP_BLOCK_SOURCE
and
IP_UNBLOCK_SOURCE
options are not
permitted for inclusive-mode group memberships.
To join a multicast group in MCAST_INCLUDE
mode with a
single source, or add another source to an existing inclusive-mode membership:
struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_ADD_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs));
struct ip_mreq_source mreqs; setsockopt(s, IPPROTO_IP, IP_DROP_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs));
IP_ADD_SOURCE_MEMBERSHIP
and
IP_DROP_SOURCE_MEMBERSHIP
options are
not accepted for exclusive-mode group memberships. However,
both exclusive and inclusive mode memberships support the use of the
full-state API documented in RFC 3678. For management of
source filter lists using this API, please refer to
sourcefilter(3).
The sysctl settings net.inet.ip.mcast.maxsocksrc and
net.inet.ip.mcast.maxgrpsrc are used to specify an upper
limit on the number of per-socket and per-group source filter entries which
the kernel may allocate.
Raw IP Sockets¶
Raw IP sockets are connectionless, and are normally used with the sendto(2) and recvfrom(2) calls, though the connect(2) call may also be used to fix the destination for future packets (in which case the read(2) or recv(2) and write(2) or send(2) system calls may be used). If proto is 0, the default protocolIPPROTO_RAW
is used for outgoing packets, and only
incoming packets destined for that protocol are received. If
proto is non-zero, that protocol number will be used on
outgoing packets and to filter incoming packets.
Outgoing packets automatically have an IP header prepended to them (based on the
destination address and the protocol number the socket is created with),
unless the IP_HDRINCL
option has been set. Incoming
packets are received with IP header and options intact.
IP_HDRINCL
indicates the complete IP header is included
with the data and may be used only with the SOCK_RAW
type.
#include <netinet/in_systm.h> #include <netinet/ip.h> int hincl = 1; /* 1 = on, 0 = off */ setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl));
ip->ip_v = IPVERSION; ip->ip_hl = hlen >> 2; ip->ip_id = 0; /* 0 means kernel set appropriate value */ ip->ip_off = offset;
INADDR_ANY
, the kernel will
choose an appropriate address.
ERRORS¶
A socket operation may fail with one of the following errors returned:- [
EISCONN
] - when trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination address specified and the socket is already connected;
- [
ENOTCONN
] - when trying to send a datagram, but no destination address is specified, and the socket has not been connected;
- [
ENOBUFS
] - when the system runs out of memory for an internal data structure;
- [
EADDRNOTAVAIL
] - when an attempt is made to create a socket with a network address for which no network interface exists.
- [
EACCES
] - when an attempt is made to create a raw IP socket by a non-privileged process.
- [
EINVAL
] - An unknown socket option name was given.
- [
EINVAL
] - The IP option field was improperly formed; an option field was shorter than the minimum value or longer than the option buffer provided.
IP_HDRINCL
option
set:
- [
EINVAL
] - The user-supplied ip_len field was not equal to the length of the datagram written to the socket.
SEE ALSO¶
getsockopt(2), recv(2), send(2), byteorder(3), icmp(4), igmp(4), inet(4), intro(4), multicast(4), sourcefilter(3) D. Thaler, B. Fenner, and B. Quinn, Socket Interface Extensions for Multicast Source Filters, RFC 3678, Jan 2004.HISTORY¶
The ip protocol appeared in 4.2BSD. The ip_mreqn structure appeared in Linux 2.4.June 1, 2009 | Debian |