1IP(7)                      Linux Programmer's Manual                     IP(7)
2
3
4

NAME

6       ip - Linux IPv4 protocol implementation
7

SYNOPSIS

9       #include <sys/socket.h>
10       #include <netinet/in.h>
11       #include <netinet/ip.h> /* superset of previous */
12
13       tcp_socket = socket(AF_INET, SOCK_STREAM, 0);
14       udp_socket = socket(AF_INET, SOCK_DGRAM, 0);
15       raw_socket = socket(AF_INET, SOCK_RAW, protocol);
16

DESCRIPTION

18       Linux implements the Internet Protocol, version 4, described in RFC 791
19       and RFC 1122.  ip contains a level 2 multicasting  implementation  con‐
20       forming  to RFC 1112.  It also contains an IP router including a packet
21       filter.
22
23       The programming interface is BSD-sockets compatible.  For more informa‐
24       tion on sockets, see socket(7).
25
26       An IP socket is created using socket(2):
27
28           socket(AF_INET, socket_type, protocol);
29
30       Valid  socket  types  include  SOCK_STREAM  to  open  a  stream socket,
31       SOCK_DGRAM to open a datagram socket, and SOCK_RAW  to  open  a  raw(7)
32       socket to access the IP protocol directly.
33
34       protocol  is  the  IP protocol in the IP header to be received or sent.
35       Valid values for protocol include:
36
37       • 0 and IPPROTO_TCP for tcp(7) stream sockets;
38
39       • 0 and IPPROTO_UDP for udp(7) datagram sockets;
40
41IPPROTO_SCTP for sctp(7) stream sockets; and
42
43IPPROTO_UDPLITE for udplite(7) datagram sockets.
44
45       For SOCK_RAW you may specify  a  valid  IANA  IP  protocol  defined  in
46       RFC 1700 assigned numbers.
47
48       When a process wants to receive new incoming packets or connections, it
49       should bind a socket to a local interface address  using  bind(2).   In
50       this case, only one IP socket may be bound to any given local (address,
51       port) pair.  When INADDR_ANY is specified in the bind call, the  socket
52       will  be bound to all local interfaces.  When listen(2) is called on an
53       unbound socket, the socket is automatically bound to a random free port
54       with the local address set to INADDR_ANY.  When connect(2) is called on
55       an unbound socket, the socket is automatically bound to a  random  free
56       port  or  to  a  usable  shared  port with the local address set to IN‐
57       ADDR_ANY.
58
59       A TCP local socket address that has been bound is unavailable for  some
60       time  after  closing,  unless the SO_REUSEADDR flag has been set.  Care
61       should be taken when using this flag as it makes TCP less reliable.
62
63   Address format
64       An IP socket address is defined as a combination of an IP interface ad‐
65       dress  and a 16-bit port number.  The basic IP protocol does not supply
66       port numbers, they are  implemented  by  higher  level  protocols  like
67       udp(7) and tcp(7).  On raw sockets sin_port is set to the IP protocol.
68
69           struct sockaddr_in {
70               sa_family_t    sin_family; /* address family: AF_INET */
71               in_port_t      sin_port;   /* port in network byte order */
72               struct in_addr sin_addr;   /* internet address */
73           };
74
75           /* Internet address */
76           struct in_addr {
77               uint32_t       s_addr;     /* address in network byte order */
78           };
79
80       sin_family  is  always  set to AF_INET.  This is required; in Linux 2.2
81       most networking functions return EINVAL when this setting  is  missing.
82       sin_port contains the port in network byte order.  The port numbers be‐
83       low 1024 are called privileged ports (or  sometimes:  reserved  ports).
84       Only   a   privileged  process  (on  Linux:  a  process  that  has  the
85       CAP_NET_BIND_SERVICE capability in the  user  namespace  governing  its
86       network  namespace)  may  bind(2)  to these sockets.  Note that the raw
87       IPv4 protocol as such has no concept of a port,  they  are  implemented
88       only by higher protocols like tcp(7) and udp(7).
89
90       sin_addr  is  the IP host address.  The s_addr member of struct in_addr
91       contains the host interface address in  network  byte  order.   in_addr
92       should  be  assigned one of the INADDR_* values (e.g., INADDR_LOOPBACK)
93       using  htonl(3)  or   set   using   the   inet_aton(3),   inet_addr(3),
94       inet_makeaddr(3)  library  functions or directly with the name resolver
95       (see gethostbyname(3)).
96
97       IPv4 addresses are divided into unicast, broadcast, and  multicast  ad‐
98       dresses.   Unicast  addresses  specify  a  single  interface of a host,
99       broadcast addresses specify all hosts on a network, and  multicast  ad‐
100       dresses address all hosts in a multicast group.  Datagrams to broadcast
101       addresses can be sent or received only  when  the  SO_BROADCAST  socket
102       flag  is set.  In the current implementation, connection-oriented sock‐
103       ets are allowed to use only unicast addresses.
104
105       Note that the address and the port are always stored  in  network  byte
106       order.  In particular, this means that you need to call htons(3) on the
107       number that is assigned to a port.  All address/port manipulation func‐
108       tions in the standard library work in network byte order.
109
110       There are several special addresses: INADDR_LOOPBACK (127.0.0.1) always
111       refers to the local host via the loopback device; INADDR_ANY  (0.0.0.0)
112       means any address for binding; INADDR_BROADCAST (255.255.255.255) means
113       any host and has the same effect on bind as INADDR_ANY  for  historical
114       reasons.
115
116   Socket options
117       IP  supports some protocol-specific socket options that can be set with
118       setsockopt(2) and read with getsockopt(2).  The socket option level for
119       IP  is  IPPROTO_IP.   A  boolean integer flag is zero when it is false,
120       otherwise true.
121
122       When an invalid socket option is specified, getsockopt(2) and  setsock‐
123       opt(2) fail with the error ENOPROTOOPT.
124
125       IP_ADD_MEMBERSHIP (since Linux 1.2)
126              Join a multicast group.  Argument is an ip_mreqn structure.
127
128           struct ip_mreqn {
129               struct in_addr imr_multiaddr; /* IP multicast group
130                                                address */
131               struct in_addr imr_address;   /* IP address of local
132                                                interface */
133               int            imr_ifindex;   /* interface index */
134           };
135
136       imr_multiaddr  contains the address of the multicast group the applica‐
137       tion wants to join or leave.  It must be a valid multicast address  (or
138       setsockopt(2) fails with the error EINVAL).  imr_address is the address
139       of the local interface with which the system should join the  multicast
140       group; if it is equal to INADDR_ANY, an appropriate interface is chosen
141       by the system.  imr_ifindex is the interface  index  of  the  interface
142       that  should  join/leave  the imr_multiaddr group, or 0 to indicate any
143       interface.
144
145              The ip_mreqn structure is available only since Linux  2.2.   For
146              compatibility,  the  old  ip_mreq structure (present since Linux
147              1.2) is still supported; it differs from ip_mreqn  only  by  not
148              including  the  imr_ifindex field.  (The kernel determines which
149              structure is being passed based on the size passed in optlen.)
150
151              IP_ADD_MEMBERSHIP is valid only for setsockopt(2).
152
153       IP_ADD_SOURCE_MEMBERSHIP (since Linux 2.4.22 / 2.5.68)
154              Join a multicast group and allow  receiving  data  only  from  a
155              specified source.  Argument is an ip_mreq_source structure.
156
157           struct ip_mreq_source {
158               struct in_addr imr_multiaddr;  /* IP multicast group
159                                                 address */
160               struct in_addr imr_interface;  /* IP address of local
161                                                 interface */
162               struct in_addr imr_sourceaddr; /* IP address of
163                                                 multicast source */
164           };
165
166       The  ip_mreq_source  structure  is  similar to ip_mreqn described under
167       IP_ADD_MEMBERSHIP.  The imr_multiaddr field contains the address of the
168       multicast group the application wants to join or leave.  The imr_inter‐
169       face field is the address of the local interface with which the  system
170       should  join  the  multicast  group.  Finally, the imr_sourceaddr field
171       contains the address of the source the  application  wants  to  receive
172       data from.
173
174              This  option  can be used multiple times to allow receiving data
175              from more than one source.
176
177       IP_BIND_ADDRESS_NO_PORT (since Linux 4.2)
178              Inform the kernel to not reserve an ephemeral  port  when  using
179              bind(2)  with  a port number of 0.  The port will later be auto‐
180              matically chosen at connect(2) time, in a way that allows  shar‐
181              ing a source port as long as the 4-tuple is unique.
182
183       IP_BLOCK_SOURCE (since Linux 2.4.22 / 2.5.68)
184              Stop  receiving multicast data from a specific source in a given
185              group.  This is valid only after the application has  subscribed
186              to   the  multicast  group  using  either  IP_ADD_MEMBERSHIP  or
187              IP_ADD_SOURCE_MEMBERSHIP.
188
189              Argument is  an  ip_mreq_source  structure  as  described  under
190              IP_ADD_SOURCE_MEMBERSHIP.
191
192       IP_DROP_MEMBERSHIP (since Linux 1.2)
193              Leave  a  multicast  group.   Argument is an ip_mreqn or ip_mreq
194              structure similar to IP_ADD_MEMBERSHIP.
195
196       IP_DROP_SOURCE_MEMBERSHIP (since Linux 2.4.22 / 2.5.68)
197              Leave a source-specific group—that is, stop receiving data  from
198              a  given  multicast group that come from a given source.  If the
199              application has subscribed to multiple sources within  the  same
200              group,  data from the remaining sources will still be delivered.
201              To  stop  receiving  data  from  all  sources   at   once,   use
202              IP_DROP_MEMBERSHIP.
203
204              Argument  is  an  ip_mreq_source  structure  as  described under
205              IP_ADD_SOURCE_MEMBERSHIP.
206
207       IP_FREEBIND (since Linux 2.4)
208              If enabled, this boolean option allows binding to an IP  address
209              that  is nonlocal or does not (yet) exist.  This permits listen‐
210              ing on a socket, without requiring the underlying network inter‐
211              face  or  the  specified dynamic IP address to be up at the time
212              that the application is trying to bind to it.   This  option  is
213              the  per-socket  equivalent of the ip_nonlocal_bind /proc inter‐
214              face described below.
215
216       IP_HDRINCL (since Linux 2.0)
217              If enabled, the user supplies an IP header in front of the  user
218              data.   Valid only for SOCK_RAW sockets; see raw(7) for more in‐
219              formation.  When this flag is enabled, the values set by  IP_OP‐
220              TIONS, IP_TTL, and IP_TOS are ignored.
221
222       IP_MSFILTER (since Linux 2.4.22 / 2.5.68)
223              This option provides access to the advanced full-state filtering
224              API.  Argument is an ip_msfilter structure.
225
226           struct ip_msfilter {
227               struct in_addr imsf_multiaddr; /* IP multicast group
228                                                 address */
229               struct in_addr imsf_interface; /* IP address of local
230                                                 interface */
231               uint32_t       imsf_fmode;     /* Filter-mode */
232
233               uint32_t       imsf_numsrc;    /* Number of sources in
234                                                 the following array */
235               struct in_addr imsf_slist[1];  /* Array of source
236                                                 addresses */
237           };
238
239       There are two macros, MCAST_INCLUDE and  MCAST_EXCLUDE,  which  can  be
240       used  to  specify  the  filtering  mode.   Additionally,  the IP_MSFIL‐
241       TER_SIZE(n) macro exists to determine how  much  memory  is  needed  to
242       store ip_msfilter structure with n sources in the source list.
243
244              For  the full description of multicast source filtering refer to
245              RFC 3376.
246
247       IP_MTU (since Linux 2.2)
248              Retrieve the current known path MTU of the current socket.   Re‐
249              turns an integer.
250
251              IP_MTU  is valid only for getsockopt(2) and can be employed only
252              when the socket has been connected.
253
254       IP_MTU_DISCOVER (since Linux 2.2)
255              Set or receive the Path MTU  Discovery  setting  for  a  socket.
256              When  enabled,  Linux will perform Path MTU Discovery as defined
257              in RFC 1191 on SOCK_STREAM sockets.  For  non-SOCK_STREAM  sock‐
258              ets,  IP_PMTUDISC_DO forces the don't-fragment flag to be set on
259              all outgoing packets.  It is the user's responsibility to packe‐
260              tize  the  data in MTU-sized chunks and to do the retransmits if
261              necessary.  The kernel will  reject  (with  EMSGSIZE)  datagrams
262              that  are bigger than the known path MTU.  IP_PMTUDISC_WANT will
263              fragment a datagram if needed according to the path MTU, or will
264              set the don't-fragment flag otherwise.
265
266              The  system-wide default can be toggled between IP_PMTUDISC_WANT
267              and IP_PMTUDISC_DONT by writing (respectively, zero and  nonzero
268              values) to the /proc/sys/net/ipv4/ip_no_pmtu_disc file.
269
270              Path MTU discovery value   Meaning
271              IP_PMTUDISC_WANT           Use per-route settings.
272              IP_PMTUDISC_DONT           Never do Path MTU Discovery.
273              IP_PMTUDISC_DO             Always do Path MTU Discovery.
274              IP_PMTUDISC_PROBE          Set DF but ignore Path MTU.
275
276              When  PMTU  discovery is enabled, the kernel automatically keeps
277              track of the path MTU per destination host.   When  it  is  con‐
278              nected  to  a specific peer with connect(2), the currently known
279              path MTU can be retrieved conveniently using the  IP_MTU  socket
280              option  (e.g.,  after an EMSGSIZE error occurred).  The path MTU
281              may change over time.  For connectionless sockets with many des‐
282              tinations,  the  new MTU for a given destination can also be ac‐
283              cessed using the error queue (see IP_RECVERR).  A new error will
284              be queued for every incoming MTU update.
285
286              While  MTU  discovery is in progress, initial packets from data‐
287              gram sockets may be dropped.  Applications using UDP  should  be
288              aware  of this and not take it into account for their packet re‐
289              transmit strategy.
290
291              To bootstrap the path MTU discovery process on unconnected sock‐
292              ets,  it  is possible to start with a big datagram size (headers
293              up to 64 kilobytes long) and let it shrink  by  updates  of  the
294              path MTU.
295
296              To  get  an initial estimate of the path MTU, connect a datagram
297              socket to the destination address using connect(2) and  retrieve
298              the MTU by calling getsockopt(2) with the IP_MTU option.
299
300              It is possible to implement RFC 4821 MTU probing with SOCK_DGRAM
301              or SOCK_RAW sockets by  setting  a  value  of  IP_PMTUDISC_PROBE
302              (available  since Linux 2.6.22).  This is also particularly use‐
303              ful for diagnostic tools such as tracepath(8) that wish  to  de‐
304              liberately send probe packets larger than the observed Path MTU.
305
306       IP_MULTICAST_ALL (since Linux 2.6.31)
307              This  option can be used to modify the delivery policy of multi‐
308              cast messages to sockets bound to the  wildcard  INADDR_ANY  ad‐
309              dress.   The  argument is a boolean integer (defaults to 1).  If
310              set to 1, the socket will receive messages from all  the  groups
311              that  have been joined globally on the whole system.  Otherwise,
312              it will deliver messages only from the groups that have been ex‐
313              plicitly  joined  (for example via the IP_ADD_MEMBERSHIP option)
314              on this particular socket.
315
316       IP_MULTICAST_IF (since Linux 1.2)
317              Set the local device for a multicast socket.  The  argument  for
318              setsockopt(2) is an ip_mreqn or (since Linux 3.5) ip_mreq struc‐
319              ture similar to  IP_ADD_MEMBERSHIP,  or  an  in_addr  structure.
320              (The  kernel determines which structure is being passed based on
321              the size passed in optlen.)  For getsockopt(2), the argument  is
322              an in_addr structure.
323
324       IP_MULTICAST_LOOP (since Linux 1.2)
325              Set  or  read a boolean integer argument that determines whether
326              sent multicast packets should be looped back to the local  sock‐
327              ets.
328
329       IP_MULTICAST_TTL (since Linux 1.2)
330              Set or read the time-to-live value of outgoing multicast packets
331              for this socket.  It is very important for multicast packets  to
332              set  the  smallest  TTL  possible.  The default is 1 which means
333              that multicast packets don't leave the local network unless  the
334              user program explicitly requests it.  Argument is an integer.
335
336       IP_NODEFRAG (since Linux 2.6.36)
337              If  enabled  (argument  is  nonzero), the reassembly of outgoing
338              packets is disabled in the netfilter layer.  The argument is  an
339              integer.
340
341              This option is valid only for SOCK_RAW sockets.
342
343       IP_OPTIONS (since Linux 2.0)
344              Set or get the IP options to be sent with every packet from this
345              socket.  The arguments are a pointer to a memory buffer contain‐
346              ing  the  options and the option length.  The setsockopt(2) call
347              sets the IP options associated with a socket.  The  maximum  op‐
348              tion size for IPv4 is 40 bytes.  See RFC 791 for the allowed op‐
349              tions.   When  the  initial  connection  request  packet  for  a
350              SOCK_STREAM  socket  contains IP options, the IP options will be
351              set automatically to the options from the  initial  packet  with
352              routing  headers  reversed.  Incoming packets are not allowed to
353              change options after the connection is  established.   The  pro‐
354              cessing  of  all  incoming source routing options is disabled by
355              default and can be  enabled  by  using  the  accept_source_route
356              /proc  interface.   Other options like timestamps are still han‐
357              dled.  For datagram sockets, IP options can be set only  by  the
358              local user.  Calling getsockopt(2) with IP_OPTIONS puts the cur‐
359              rent IP options used for sending into the supplied buffer.
360
361       IP_PASSSEC (since Linux 2.6.17)
362              If labeled IPSEC or NetLabel is configured on  the  sending  and
363              receiving  hosts,  this option enables receiving of the security
364              context of the peer socket  in  an  ancillary  message  of  type
365              SCM_SECURITY  retrieved  using  recvmsg(2).  This option is sup‐
366              ported only for UDP sockets; for TCP or SCTP  sockets,  see  the
367              description of the SO_PEERSEC option below.
368
369              The  value given as an argument to setsockopt(2) and returned as
370              the result of getsockopt(2) is an integer boolean flag.
371
372              The security context returned in the SCM_SECURITY ancillary mes‐
373              sage  is  of  the  same  format  as  the one described under the
374              SO_PEERSEC option below.
375
376              Note: the  reuse  of  the  SCM_SECURITY  message  type  for  the
377              IP_PASSSEC  socket  option  was likely a mistake, since other IP
378              control messages use their own numbering scheme in the IP  name‐
379              space and often use the socket option value as the message type.
380              There is no conflict currently since the IP option with the same
381              value as SCM_SECURITY is IP_HDRINCL and this is never used for a
382              control message type.
383
384       IP_PKTINFO (since Linux 2.2)
385              Pass an IP_PKTINFO ancillary message  that  contains  a  pktinfo
386              structure  that  supplies  some  information  about the incoming
387              packet.  This works only for datagram oriented sockets.  The ar‐
388              gument  is  a  flag that tells the socket whether the IP_PKTINFO
389              message should be passed or not.   The  message  itself  can  be
390              sent/retrieved  only  as  a  control message with a packet using
391              recvmsg(2) or sendmsg(2).
392
393                  struct in_pktinfo {
394                      unsigned int   ipi_ifindex;  /* Interface index */
395                      struct in_addr ipi_spec_dst; /* Local address */
396                      struct in_addr ipi_addr;     /* Header Destination
397                                                      address */
398                  };
399
400              ipi_ifindex is the unique index of the interface the packet  was
401              received  on.   ipi_spec_dst  is the local address of the packet
402              and ipi_addr is the destination address in  the  packet  header.
403              If  IP_PKTINFO  is  passed to sendmsg(2) and ipi_spec_dst is not
404              zero, then it is used as the local source address for the  rout‐
405              ing  table  lookup  and  for setting up IP source route options.
406              When ipi_ifindex is not zero, the primary local address  of  the
407              interface specified by the index overwrites ipi_spec_dst for the
408              routing table lookup.
409
410       IP_RECVERR (since Linux 2.2)
411              Enable extended reliable error message passing.  When enabled on
412              a datagram socket, all generated errors will be queued in a per-
413              socket error queue.  When the user  receives  an  error  from  a
414              socket   operation,  the  errors  can  be  received  by  calling
415              recvmsg(2)  with  the  MSG_ERRQUEUE  flag  set.   The   sock_ex‐
416              tended_err  structure  describing the error will be passed in an
417              ancillary message with the type IP_RECVERR  and  the  level  IP‐
418              PROTO_IP.   This is useful for reliable error handling on uncon‐
419              nected sockets.  The received data portion of  the  error  queue
420              contains the error packet.
421
422              The  IP_RECVERR  control  message  contains  a sock_extended_err
423              structure:
424
425                  #define SO_EE_ORIGIN_NONE    0
426                  #define SO_EE_ORIGIN_LOCAL   1
427                  #define SO_EE_ORIGIN_ICMP    2
428                  #define SO_EE_ORIGIN_ICMP6   3
429
430                  struct sock_extended_err {
431                      uint32_t ee_errno;   /* error number */
432                      uint8_t  ee_origin;  /* where the error originated */
433                      uint8_t  ee_type;    /* type */
434                      uint8_t  ee_code;    /* code */
435                      uint8_t  ee_pad;
436                      uint32_t ee_info;    /* additional information */
437                      uint32_t ee_data;    /* other data */
438                      /* More data may follow */
439                  };
440
441                  struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
442
443              ee_errno contains the errno number of the queued error.  ee_ori‐
444              gin is the origin code of where the error originated.  The other
445              fields are protocol-specific.  The macro SO_EE_OFFENDER  returns
446              a  pointer  to the address of the network object where the error
447              originated from given a pointer to the  ancillary  message.   If
448              this  address is not known, the sa_family member of the sockaddr
449              contains AF_UNSPEC and the other fields of the sockaddr are  un‐
450              defined.
451
452              IP uses the sock_extended_err structure as follows: ee_origin is
453              set to SO_EE_ORIGIN_ICMP for errors received as an ICMP  packet,
454              or  SO_EE_ORIGIN_LOCAL  for  locally  generated errors.  Unknown
455              values should be ignored.  ee_type and ee_code are set from  the
456              type  and  code fields of the ICMP header.  ee_info contains the
457              discovered MTU for EMSGSIZE errors.  The message  also  contains
458              the  sockaddr_in  of the node caused the error, which can be ac‐
459              cessed with the SO_EE_OFFENDER macro.  The sin_family  field  of
460              the  SO_EE_OFFENDER address is AF_UNSPEC when the source was un‐
461              known.  When the error originated from the network, all  IP  op‐
462              tions  (IP_OPTIONS, IP_TTL, etc.) enabled on the socket and con‐
463              tained in the error packet are passed as control messages.   The
464              payload  of  the  packet causing the error is returned as normal
465              payload.  Note that TCP has no error queue; MSG_ERRQUEUE is  not
466              permitted  on SOCK_STREAM sockets.  IP_RECVERR is valid for TCP,
467              but all errors are returned by socket function return or  SO_ER‐
468              ROR only.
469
470              For raw sockets, IP_RECVERR enables passing of all received ICMP
471              errors to the application, otherwise errors are reported only on
472              connected sockets
473
474              It  sets  or  retrieves an integer boolean flag.  IP_RECVERR de‐
475              faults to off.
476
477       IP_RECVOPTS (since Linux 2.2)
478              Pass all incoming IP options to the user in a IP_OPTIONS control
479              message.   The  routing  header  and  other  options are already
480              filled in for the local host.   Not  supported  for  SOCK_STREAM
481              sockets.
482
483       IP_RECVORIGDSTADDR (since Linux 2.6.29)
484              This boolean option enables the IP_ORIGDSTADDR ancillary message
485              in recvmsg(2), in which the kernel returns the original destina‐
486              tion address of the datagram being received.  The ancillary mes‐
487              sage contains a struct sockaddr_in.
488
489       IP_RECVTOS (since Linux 2.2)
490              If enabled, the IP_TOS ancillary message is passed with incoming
491              packets.   It  contains  a byte which specifies the Type of Ser‐
492              vice/Precedence field of the packet header.  Expects  a  boolean
493              integer flag.
494
495       IP_RECVTTL (since Linux 2.2)
496              When  this  flag  is set, pass a IP_TTL control message with the
497              time-to-live field of the received packet as a 32  bit  integer.
498              Not supported for SOCK_STREAM sockets.
499
500       IP_RETOPTS (since Linux 2.2)
501              Identical  to  IP_RECVOPTS,  but returns raw unprocessed options
502              with timestamp and route record options not filled in  for  this
503              hop.
504
505       IP_ROUTER_ALERT (since Linux 2.2)
506              Pass all to-be forwarded packets with the IP Router Alert option
507              set to this socket.  Valid only for raw sockets.  This  is  use‐
508              ful,  for  instance,  for  user-space  RSVP daemons.  The tapped
509              packets are not forwarded by the kernel; it is  the  user's  re‐
510              sponsibility to send them out again.  Socket binding is ignored,
511              such packets are filtered only by protocol.  Expects an  integer
512              flag.
513
514       IP_TOS (since Linux 1.0)
515              Set or receive the Type-Of-Service (TOS) field that is sent with
516              every IP packet originating from this socket.   It  is  used  to
517              prioritize  packets  on  the network.  TOS is a byte.  There are
518              some standard TOS flags defined: IPTOS_LOWDELAY to minimize  de‐
519              lays  for  interactive  traffic,  IPTOS_THROUGHPUT  to  optimize
520              throughput, IPTOS_RELIABILITY to optimize for  reliability,  IP‐
521              TOS_MINCOST  should  be used for "filler data" where slow trans‐
522              mission doesn't matter.  At most one of these TOS values can  be
523              specified.   Other bits are invalid and shall be cleared.  Linux
524              sends IPTOS_LOWDELAY datagrams first by default, but  the  exact
525              behavior  depends  on  the configured queueing discipline.  Some
526              high-priority  levels  may  require  superuser  privileges  (the
527              CAP_NET_ADMIN capability).
528
529       IP_TRANSPARENT (since Linux 2.6.24)
530              Setting this boolean option enables transparent proxying on this
531              socket.  This socket option allows the  calling  application  to
532              bind to a nonlocal IP address and operate both as a client and a
533              server with the foreign address as the  local  endpoint.   NOTE:
534              this requires that routing be set up in a way that packets going
535              to the foreign address are routed through the TProxy box  (i.e.,
536              the system hosting the application that employs the IP_TRANSPAR‐
537              ENT socket option).  Enabling this socket option requires  supe‐
538              ruser privileges (the CAP_NET_ADMIN capability).
539
540              TProxy redirection with the iptables TPROXY target also requires
541              that this option be set on the redirected socket.
542
543       IP_TTL (since Linux 1.0)
544              Set or retrieve the current time-to-live field that is  used  in
545              every packet sent from this socket.
546
547       IP_UNBLOCK_SOURCE (since Linux 2.4.22 / 2.5.68)
548              Unblock  previously  blocked multicast source.  Returns EADDRNO‐
549              TAVAIL when given source is not being blocked.
550
551              Argument is  an  ip_mreq_source  structure  as  described  under
552              IP_ADD_SOURCE_MEMBERSHIP.
553
554       SO_PEERSEC (since Linux 2.6.17)
555              If  labeled  IPSEC or NetLabel is configured on both the sending
556              and receiving hosts, this read-only socket  option  returns  the
557              security  context  of  the peer socket connected to this socket.
558              By default, this will be the same as the security context of the
559              process  that  created  the peer socket unless overridden by the
560              policy or by a process with the required permissions.
561
562              The argument to getsockopt(2) is a pointer to a  buffer  of  the
563              specified length in bytes into which the security context string
564              will be copied.  If the buffer length is less than the length of
565              the security context string, then getsockopt(2) returns -1, sets
566              errno to ERANGE, and returns the  required  length  via  optlen.
567              The  caller should allocate at least NAME_MAX bytes for the buf‐
568              fer initially, although this is not guaranteed to be sufficient.
569              Resizing  the  buffer to the returned length and retrying may be
570              necessary.
571
572              The security context string may include a terminating null char‐
573              acter  in the returned length, but is not guaranteed to do so: a
574              security  context  "foo"  might   be   represented   as   either
575              {'f','o','o'}  of  length  3  or {'f','o','o','\0'} of length 4,
576              which are considered  to  be  interchangeable.   The  string  is
577              printable, does not contain non-terminating null characters, and
578              is in an unspecified encoding (in particular, it is not  guaran‐
579              teed to be ASCII or UTF-8).
580
581              The use of this option for sockets in the AF_INET address family
582              is supported since Linux 2.6.17 for TCP sockets, and since Linux
583              4.17 for SCTP sockets.
584
585              For  SELinux, NetLabel conveys only the MLS portion of the secu‐
586              rity context of the peer across the wire, defaulting the rest of
587              the security context to the values defined in the policy for the
588              netmsg initial security identifier (SID).  However, NetLabel can
589              be configured to pass full security contexts over loopback.  La‐
590              beled IPSEC always passes full security contexts as part of  es‐
591              tablishing the security association (SA) and looks them up based
592              on the association for each packet.
593
594   /proc interfaces
595       The IP protocol supports a set of /proc interfaces  to  configure  some
596       global  parameters.  The parameters can be accessed by reading or writ‐
597       ing files in the directory /proc/sys/net/ipv4/.   Interfaces  described
598       as Boolean take an integer value, with a nonzero value ("true") meaning
599       that the corresponding option is enabled, and a  zero  value  ("false")
600       meaning that the option is disabled.
601
602       ip_always_defrag (Boolean; since Linux 2.2.13)
603              [New with kernel 2.2.13; in earlier kernel versions this feature
604              was controlled at compile time  by  the  CONFIG_IP_ALWAYS_DEFRAG
605              option; this option is not present in 2.4.x and later]
606
607              When  this boolean flag is enabled (not equal 0), incoming frag‐
608              ments (parts of IP packets that arose  when  some  host  between
609              origin  and  destination decided that the packets were too large
610              and cut them into pieces) will be reassembled (defragmented) be‐
611              fore being processed, even if they are about to be forwarded.
612
613              Enable  only  if running either a firewall that is the sole link
614              to your network or a transparent proxy; never ever use it for  a
615              normal  router or host.  Otherwise, fragmented communication can
616              be disturbed if the fragments travel over different links.   De‐
617              fragmentation also has a large memory and CPU time cost.
618
619              This is automagically turned on when masquerading or transparent
620              proxying are configured.
621
622       ip_autoconfig (since Linux 2.2 to 2.6.17)
623              Not documented.
624
625       ip_default_ttl (integer; default: 64; since Linux 2.2)
626              Set the default time-to-live value of  outgoing  packets.   This
627              can be changed per socket with the IP_TTL option.
628
629       ip_dynaddr (Boolean; default: disabled; since Linux 2.0.31)
630              Enable  dynamic  socket address and masquerading entry rewriting
631              on interface address change.  This is useful for  dialup  inter‐
632              face  with changing IP addresses.  0 means no rewriting, 1 turns
633              it on and 2 enables verbose mode.
634
635       ip_forward (Boolean; default: disabled; since Linux 1.2)
636              Enable IP forwarding with a boolean flag.  IP forwarding can  be
637              also set on a per-interface basis.
638
639       ip_local_port_range (since Linux 2.2)
640              This  file  contains  two integers that define the default local
641              port range allocated to sockets that are not explicitly bound to
642              a  port  number—that is, the range used for ephemeral ports.  An
643              ephemeral port is allocated to a socket in the following circum‐
644              stances:
645
646              *  the  port  number  in a socket address is specified as 0 when
647                 calling bind(2);
648
649              *  listen(2) is called on a stream socket that  was  not  previ‐
650                 ously bound;
651
652              *  connect(2)  was  called  on  a socket that was not previously
653                 bound;
654
655              *  sendto(2) is called on a datagram socket that was not  previ‐
656                 ously bound.
657
658              Allocation  of  ephemeral  ports starts with the first number in
659              ip_local_port_range and ends with the  second  number.   If  the
660              range  of ephemeral ports is exhausted, then the relevant system
661              call returns an error (but see BUGS).
662
663              Note that the port range in ip_local_port_range should not  con‐
664              flict  with the ports used by masquerading (although the case is
665              handled).  Also, arbitrary choices may cause problems with  some
666              firewall  packet  filters  that make assumptions about the local
667              ports in use.  The first number should be at least greater  than
668              1024,  or  better, greater than 4096, to avoid clashes with well
669              known ports and to minimize firewall problems.
670
671       ip_no_pmtu_disc (Boolean; default: disabled; since Linux 2.2)
672              If enabled, don't do Path MTU Discovery for TCP sockets  by  de‐
673              fault.   Path  MTU discovery may fail if misconfigured firewalls
674              (that drop all ICMP packets) or misconfigured interfaces  (e.g.,
675              a  point-to-point  link  where  the both ends don't agree on the
676              MTU) are on the path.  It is better to fix the broken routers on
677              the  path  than to turn off Path MTU Discovery globally, because
678              not doing it incurs a high cost to the network.
679
680       ip_nonlocal_bind (Boolean; default: disabled; since Linux 2.4)
681              If set, allows processes to bind(2) to  nonlocal  IP  addresses,
682              which can be quite useful, but may break some applications.
683
684       ip6frag_time (integer; default: 30)
685              Time in seconds to keep an IPv6 fragment in memory.
686
687       ip6frag_secret_interval (integer; default: 600)
688              Regeneration  interval (in seconds) of the hash secret (or life‐
689              time for the hash secret) for IPv6 fragments.
690
691       ipfrag_high_thresh (integer), ipfrag_low_thresh (integer)
692              If the amount of queued IP fragments reaches ipfrag_high_thresh,
693              the  queue is pruned down to ipfrag_low_thresh.  Contains an in‐
694              teger with the number of bytes.
695
696       neigh/*
697              See arp(7).
698
699   Ioctls
700       All ioctls described in socket(7) apply to ip.
701
702       Ioctls to configure generic device parameters are described  in  netde‐
703       vice(7).
704

ERRORS

706       EACCES The  user  tried  to  execute an operation without the necessary
707              permissions.  These include: sending a packet to a broadcast ad‐
708              dress without having the SO_BROADCAST flag set; sending a packet
709              via a prohibit route; modifying firewall settings without  supe‐
710              ruser  privileges  (the  CAP_NET_ADMIN capability); binding to a
711              privileged    port    without    superuser    privileges    (the
712              CAP_NET_BIND_SERVICE capability).
713
714       EADDRINUSE
715              Tried to bind to an address already in use.
716
717       EADDRNOTAVAIL
718              A  nonexistent  interface  was requested or the requested source
719              address was not local.
720
721       EAGAIN Operation on a nonblocking socket would block.
722
723       EALREADY
724              A connection operation on a nonblocking  socket  is  already  in
725              progress.
726
727       ECONNABORTED
728              A connection was closed during an accept(2).
729
730       EHOSTUNREACH
731              No  valid  routing  table entry matches the destination address.
732              This error can be caused by an ICMP message from a remote router
733              or for the local routing table.
734
735       EINVAL Invalid argument passed.  For send operations this can be caused
736              by sending to a blackhole route.
737
738       EISCONN
739              connect(2) was called on an already connected socket.
740
741       EMSGSIZE
742              Datagram is bigger than an MTU on the  path  and  it  cannot  be
743              fragmented.
744
745       ENOBUFS, ENOMEM
746              Not  enough free memory.  This often means that the memory allo‐
747              cation is limited by the socket buffer limits, not by the system
748              memory, but this is not 100% consistent.
749
750       ENOENT SIOCGSTAMP was called on a socket where no packet arrived.
751
752       ENOPKG A kernel subsystem was not configured.
753
754       ENOPROTOOPT and EOPNOTSUPP
755              Invalid socket option passed.
756
757       ENOTCONN
758              The  operation  is  defined  only on a connected socket, but the
759              socket wasn't connected.
760
761       EPERM  User doesn't have permission to set high priority,  change  con‐
762              figuration, or send signals to the requested process or group.
763
764       EPIPE  The connection was unexpectedly closed or shut down by the other
765              end.
766
767       ESOCKTNOSUPPORT
768              The socket is not configured or an unknown socket type  was  re‐
769              quested.
770
771       Other  errors may be generated by the overlaying protocols; see tcp(7),
772       raw(7), udp(7), and socket(7).
773

NOTES

775       IP_FREEBIND, IP_MSFILTER, IP_MTU, IP_MTU_DISCOVER,  IP_RECVORIGDSTADDR,
776       IP_PASSSEC, IP_PKTINFO, IP_RECVERR, IP_ROUTER_ALERT, and IP_TRANSPARENT
777       are Linux-specific.
778
779       Be very careful with the SO_BROADCAST option - it is not privileged  in
780       Linux.   It  is  easy to overload the network with careless broadcasts.
781       For new application protocols it is better to use a multicast group in‐
782       stead of broadcasting.  Broadcasting is discouraged.
783
784       Some  other  BSD  sockets  implementations  provide  IP_RCVDSTADDR  and
785       IP_RECVIF socket options to get the destination address and the  inter‐
786       face  of received datagrams.  Linux has the more general IP_PKTINFO for
787       the same task.
788
789       Some BSD sockets implementations also provide an IP_RECVTTL option, but
790       an  ancillary  message with type IP_RECVTTL is passed with the incoming
791       packet.  This is different from the IP_TTL option used in Linux.
792
793       Using the SOL_IP socket options level isn't portable; BSD-based  stacks
794       use the IPPROTO_IP level.
795
796       INADDR_ANY  (0.0.0.0)  and INADDR_BROADCAST (255.255.255.255) are byte-
797       order-neutral.
798        This means htonl(3) has no effect on them.
799
800   Compatibility
801       For  compatibility  with  Linux  2.0,  the   obsolete   socket(AF_INET,
802       SOCK_PACKET,  protocol)  syntax  is still supported to open a packet(7)
803       socket.  This is deprecated and should be replaced by socket(AF_PACKET,
804       SOCK_RAW,  protocol)  instead.   The  main  difference is the new sock‐
805       addr_ll address structure for generic link layer information instead of
806       the old sockaddr_pkt.
807

BUGS

809       There are too many inconsistent error values.
810
811       The  error used to diagnose exhaustion of the ephemeral port range dif‐
812       fers across the various system calls (connect(2),  bind(2),  listen(2),
813       sendto(2)) that can assign ephemeral ports.
814
815       The  ioctls  to  configure IP-specific interface options and ARP tables
816       are not described.
817
818       Receiving  the  original  destination  address  with  MSG_ERRQUEUE   in
819       msg_name by recvmsg(2) does not work in some 2.2 kernels.
820

SEE ALSO

822       recvmsg(2),   sendmsg(2),   byteorder(3),   capabilities(7),   icmp(7),
823       ipv6(7), netdevice(7), netlink(7), raw(7), socket(7),  tcp(7),  udp(7),
824       ip(8)
825
826       The kernel source file Documentation/networking/ip-sysctl.txt.
827
828       RFC 791  for the original IP specification.  RFC 1122 for the IPv4 host
829       requirements.  RFC 1812 for the IPv4 router requirements.
830

COLOPHON

832       This page is part of release 5.13 of the Linux  man-pages  project.   A
833       description  of  the project, information about reporting bugs, and the
834       latest    version    of    this    page,    can     be     found     at
835       https://www.kernel.org/doc/man-pages/.
836
837
838
839Linux                             2021-03-22                             IP(7)
Impressum