468 lines
13 KiB
Groff
468 lines
13 KiB
Groff
.\" $NetBSD: ip.4,v 1.31 2011/05/19 21:16:45 riastradh Exp $
|
|
.\"
|
|
.\" Copyright (c) 1983, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)ip.4 8.2 (Berkeley) 11/30/93
|
|
.\"
|
|
.Dd May 19, 2011
|
|
.Dt IP 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ip
|
|
.Nd Internet Protocol
|
|
.Sh SYNOPSIS
|
|
.In sys/socket.h
|
|
.In netinet/in.h
|
|
.Ft int
|
|
.Fn socket AF_INET SOCK_RAW proto
|
|
.Sh DESCRIPTION
|
|
.Tn IP
|
|
is the network layer protocol used by the Internet protocol family.
|
|
Options may be set at the
|
|
.Tn IP
|
|
level when using higher-level protocols that are based on
|
|
.Tn IP
|
|
(such as
|
|
.Tn TCP
|
|
and
|
|
.Tn UDP ) .
|
|
It may also be accessed through a
|
|
.Dq raw socket
|
|
when developing new protocols, or special-purpose applications.
|
|
.Pp
|
|
There are several
|
|
.Tn IP-level
|
|
.Xr setsockopt 2 Ns / Ns Xr getsockopt 2
|
|
options.
|
|
.Dv IP_OPTIONS
|
|
may be used to provide
|
|
.Tn IP
|
|
options to be transmitted in the
|
|
.Tn IP
|
|
header of each outgoing packet
|
|
or to examine the header options on incoming packets.
|
|
.Tn IP
|
|
options may be used with any socket type in the Internet family.
|
|
The format of
|
|
.Tn IP
|
|
options to be sent is that specified by the
|
|
.Tn 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:
|
|
.Bd -literal
|
|
setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0);
|
|
.Ed
|
|
.Pp
|
|
.Dv IP_TOS
|
|
and
|
|
.Dv IP_TTL
|
|
may be used to set the type-of-service and time-to-live fields in the
|
|
.Tn IP
|
|
header for
|
|
.Dv SOCK_STREAM
|
|
and
|
|
.Dv SOCK_DGRAM
|
|
sockets.
|
|
For example,
|
|
.Bd -literal
|
|
int tos = IPTOS_LOWDELAY; /* see \*[Lt]netinet/ip.h\*[Gt] */
|
|
setsockopt(s, IPPROTO_IP, IP_TOS, \*[Am]tos, sizeof(tos));
|
|
|
|
int ttl = 60; /* max = 255 */
|
|
setsockopt(s, IPPROTO_IP, IP_TTL, \*[Am]ttl, sizeof(ttl));
|
|
.Ed
|
|
.Pp
|
|
.Dv IP_IPSEC_POLICY
|
|
controls IPSec policy for sockets.
|
|
For example,
|
|
.Bd -literal
|
|
const char *policy = "in ipsec ah/transport//require";
|
|
char *buf = ipsec_set_policy(policy, strlen(policy));
|
|
setsockopt(s, IPPROTO_IP, IP_IPSEC_POLICY, buf, ipsec_get_policylen(buf));
|
|
.Ed
|
|
.Pp
|
|
.Dv IP_PORTRANGE
|
|
controls how ephemeral ports are allocated for
|
|
.Dv SOCK_STREAM
|
|
and
|
|
.Dv SOCK_DGRAM
|
|
sockets.
|
|
For example,
|
|
.Bd -literal
|
|
int range = IP_PORTRANGE_LOW; /* see \*[Lt]netinet/in.h\*[Gt] */
|
|
setsockopt(s, IPPROTO_IP, IP_PORTRANGE, \*[Am]range, sizeof(range));
|
|
.Ed
|
|
.Pp
|
|
If the
|
|
.Dv IP_RECVDSTADDR
|
|
option is enabled on a
|
|
.Dv SOCK_DGRAM
|
|
or
|
|
.Dv SOCK_RAW
|
|
socket,
|
|
the
|
|
.Xr recvmsg 2
|
|
call will return the destination
|
|
.Tn IP
|
|
address for a
|
|
.Tn UDP
|
|
datagram.
|
|
The msg_control field in the msghdr structure points to a buffer
|
|
that contains a cmsghdr structure followed by the
|
|
.Tn IP
|
|
address.
|
|
The cmsghdr fields have the following values:
|
|
.Bd -literal
|
|
cmsg_len = CMSG_LEN(sizeof(struct in_addr))
|
|
cmsg_level = IPPROTO_IP
|
|
cmsg_type = IP_RECVDSTADDR
|
|
.Ed
|
|
.Pp
|
|
If the
|
|
.Dv IP_RECVIF
|
|
option is enabled on a
|
|
.Dv SOCK_DGRAM
|
|
or
|
|
.Dv SOCK_RAW
|
|
socket,
|
|
the
|
|
.Xr recvmsg 2
|
|
call will return 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:
|
|
.Bd -literal
|
|
cmsg_len = CMSG_LEN(sizeof(struct sockaddr_dl))
|
|
cmsg_level = IPPROTO_IP
|
|
cmsg_type = IP_RECVIF
|
|
.Ed
|
|
.Pp
|
|
If the
|
|
.Dv IP_RECVTTL
|
|
option is enabled on a
|
|
.Dv SOCK_DGRAM
|
|
socket, the
|
|
.Xr recvmsg 2
|
|
call will return the
|
|
.Tn TTL
|
|
of the received datagram.
|
|
The msg_control field in the msghdr structure points to a buffer
|
|
that contains a cmsghdr structure followed by the
|
|
.Tn TTL
|
|
value.
|
|
The cmsghdr fields have the following values:
|
|
.Bd -literal
|
|
cmsg_len = CMSG_LEN(sizeof(uint8_t))
|
|
cmsg_level = IPPROTO_IP
|
|
cmsg_type = IP_RECVTTL
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Dv IP_MINTTL
|
|
option may be used on
|
|
.Dv SOCK_DGRAM
|
|
or
|
|
.Dv SOCK_STREAM
|
|
sockets to discard packets with a TTL lower than the option value.
|
|
This can be used to implement the
|
|
.Em Generalized TTL Security Mechanism (GTSM)
|
|
according to RFC 3682.
|
|
To discard all packets with a TTL lower than 255:
|
|
.Bd -literal -offset indent
|
|
int minttl = 255;
|
|
setsockopt(s, IPPROTO_IP, IP_MINTTL, \*[Am]minttl, sizeof(minttl));
|
|
.Ed
|
|
.Ss MULTICAST OPTIONS
|
|
.Tn IP
|
|
multicasting is supported only on
|
|
.Dv AF_INET
|
|
sockets of type
|
|
.Dv SOCK_DGRAM
|
|
and
|
|
.Dv SOCK_RAW ,
|
|
and only on networks where the interface driver supports multicasting.
|
|
.Pp
|
|
The
|
|
.Dv IP_MULTICAST_TTL
|
|
option changes the time-to-live (TTL) for outgoing multicast datagrams
|
|
in order to control the scope of the multicasts:
|
|
.Bd -literal
|
|
u_char ttl; /* range: 0 to 255, default = 1 */
|
|
setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, \*[Am]ttl, sizeof(ttl));
|
|
.Ed
|
|
.Pp
|
|
Datagrams with a TTL of 1 are not forwarded beyond the local network.
|
|
Multicast datagrams with a TTL of 0 will not be transmitted on any network,
|
|
but may be delivered locally if the sending host belongs to the destination
|
|
group and if multicast loopback has not been disabled on the sending socket
|
|
(see below).
|
|
Multicast datagrams with TTL greater than 1 may be forwarded
|
|
to other networks if a multicast router is attached to the local network.
|
|
.Pp
|
|
For hosts with multiple interfaces, each multicast transmission is
|
|
sent from the primary network interface.
|
|
The
|
|
.Dv IP_MULTICAST_IF
|
|
option overrides the default for
|
|
subsequent transmissions from a given socket:
|
|
.Bd -literal
|
|
struct in_addr addr;
|
|
setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]addr, sizeof(addr));
|
|
.Ed
|
|
.Pp
|
|
where "addr" is the local
|
|
.Tn IP
|
|
address of the desired interface or
|
|
.Dv INADDR_ANY
|
|
to specify the default interface.
|
|
An interface's local IP address and multicast capability can
|
|
be obtained via the
|
|
.Dv SIOCGIFCONF
|
|
and
|
|
.Dv SIOCGIFFLAGS
|
|
ioctls.
|
|
An application may also specify an alternative to the default network interface
|
|
by index:
|
|
.Bd -literal
|
|
struct uint32_t idx = htonl(ifindex);
|
|
setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]idx, sizeof(idx));
|
|
.Ed
|
|
.Pp
|
|
where "ifindex" is an interface index as returned by
|
|
.Xr if_nametoindex 3 .
|
|
.Pp
|
|
Normal applications should not need to use
|
|
.Dv IP_MULTICAST_IF .
|
|
.Pp
|
|
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
|
|
.Dv IP_MULTICAST_LOOP
|
|
option gives the sender explicit control
|
|
over whether or not subsequent datagrams are looped back:
|
|
.Bd -literal
|
|
u_char loop; /* 0 = disable, 1 = enable (default) */
|
|
setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, \*[Am]loop, sizeof(loop));
|
|
.Ed
|
|
.Pp
|
|
This option
|
|
improves performance for applications that may have no more than one
|
|
instance on a single host (such as a router demon), by eliminating
|
|
the overhead of receiving their own transmissions.
|
|
It should generally not be used by applications for which there
|
|
may be more than one instance on a single host (such as a conferencing
|
|
program) or for which the sender does not belong to the destination
|
|
group (such as a time querying program).
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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
|
|
.Dv IP_ADD_MEMBERSHIP
|
|
option:
|
|
.Bd -literal
|
|
struct ip_mreq mreq;
|
|
setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, \*[Am]mreq, sizeof(mreq));
|
|
.Ed
|
|
.Pp
|
|
where
|
|
.Fa mreq
|
|
is the following structure:
|
|
.Bd -literal
|
|
struct ip_mreq {
|
|
struct in_addr imr_multiaddr; /* multicast group to join */
|
|
struct in_addr imr_interface; /* interface to join on */
|
|
}
|
|
.Ed
|
|
.Pp
|
|
.Dv imr_interface
|
|
should be
|
|
.Dv INADDR_ANY
|
|
to choose the default multicast interface, or the
|
|
.Tn IP
|
|
address of a particular multicast-capable interface if
|
|
the host is multihomed.
|
|
Membership is associated with a single interface;
|
|
programs running on multihomed hosts may need to
|
|
join the same group on more than one interface.
|
|
Up to
|
|
.Dv IP_MAX_MEMBERSHIPS
|
|
(currently 20) memberships may be added on a single socket.
|
|
.Pp
|
|
To drop a membership, use:
|
|
.Bd -literal
|
|
struct ip_mreq mreq;
|
|
setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, \*[Am]mreq, sizeof(mreq));
|
|
.Ed
|
|
.Pp
|
|
where
|
|
.Fa mreq
|
|
contains the same values as used to add the membership.
|
|
Memberships are dropped when the socket is closed or the process exits.
|
|
.\"-----------------------
|
|
.Ss RAW IP SOCKETS
|
|
Raw
|
|
.Tn IP
|
|
sockets are connectionless, and are normally used with the
|
|
.Xr sendto 2
|
|
and
|
|
.Xr recvfrom 2
|
|
calls, though the
|
|
.Xr connect 2
|
|
call may also be used to fix the destination for future
|
|
packets (in which case the
|
|
.Xr read 2
|
|
or
|
|
.Xr recv 2
|
|
and
|
|
.Xr write 2
|
|
or
|
|
.Xr send 2
|
|
system calls may be used).
|
|
.Pp
|
|
If
|
|
.Fa proto
|
|
is 0, the default protocol
|
|
.Dv IPPROTO_RAW
|
|
is used for outgoing packets, and only incoming packets destined
|
|
for that protocol are received.
|
|
If
|
|
.Fa proto
|
|
is non-zero, that protocol number will be used on outgoing packets
|
|
and to filter incoming packets.
|
|
.Pp
|
|
Outgoing packets automatically have an
|
|
.Tn IP
|
|
header prepended to them (based on the destination address and the
|
|
protocol number the socket is created with), unless the
|
|
.Dv IP_HDRINCL
|
|
option has been set.
|
|
Incoming packets are received with
|
|
.Tn IP
|
|
header and options intact.
|
|
.Pp
|
|
.Dv IP_HDRINCL
|
|
indicates the complete IP header is included with the data and may
|
|
be used only with the
|
|
.Dv SOCK_RAW
|
|
type.
|
|
.Bd -literal
|
|
#include \*[Lt]netinet/ip.h\*[Gt]
|
|
|
|
int hincl = 1; /* 1 = on, 0 = off */
|
|
setsockopt(s, IPPROTO_IP, IP_HDRINCL, \*[Am]hincl, sizeof(hincl));
|
|
.Ed
|
|
.Pp
|
|
Unlike previous
|
|
.Bx
|
|
releases, the program must set all
|
|
the fields of the IP header, including the following:
|
|
.Bd -literal
|
|
ip-\*[Gt]ip_v = IPVERSION;
|
|
ip-\*[Gt]ip_hl = hlen \*[Gt]\*[Gt] 2;
|
|
ip-\*[Gt]ip_id = 0; /* 0 means kernel set appropriate value */
|
|
ip-\*[Gt]ip_off = offset;
|
|
.Ed
|
|
.Pp
|
|
If the header source address is set to
|
|
.Dv INADDR_ANY ,
|
|
the kernel will choose an appropriate address.
|
|
.Sh DIAGNOSTICS
|
|
A socket operation may fail with one of the following errors returned:
|
|
.Bl -tag -width [EADDRNOTAVAIL]
|
|
.It Bq Er 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;
|
|
.It Bq Er ENOTCONN
|
|
when trying to send a datagram, but no destination address is
|
|
specified, and the socket hasn't been connected;
|
|
.It Bq Er ENOBUFS
|
|
when the system runs out of memory for an internal data structure;
|
|
.It Bq Er EADDRNOTAVAIL
|
|
when an attempt is made to create a socket with a network address
|
|
for which no network interface exists.
|
|
.It Bq Er EACCES
|
|
when an attempt is made to create a raw IP socket by a non-privileged process.
|
|
.El
|
|
.Pp
|
|
The following errors specific to
|
|
.Tn IP
|
|
may occur when setting or getting
|
|
.Tn IP
|
|
options:
|
|
.Bl -tag -width EADDRNOTAVAILxx
|
|
.It Bq Er EINVAL
|
|
An unknown socket option name was given.
|
|
.It Bq Er EINVAL
|
|
The IP option field was improperly formed; an option field was
|
|
shorter than the minimum value or longer than the option buffer provided.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr getsockopt 2 ,
|
|
.Xr recv 2 ,
|
|
.Xr send 2 ,
|
|
.Xr CMSG_DATA 3 ,
|
|
.Xr ipsec_set_policy 3 ,
|
|
.Xr icmp 4 ,
|
|
.Xr inet 4 ,
|
|
.Xr intro 4
|
|
.Rs
|
|
.%R RFC
|
|
.%N 791
|
|
.%D September 1981
|
|
.%T "Internet Protocol"
|
|
.Re
|
|
.Rs
|
|
.%R RFC
|
|
.%N 1112
|
|
.%D August 1989
|
|
.%T "Host Extensions for IP Multicasting"
|
|
.Re
|
|
.Rs
|
|
.%R RFC
|
|
.%N 1122
|
|
.%D October 1989
|
|
.%T "Requirements for Internet Hosts -- Communication Layers"
|
|
.Re
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
protocol appeared in
|
|
.Bx 4.2 .
|