| 1 |
'\" t |
| 2 |
.\" SPDX-License-Identifier: Linux-man-pages-1-para |
| 3 |
.\" |
| 4 |
.\" This man page is Copyright (C) 1999 Andi Kleen <[email protected]>. |
| 5 |
.\" |
| 6 |
.\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $ |
| 7 |
.\" |
| 8 |
.\" FIXME The following socket options are yet to be documented |
| 9 |
.\" |
| 10 |
.\" IP_XFRM_POLICY (2.5.48) |
| 11 |
.\" Needs CAP_NET_ADMIN |
| 12 |
.\" |
| 13 |
.\" IP_IPSEC_POLICY (2.5.47) |
| 14 |
.\" Needs CAP_NET_ADMIN |
| 15 |
.\" |
| 16 |
.\" IP_MINTTL (2.6.34) |
| 17 |
.\" commit d218d11133d888f9745802146a50255a4781d37a |
| 18 |
.\" Author: Stephen Hemminger <[email protected]> |
| 19 |
.\" |
| 20 |
.\" MCAST_JOIN_GROUP (2.4.22 / 2.6) |
| 21 |
.\" |
| 22 |
.\" MCAST_BLOCK_SOURCE (2.4.22 / 2.6) |
| 23 |
.\" |
| 24 |
.\" MCAST_UNBLOCK_SOURCE (2.4.22 / 2.6) |
| 25 |
.\" |
| 26 |
.\" MCAST_LEAVE_GROUP (2.4.22 / 2.6) |
| 27 |
.\" |
| 28 |
.\" MCAST_JOIN_SOURCE_GROUP (2.4.22 / 2.6) |
| 29 |
.\" |
| 30 |
.\" MCAST_LEAVE_SOURCE_GROUP (2.4.22 / 2.6) |
| 31 |
.\" |
| 32 |
.\" MCAST_MSFILTER (2.4.22 / 2.6) |
| 33 |
.\" |
| 34 |
.\" IP_UNICAST_IF (3.4) |
| 35 |
.\" commit 76e21053b5bf33a07c76f99d27a74238310e3c71 |
| 36 |
.\" Author: Erich E. Hoover <[email protected]> |
| 37 |
.\" |
| 38 |
.TH ip 7 2024-05-02 "Linux man-pages 6.9.1" |
| 39 |
.SH NAME |
| 40 |
ip \- Linux IPv4 protocol implementation |
| 41 |
.SH SYNOPSIS |
| 42 |
.nf |
| 43 |
.B #include <sys/socket.h> |
| 44 |
.\" .B #include <net/netinet.h> -- does not exist anymore |
| 45 |
.\" .B #include <linux/errqueue.h> -- never include <linux/foo.h> |
| 46 |
.B #include <netinet/in.h> |
| 47 |
.B #include <netinet/ip.h> \fR/* superset of previous */ |
| 48 |
.P |
| 49 |
.IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" |
| 50 |
.IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" |
| 51 |
.IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");" |
| 52 |
.fi |
| 53 |
.SH DESCRIPTION |
| 54 |
Linux implements the Internet Protocol, version 4, |
| 55 |
described in RFC\ 791 and RFC\ 1122. |
| 56 |
.B ip |
| 57 |
contains a level 2 multicasting implementation conforming to RFC\ 1112. |
| 58 |
It also contains an IP router including a packet filter. |
| 59 |
.P |
| 60 |
The programming interface is BSD-sockets compatible. |
| 61 |
For more information on sockets, see |
| 62 |
.BR socket (7). |
| 63 |
.P |
| 64 |
An IP socket is created using |
| 65 |
.BR socket (2): |
| 66 |
.P |
| 67 |
.in +4n |
| 68 |
.EX |
| 69 |
socket(AF_INET, socket_type, protocol); |
| 70 |
.EE |
| 71 |
.in |
| 72 |
.P |
| 73 |
Valid socket types include |
| 74 |
.B SOCK_STREAM |
| 75 |
to open a stream socket, |
| 76 |
.B SOCK_DGRAM |
| 77 |
to open a datagram socket, and |
| 78 |
.B SOCK_RAW |
| 79 |
to open a |
| 80 |
.BR raw (7) |
| 81 |
socket to access the IP protocol directly. |
| 82 |
.P |
| 83 |
.I protocol |
| 84 |
is the IP protocol in the IP header to be received or sent. |
| 85 |
Valid values for |
| 86 |
.I protocol |
| 87 |
include: |
| 88 |
.IP \[bu] 3 |
| 89 |
0 and |
| 90 |
.B IPPROTO_TCP |
| 91 |
for |
| 92 |
.BR tcp (7) |
| 93 |
stream sockets; |
| 94 |
.IP \[bu] |
| 95 |
0 and |
| 96 |
.B IPPROTO_UDP |
| 97 |
for |
| 98 |
.BR udp (7) |
| 99 |
datagram sockets; |
| 100 |
.IP \[bu] |
| 101 |
.B IPPROTO_SCTP |
| 102 |
for |
| 103 |
.BR sctp (7) |
| 104 |
stream sockets; and |
| 105 |
.IP \[bu] |
| 106 |
.B IPPROTO_UDPLITE |
| 107 |
for |
| 108 |
.BR udplite (7) |
| 109 |
datagram sockets. |
| 110 |
.P |
| 111 |
For |
| 112 |
.B SOCK_RAW |
| 113 |
you may specify a valid IANA IP protocol defined in |
| 114 |
RFC\ 1700 assigned numbers. |
| 115 |
.P |
| 116 |
When a process wants to receive new incoming packets or connections, it |
| 117 |
should bind a socket to a local interface address using |
| 118 |
.BR bind (2). |
| 119 |
In this case, only one IP socket may be bound to any given local |
| 120 |
(address, port) pair. |
| 121 |
When |
| 122 |
.B INADDR_ANY |
| 123 |
is specified in the bind call, the socket will be bound to |
| 124 |
.I all |
| 125 |
local interfaces. |
| 126 |
When |
| 127 |
.BR listen (2) |
| 128 |
is called on an unbound socket, the socket is automatically bound |
| 129 |
to a random free port with the local address set to |
| 130 |
.BR INADDR_ANY . |
| 131 |
When |
| 132 |
.BR connect (2) |
| 133 |
is called on an unbound socket, the socket is automatically bound |
| 134 |
to a random free port or to a usable shared port with the local address |
| 135 |
set to |
| 136 |
.BR INADDR_ANY . |
| 137 |
.P |
| 138 |
A TCP local socket address that has been bound is unavailable for |
| 139 |
some time after closing, unless the |
| 140 |
.B SO_REUSEADDR |
| 141 |
flag has been set. |
| 142 |
Care should be taken when using this flag as it makes TCP less reliable. |
| 143 |
.SS Address format |
| 144 |
An IP socket address is defined as a combination of an IP interface |
| 145 |
address and a 16-bit port number. |
| 146 |
The basic IP protocol does not supply port numbers, they |
| 147 |
are implemented by higher level protocols like |
| 148 |
.BR udp (7) |
| 149 |
and |
| 150 |
.BR tcp (7). |
| 151 |
On raw sockets |
| 152 |
.I sin_port |
| 153 |
is set to the IP protocol. |
| 154 |
.P |
| 155 |
.in +4n |
| 156 |
.EX |
| 157 |
struct sockaddr_in { |
| 158 |
sa_family_t sin_family; /* address family: AF_INET */ |
| 159 |
in_port_t sin_port; /* port in network byte order */ |
| 160 |
struct in_addr sin_addr; /* internet address */ |
| 161 |
}; |
| 162 |
\& |
| 163 |
/* Internet address */ |
| 164 |
struct in_addr { |
| 165 |
uint32_t s_addr; /* address in network byte order */ |
| 166 |
}; |
| 167 |
.EE |
| 168 |
.in |
| 169 |
.P |
| 170 |
.I sin_family |
| 171 |
is always set to |
| 172 |
.BR AF_INET . |
| 173 |
This is required; in Linux 2.2 most networking functions return |
| 174 |
.B EINVAL |
| 175 |
when this setting is missing. |
| 176 |
.I sin_port |
| 177 |
contains the port in network byte order. |
| 178 |
The port numbers below 1024 are called |
| 179 |
.I privileged ports |
| 180 |
(or sometimes: |
| 181 |
.IR "reserved ports" ). |
| 182 |
Only a privileged process |
| 183 |
(on Linux: a process that has the |
| 184 |
.B CAP_NET_BIND_SERVICE |
| 185 |
capability in the user namespace governing its network namespace) may |
| 186 |
.BR bind (2) |
| 187 |
to these sockets. |
| 188 |
Note that the raw IPv4 protocol as such has no concept of a |
| 189 |
port, they are implemented only by higher protocols like |
| 190 |
.BR tcp (7) |
| 191 |
and |
| 192 |
.BR udp (7). |
| 193 |
.P |
| 194 |
.I sin_addr |
| 195 |
is the IP host address. |
| 196 |
The |
| 197 |
.I s_addr |
| 198 |
member of |
| 199 |
.I struct in_addr |
| 200 |
contains the host interface address in network byte order. |
| 201 |
.I in_addr |
| 202 |
should be assigned one of the |
| 203 |
.B INADDR_* |
| 204 |
values |
| 205 |
(e.g., |
| 206 |
.BR INADDR_LOOPBACK ) |
| 207 |
using |
| 208 |
.BR htonl (3) |
| 209 |
or set using the |
| 210 |
.BR inet_aton (3), |
| 211 |
.BR inet_addr (3), |
| 212 |
.BR inet_makeaddr (3) |
| 213 |
library functions or directly with the name resolver (see |
| 214 |
.BR gethostbyname (3)). |
| 215 |
.P |
| 216 |
IPv4 addresses are divided into unicast, broadcast, |
| 217 |
and multicast addresses. |
| 218 |
Unicast addresses specify a single interface of a host, |
| 219 |
broadcast addresses specify all hosts on a network, and multicast |
| 220 |
addresses address all hosts in a multicast group. |
| 221 |
Datagrams to broadcast addresses can be sent or received only when the |
| 222 |
.B SO_BROADCAST |
| 223 |
socket flag is set. |
| 224 |
In the current implementation, connection-oriented sockets are allowed |
| 225 |
to use only unicast addresses. |
| 226 |
.\" Leave a loophole for XTP @) |
| 227 |
.P |
| 228 |
Note that the address and the port are always stored in |
| 229 |
network byte order. |
| 230 |
In particular, this means that you need to call |
| 231 |
.BR htons (3) |
| 232 |
on the number that is assigned to a port. |
| 233 |
All address/port manipulation |
| 234 |
functions in the standard library work in network byte order. |
| 235 |
.SS Special and reserved addresses |
| 236 |
There are several special addresses: |
| 237 |
.TP |
| 238 |
.BR INADDR_LOOPBACK " (127.0.0.1)" |
| 239 |
always refers to the local host via the loopback device; |
| 240 |
.TP |
| 241 |
.BR INADDR_ANY " (0.0.0.0)" |
| 242 |
means any address for socket binding; |
| 243 |
.TP |
| 244 |
.BR INADDR_BROADCAST " (255.255.255.255)" |
| 245 |
has the same effect on |
| 246 |
.BR bind (2) |
| 247 |
as |
| 248 |
.B INADDR_ANY |
| 249 |
for historical reasons. |
| 250 |
A packet addressed to |
| 251 |
.B INADDR_BROADCAST |
| 252 |
through a socket which has |
| 253 |
.B SO_BROADCAST |
| 254 |
set will be broadcast to all hosts on the local network segment, |
| 255 |
as long as the link is broadcast-capable. |
| 256 |
.TP |
| 257 |
Highest-numbered address |
| 258 |
.TQ |
| 259 |
Lowest-numbered address |
| 260 |
On any locally-attached non-point-to-point IP subnet |
| 261 |
with a link type that supports broadcasts, |
| 262 |
the highest-numbered address |
| 263 |
(e.g., the .255 address on a subnet with netmask 255.255.255.0) |
| 264 |
is designated as a broadcast address. |
| 265 |
It cannot usefully be assigned to an individual interface, |
| 266 |
and can only be addressed with a socket on which the |
| 267 |
.B SO_BROADCAST |
| 268 |
option has been set. |
| 269 |
Internet standards have historically |
| 270 |
also reserved the lowest-numbered address |
| 271 |
(e.g., the .0 address on a subnet with netmask 255.255.255.0) |
| 272 |
for broadcast, though they call it "obsolete" for this purpose. |
| 273 |
(Some sources also refer to this as the "network address.") |
| 274 |
Since Linux 5.14, |
| 275 |
.\" commit 58fee5fc83658aaacf60246aeab738946a9ba516 |
| 276 |
it is treated as an ordinary unicast address |
| 277 |
and can be assigned to an interface. |
| 278 |
.P |
| 279 |
Internet standards have traditionally also reserved various addresses |
| 280 |
for particular uses, though Linux no longer treats |
| 281 |
some of these specially. |
| 282 |
.TP |
| 283 |
[0.0.0.1, 0.255.255.255] |
| 284 |
.TQ |
| 285 |
[240.0.0.0, 255.255.255.254] |
| 286 |
Addresses in these ranges (0/8 and 240/4) are reserved globally. |
| 287 |
Since Linux 5.3 |
| 288 |
.\" commit 96125bf9985a75db00496dd2bc9249b777d2b19b |
| 289 |
and Linux 2.6.25, |
| 290 |
.\" commit 1e637c74b0f84eaca02b914c0b8c6f67276e9697 |
| 291 |
respectively, |
| 292 |
the 0/8 and 240/4 addresses, other than |
| 293 |
.B INADDR_ANY |
| 294 |
and |
| 295 |
.BR INADDR_BROADCAST , |
| 296 |
are treated as ordinary unicast addresses. |
| 297 |
Systems that follow the traditional behaviors may not |
| 298 |
interoperate with these historically reserved addresses. |
| 299 |
.TP |
| 300 |
[127.0.0.1, 127.255.255.254] |
| 301 |
Addresses in this range (127/8) are treated as loopback addresses |
| 302 |
akin to the standardized local loopback address |
| 303 |
.B INADDR_LOOPBACK |
| 304 |
(127.0.0.1); |
| 305 |
.TP |
| 306 |
[224.0.0.0, 239.255.255.255] |
| 307 |
Addresses in this range (224/4) are dedicated to multicast use. |
| 308 |
.SS Socket options |
| 309 |
IP supports some protocol-specific socket options that can be set with |
| 310 |
.BR setsockopt (2) |
| 311 |
and read with |
| 312 |
.BR getsockopt (2). |
| 313 |
The socket option level for IP is |
| 314 |
.BR IPPROTO_IP . |
| 315 |
.\" or SOL_IP on Linux |
| 316 |
A boolean integer flag is zero when it is false, otherwise true. |
| 317 |
.P |
| 318 |
When an invalid socket option is specified, |
| 319 |
.BR getsockopt (2) |
| 320 |
and |
| 321 |
.BR setsockopt (2) |
| 322 |
fail with the error |
| 323 |
.BR ENOPROTOOPT . |
| 324 |
.TP |
| 325 |
.BR IP_ADD_MEMBERSHIP " (since Linux 1.2)" |
| 326 |
Join a multicast group. |
| 327 |
Argument is an |
| 328 |
.I ip_mreqn |
| 329 |
structure. |
| 330 |
.IP |
| 331 |
.in +4n |
| 332 |
.EX |
| 333 |
struct ip_mreqn { |
| 334 |
struct in_addr imr_multiaddr; /* IP multicast group |
| 335 |
address */ |
| 336 |
struct in_addr imr_address; /* IP address of local |
| 337 |
interface */ |
| 338 |
int imr_ifindex; /* interface index */ |
| 339 |
}; |
| 340 |
.EE |
| 341 |
.in |
| 342 |
.IP |
| 343 |
.I imr_multiaddr |
| 344 |
contains the address of the multicast group the application |
| 345 |
wants to join or leave. |
| 346 |
It must be a valid multicast address |
| 347 |
.\" (i.e., within the 224.0.0.0-239.255.255.255 range) |
| 348 |
(or |
| 349 |
.BR setsockopt (2) |
| 350 |
fails with the error |
| 351 |
.BR EINVAL ). |
| 352 |
.I imr_address |
| 353 |
is the address of the local interface with which the system |
| 354 |
should join the multicast group; if it is equal to |
| 355 |
.BR INADDR_ANY , |
| 356 |
an appropriate interface is chosen by the system. |
| 357 |
.I imr_ifindex |
| 358 |
is the interface index of the interface that should join/leave the |
| 359 |
.I imr_multiaddr |
| 360 |
group, or 0 to indicate any interface. |
| 361 |
.IP |
| 362 |
The |
| 363 |
.I ip_mreqn |
| 364 |
structure is available only since Linux 2.2. |
| 365 |
For compatibility, the old |
| 366 |
.I ip_mreq |
| 367 |
structure (present since Linux 1.2) is still supported; |
| 368 |
it differs from |
| 369 |
.I ip_mreqn |
| 370 |
only by not including the |
| 371 |
.I imr_ifindex |
| 372 |
field. |
| 373 |
(The kernel determines which structure is being passed based |
| 374 |
on the size passed in |
| 375 |
.IR optlen .) |
| 376 |
.IP |
| 377 |
.B IP_ADD_MEMBERSHIP |
| 378 |
is valid only for |
| 379 |
.BR setsockopt (2). |
| 380 |
.\" |
| 381 |
.TP |
| 382 |
.BR IP_ADD_SOURCE_MEMBERSHIP " (since Linux 2.4.22 / Linux 2.5.68)" |
| 383 |
Join a multicast group and allow receiving data only |
| 384 |
from a specified source. |
| 385 |
Argument is an |
| 386 |
.I ip_mreq_source |
| 387 |
structure. |
| 388 |
.IP |
| 389 |
.in +4n |
| 390 |
.EX |
| 391 |
struct ip_mreq_source { |
| 392 |
struct in_addr imr_multiaddr; /* IP multicast group |
| 393 |
address */ |
| 394 |
struct in_addr imr_interface; /* IP address of local |
| 395 |
interface */ |
| 396 |
struct in_addr imr_sourceaddr; /* IP address of |
| 397 |
multicast source */ |
| 398 |
}; |
| 399 |
.EE |
| 400 |
.in |
| 401 |
.IP |
| 402 |
The |
| 403 |
.I ip_mreq_source |
| 404 |
structure is similar to |
| 405 |
.I ip_mreqn |
| 406 |
described under |
| 407 |
.BR IP_ADD_MEMBERSHIP . |
| 408 |
The |
| 409 |
.I imr_multiaddr |
| 410 |
field contains the address of the multicast group the application |
| 411 |
wants to join or leave. |
| 412 |
The |
| 413 |
.I imr_interface |
| 414 |
field is the address of the local interface with which |
| 415 |
the system should join the multicast group. |
| 416 |
Finally, the |
| 417 |
.I imr_sourceaddr |
| 418 |
field contains the address of the source the |
| 419 |
application wants to receive data from. |
| 420 |
.IP |
| 421 |
This option can be used multiple times to allow |
| 422 |
receiving data from more than one source. |
| 423 |
.TP |
| 424 |
.BR IP_BIND_ADDRESS_NO_PORT " (since Linux 4.2)" |
| 425 |
.\" commit 90c337da1524863838658078ec34241f45d8394d |
| 426 |
Inform the kernel to not reserve an ephemeral port when using |
| 427 |
.BR bind (2) |
| 428 |
with a port number of 0. |
| 429 |
The port will later be automatically chosen at |
| 430 |
.BR connect (2) |
| 431 |
time, |
| 432 |
in a way that allows sharing a source port as long as the 4-tuple is unique. |
| 433 |
.TP |
| 434 |
.BR IP_BLOCK_SOURCE " (since Linux 2.4.22 / 2.5.68)" |
| 435 |
Stop receiving multicast data from a specific source in a given group. |
| 436 |
This is valid only after the application has subscribed |
| 437 |
to the multicast group using either |
| 438 |
.B IP_ADD_MEMBERSHIP |
| 439 |
or |
| 440 |
.BR IP_ADD_SOURCE_MEMBERSHIP . |
| 441 |
.IP |
| 442 |
Argument is an |
| 443 |
.I ip_mreq_source |
| 444 |
structure as described under |
| 445 |
.BR IP_ADD_SOURCE_MEMBERSHIP . |
| 446 |
.TP |
| 447 |
.BR IP_DROP_MEMBERSHIP " (since Linux 1.2)" |
| 448 |
Leave a multicast group. |
| 449 |
Argument is an |
| 450 |
.I ip_mreqn |
| 451 |
or |
| 452 |
.I ip_mreq |
| 453 |
structure similar to |
| 454 |
.BR IP_ADD_MEMBERSHIP . |
| 455 |
.TP |
| 456 |
.BR IP_DROP_SOURCE_MEMBERSHIP " (since Linux 2.4.22 / 2.5.68)" |
| 457 |
Leave a source-specific group\[em]that is, stop receiving data from |
| 458 |
a given multicast group that come from a given source. |
| 459 |
If the application has subscribed to multiple sources within |
| 460 |
the same group, data from the remaining sources will still be delivered. |
| 461 |
To stop receiving data from all sources at once, use |
| 462 |
.BR IP_DROP_MEMBERSHIP . |
| 463 |
.IP |
| 464 |
Argument is an |
| 465 |
.I ip_mreq_source |
| 466 |
structure as described under |
| 467 |
.BR IP_ADD_SOURCE_MEMBERSHIP . |
| 468 |
.TP |
| 469 |
.BR IP_FREEBIND " (since Linux 2.4)" |
| 470 |
.\" Precisely: since Linux 2.4.0-test10 |
| 471 |
If enabled, this boolean option allows binding to an IP address |
| 472 |
that is nonlocal or does not (yet) exist. |
| 473 |
This permits listening on a socket, |
| 474 |
without requiring the underlying network interface or the |
| 475 |
specified dynamic IP address to be up at the time that |
| 476 |
the application is trying to bind to it. |
| 477 |
This option is the per-socket equivalent of the |
| 478 |
.I ip_nonlocal_bind |
| 479 |
.I /proc |
| 480 |
interface described below. |
| 481 |
.TP |
| 482 |
.BR IP_HDRINCL " (since Linux 2.0)" |
| 483 |
If enabled, |
| 484 |
the user supplies an IP header in front of the user data. |
| 485 |
Valid only for |
| 486 |
.B SOCK_RAW |
| 487 |
sockets; see |
| 488 |
.BR raw (7) |
| 489 |
for more information. |
| 490 |
When this flag is enabled, the values set by |
| 491 |
.BR IP_OPTIONS , |
| 492 |
.BR IP_TTL , |
| 493 |
and |
| 494 |
.B IP_TOS |
| 495 |
are ignored. |
| 496 |
.TP |
| 497 |
.BR IP_LOCAL_PORT_RANGE " (since Linux 6.3)" |
| 498 |
Set or get the per-socket default local port range. |
| 499 |
This option can be used to clamp down the global local port range, |
| 500 |
defined by the |
| 501 |
.I ip_local_port_range |
| 502 |
.I /proc |
| 503 |
interface described below, for a given socket. |
| 504 |
.IP |
| 505 |
The option takes an |
| 506 |
.I uint32_t |
| 507 |
value with |
| 508 |
the high 16 bits set to the upper range bound, |
| 509 |
and the low 16 bits set to the lower range bound. |
| 510 |
Range bounds are inclusive. |
| 511 |
The 16-bit values should be in host byte order. |
| 512 |
.IP |
| 513 |
The lower bound has to be less than the upper bound |
| 514 |
when both bounds are not zero. |
| 515 |
Otherwise, setting the option fails with EINVAL. |
| 516 |
.IP |
| 517 |
If either bound is outside of the global local port range, or is zero, |
| 518 |
then that bound has no effect. |
| 519 |
.IP |
| 520 |
To reset the setting, |
| 521 |
pass zero as both the upper and the lower bound. |
| 522 |
.TP |
| 523 |
.BR IP_MSFILTER " (since Linux 2.4.22 / 2.5.68)" |
| 524 |
This option provides access to the advanced full-state filtering API. |
| 525 |
Argument is an |
| 526 |
.I ip_msfilter |
| 527 |
structure. |
| 528 |
.IP |
| 529 |
.in +4n |
| 530 |
.EX |
| 531 |
struct ip_msfilter { |
| 532 |
struct in_addr imsf_multiaddr; /* IP multicast group |
| 533 |
address */ |
| 534 |
struct in_addr imsf_interface; /* IP address of local |
| 535 |
interface */ |
| 536 |
uint32_t imsf_fmode; /* Filter\-mode */ |
| 537 |
\& |
| 538 |
uint32_t imsf_numsrc; /* Number of sources in |
| 539 |
the following array */ |
| 540 |
struct in_addr imsf_slist[1]; /* Array of source |
| 541 |
addresses */ |
| 542 |
}; |
| 543 |
.EE |
| 544 |
.in |
| 545 |
.IP |
| 546 |
There are two macros, |
| 547 |
.B MCAST_INCLUDE |
| 548 |
and |
| 549 |
.BR MCAST_EXCLUDE , |
| 550 |
which can be used to specify the filtering mode. |
| 551 |
Additionally, the |
| 552 |
.BR IP_MSFILTER_SIZE (n) |
| 553 |
macro exists to determine how much memory is needed to store |
| 554 |
.I ip_msfilter |
| 555 |
structure with |
| 556 |
.I n |
| 557 |
sources in the source list. |
| 558 |
.IP |
| 559 |
For the full description of multicast source filtering |
| 560 |
refer to RFC 3376. |
| 561 |
.TP |
| 562 |
.BR IP_MTU " (since Linux 2.2)" |
| 563 |
.\" Precisely: since Linux 2.1.124 |
| 564 |
Retrieve the current known path MTU of the current socket. |
| 565 |
Returns an integer. |
| 566 |
.IP |
| 567 |
.B IP_MTU |
| 568 |
is valid only for |
| 569 |
.BR getsockopt (2) |
| 570 |
and can be employed only when the socket has been connected. |
| 571 |
.TP |
| 572 |
.BR IP_MTU_DISCOVER " (since Linux 2.2)" |
| 573 |
.\" Precisely: since Linux 2.1.124 |
| 574 |
Set or receive the Path MTU Discovery setting for a socket. |
| 575 |
When enabled, Linux will perform Path MTU Discovery |
| 576 |
as defined in RFC\ 1191 on |
| 577 |
.B SOCK_STREAM |
| 578 |
sockets. |
| 579 |
For |
| 580 |
.RB non- SOCK_STREAM |
| 581 |
sockets, |
| 582 |
.B IP_PMTUDISC_DO |
| 583 |
forces the don't-fragment flag to be set on all outgoing packets. |
| 584 |
It is the user's responsibility to packetize the data |
| 585 |
in MTU-sized chunks and to do the retransmits if necessary. |
| 586 |
The kernel will reject (with |
| 587 |
.BR EMSGSIZE ) |
| 588 |
datagrams that are bigger than the known path MTU. |
| 589 |
.B IP_PMTUDISC_WANT |
| 590 |
will fragment a datagram if needed according to the path MTU, |
| 591 |
or will set the don't-fragment flag otherwise. |
| 592 |
.IP |
| 593 |
The system-wide default can be toggled between |
| 594 |
.B IP_PMTUDISC_WANT |
| 595 |
and |
| 596 |
.B IP_PMTUDISC_DONT |
| 597 |
by writing (respectively, zero and nonzero values) to the |
| 598 |
.I /proc/sys/net/ipv4/ip_no_pmtu_disc |
| 599 |
file. |
| 600 |
.TS |
| 601 |
tab(:); |
| 602 |
c l |
| 603 |
l l. |
| 604 |
Path MTU discovery value:Meaning |
| 605 |
IP_PMTUDISC_WANT:Use per-route settings. |
| 606 |
IP_PMTUDISC_DONT:Never do Path MTU Discovery. |
| 607 |
IP_PMTUDISC_DO:Always do Path MTU Discovery. |
| 608 |
IP_PMTUDISC_PROBE:Set DF but ignore Path MTU. |
| 609 |
.TE |
| 610 |
.IP |
| 611 |
When PMTU discovery is enabled, the kernel automatically keeps track of |
| 612 |
the path MTU per destination host. |
| 613 |
When it is connected to a specific peer with |
| 614 |
.BR connect (2), |
| 615 |
the currently known path MTU can be retrieved conveniently using the |
| 616 |
.B IP_MTU |
| 617 |
socket option (e.g., after an |
| 618 |
.B EMSGSIZE |
| 619 |
error occurred). |
| 620 |
The path MTU may change over time. |
| 621 |
For connectionless sockets with many destinations, |
| 622 |
the new MTU for a given destination can also be accessed using the |
| 623 |
error queue (see |
| 624 |
.BR IP_RECVERR ). |
| 625 |
A new error will be queued for every incoming MTU update. |
| 626 |
.IP |
| 627 |
While MTU discovery is in progress, initial packets from datagram sockets |
| 628 |
may be dropped. |
| 629 |
Applications using UDP should be aware of this and not |
| 630 |
take it into account for their packet retransmit strategy. |
| 631 |
.IP |
| 632 |
To bootstrap the path MTU discovery process on unconnected sockets, it |
| 633 |
is possible to start with a big datagram size |
| 634 |
(headers up to 64 kilobytes long) and let it shrink by updates of the path MTU. |
| 635 |
.IP |
| 636 |
To get an initial estimate of the |
| 637 |
path MTU, connect a datagram socket to the destination address using |
| 638 |
.BR connect (2) |
| 639 |
and retrieve the MTU by calling |
| 640 |
.BR getsockopt (2) |
| 641 |
with the |
| 642 |
.B IP_MTU |
| 643 |
option. |
| 644 |
.IP |
| 645 |
It is possible to implement RFC 4821 MTU probing with |
| 646 |
.B SOCK_DGRAM |
| 647 |
or |
| 648 |
.B SOCK_RAW |
| 649 |
sockets by setting a value of |
| 650 |
.B IP_PMTUDISC_PROBE |
| 651 |
(available since Linux 2.6.22). |
| 652 |
This is also particularly useful for diagnostic tools such as |
| 653 |
.BR tracepath (8) |
| 654 |
that wish to deliberately send probe packets larger than |
| 655 |
the observed Path MTU. |
| 656 |
.TP |
| 657 |
.BR IP_MULTICAST_ALL " (since Linux 2.6.31)" |
| 658 |
This option can be used to modify the delivery policy of multicast messages. |
| 659 |
The argument is a boolean integer (defaults to 1). |
| 660 |
If set to 1, |
| 661 |
the socket will receive messages from all the groups that have been joined |
| 662 |
globally on the whole system. |
| 663 |
Otherwise, it will deliver messages only from |
| 664 |
the groups that have been explicitly joined (for example via the |
| 665 |
.B IP_ADD_MEMBERSHIP |
| 666 |
option) on this particular socket. |
| 667 |
.TP |
| 668 |
.BR IP_MULTICAST_IF " (since Linux 1.2)" |
| 669 |
Set the local device for a multicast socket. |
| 670 |
The argument for |
| 671 |
.BR setsockopt (2) |
| 672 |
is an |
| 673 |
.I ip_mreqn |
| 674 |
or |
| 675 |
.\" net: IP_MULTICAST_IF setsockopt now recognizes struct mreq |
| 676 |
.\" Commit: 3a084ddb4bf299a6e898a9a07c89f3917f0713f7 |
| 677 |
(since Linux 3.5) |
| 678 |
.I ip_mreq |
| 679 |
structure similar to |
| 680 |
.BR IP_ADD_MEMBERSHIP , |
| 681 |
or an |
| 682 |
.I in_addr |
| 683 |
structure. |
| 684 |
(The kernel determines which structure is being passed based |
| 685 |
on the size passed in |
| 686 |
.IR optlen .) |
| 687 |
For |
| 688 |
.BR getsockopt (2), |
| 689 |
the argument is an |
| 690 |
.I in_addr |
| 691 |
structure. |
| 692 |
.TP |
| 693 |
.BR IP_MULTICAST_LOOP " (since Linux 1.2)" |
| 694 |
Set or read a boolean integer argument that determines whether |
| 695 |
sent multicast packets should be looped back to the local sockets. |
| 696 |
.TP |
| 697 |
.BR IP_MULTICAST_TTL " (since Linux 1.2)" |
| 698 |
Set or read the time-to-live value of outgoing multicast packets for this |
| 699 |
socket. |
| 700 |
It is very important for multicast packets to set the smallest TTL possible. |
| 701 |
The default is 1 which means that multicast packets don't leave the local |
| 702 |
network unless the user program explicitly requests it. |
| 703 |
Argument is an integer. |
| 704 |
.TP |
| 705 |
.BR IP_NODEFRAG " (since Linux 2.6.36)" |
| 706 |
If enabled (argument is nonzero), |
| 707 |
the reassembly of outgoing packets is disabled in the netfilter layer. |
| 708 |
The argument is an integer. |
| 709 |
.IP |
| 710 |
This option is valid only for |
| 711 |
.B SOCK_RAW |
| 712 |
sockets. |
| 713 |
.TP |
| 714 |
.BR IP_OPTIONS " (since Linux 2.0)" |
| 715 |
.\" Precisely: since Linux 1.3.30 |
| 716 |
Set or get the IP options to be sent with every packet from this socket. |
| 717 |
The arguments are a pointer to a memory buffer containing the options |
| 718 |
and the option length. |
| 719 |
The |
| 720 |
.BR setsockopt (2) |
| 721 |
call sets the IP options associated with a socket. |
| 722 |
The maximum option size for IPv4 is 40 bytes. |
| 723 |
See RFC\ 791 for the allowed options. |
| 724 |
When the initial connection request packet for a |
| 725 |
.B SOCK_STREAM |
| 726 |
socket contains IP options, the IP options will be set automatically |
| 727 |
to the options from the initial packet with routing headers reversed. |
| 728 |
Incoming packets are not allowed to change options after the connection |
| 729 |
is established. |
| 730 |
The processing of all incoming source routing options |
| 731 |
is disabled by default and can be enabled by using the |
| 732 |
.I accept_source_route |
| 733 |
.I /proc |
| 734 |
interface. |
| 735 |
Other options like timestamps are still handled. |
| 736 |
For datagram sockets, IP options can be set only by the local user. |
| 737 |
Calling |
| 738 |
.BR getsockopt (2) |
| 739 |
with |
| 740 |
.B IP_OPTIONS |
| 741 |
puts the current IP options used for sending into the supplied buffer. |
| 742 |
.TP |
| 743 |
.BR IP_PASSSEC " (since Linux 2.6.17)" |
| 744 |
.\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c |
| 745 |
If labeled IPSEC or NetLabel is configured on the sending and receiving |
| 746 |
hosts, this option enables receiving of the security context of the peer |
| 747 |
socket in an ancillary message of type |
| 748 |
.B SCM_SECURITY |
| 749 |
retrieved using |
| 750 |
.BR recvmsg (2). |
| 751 |
This option is supported only for UDP sockets; for TCP or SCTP sockets, |
| 752 |
see the description of the |
| 753 |
.B SO_PEERSEC |
| 754 |
option below. |
| 755 |
.IP |
| 756 |
The value given as an argument to |
| 757 |
.BR setsockopt (2) |
| 758 |
and returned as the result of |
| 759 |
.BR getsockopt (2) |
| 760 |
is an integer boolean flag. |
| 761 |
.IP |
| 762 |
The security context returned in the |
| 763 |
.B SCM_SECURITY |
| 764 |
ancillary message |
| 765 |
is of the same format as the one described under the |
| 766 |
.B SO_PEERSEC |
| 767 |
option below. |
| 768 |
.IP |
| 769 |
Note: the reuse of the |
| 770 |
.B SCM_SECURITY |
| 771 |
message type for the |
| 772 |
.B IP_PASSSEC |
| 773 |
socket option was likely a mistake, since other IP control messages use |
| 774 |
their own numbering scheme in the IP namespace and often use the |
| 775 |
socket option value as the message type. |
| 776 |
There is no conflict currently since the IP option with the same value as |
| 777 |
.B SCM_SECURITY |
| 778 |
is |
| 779 |
.B IP_HDRINCL |
| 780 |
and this is never used for a control message type. |
| 781 |
.TP |
| 782 |
.BR IP_PKTINFO " (since Linux 2.2)" |
| 783 |
.\" Precisely: since Linux 2.1.68 |
| 784 |
Pass an |
| 785 |
.B IP_PKTINFO |
| 786 |
ancillary message that contains a |
| 787 |
.I pktinfo |
| 788 |
structure that supplies some information about the incoming packet. |
| 789 |
This works only for datagram oriented sockets. |
| 790 |
The argument is a flag that tells the socket whether the |
| 791 |
.B IP_PKTINFO |
| 792 |
message should be passed or not. |
| 793 |
The message itself can be sent/retrieved |
| 794 |
only as a control message with a packet using |
| 795 |
.BR recvmsg (2) |
| 796 |
or |
| 797 |
.BR sendmsg (2). |
| 798 |
.IP |
| 799 |
.in +4n |
| 800 |
.EX |
| 801 |
struct in_pktinfo { |
| 802 |
unsigned int ipi_ifindex; /* Interface index */ |
| 803 |
struct in_addr ipi_spec_dst; /* Local address */ |
| 804 |
struct in_addr ipi_addr; /* Header Destination |
| 805 |
address */ |
| 806 |
}; |
| 807 |
.EE |
| 808 |
.in |
| 809 |
.IP |
| 810 |
.I ipi_ifindex |
| 811 |
is the unique index of the interface the packet was received on. |
| 812 |
.I ipi_spec_dst |
| 813 |
is the local address of the packet and |
| 814 |
.I ipi_addr |
| 815 |
is the destination address in the packet header. |
| 816 |
If |
| 817 |
.B IP_PKTINFO |
| 818 |
is passed to |
| 819 |
.BR sendmsg (2) |
| 820 |
and |
| 821 |
.\" This field is grossly misnamed |
| 822 |
.I ipi_spec_dst |
| 823 |
is not zero, then it is used as the local source address for the routing |
| 824 |
table lookup and for setting up IP source route options. |
| 825 |
When |
| 826 |
.I ipi_ifindex |
| 827 |
is not zero, the primary local address of the interface specified by the |
| 828 |
index overwrites |
| 829 |
.I ipi_spec_dst |
| 830 |
for the routing table lookup. |
| 831 |
.IP |
| 832 |
Not supported for |
| 833 |
.B SOCK_STREAM |
| 834 |
sockets. |
| 835 |
.TP |
| 836 |
.BR IP_RECVERR " (since Linux 2.2)" |
| 837 |
.\" Precisely: since Linux 2.1.15 |
| 838 |
Enable extended reliable error message passing. |
| 839 |
When enabled on a datagram socket, all |
| 840 |
generated errors will be queued in a per-socket error queue. |
| 841 |
When the user receives an error from a socket operation, |
| 842 |
the errors can be received by calling |
| 843 |
.BR recvmsg (2) |
| 844 |
with the |
| 845 |
.B MSG_ERRQUEUE |
| 846 |
flag set. |
| 847 |
The |
| 848 |
.I sock_extended_err |
| 849 |
structure describing the error will be passed in an ancillary message with |
| 850 |
the type |
| 851 |
.B IP_RECVERR |
| 852 |
and the level |
| 853 |
.BR IPPROTO_IP . |
| 854 |
.\" or SOL_IP on Linux |
| 855 |
This is useful for reliable error handling on unconnected sockets. |
| 856 |
The received data portion of the error queue contains the error packet. |
| 857 |
.IP |
| 858 |
The |
| 859 |
.B IP_RECVERR |
| 860 |
control message contains a |
| 861 |
.I sock_extended_err |
| 862 |
structure: |
| 863 |
.IP |
| 864 |
.in +4n |
| 865 |
.EX |
| 866 |
#define SO_EE_ORIGIN_NONE 0 |
| 867 |
#define SO_EE_ORIGIN_LOCAL 1 |
| 868 |
#define SO_EE_ORIGIN_ICMP 2 |
| 869 |
#define SO_EE_ORIGIN_ICMP6 3 |
| 870 |
\& |
| 871 |
struct sock_extended_err { |
| 872 |
uint32_t ee_errno; /* error number */ |
| 873 |
uint8_t ee_origin; /* where the error originated */ |
| 874 |
uint8_t ee_type; /* type */ |
| 875 |
uint8_t ee_code; /* code */ |
| 876 |
uint8_t ee_pad; |
| 877 |
uint32_t ee_info; /* additional information */ |
| 878 |
uint32_t ee_data; /* other data */ |
| 879 |
/* More data may follow */ |
| 880 |
}; |
| 881 |
\& |
| 882 |
struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); |
| 883 |
.EE |
| 884 |
.in |
| 885 |
.IP |
| 886 |
.I ee_errno |
| 887 |
contains the |
| 888 |
.I errno |
| 889 |
number of the queued error. |
| 890 |
.I ee_origin |
| 891 |
is the origin code of where the error originated. |
| 892 |
The other fields are protocol-specific. |
| 893 |
The macro |
| 894 |
.B SO_EE_OFFENDER |
| 895 |
returns a pointer to the address of the network object |
| 896 |
where the error originated from given a pointer to the ancillary message. |
| 897 |
If this address is not known, the |
| 898 |
.I sa_family |
| 899 |
member of the |
| 900 |
.I sockaddr |
| 901 |
contains |
| 902 |
.B AF_UNSPEC |
| 903 |
and the other fields of the |
| 904 |
.I sockaddr |
| 905 |
are undefined. |
| 906 |
.IP |
| 907 |
IP uses the |
| 908 |
.I sock_extended_err |
| 909 |
structure as follows: |
| 910 |
.I ee_origin |
| 911 |
is set to |
| 912 |
.B SO_EE_ORIGIN_ICMP |
| 913 |
for errors received as an ICMP packet, or |
| 914 |
.B SO_EE_ORIGIN_LOCAL |
| 915 |
for locally generated errors. |
| 916 |
Unknown values should be ignored. |
| 917 |
.I ee_type |
| 918 |
and |
| 919 |
.I ee_code |
| 920 |
are set from the type and code fields of the ICMP header. |
| 921 |
.I ee_info |
| 922 |
contains the discovered MTU for |
| 923 |
.B EMSGSIZE |
| 924 |
errors. |
| 925 |
The message also contains the |
| 926 |
.I sockaddr_in of the node |
| 927 |
caused the error, which can be accessed with the |
| 928 |
.B SO_EE_OFFENDER |
| 929 |
macro. |
| 930 |
The |
| 931 |
.I sin_family |
| 932 |
field of the |
| 933 |
.B SO_EE_OFFENDER |
| 934 |
address is |
| 935 |
.B AF_UNSPEC |
| 936 |
when the source was unknown. |
| 937 |
When the error originated from the network, all IP options |
| 938 |
.RB ( IP_OPTIONS ", " IP_TTL , |
| 939 |
etc.) enabled on the socket and contained in the |
| 940 |
error packet are passed as control messages. |
| 941 |
The payload of the packet causing the error is returned as normal payload. |
| 942 |
.\" FIXME . Is it a good idea to document that? It is a dubious feature. |
| 943 |
.\" On |
| 944 |
.\" .B SOCK_STREAM |
| 945 |
.\" sockets, |
| 946 |
.\" .B IP_RECVERR |
| 947 |
.\" has slightly different semantics. Instead of |
| 948 |
.\" saving the errors for the next timeout, it passes all incoming |
| 949 |
.\" errors immediately to the user. |
| 950 |
.\" This might be useful for very short-lived TCP connections which |
| 951 |
.\" need fast error handling. Use this option with care: |
| 952 |
.\" it makes TCP unreliable |
| 953 |
.\" by not allowing it to recover properly from routing |
| 954 |
.\" shifts and other normal |
| 955 |
.\" conditions and breaks the protocol specification. |
| 956 |
Note that TCP has no error queue; |
| 957 |
.B MSG_ERRQUEUE |
| 958 |
is not permitted on |
| 959 |
.B SOCK_STREAM |
| 960 |
sockets. |
| 961 |
.B IP_RECVERR |
| 962 |
is valid for TCP, but all errors are returned by socket function return or |
| 963 |
.B SO_ERROR |
| 964 |
only. |
| 965 |
.IP |
| 966 |
For raw sockets, |
| 967 |
.B IP_RECVERR |
| 968 |
enables passing of all received ICMP errors to the |
| 969 |
application, otherwise errors are reported only on connected sockets |
| 970 |
.IP |
| 971 |
It sets or retrieves an integer boolean flag. |
| 972 |
.B IP_RECVERR |
| 973 |
defaults to off. |
| 974 |
.TP |
| 975 |
.BR IP_RECVOPTS " (since Linux 2.2)" |
| 976 |
.\" Precisely: since Linux 2.1.15 |
| 977 |
Pass all incoming IP options to the user in a |
| 978 |
.B IP_OPTIONS |
| 979 |
control message. |
| 980 |
The routing header and other options are already filled in |
| 981 |
for the local host. |
| 982 |
Not supported for |
| 983 |
.B SOCK_STREAM |
| 984 |
sockets. |
| 985 |
.TP |
| 986 |
.BR IP_RECVORIGDSTADDR " (since Linux 2.6.29)" |
| 987 |
.\" commit e8b2dfe9b4501ed0047459b2756ba26e5a940a69 |
| 988 |
This boolean option enables the |
| 989 |
.B IP_ORIGDSTADDR |
| 990 |
ancillary message in |
| 991 |
.BR recvmsg (2), |
| 992 |
in which the kernel returns the original destination address |
| 993 |
of the datagram being received. |
| 994 |
The ancillary message contains a |
| 995 |
.IR "struct sockaddr_in" . |
| 996 |
Not supported for |
| 997 |
.B SOCK_STREAM |
| 998 |
sockets. |
| 999 |
.TP |
| 1000 |
.BR IP_RECVTOS " (since Linux 2.2)" |
| 1001 |
.\" Precisely: since Linux 2.1.68 |
| 1002 |
If enabled, the |
| 1003 |
.B IP_TOS |
| 1004 |
ancillary message is passed with incoming packets. |
| 1005 |
It contains a byte which specifies the Type of Service/Precedence |
| 1006 |
field of the packet header. |
| 1007 |
Expects a boolean integer flag. |
| 1008 |
Not supported for |
| 1009 |
.B SOCK_STREAM |
| 1010 |
sockets. |
| 1011 |
.TP |
| 1012 |
.BR IP_RECVTTL " (since Linux 2.2)" |
| 1013 |
.\" Precisely: since Linux 2.1.68 |
| 1014 |
When this flag is set, pass a |
| 1015 |
.B IP_TTL |
| 1016 |
control message with the time-to-live |
| 1017 |
field of the received packet as a 32 bit integer. |
| 1018 |
Not supported for |
| 1019 |
.B SOCK_STREAM |
| 1020 |
sockets. |
| 1021 |
.TP |
| 1022 |
.BR IP_RETOPTS " (since Linux 2.2)" |
| 1023 |
.\" Precisely: since Linux 2.1.15 |
| 1024 |
Identical to |
| 1025 |
.BR IP_RECVOPTS , |
| 1026 |
but returns raw unprocessed options with timestamp and route record |
| 1027 |
options not filled in for this hop. |
| 1028 |
Not supported for |
| 1029 |
.B SOCK_STREAM |
| 1030 |
sockets. |
| 1031 |
.TP |
| 1032 |
.BR IP_ROUTER_ALERT " (since Linux 2.2)" |
| 1033 |
.\" Precisely: since Linux 2.1.68 |
| 1034 |
Pass all to-be forwarded packets with the |
| 1035 |
IP Router Alert option set to this socket. |
| 1036 |
Valid only for raw sockets. |
| 1037 |
This is useful, for instance, for user-space RSVP daemons. |
| 1038 |
The tapped packets are not forwarded by the kernel; it is |
| 1039 |
the user's responsibility to send them out again. |
| 1040 |
Socket binding is ignored, |
| 1041 |
such packets are filtered only by protocol. |
| 1042 |
Expects an integer flag. |
| 1043 |
.TP |
| 1044 |
.BR IP_TOS " (since Linux 1.0)" |
| 1045 |
Set or receive the Type-Of-Service (TOS) field that is sent |
| 1046 |
with every IP packet originating from this socket. |
| 1047 |
It is used to prioritize packets on the network. |
| 1048 |
TOS is a byte. |
| 1049 |
There are some standard TOS flags defined: |
| 1050 |
.B IPTOS_LOWDELAY |
| 1051 |
to minimize delays for interactive traffic, |
| 1052 |
.B IPTOS_THROUGHPUT |
| 1053 |
to optimize throughput, |
| 1054 |
.B IPTOS_RELIABILITY |
| 1055 |
to optimize for reliability, |
| 1056 |
.B IPTOS_MINCOST |
| 1057 |
should be used for "filler data" where slow transmission doesn't matter. |
| 1058 |
At most one of these TOS values can be specified. |
| 1059 |
Other bits are invalid and shall be cleared. |
| 1060 |
Linux sends |
| 1061 |
.B IPTOS_LOWDELAY |
| 1062 |
datagrams first by default, |
| 1063 |
but the exact behavior depends on the configured queueing discipline. |
| 1064 |
.\" FIXME elaborate on this |
| 1065 |
Some high-priority levels may require superuser privileges (the |
| 1066 |
.B CAP_NET_ADMIN |
| 1067 |
capability). |
| 1068 |
.\" The priority can also be set in a protocol-independent way by the |
| 1069 |
.\" .RB ( SOL_SOCKET ", " SO_PRIORITY ) |
| 1070 |
.\" socket option (see |
| 1071 |
.\" .BR socket (7)). |
| 1072 |
.TP |
| 1073 |
.BR IP_TRANSPARENT " (since Linux 2.6.24)" |
| 1074 |
.\" commit f5715aea4564f233767ea1d944b2637a5fd7cd2e |
| 1075 |
.\" This patch introduces the IP_TRANSPARENT socket option: enabling that |
| 1076 |
.\" will make the IPv4 routing omit the non-local source address check on |
| 1077 |
.\" output. Setting IP_TRANSPARENT requires NET_ADMIN capability. |
| 1078 |
.\" http://lwn.net/Articles/252545/ |
| 1079 |
Setting this boolean option enables transparent proxying on this socket. |
| 1080 |
This socket option allows |
| 1081 |
the calling application to bind to a nonlocal IP address and operate |
| 1082 |
both as a client and a server with the foreign address as the local endpoint. |
| 1083 |
NOTE: this requires that routing be set up in a way that |
| 1084 |
packets going to the foreign address are routed through the TProxy box |
| 1085 |
(i.e., the system hosting the application that employs the |
| 1086 |
.B IP_TRANSPARENT |
| 1087 |
socket option). |
| 1088 |
Enabling this socket option requires superuser privileges |
| 1089 |
(the |
| 1090 |
.B CAP_NET_ADMIN |
| 1091 |
capability). |
| 1092 |
.IP |
| 1093 |
TProxy redirection with the iptables TPROXY target also requires that |
| 1094 |
this option be set on the redirected socket. |
| 1095 |
.TP |
| 1096 |
.BR IP_TTL " (since Linux 1.0)" |
| 1097 |
Set or retrieve the current time-to-live field that is used in every packet |
| 1098 |
sent from this socket. |
| 1099 |
.TP |
| 1100 |
.BR IP_UNBLOCK_SOURCE " (since Linux 2.4.22 / 2.5.68)" |
| 1101 |
Unblock previously blocked multicast source. |
| 1102 |
Returns |
| 1103 |
.B EADDRNOTAVAIL |
| 1104 |
when given source is not being blocked. |
| 1105 |
.IP |
| 1106 |
Argument is an |
| 1107 |
.I ip_mreq_source |
| 1108 |
structure as described under |
| 1109 |
.BR IP_ADD_SOURCE_MEMBERSHIP . |
| 1110 |
.TP |
| 1111 |
.BR SO_PEERSEC " (since Linux 2.6.17)" |
| 1112 |
If labeled IPSEC or NetLabel is configured on both the sending and |
| 1113 |
receiving hosts, this read-only socket option returns the security |
| 1114 |
context of the peer socket connected to this socket. |
| 1115 |
By default, |
| 1116 |
this will be the same as the security context of the process that created |
| 1117 |
the peer socket unless overridden by the policy or by a process with |
| 1118 |
the required permissions. |
| 1119 |
.IP |
| 1120 |
The argument to |
| 1121 |
.BR getsockopt (2) |
| 1122 |
is a pointer to a buffer of the specified length in bytes |
| 1123 |
into which the security context string will be copied. |
| 1124 |
If the buffer length is less than the length of the security |
| 1125 |
context string, then |
| 1126 |
.BR getsockopt (2) |
| 1127 |
returns \-1, sets |
| 1128 |
.I errno |
| 1129 |
to |
| 1130 |
.BR ERANGE , |
| 1131 |
and returns the required length via |
| 1132 |
.IR optlen . |
| 1133 |
The caller should allocate at least |
| 1134 |
.B NAME_MAX |
| 1135 |
bytes for the buffer initially, although this is not guaranteed |
| 1136 |
to be sufficient. |
| 1137 |
Resizing the buffer to the returned length |
| 1138 |
and retrying may be necessary. |
| 1139 |
.IP |
| 1140 |
The security context string may include a terminating null character |
| 1141 |
in the returned length, but is not guaranteed to do so: a security |
| 1142 |
context "foo" might be represented as either {'f','o','o'} of length 3 |
| 1143 |
or {'f','o','o','\\0'} of length 4, which are considered to be |
| 1144 |
interchangeable. |
| 1145 |
The string is printable, does not contain non-terminating null characters, |
| 1146 |
and is in an unspecified encoding (in particular, it |
| 1147 |
is not guaranteed to be ASCII or UTF-8). |
| 1148 |
.IP |
| 1149 |
The use of this option for sockets in the |
| 1150 |
.B AF_INET |
| 1151 |
address family is supported since Linux 2.6.17 |
| 1152 |
.\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c |
| 1153 |
for TCP sockets, and since Linux 4.17 |
| 1154 |
.\" commit d452930fd3b9031e59abfeddb2fa383f1403d61a |
| 1155 |
for SCTP sockets. |
| 1156 |
.IP |
| 1157 |
For SELinux, NetLabel conveys only the MLS portion of the security |
| 1158 |
context of the peer across the wire, defaulting the rest of the |
| 1159 |
security context to the values defined in the policy for the |
| 1160 |
netmsg initial security identifier (SID). |
| 1161 |
However, NetLabel can |
| 1162 |
be configured to pass full security contexts over loopback. |
| 1163 |
Labeled IPSEC always passes full security contexts as part of establishing |
| 1164 |
the security association (SA) and looks them up based on the association |
| 1165 |
for each packet. |
| 1166 |
.\" |
| 1167 |
.SS /proc interfaces |
| 1168 |
The IP protocol |
| 1169 |
supports a set of |
| 1170 |
.I /proc |
| 1171 |
interfaces to configure some global parameters. |
| 1172 |
The parameters can be accessed by reading or writing files in the directory |
| 1173 |
.IR /proc/sys/net/ipv4/ . |
| 1174 |
.\" FIXME As at 2.6.12, 14 Jun 2005, the following are undocumented: |
| 1175 |
.\" ip_queue_maxlen |
| 1176 |
.\" ip_conntrack_max |
| 1177 |
Interfaces described as |
| 1178 |
.I Boolean |
| 1179 |
take an integer value, with a nonzero value ("true") meaning that |
| 1180 |
the corresponding option is enabled, and a zero value ("false") |
| 1181 |
meaning that the option is disabled. |
| 1182 |
.\" |
| 1183 |
.TP |
| 1184 |
.IR ip_always_defrag " (Boolean; since Linux 2.2.13)" |
| 1185 |
[New with Linux 2.2.13; in earlier kernel versions this feature |
| 1186 |
was controlled at compile time by the |
| 1187 |
.B CONFIG_IP_ALWAYS_DEFRAG |
| 1188 |
option; this option is not present in Linux 2.4.x and later] |
| 1189 |
.IP |
| 1190 |
When this boolean flag is enabled (not equal 0), incoming fragments |
| 1191 |
(parts of IP packets |
| 1192 |
that arose when some host between origin and destination decided |
| 1193 |
that the packets were too large and cut them into pieces) will be |
| 1194 |
reassembled (defragmented) before being processed, even if they are |
| 1195 |
about to be forwarded. |
| 1196 |
.IP |
| 1197 |
Enable only if running either a firewall that is the sole link |
| 1198 |
to your network or a transparent proxy; never ever use it for a |
| 1199 |
normal router or host. |
| 1200 |
Otherwise, fragmented communication can be disturbed |
| 1201 |
if the fragments travel over different links. |
| 1202 |
Defragmentation also has a large memory and CPU time cost. |
| 1203 |
.IP |
| 1204 |
This is automagically turned on when masquerading or transparent |
| 1205 |
proxying are configured. |
| 1206 |
.\" |
| 1207 |
.TP |
| 1208 |
.IR ip_autoconfig " (since Linux 2.2 to Linux 2.6.17)" |
| 1209 |
.\" Precisely: since Linux 2.1.68 |
| 1210 |
.\" FIXME document ip_autoconfig |
| 1211 |
Not documented. |
| 1212 |
.\" |
| 1213 |
.TP |
| 1214 |
.IR ip_default_ttl " (integer; default: 64; since Linux 2.2)" |
| 1215 |
.\" Precisely: since Linux 2.1.15 |
| 1216 |
Set the default time-to-live value of outgoing packets. |
| 1217 |
This can be changed per socket with the |
| 1218 |
.B IP_TTL |
| 1219 |
option. |
| 1220 |
.\" |
| 1221 |
.TP |
| 1222 |
.IR ip_dynaddr " (Boolean; default: disabled; since Linux 2.0.31)" |
| 1223 |
Enable dynamic socket address and masquerading entry rewriting on interface |
| 1224 |
address change. |
| 1225 |
This is useful for dialup interface with changing IP addresses. |
| 1226 |
0 means no rewriting, 1 turns it on and 2 enables verbose mode. |
| 1227 |
.\" |
| 1228 |
.TP |
| 1229 |
.IR ip_forward " (Boolean; default: disabled; since Linux 1.2)" |
| 1230 |
Enable IP forwarding with a boolean flag. |
| 1231 |
IP forwarding can be also set on a per-interface basis. |
| 1232 |
.\" |
| 1233 |
.TP |
| 1234 |
.IR ip_local_port_range " (since Linux 2.2)" |
| 1235 |
.\" Precisely: since Linux 2.1.68 |
| 1236 |
This file contains two integers that define the default local port range |
| 1237 |
allocated to sockets that are not explicitly bound to a port number\[em]that |
| 1238 |
is, the range used for |
| 1239 |
.IR "ephemeral ports" . |
| 1240 |
An ephemeral port is allocated to a socket in the following circumstances: |
| 1241 |
.RS |
| 1242 |
.IP \[bu] 3 |
| 1243 |
the port number in a socket address is specified as 0 when calling |
| 1244 |
.BR bind (2); |
| 1245 |
.IP \[bu] |
| 1246 |
.BR listen (2) |
| 1247 |
is called on a stream socket that was not previously bound; |
| 1248 |
.IP \[bu] |
| 1249 |
.BR connect (2) |
| 1250 |
was called on a socket that was not previously bound; |
| 1251 |
.IP \[bu] |
| 1252 |
.BR sendto (2) |
| 1253 |
is called on a datagram socket that was not previously bound. |
| 1254 |
.RE |
| 1255 |
.IP |
| 1256 |
Allocation of ephemeral ports starts with the first number in |
| 1257 |
.I ip_local_port_range |
| 1258 |
and ends with the second number. |
| 1259 |
If the range of ephemeral ports is exhausted, |
| 1260 |
then the relevant system call returns an error (but see BUGS). |
| 1261 |
.IP |
| 1262 |
Note that the port range in |
| 1263 |
.I ip_local_port_range |
| 1264 |
should not conflict with the ports used by masquerading |
| 1265 |
(although the case is handled). |
| 1266 |
Also, arbitrary choices may cause problems with some firewall packet |
| 1267 |
filters that make assumptions about the local ports in use. |
| 1268 |
The first number should be at least greater than 1024, |
| 1269 |
or better, greater than 4096, to avoid clashes |
| 1270 |
with well known ports and to minimize firewall problems. |
| 1271 |
.\" |
| 1272 |
.TP |
| 1273 |
.IR ip_no_pmtu_disc " (Boolean; default: disabled; since Linux 2.2)" |
| 1274 |
.\" Precisely: 2.1.15 |
| 1275 |
If enabled, don't do Path MTU Discovery for TCP sockets by default. |
| 1276 |
Path MTU discovery may fail if misconfigured firewalls (that drop |
| 1277 |
all ICMP packets) or misconfigured interfaces (e.g., a point-to-point |
| 1278 |
link where the both ends don't agree on the MTU) are on the path. |
| 1279 |
It is better to fix the broken routers on the path than to turn off |
| 1280 |
Path MTU Discovery globally, because not doing it incurs a high cost |
| 1281 |
to the network. |
| 1282 |
.\" |
| 1283 |
.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt |
| 1284 |
.TP |
| 1285 |
.IR ip_nonlocal_bind " (Boolean; default: disabled; since Linux 2.4)" |
| 1286 |
.\" Precisely: patch-2.4.0-test10 |
| 1287 |
If set, allows processes to |
| 1288 |
.BR bind (2) |
| 1289 |
to nonlocal IP addresses, |
| 1290 |
which can be quite useful, but may break some applications. |
| 1291 |
.\" |
| 1292 |
.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt |
| 1293 |
.TP |
| 1294 |
.IR ip6frag_time " (integer; default: 30)" |
| 1295 |
Time in seconds to keep an IPv6 fragment in memory. |
| 1296 |
.\" |
| 1297 |
.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt |
| 1298 |
.TP |
| 1299 |
.IR ip6frag_secret_interval " (integer; default: 600)" |
| 1300 |
Regeneration interval (in seconds) of the hash secret (or lifetime |
| 1301 |
for the hash secret) for IPv6 fragments. |
| 1302 |
.TP |
| 1303 |
.IR ipfrag_high_thresh " (integer)" |
| 1304 |
.TQ |
| 1305 |
.IR ipfrag_low_thresh " (integer)" |
| 1306 |
If the amount of queued IP fragments reaches |
| 1307 |
.IR ipfrag_high_thresh , |
| 1308 |
the queue is pruned down to |
| 1309 |
.IR ipfrag_low_thresh . |
| 1310 |
Contains an integer with the number of bytes. |
| 1311 |
.TP |
| 1312 |
.I neigh/* |
| 1313 |
See |
| 1314 |
.BR arp (7). |
| 1315 |
.\" FIXME Document the conf/*/* interfaces |
| 1316 |
.\" |
| 1317 |
.\" FIXME Document the route/* interfaces |
| 1318 |
.SS Ioctls |
| 1319 |
All ioctls described in |
| 1320 |
.BR socket (7) |
| 1321 |
apply to |
| 1322 |
.BR ip . |
| 1323 |
.P |
| 1324 |
Ioctls to configure generic device parameters are described in |
| 1325 |
.BR netdevice (7). |
| 1326 |
.\" FIXME Add a discussion of multicasting |
| 1327 |
.SH ERRORS |
| 1328 |
.\" FIXME document all errors. |
| 1329 |
.\" We should really fix the kernels to give more uniform |
| 1330 |
.\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.) |
| 1331 |
.TP |
| 1332 |
.B EACCES |
| 1333 |
The user tried to execute an operation without the necessary permissions. |
| 1334 |
These include: |
| 1335 |
sending a packet to a broadcast address without having the |
| 1336 |
.B SO_BROADCAST |
| 1337 |
flag set; |
| 1338 |
sending a packet via a |
| 1339 |
.I prohibit |
| 1340 |
route; |
| 1341 |
modifying firewall settings without superuser privileges (the |
| 1342 |
.B CAP_NET_ADMIN |
| 1343 |
capability); |
| 1344 |
binding to a privileged port without superuser privileges (the |
| 1345 |
.B CAP_NET_BIND_SERVICE |
| 1346 |
capability). |
| 1347 |
.TP |
| 1348 |
.B EADDRINUSE |
| 1349 |
Tried to bind to an address already in use. |
| 1350 |
.TP |
| 1351 |
.B EADDRNOTAVAIL |
| 1352 |
A nonexistent interface was requested or the requested source |
| 1353 |
address was not local. |
| 1354 |
.TP |
| 1355 |
.B EAGAIN |
| 1356 |
Operation on a nonblocking socket would block. |
| 1357 |
.TP |
| 1358 |
.B EALREADY |
| 1359 |
A connection operation on a nonblocking socket is already in progress. |
| 1360 |
.TP |
| 1361 |
.B ECONNABORTED |
| 1362 |
A connection was closed during an |
| 1363 |
.BR accept (2). |
| 1364 |
.TP |
| 1365 |
.B EHOSTUNREACH |
| 1366 |
No valid routing table entry matches the destination address. |
| 1367 |
This error can be caused by an ICMP message from a remote router or |
| 1368 |
for the local routing table. |
| 1369 |
.TP |
| 1370 |
.B EINVAL |
| 1371 |
Invalid argument passed. |
| 1372 |
For send operations this can be caused by sending to a |
| 1373 |
.I blackhole |
| 1374 |
route. |
| 1375 |
.TP |
| 1376 |
.B EISCONN |
| 1377 |
.BR connect (2) |
| 1378 |
was called on an already connected socket. |
| 1379 |
.TP |
| 1380 |
.B EMSGSIZE |
| 1381 |
Datagram is bigger than an MTU on the path and it cannot be fragmented. |
| 1382 |
.TP |
| 1383 |
.B ENOBUFS |
| 1384 |
.TQ |
| 1385 |
.B ENOMEM |
| 1386 |
Not enough free memory. |
| 1387 |
This often means that the memory allocation is limited by the socket |
| 1388 |
buffer limits, not by the system memory, but this is not 100% consistent. |
| 1389 |
.TP |
| 1390 |
.B ENOENT |
| 1391 |
.B SIOCGSTAMP |
| 1392 |
was called on a socket where no packet arrived. |
| 1393 |
.TP |
| 1394 |
.B ENOPKG |
| 1395 |
A kernel subsystem was not configured. |
| 1396 |
.TP |
| 1397 |
.BR ENOPROTOOPT " and " EOPNOTSUPP |
| 1398 |
Invalid socket option passed. |
| 1399 |
.TP |
| 1400 |
.B ENOTCONN |
| 1401 |
The operation is defined only on a connected socket, but the socket wasn't |
| 1402 |
connected. |
| 1403 |
.TP |
| 1404 |
.B EPERM |
| 1405 |
User doesn't have permission to set high priority, change configuration, |
| 1406 |
or send signals to the requested process or group. |
| 1407 |
.TP |
| 1408 |
.B EPIPE |
| 1409 |
The connection was unexpectedly closed or shut down by the other end. |
| 1410 |
.TP |
| 1411 |
.B ESOCKTNOSUPPORT |
| 1412 |
The socket is not configured or an unknown socket type was requested. |
| 1413 |
.P |
| 1414 |
Other errors may be generated by the overlaying protocols; see |
| 1415 |
.BR tcp (7), |
| 1416 |
.BR raw (7), |
| 1417 |
.BR udp (7), |
| 1418 |
and |
| 1419 |
.BR socket (7). |
| 1420 |
.SH NOTES |
| 1421 |
.BR IP_FREEBIND , |
| 1422 |
.BR IP_MSFILTER , |
| 1423 |
.BR IP_MTU , |
| 1424 |
.BR IP_MTU_DISCOVER , |
| 1425 |
.BR IP_RECVORIGDSTADDR , |
| 1426 |
.BR IP_PASSSEC , |
| 1427 |
.BR IP_PKTINFO , |
| 1428 |
.BR IP_RECVERR , |
| 1429 |
.BR IP_ROUTER_ALERT , |
| 1430 |
and |
| 1431 |
.B IP_TRANSPARENT |
| 1432 |
are Linux-specific. |
| 1433 |
.\" IP_XFRM_POLICY is Linux-specific |
| 1434 |
.\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs |
| 1435 |
.P |
| 1436 |
Be very careful with the |
| 1437 |
.B SO_BROADCAST |
| 1438 |
option \- it is not privileged in Linux. |
| 1439 |
It is easy to overload the network |
| 1440 |
with careless broadcasts. |
| 1441 |
For new application protocols |
| 1442 |
it is better to use a multicast group instead of broadcasting. |
| 1443 |
Broadcasting is discouraged. |
| 1444 |
See RFC 6762 for an example of a protocol (mDNS) |
| 1445 |
using the more modern multicast approach |
| 1446 |
to communicating with an open-ended |
| 1447 |
group of hosts on the local network. |
| 1448 |
.P |
| 1449 |
Some other BSD sockets implementations provide |
| 1450 |
.B IP_RCVDSTADDR |
| 1451 |
and |
| 1452 |
.B IP_RECVIF |
| 1453 |
socket options to get the destination address and the interface of |
| 1454 |
received datagrams. |
| 1455 |
Linux has the more general |
| 1456 |
.B IP_PKTINFO |
| 1457 |
for the same task. |
| 1458 |
.P |
| 1459 |
Some BSD sockets implementations also provide an |
| 1460 |
.B IP_RECVTTL |
| 1461 |
option, but an ancillary message with type |
| 1462 |
.B IP_RECVTTL |
| 1463 |
is passed with the incoming packet. |
| 1464 |
This is different from the |
| 1465 |
.B IP_TTL |
| 1466 |
option used in Linux. |
| 1467 |
.P |
| 1468 |
Using the |
| 1469 |
.B SOL_IP |
| 1470 |
socket options level isn't portable; BSD-based stacks use the |
| 1471 |
.B IPPROTO_IP |
| 1472 |
level. |
| 1473 |
.P |
| 1474 |
.B INADDR_ANY |
| 1475 |
(0.0.0.0) and |
| 1476 |
.B INADDR_BROADCAST |
| 1477 |
(255.255.255.255) are byte-order-neutral. |
| 1478 |
This means |
| 1479 |
.BR htonl (3) |
| 1480 |
has no effect on them. |
| 1481 |
.SS Compatibility |
| 1482 |
For compatibility with Linux 2.0, the obsolete |
| 1483 |
.BI "socket(AF_INET, SOCK_PACKET, " protocol ) |
| 1484 |
syntax is still supported to open a |
| 1485 |
.BR packet (7) |
| 1486 |
socket. |
| 1487 |
This is deprecated and should be replaced by |
| 1488 |
.BI "socket(AF_PACKET, SOCK_RAW, " protocol ) |
| 1489 |
instead. |
| 1490 |
The main difference is the new |
| 1491 |
.I sockaddr_ll |
| 1492 |
address structure for generic link layer information instead of the old |
| 1493 |
.BR sockaddr_pkt . |
| 1494 |
.SH BUGS |
| 1495 |
There are too many inconsistent error values. |
| 1496 |
.P |
| 1497 |
The error used to diagnose exhaustion of the ephemeral port range differs |
| 1498 |
across the various system calls |
| 1499 |
.RB ( connect (2), |
| 1500 |
.BR bind (2), |
| 1501 |
.BR listen (2), |
| 1502 |
.BR sendto (2)) |
| 1503 |
that can assign ephemeral ports. |
| 1504 |
.P |
| 1505 |
The ioctls to configure IP-specific interface options and ARP tables are |
| 1506 |
not described. |
| 1507 |
.\" .P |
| 1508 |
.\" Some versions of glibc forget to declare |
| 1509 |
.\" .IR in_pktinfo . |
| 1510 |
.\" Workaround currently is to copy it into your program from this man page. |
| 1511 |
.P |
| 1512 |
Receiving the original destination address with |
| 1513 |
.B MSG_ERRQUEUE |
| 1514 |
in |
| 1515 |
.I msg_name |
| 1516 |
by |
| 1517 |
.BR recvmsg (2) |
| 1518 |
does not work in some Linux 2.2 kernels. |
| 1519 |
.\" .SH AUTHORS |
| 1520 |
.\" This man page was written by Andi Kleen. |
| 1521 |
.SH SEE ALSO |
| 1522 |
.BR recvmsg (2), |
| 1523 |
.BR sendmsg (2), |
| 1524 |
.BR byteorder (3), |
| 1525 |
.BR capabilities (7), |
| 1526 |
.BR icmp (7), |
| 1527 |
.BR ipv6 (7), |
| 1528 |
.BR netdevice (7), |
| 1529 |
.BR netlink (7), |
| 1530 |
.BR raw (7), |
| 1531 |
.BR socket (7), |
| 1532 |
.BR tcp (7), |
| 1533 |
.BR udp (7), |
| 1534 |
.BR ip (8) |
| 1535 |
.P |
| 1536 |
The kernel source file |
| 1537 |
.IR Documentation/networking/ip\-sysctl.txt . |
| 1538 |
.P |
| 1539 |
RFC\ 791 for the original IP specification. |
| 1540 |
RFC\ 1122 for the IPv4 host requirements. |
| 1541 |
RFC\ 1812 for the IPv4 router requirements. |