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

ERRORS

634       EACCES The  user  tried  to  execute an operation without the necessary
635              permissions.  These include: sending a  packet  to  a  broadcast
636              address  without  having  the  SO_BROADCAST  flag set; sending a
637              packet via a prohibit route; modifying firewall settings without
638              superuser  privileges (the CAP_NET_ADMIN capability); binding to
639              a   privileged   port   without   superuser   privileges    (the
640              CAP_NET_BIND_SERVICE capability).
641
642       EADDRINUSE
643              Tried to bind to an address already in use.
644
645       EADDRNOTAVAIL
646              A  nonexistent  interface  was requested or the requested source
647              address was not local.
648
649       EAGAIN Operation on a nonblocking socket would block.
650
651       EALREADY
652              A connection operation on a nonblocking  socket  is  already  in
653              progress.
654
655       ECONNABORTED
656              A connection was closed during an accept(2).
657
658       EHOSTUNREACH
659              No  valid  routing  table entry matches the destination address.
660              This error can be caused by an ICMP message from a remote router
661              or for the local routing table.
662
663       EINVAL Invalid argument passed.  For send operations this can be caused
664              by sending to a blackhole route.
665
666       EISCONN
667              connect(2) was called on an already connected socket.
668
669       EMSGSIZE
670              Datagram is bigger than an MTU on the  path  and  it  cannot  be
671              fragmented.
672
673       ENOBUFS, ENOMEM
674              Not  enough free memory.  This often means that the memory allo‐
675              cation is limited by the socket buffer limits, not by the system
676              memory, but this is not 100% consistent.
677
678       ENOENT SIOCGSTAMP was called on a socket where no packet arrived.
679
680       ENOPKG A kernel subsystem was not configured.
681
682       ENOPROTOOPT and EOPNOTSUPP
683              Invalid socket option passed.
684
685       ENOTCONN
686              The  operation  is  defined  only on a connected socket, but the
687              socket wasn't connected.
688
689       EPERM  User doesn't have permission to set high priority,  change  con‐
690              figuration, or send signals to the requested process or group.
691
692       EPIPE  The connection was unexpectedly closed or shut down by the other
693              end.
694
695       ESOCKTNOSUPPORT
696              The socket is not configured  or  an  unknown  socket  type  was
697              requested.
698
699       Other  errors may be generated by the overlaying protocols; see tcp(7),
700       raw(7), udp(7), and socket(7).
701

NOTES

703       IP_FREEBIND, IP_MSFILTER, IP_MTU, IP_MTU_DISCOVER,  IP_RECVORIGDSTADDR,
704       IP_PKTINFO,  IP_RECVERR, IP_ROUTER_ALERT, and IP_TRANSPARENT are Linux-
705       specific.
706
707       Be very careful with the SO_BROADCAST option - it is not privileged  in
708       Linux.   It  is  easy to overload the network with careless broadcasts.
709       For new application protocols it is better to  use  a  multicast  group
710       instead of broadcasting.  Broadcasting is discouraged.
711
712       Some  other  BSD  sockets  implementations  provide  IP_RCVDSTADDR  and
713       IP_RECVIF socket options to get the destination address and the  inter‐
714       face  of received datagrams.  Linux has the more general IP_PKTINFO for
715       the same task.
716
717       Some BSD sockets implementations also provide an IP_RECVTTL option, but
718       an  ancillary  message with type IP_RECVTTL is passed with the incoming
719       packet.  This is different from the IP_TTL option used in Linux.
720
721       Using the SOL_IP socket options level isn't portable; BSD-based  stacks
722       use the IPPROTO_IP level.
723
724       INADDR_ANY  (0.0.0.0)  and INADDR_BROADCAST (255.255.255.255) are byte-
725       order-neutral.
726        This means htonl(3) has no effect on them.
727
728   Compatibility
729       For  compatibility  with  Linux  2.0,  the   obsolete   socket(AF_INET,
730       SOCK_PACKET,  protocol)  syntax  is still supported to open a packet(7)
731       socket.  This is deprecated and should be replaced by socket(AF_PACKET,
732       SOCK_RAW,  protocol)  instead.   The  main  difference is the new sock‐
733       addr_ll address structure for generic link layer information instead of
734       the old sockaddr_pkt.
735

BUGS

737       There are too many inconsistent error values.
738
739       The  error used to diagnose exhaustion of the ephemeral port range dif‐
740       fers across the various system calls (connect(2),  bind(2),  listen(2),
741       sendto(2)) that can assign ephemeral ports.
742
743       The  ioctls  to  configure IP-specific interface options and ARP tables
744       are not described.
745
746       Receiving  the  original  destination  address  with  MSG_ERRQUEUE   in
747       msg_name by recvmsg(2) does not work in some 2.2 kernels.
748

SEE ALSO

750       recvmsg(2),   sendmsg(2),   byteorder(3),   ipfw(4),   capabilities(7),
751       icmp(7), ipv6(7), netlink(7), raw(7), socket(7), tcp(7), udp(7), ip(8)
752
753       RFC 791 for the original IP specification.  RFC 1122 for the IPv4  host
754       requirements.  RFC 1812 for the IPv4 router requirements.
755

COLOPHON

757       This  page  is  part of release 4.16 of the Linux man-pages project.  A
758       description of the project, information about reporting bugs,  and  the
759       latest     version     of     this    page,    can    be    found    at
760       https://www.kernel.org/doc/man-pages/.
761
762
763
764Linux                             2018-02-02                             IP(7)
Impressum