{ "content": [ { "type": "text", "text": "# ip(7) (man)\n\n## TLDR\n\n> Show/manipulate routing, devices, policy routing and tunnels.\n\n- List interfaces with detailed info:\n `ip {{a|address}}`\n- List interfaces with brief network layer info:\n `ip {{-br|-brief}} {{a|address}}`\n- List interfaces with brief link layer info:\n `ip {{-br|-brief}} {{l|link}}`\n- Display the routing table:\n `ip {{r|route}}`\n- Show neighbors (ARP table):\n `ip {{n|neighbour}}`\n- Make an interface up/down:\n `sudo ip {{l|link}} {{s|set}} {{ethX}} {{up|down}}`\n- Add/Delete an IP address to an interface:\n `sudo ip {{a|address}} {{add|delete}} {{ip_address}}/{{mask}} dev {{ethX}}`\n- Add a default route:\n `sudo ip {{r|route}} {{a|add}} default via {{ip_address}} dev {{ethX}}`\n\n*Source: tldr-pages*\n\n---\n\n**Summary:** ip - Linux IPv4 protocol implementation\n\n## See Also\n\n- recvmsg(2)\n- sendmsg(2)\n- byteorder(3)\n- capabilities(7)\n- icmp(7)\n- ipv6(7)\n- netdevice(7)\n- netlink(7)\n- raw(7)\n- socket(7)\n- tcp(7)\n- udp(7)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (1 lines) — 2 subsections\n - #include (1 lines)\n - #include (6 lines)\n- **DESCRIPTION** (39 lines) — 4 subsections\n - Address format (43 lines)\n - Socket options (398 lines)\n - /proc interfaces (90 lines)\n - Ioctls (4 lines)\n- **ERRORS** (58 lines)\n- **NOTES** (21 lines) — 1 subsections\n - Compatibility (5 lines)\n- **BUGS** (10 lines)\n- **SEE ALSO** (8 lines)\n- **COLOPHON** (7 lines)\n\n## Full Content\n\n### NAME\n\nip - Linux IPv4 protocol implementation\n\n### SYNOPSIS\n\n#### #include \n\n#### #include \n\n#include /* superset of previous */\n\ntcpsocket = socket(AFINET, SOCKSTREAM, 0);\nudpsocket = socket(AFINET, SOCKDGRAM, 0);\nrawsocket = socket(AFINET, SOCKRAW, protocol);\n\n### DESCRIPTION\n\nLinux implements the Internet Protocol, version 4, described in RFC 791 and RFC 1122. ip\ncontains a level 2 multicasting implementation conforming to RFC 1112. It also contains an\nIP router including a packet filter.\n\nThe programming interface is BSD-sockets compatible. For more information on sockets, see\nsocket(7).\n\nAn IP socket is created using socket(2):\n\nsocket(AFINET, sockettype, protocol);\n\nValid socket types include SOCKSTREAM to open a stream socket, SOCKDGRAM to open a datagram\nsocket, and SOCKRAW to open a raw(7) socket to access the IP protocol directly.\n\nprotocol is the IP protocol in the IP header to be received or sent. Valid values for proto‐\ncol include:\n\n• 0 and IPPROTOTCP for tcp(7) stream sockets;\n\n• 0 and IPPROTOUDP for udp(7) datagram sockets;\n\n• IPPROTOSCTP for sctp(7) stream sockets; and\n\n• IPPROTOUDPLITE for udplite(7) datagram sockets.\n\nFor SOCKRAW you may specify a valid IANA IP protocol defined in RFC 1700 assigned numbers.\n\nWhen a process wants to receive new incoming packets or connections, it should bind a socket\nto a local interface address using bind(2). In this case, only one IP socket may be bound to\nany given local (address, port) pair. When INADDRANY is specified in the bind call, the\nsocket will be bound to all local interfaces. When listen(2) is called on an unbound socket,\nthe socket is automatically bound to a random free port with the local address set to IN‐‐\nADDRANY. When connect(2) is called on an unbound socket, the socket is automatically bound\nto a random free port or to a usable shared port with the local address set to INADDRANY.\n\nA TCP local socket address that has been bound is unavailable for some time after closing,\nunless the SOREUSEADDR flag has been set. Care should be taken when using this flag as it\nmakes TCP less reliable.\n\n#### Address format\n\nAn IP socket address is defined as a combination of an IP interface address and a 16-bit port\nnumber. The basic IP protocol does not supply port numbers, they are implemented by higher\nlevel protocols like udp(7) and tcp(7). On raw sockets sinport is set to the IP protocol.\n\nstruct sockaddrin {\nsafamilyt sinfamily; /* address family: AFINET */\ninportt sinport; /* port in network byte order */\nstruct inaddr sinaddr; /* internet address */\n};\n\n/* Internet address. */\nstruct inaddr {\nuint32t saddr; /* address in network byte order */\n};\n\nsinfamily is always set to AFINET. This is required; in Linux 2.2 most networking func‐\ntions return EINVAL when this setting is missing. sinport contains the port in network byte\norder. The port numbers below 1024 are called privileged ports (or sometimes: reserved\nports). Only a privileged process (on Linux: a process that has the CAPNETBINDSERVICE ca‐\npability in the user namespace governing its network namespace) may bind(2) to these sockets.\nNote that the raw IPv4 protocol as such has no concept of a port, they are implemented only\nby higher protocols like tcp(7) and udp(7).\n\nsinaddr is the IP host address. The saddr member of struct inaddr contains the host in‐\nterface address in network byte order. inaddr should be assigned one of the INADDR* values\n(e.g., INADDRLOOPBACK) using htonl(3) or set using the inetaton(3), inetaddr(3),\ninetmakeaddr(3) library functions or directly with the name resolver (see gethostbyname(3)).\n\nIPv4 addresses are divided into unicast, broadcast, and multicast addresses. Unicast ad‐\ndresses specify a single interface of a host, broadcast addresses specify all hosts on a net‐\nwork, and multicast addresses address all hosts in a multicast group. Datagrams to broadcast\naddresses can be sent or received only when the SOBROADCAST socket flag is set. In the cur‐\nrent implementation, connection-oriented sockets are allowed to use only unicast addresses.\n\nNote that the address and the port are always stored in network byte order. In particular,\nthis means that you need to call htons(3) on the number that is assigned to a port. All ad‐\ndress/port manipulation functions in the standard library work in network byte order.\n\nThere are several special addresses: INADDRLOOPBACK (127.0.0.1) always refers to the local\nhost via the loopback device; INADDRANY (0.0.0.0) means any address for binding; IN‐‐\nADDRBROADCAST (255.255.255.255) means any host and has the same effect on bind as INADDRANY\nfor historical reasons.\n\n#### Socket options\n\nIP supports some protocol-specific socket options that can be set with setsockopt(2) and read\nwith getsockopt(2). The socket option level for IP is IPPROTOIP. A boolean integer flag is\nzero when it is false, otherwise true.\n\nWhen an invalid socket option is specified, getsockopt(2) and setsockopt(2) fail with the er‐\nror ENOPROTOOPT.\n\nIPADDMEMBERSHIP (since Linux 1.2)\nJoin a multicast group. Argument is an ipmreqn structure.\n\nstruct ipmreqn {\nstruct inaddr imrmultiaddr; /* IP multicast group\naddress */\nstruct inaddr imraddress; /* IP address of local\ninterface */\nint imrifindex; /* interface index */\n};\n\nimrmultiaddr contains the address of the multicast group the application wants to join or\nleave. It must be a valid multicast address (or setsockopt(2) fails with the error EINVAL).\nimraddress is the address of the local interface with which the system should join the mul‐\nticast group; if it is equal to INADDRANY, an appropriate interface is chosen by the system.\nimrifindex is the interface index of the interface that should join/leave the imrmultiaddr\ngroup, or 0 to indicate any interface.\n\nThe ipmreqn structure is available only since Linux 2.2. For compatibility, the old\nipmreq structure (present since Linux 1.2) is still supported; it differs from\nipmreqn only by not including the imrifindex field. (The kernel determines which\nstructure is being passed based on the size passed in optlen.)\n\nIPADDMEMBERSHIP is valid only for setsockopt(2).\n\nIPADDSOURCEMEMBERSHIP (since Linux 2.4.22 / 2.5.68)\nJoin a multicast group and allow receiving data only from a specified source. Argu‐\nment is an ipmreqsource structure.\n\nstruct ipmreqsource {\nstruct inaddr imrmultiaddr; /* IP multicast group\naddress */\nstruct inaddr imrinterface; /* IP address of local\ninterface */\nstruct inaddr imrsourceaddr; /* IP address of\nmulticast source */\n};\n\nThe ipmreqsource structure is similar to ipmreqn described under IPADDMEMBERSHIP. The\nimrmultiaddr field contains the address of the multicast group the application wants to join\nor leave. The imrinterface field is the address of the local interface with which the sys‐\ntem should join the multicast group. Finally, the imrsourceaddr field contains the address\nof the source the application wants to receive data from.\n\nThis option can be used multiple times to allow receiving data from more than one\nsource.\n\nIPBINDADDRESSNOPORT (since Linux 4.2)\nInform the kernel to not reserve an ephemeral port when using bind(2) with a port num‐\nber of 0. The port will later be automatically chosen at connect(2) time, in a way\nthat allows sharing a source port as long as the 4-tuple is unique.\n\nIPBLOCKSOURCE (since Linux 2.4.22 / 2.5.68)\nStop receiving multicast data from a specific source in a given group. This is valid\nonly after the application has subscribed to the multicast group using either\nIPADDMEMBERSHIP or IPADDSOURCEMEMBERSHIP.\n\nArgument is an ipmreqsource structure as described under IPADDSOURCEMEMBERSHIP.\n\nIPDROPMEMBERSHIP (since Linux 1.2)\nLeave a multicast group. Argument is an ipmreqn or ipmreq structure similar to\nIPADDMEMBERSHIP.\n\nIPDROPSOURCEMEMBERSHIP (since Linux 2.4.22 / 2.5.68)\nLeave a source-specific group—that is, stop receiving data from a given multicast\ngroup that come from a given source. If the application has subscribed to multiple\nsources within the same group, data from the remaining sources will still be deliv‐\nered. To stop receiving data from all sources at once, use IPDROPMEMBERSHIP.\n\nArgument is an ipmreqsource structure as described under IPADDSOURCEMEMBERSHIP.\n\nIPFREEBIND (since Linux 2.4)\nIf enabled, this boolean option allows binding to an IP address that is nonlocal or\ndoes not (yet) exist. This permits listening on a socket, without requiring the un‐\nderlying network interface or the specified dynamic IP address to be up at the time\nthat the application is trying to bind to it. This option is the per-socket equiva‐\nlent of the ipnonlocalbind /proc interface described below.\n\nIPHDRINCL (since Linux 2.0)\nIf enabled, the user supplies an IP header in front of the user data. Valid only for\nSOCKRAW sockets; see raw(7) for more information. When this flag is enabled, the\nvalues set by IPOPTIONS, IPTTL, and IPTOS are ignored.\n\nIPMSFILTER (since Linux 2.4.22 / 2.5.68)\nThis option provides access to the advanced full-state filtering API. Argument is an\nipmsfilter structure.\n\nstruct ipmsfilter {\nstruct inaddr imsfmultiaddr; /* IP multicast group\naddress */\nstruct inaddr imsfinterface; /* IP address of local\ninterface */\nuint32t imsffmode; /* Filter-mode */\n\nuint32t imsfnumsrc; /* Number of sources in\nthe following array */\nstruct inaddr imsfslist[1]; /* Array of source\naddresses */\n};\n\nThere are two macros, MCASTINCLUDE and MCASTEXCLUDE, which can be used to specify the fil‐\ntering mode. Additionally, the IPMSFILTERSIZE(n) macro exists to determine how much memory\nis needed to store ipmsfilter structure with n sources in the source list.\n\nFor the full description of multicast source filtering refer to RFC 3376.\n\nIPMTU (since Linux 2.2)\nRetrieve the current known path MTU of the current socket. Returns an integer.\n\nIPMTU is valid only for getsockopt(2) and can be employed only when the socket has\nbeen connected.\n\nIPMTUDISCOVER (since Linux 2.2)\nSet or receive the Path MTU Discovery setting for a socket. When enabled, Linux will\nperform Path MTU Discovery as defined in RFC 1191 on SOCKSTREAM sockets. For non-\nSOCKSTREAM sockets, IPPMTUDISCDO forces the don't-fragment flag to be set on all\noutgoing packets. It is the user's responsibility to packetize the data in MTU-sized\nchunks and to do the retransmits if necessary. The kernel will reject (with EMSGSIZE)\ndatagrams that are bigger than the known path MTU. IPPMTUDISCWANT will fragment a\ndatagram if needed according to the path MTU, or will set the don't-fragment flag oth‐\nerwise.\n\nThe system-wide default can be toggled between IPPMTUDISCWANT and IPPMTUDISCDONT\nby writing (respectively, zero and nonzero values) to the\n/proc/sys/net/ipv4/ipnopmtudisc file.\n\nPath MTU discovery value Meaning\nIPPMTUDISCWANT Use per-route settings.\nIPPMTUDISCDONT Never do Path MTU Discovery.\nIPPMTUDISCDO Always do Path MTU Discovery.\nIPPMTUDISCPROBE Set DF but ignore Path MTU.\n\nWhen PMTU discovery is enabled, the kernel automatically keeps track of the path MTU\nper destination host. When it is connected to a specific peer with connect(2), the\ncurrently known path MTU can be retrieved conveniently using the IPMTU socket option\n(e.g., after an EMSGSIZE error occurred). The path MTU may change over time. For\nconnectionless sockets with many destinations, the new MTU for a given destination can\nalso be accessed using the error queue (see IPRECVERR). A new error will be queued\nfor every incoming MTU update.\n\nWhile MTU discovery is in progress, initial packets from datagram sockets may be\ndropped. Applications using UDP should be aware of this and not take it into account\nfor their packet retransmit strategy.\n\nTo bootstrap the path MTU discovery process on unconnected sockets, it is possible to\nstart with a big datagram size (headers up to 64 kilobytes long) and let it shrink by\nupdates of the path MTU.\n\nTo get an initial estimate of the path MTU, connect a datagram socket to the destina‐\ntion address using connect(2) and retrieve the MTU by calling getsockopt(2) with the\nIPMTU option.\n\nIt is possible to implement RFC 4821 MTU probing with SOCKDGRAM or SOCKRAW sockets\nby setting a value of IPPMTUDISCPROBE (available since Linux 2.6.22). This is also\nparticularly useful for diagnostic tools such as tracepath(8) that wish to deliber‐\nately send probe packets larger than the observed Path MTU.\n\nIPMULTICASTALL (since Linux 2.6.31)\nThis option can be used to modify the delivery policy of multicast messages to sockets\nbound to the wildcard INADDRANY address. The argument is a boolean integer (defaults\nto 1). If set to 1, the socket will receive messages from all the groups that have\nbeen joined globally on the whole system. Otherwise, it will deliver messages only\nfrom the groups that have been explicitly joined (for example via the IPADDMEMBER‐‐\nSHIP option) on this particular socket.\n\nIPMULTICASTIF (since Linux 1.2)\nSet the local device for a multicast socket. The argument for setsockopt(2) is an\nipmreqn or (since Linux 3.5) ipmreq structure similar to IPADDMEMBERSHIP, or an\ninaddr structure. (The kernel determines which structure is being passed based on\nthe size passed in optlen.) For getsockopt(2), the argument is an inaddr structure.\n\nIPMULTICASTLOOP (since Linux 1.2)\nSet or read a boolean integer argument that determines whether sent multicast packets\nshould be looped back to the local sockets.\n\nIPMULTICASTTTL (since Linux 1.2)\nSet or read the time-to-live value of outgoing multicast packets for this socket. It\nis very important for multicast packets to set the smallest TTL possible. The default\nis 1 which means that multicast packets don't leave the local network unless the user\nprogram explicitly requests it. Argument is an integer.\n\nIPNODEFRAG (since Linux 2.6.36)\nIf enabled (argument is nonzero), the reassembly of outgoing packets is disabled in\nthe netfilter layer. The argument is an integer.\n\nThis option is valid only for SOCKRAW sockets.\n\nIPOPTIONS (since Linux 2.0)\nSet or get the IP options to be sent with every packet from this socket. The argu‐\nments are a pointer to a memory buffer containing the options and the option length.\nThe setsockopt(2) call sets the IP options associated with a socket. The maximum op‐\ntion size for IPv4 is 40 bytes. See RFC 791 for the allowed options. When the ini‐\ntial connection request packet for a SOCKSTREAM socket contains IP options, the IP\noptions will be set automatically to the options from the initial packet with routing\nheaders reversed. Incoming packets are not allowed to change options after the con‐\nnection is established. The processing of all incoming source routing options is dis‐\nabled by default and can be enabled by using the acceptsourceroute /proc interface.\nOther options like timestamps are still handled. For datagram sockets, IP options can\nbe set only by the local user. Calling getsockopt(2) with IPOPTIONS puts the current\nIP options used for sending into the supplied buffer.\n\nIPPASSSEC (since Linux 2.6.17)\nIf labeled IPSEC or NetLabel is configured on the sending and receiving hosts, this\noption enables receiving of the security context of the peer socket in an ancillary\nmessage of type SCMSECURITY retrieved using recvmsg(2). This option is supported\nonly for UDP sockets; for TCP or SCTP sockets, see the description of the SOPEERSEC\noption below.\n\nThe value given as an argument to setsockopt(2) and returned as the result of getsock‐‐\nopt(2) is an integer boolean flag.\n\nThe security context returned in the SCMSECURITY ancillary message is of the same\nformat as the one described under the SOPEERSEC option below.\n\nNote: the reuse of the SCMSECURITY message type for the IPPASSSEC socket option was\nlikely a mistake, since other IP control messages use their own numbering scheme in\nthe IP namespace and often use the socket option value as the message type. There is\nno conflict currently since the IP option with the same value as SCMSECURITY is\nIPHDRINCL and this is never used for a control message type.\n\nIPPKTINFO (since Linux 2.2)\nPass an IPPKTINFO ancillary message that contains a pktinfo structure that supplies\nsome information about the incoming packet. This works only for datagram oriented\nsockets. The argument is a flag that tells the socket whether the IPPKTINFO message\nshould be passed or not. The message itself can be sent/retrieved only as a control\nmessage with a packet using recvmsg(2) or sendmsg(2).\n\nstruct inpktinfo {\nunsigned int ipiifindex; /* Interface index */\nstruct inaddr ipispecdst; /* Local address */\nstruct inaddr ipiaddr; /* Header Destination\naddress */\n};\n\nipiifindex is the unique index of the interface the packet was received on.\nipispecdst is the local address of the packet and ipiaddr is the destination ad‐\ndress in the packet header. If IPPKTINFO is passed to sendmsg(2) and ipispecdst is\nnot zero, then it is used as the local source address for the routing table lookup and\nfor setting up IP source route options. When ipiifindex is not zero, the primary lo‐\ncal address of the interface specified by the index overwrites ipispecdst for the\nrouting table lookup.\n\nIPRECVERR (since Linux 2.2)\nEnable extended reliable error message passing. When enabled on a datagram socket,\nall generated errors will be queued in a per-socket error queue. When the user re‐\nceives an error from a socket operation, the errors can be received by calling\nrecvmsg(2) with the MSGERRQUEUE flag set. The sockextendederr structure describing\nthe error will be passed in an ancillary message with the type IPRECVERR and the\nlevel IPPROTOIP. This is useful for reliable error handling on unconnected sockets.\nThe received data portion of the error queue contains the error packet.\n\nThe IPRECVERR control message contains a sockextendederr structure:\n\n#define SOEEORIGINNONE 0\n#define SOEEORIGINLOCAL 1\n#define SOEEORIGINICMP 2\n#define SOEEORIGINICMP6 3\n\nstruct sockextendederr {\nuint32t eeerrno; /* error number */\nuint8t eeorigin; /* where the error originated */\nuint8t eetype; /* type */\nuint8t eecode; /* code */\nuint8t eepad;\nuint32t eeinfo; /* additional information */\nuint32t eedata; /* other data */\n/* More data may follow */\n};\n\nstruct sockaddr *SOEEOFFENDER(struct sockextendederr *);\n\neeerrno contains the errno number of the queued error. eeorigin is the origin code\nof where the error originated. The other fields are protocol-specific. The macro\nSOEEOFFENDER returns a pointer to the address of the network object where the error\noriginated from given a pointer to the ancillary message. If this address is not\nknown, the safamily member of the sockaddr contains AFUNSPEC and the other fields of\nthe sockaddr are undefined.\n\nIP uses the sockextendederr structure as follows: eeorigin is set to SOEEORI‐‐\nGINICMP for errors received as an ICMP packet, or SOEEORIGINLOCAL for locally gen‐\nerated errors. Unknown values should be ignored. eetype and eecode are set from\nthe type and code fields of the ICMP header. eeinfo contains the discovered MTU for\nEMSGSIZE errors. The message also contains the sockaddrin of the node caused the er‐\nror, which can be accessed with the SOEEOFFENDER macro. The sinfamily field of the\nSOEEOFFENDER address is AFUNSPEC when the source was unknown. When the error orig‐\ninated from the network, all IP options (IPOPTIONS, IPTTL, etc.) enabled on the\nsocket and contained in the error packet are passed as control messages. The payload\nof the packet causing the error is returned as normal payload. Note that TCP has no\nerror queue; MSGERRQUEUE is not permitted on SOCKSTREAM sockets. IPRECVERR is\nvalid for TCP, but all errors are returned by socket function return or SOERROR only.\n\nFor raw sockets, IPRECVERR enables passing of all received ICMP errors to the appli‐\ncation, otherwise errors are reported only on connected sockets\n\nIt sets or retrieves an integer boolean flag. IPRECVERR defaults to off.\n\nIPRECVOPTS (since Linux 2.2)\nPass all incoming IP options to the user in a IPOPTIONS control message. The routing\nheader and other options are already filled in for the local host. Not supported for\nSOCKSTREAM sockets.\n\nIPRECVORIGDSTADDR (since Linux 2.6.29)\nThis boolean option enables the IPORIGDSTADDR ancillary message in recvmsg(2), in\nwhich the kernel returns the original destination address of the datagram being re‐\nceived. The ancillary message contains a struct sockaddrin.\n\nIPRECVTOS (since Linux 2.2)\nIf enabled, the IPTOS ancillary message is passed with incoming packets. It contains\na byte which specifies the Type of Service/Precedence field of the packet header. Ex‐\npects a boolean integer flag.\n\nIPRECVTTL (since Linux 2.2)\nWhen this flag is set, pass a IPTTL control message with the time-to-live field of\nthe received packet as a 32 bit integer. Not supported for SOCKSTREAM sockets.\n\nIPRETOPTS (since Linux 2.2)\nIdentical to IPRECVOPTS, but returns raw unprocessed options with timestamp and route\nrecord options not filled in for this hop.\n\nIPROUTERALERT (since Linux 2.2)\nPass all to-be forwarded packets with the IP Router Alert option set to this socket.\nValid only for raw sockets. This is useful, for instance, for user-space RSVP dae‐\nmons. The tapped packets are not forwarded by the kernel; it is the user's responsi‐\nbility to send them out again. Socket binding is ignored, such packets are filtered\nonly by protocol. Expects an integer flag.\n\nIPTOS (since Linux 1.0)\nSet or receive the Type-Of-Service (TOS) field that is sent with every IP packet orig‐\ninating from this socket. It is used to prioritize packets on the network. TOS is a\nbyte. There are some standard TOS flags defined: IPTOSLOWDELAY to minimize delays\nfor interactive traffic, IPTOSTHROUGHPUT to optimize throughput, IPTOSRELIABILITY to\noptimize for reliability, IPTOSMINCOST should be used for \"filler data\" where slow\ntransmission doesn't matter. At most one of these TOS values can be specified. Other\nbits are invalid and shall be cleared. Linux sends IPTOSLOWDELAY datagrams first by\ndefault, but the exact behavior depends on the configured queueing discipline. Some\nhigh-priority levels may require superuser privileges (the CAPNETADMIN capability).\n\nIPTRANSPARENT (since Linux 2.6.24)\nSetting this boolean option enables transparent proxying on this socket. This socket\noption allows the calling application to bind to a nonlocal IP address and operate\nboth as a client and a server with the foreign address as the local endpoint. NOTE:\nthis requires that routing be set up in a way that packets going to the foreign ad‐\ndress are routed through the TProxy box (i.e., the system hosting the application that\nemploys the IPTRANSPARENT socket option). Enabling this socket option requires supe‐\nruser privileges (the CAPNETADMIN capability).\n\nTProxy redirection with the iptables TPROXY target also requires that this option be\nset on the redirected socket.\n\nIPTTL (since Linux 1.0)\nSet or retrieve the current time-to-live field that is used in every packet sent from\nthis socket.\n\nIPUNBLOCKSOURCE (since Linux 2.4.22 / 2.5.68)\nUnblock previously blocked multicast source. Returns EADDRNOTAVAIL when given source\nis not being blocked.\n\nArgument is an ipmreqsource structure as described under IPADDSOURCEMEMBERSHIP.\n\nSOPEERSEC (since Linux 2.6.17)\nIf labeled IPSEC or NetLabel is configured on both the sending and receiving hosts,\nthis read-only socket option returns the security context of the peer socket connected\nto this socket. By default, this will be the same as the security context of the\nprocess that created the peer socket unless overridden by the policy or by a process\nwith the required permissions.\n\nThe argument to getsockopt(2) is a pointer to a buffer of the specified length in\nbytes into which the security context string will be copied. If the buffer length is\nless than the length of the security context string, then getsockopt(2) returns -1,\nsets errno to ERANGE, and returns the required length via optlen. The caller should\nallocate at least NAMEMAX bytes for the buffer initially, although this is not guar‐\nanteed to be sufficient. Resizing the buffer to the returned length and retrying may\nbe necessary.\n\nThe security context string may include a terminating null character in the returned\nlength, but is not guaranteed to do so: a security context \"foo\" might be represented\nas either {'f','o','o'} of length 3 or {'f','o','o','\\0'} of length 4, which are con‐\nsidered to be interchangeable. The string is printable, does not contain non-termi‐\nnating null characters, and is in an unspecified encoding (in particular, it is not\nguaranteed to be ASCII or UTF-8).\n\nThe use of this option for sockets in the AFINET address family is supported since\nLinux 2.6.17 for TCP sockets, and since Linux 4.17 for SCTP sockets.\n\nFor SELinux, NetLabel conveys only the MLS portion of the security context of the peer\nacross the wire, defaulting the rest of the security context to the values defined in\nthe policy for the netmsg initial security identifier (SID). However, NetLabel can be\nconfigured to pass full security contexts over loopback. Labeled IPSEC always passes\nfull security contexts as part of establishing the security association (SA) and looks\nthem up based on the association for each packet.\n\n#### /proc interfaces\n\nThe IP protocol supports a set of /proc interfaces to configure some global parameters. The\nparameters can be accessed by reading or writing files in the directory /proc/sys/net/ipv4/.\nInterfaces described as Boolean take an integer value, with a nonzero value (\"true\") meaning\nthat the corresponding option is enabled, and a zero value (\"false\") meaning that the option\nis disabled.\n\nipalwaysdefrag (Boolean; since Linux 2.2.13)\n[New with kernel 2.2.13; in earlier kernel versions this feature was controlled at\ncompile time by the CONFIGIPALWAYSDEFRAG option; this option is not present in\n2.4.x and later]\n\nWhen this boolean flag is enabled (not equal 0), incoming fragments (parts of IP pack‐\nets that arose when some host between origin and destination decided that the packets\nwere too large and cut them into pieces) will be reassembled (defragmented) before be‐\ning processed, even if they are about to be forwarded.\n\nEnable only if running either a firewall that is the sole link to your network or a\ntransparent proxy; never ever use it for a normal router or host. Otherwise, frag‐\nmented communication can be disturbed if the fragments travel over different links.\nDefragmentation also has a large memory and CPU time cost.\n\nThis is automagically turned on when masquerading or transparent proxying are config‐\nured.\n\nipautoconfig (since Linux 2.2 to 2.6.17)\nNot documented.\n\nipdefaultttl (integer; default: 64; since Linux 2.2)\nSet the default time-to-live value of outgoing packets. This can be changed per\nsocket with the IPTTL option.\n\nipdynaddr (Boolean; default: disabled; since Linux 2.0.31)\nEnable dynamic socket address and masquerading entry rewriting on interface address\nchange. This is useful for dialup interface with changing IP addresses. 0 means no\nrewriting, 1 turns it on and 2 enables verbose mode.\n\nipforward (Boolean; default: disabled; since Linux 1.2)\nEnable IP forwarding with a boolean flag. IP forwarding can be also set on a per-in‐\nterface basis.\n\niplocalportrange (since Linux 2.2)\nThis file contains two integers that define the default local port range allocated to\nsockets that are not explicitly bound to a port number—that is, the range used for\nephemeral ports. An ephemeral port is allocated to a socket in the following circum‐\nstances:\n\n* the port number in a socket address is specified as 0 when calling bind(2);\n\n* listen(2) is called on a stream socket that was not previously bound;\n\n* connect(2) was called on a socket that was not previously bound;\n\n* sendto(2) is called on a datagram socket that was not previously bound.\n\nAllocation of ephemeral ports starts with the first number in iplocalportrange and\nends with the second number. If the range of ephemeral ports is exhausted, then the\nrelevant system call returns an error (but see BUGS).\n\nNote that the port range in iplocalportrange should not conflict with the ports\nused by masquerading (although the case is handled). Also, arbitrary choices may\ncause problems with some firewall packet filters that make assumptions about the local\nports in use. The first number should be at least greater than 1024, or better,\ngreater than 4096, to avoid clashes with well known ports and to minimize firewall\nproblems.\n\nipnopmtudisc (Boolean; default: disabled; since Linux 2.2)\nIf enabled, don't do Path MTU Discovery for TCP sockets by default. Path MTU discov‐\nery may fail if misconfigured firewalls (that drop all ICMP packets) or misconfigured\ninterfaces (e.g., a point-to-point link where the both ends don't agree on the MTU)\nare on the path. It is better to fix the broken routers on the path than to turn off\nPath MTU Discovery globally, because not doing it incurs a high cost to the network.\n\nipnonlocalbind (Boolean; default: disabled; since Linux 2.4)\nIf set, allows processes to bind(2) to nonlocal IP addresses, which can be quite use‐\nful, but may break some applications.\n\nip6fragtime (integer; default: 30)\nTime in seconds to keep an IPv6 fragment in memory.\n\nip6fragsecretinterval (integer; default: 600)\nRegeneration interval (in seconds) of the hash secret (or lifetime for the hash se‐\ncret) for IPv6 fragments.\n\nipfraghighthresh (integer), ipfraglowthresh (integer)\nIf the amount of queued IP fragments reaches ipfraghighthresh, the queue is pruned\ndown to ipfraglowthresh. Contains an integer with the number of bytes.\n\nneigh/*\nSee arp(7).\n\n#### Ioctls\n\nAll ioctls described in socket(7) apply to ip.\n\nIoctls to configure generic device parameters are described in netdevice(7).\n\n### ERRORS\n\nEACCES The user tried to execute an operation without the necessary permissions. These in‐\nclude: sending a packet to a broadcast address without having the SOBROADCAST flag\nset; sending a packet via a prohibit route; modifying firewall settings without supe‐\nruser privileges (the CAPNETADMIN capability); binding to a privileged port without\nsuperuser privileges (the CAPNETBINDSERVICE capability).\n\nEADDRINUSE\nTried to bind to an address already in use.\n\nEADDRNOTAVAIL\nA nonexistent interface was requested or the requested source address was not local.\n\nEAGAIN Operation on a nonblocking socket would block.\n\nEALREADY\nA connection operation on a nonblocking socket is already in progress.\n\nECONNABORTED\nA connection was closed during an accept(2).\n\nEHOSTUNREACH\nNo valid routing table entry matches the destination address. This error can be\ncaused by an ICMP message from a remote router or for the local routing table.\n\nEINVAL Invalid argument passed. For send operations this can be caused by sending to a\nblackhole route.\n\nEISCONN\nconnect(2) was called on an already connected socket.\n\nEMSGSIZE\nDatagram is bigger than an MTU on the path and it cannot be fragmented.\n\nENOBUFS, ENOMEM\nNot enough free memory. This often means that the memory allocation is limited by the\nsocket buffer limits, not by the system memory, but this is not 100% consistent.\n\nENOENT SIOCGSTAMP was called on a socket where no packet arrived.\n\nENOPKG A kernel subsystem was not configured.\n\nENOPROTOOPT and EOPNOTSUPP\nInvalid socket option passed.\n\nENOTCONN\nThe operation is defined only on a connected socket, but the socket wasn't connected.\n\nEPERM User doesn't have permission to set high priority, change configuration, or send sig‐\nnals to the requested process or group.\n\nEPIPE The connection was unexpectedly closed or shut down by the other end.\n\nESOCKTNOSUPPORT\nThe socket is not configured or an unknown socket type was requested.\n\nOther errors may be generated by the overlaying protocols; see tcp(7), raw(7), udp(7), and\nsocket(7).\n\n### NOTES\n\nIPFREEBIND, IPMSFILTER, IPMTU, IPMTUDISCOVER, IPRECVORIGDSTADDR, IPPASSSEC, IPPKT‐‐\nINFO, IPRECVERR, IPROUTERALERT, and IPTRANSPARENT are Linux-specific.\n\nBe very careful with the SOBROADCAST option - it is not privileged in Linux. It is easy to\noverload the network with careless broadcasts. For new application protocols it is better to\nuse a multicast group instead of broadcasting. Broadcasting is discouraged.\n\nSome other BSD sockets implementations provide IPRCVDSTADDR and IPRECVIF socket options to\nget the destination address and the interface of received datagrams. Linux has the more gen‐\neral IPPKTINFO for the same task.\n\nSome BSD sockets implementations also provide an IPRECVTTL option, but an ancillary message\nwith type IPRECVTTL is passed with the incoming packet. This is different from the IPTTL\noption used in Linux.\n\nUsing the SOLIP socket options level isn't portable; BSD-based stacks use the IPPROTOIP\nlevel.\n\nINADDRANY (0.0.0.0) and INADDRBROADCAST (255.255.255.255) are byte-order-neutral.\nThis means htonl(3) has no effect on them.\n\n#### Compatibility\n\nFor compatibility with Linux 2.0, the obsolete socket(AFINET, SOCKPACKET, protocol) syntax\nis still supported to open a packet(7) socket. This is deprecated and should be replaced by\nsocket(AFPACKET, SOCKRAW, protocol) instead. The main difference is the new sockaddrll\naddress structure for generic link layer information instead of the old sockaddrpkt.\n\n### BUGS\n\nThere are too many inconsistent error values.\n\nThe error used to diagnose exhaustion of the ephemeral port range differs across the various\nsystem calls (connect(2), bind(2), listen(2), sendto(2)) that can assign ephemeral ports.\n\nThe ioctls to configure IP-specific interface options and ARP tables are not described.\n\nReceiving the original destination address with MSGERRQUEUE in msgname by recvmsg(2) does\nnot work in some 2.2 kernels.\n\n### SEE ALSO\n\nrecvmsg(2), sendmsg(2), byteorder(3), capabilities(7), icmp(7), ipv6(7), netdevice(7),\nnetlink(7), raw(7), socket(7), tcp(7), udp(7), ip(8)\n\nThe kernel source file Documentation/networking/ip-sysctl.txt.\n\nRFC 791 for the original IP specification. RFC 1122 for the IPv4 host requirements.\nRFC 1812 for the IPv4 router requirements.\n\n### COLOPHON\n\nThis page is part of release 5.10 of the Linux man-pages project. A description of the\nproject, information about reporting bugs, and the latest version of this page, can be found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nLinux 2020-11-01 IP(7)\n\n" } ], "structuredContent": { "command": "ip", "section": "7", "mode": "man", "summary": "ip - Linux IPv4 protocol implementation", "synopsis": "", "tldr_summary": "Show/manipulate routing, devices, policy routing and tunnels.", "tldr_examples": [ { "description": "List interfaces with detailed info", "command": "ip {{a|address}}" }, { "description": "List interfaces with brief network layer info", "command": "ip {{-br|-brief}} {{a|address}}" }, { "description": "List interfaces with brief link layer info", "command": "ip {{-br|-brief}} {{l|link}}" }, { "description": "Display the routing table", "command": "ip {{r|route}}" }, { "description": "Show neighbors (ARP table)", "command": "ip {{n|neighbour}}" }, { "description": "Make an interface up/down", "command": "sudo ip {{l|link}} {{s|set}} {{ethX}} {{up|down}}" }, { "description": "Add/Delete an IP address to an interface", "command": "sudo ip {{a|address}} {{add|delete}} {{ip_address}}/{{mask}} dev {{ethX}}" }, { "description": "Add a default route", "command": "sudo ip {{r|route}} {{a|add}} default via {{ip_address}} dev {{ethX}}" } ], "tldr_source": "official", "flags": [], "examples": [], "see_also": [ { "name": "recvmsg", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/recvmsg/2/json" }, { "name": "sendmsg", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/sendmsg/2/json" }, { "name": "byteorder", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/byteorder/3/json" }, { "name": "capabilities", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/capabilities/7/json" }, { "name": "icmp", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/icmp/7/json" }, { "name": "ipv6", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/ipv6/7/json" }, { "name": "netdevice", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/netdevice/7/json" }, { "name": "netlink", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/netlink/7/json" }, { "name": "raw", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/raw/7/json" }, { "name": "socket", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/socket/7/json" }, { "name": "tcp", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/tcp/7/json" }, { "name": "udp", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/udp/7/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 1, "subsections": [ { "name": "#include ", "lines": 1 }, { "name": "#include ", "lines": 6 } ] }, { "name": "DESCRIPTION", "lines": 39, "subsections": [ { "name": "Address format", "lines": 43 }, { "name": "Socket options", "lines": 398 }, { "name": "/proc interfaces", "lines": 90 }, { "name": "Ioctls", "lines": 4 } ] }, { "name": "ERRORS", "lines": 58, "subsections": [] }, { "name": "NOTES", "lines": 21, "subsections": [ { "name": "Compatibility", "lines": 5 } ] }, { "name": "BUGS", "lines": 10, "subsections": [] }, { "name": "SEE ALSO", "lines": 8, "subsections": [] }, { "name": "COLOPHON", "lines": 7, "subsections": [] } ] } }