ip man page on Plan9

Man page or keyword search:  
man Server   549 pages
apropos Keyword Search (all sections)
Output format
Plan9 logo
[printable version]

IP(3)									 IP(3)

       ip,  esp,  gre, icmp, icmpv6, ipmux, rudp, tcp, udp - network protocols
       over IP

       bind -a #Ispec /net

       The ip device provides the interface to Internet Protocol stacks.  Spec
       is  an integer from 0 to 15 identifying a stack.	 Each stack implements
       IPv4 and IPv6.  Each stack is  independent  of  all  others:  the  only
       information  transfer  between them is via programs that mount multiple
       stacks.	Normally a system  uses	 only  one  stack.   However  multiple
       stacks  can be used for debugging new IP networks or implementing fire‐
       walls or proxy services.

       All addresses used are 16-byte IPv6 addresses.  IPv4  addresses	are  a
       subset  of  the	IPv6  addresses	 and  both  standard ASCII formats are
       accepted.  In binary representation, all v4 addresses start with the 12
       bytes, in hex:

	      00 00 00 00 00 00 00 00 00 00 ff ff

   Configuring interfaces
       Each  stack  may	 have  multiple interfaces and each interface may have
       multiple addresses.  The /net/ipifc directory contains a clone file,  a
       stats file, and numbered subdirectories for each physical interface.

       Opening	the  clone  file  reserves  an interface.  The file descriptor
       returned from the open(2) will point to the control file, ctl,  of  the
       newly  allocated	 interface.   Reading ctl returns a text string repre‐
       senting the number of the interface.  Writing ctl alters aspects of the
       interface.   The possible ctl messages are those described under Proto‐
       col directories below and these:

       bind ether path
	      Treat the device mounted at path as an Ethernet medium  carrying
	      IP  and  ARP  packets and associate it with this interface.  The
	      kernel will dial(2) path!0x800, path!0x806 and  path!0x86dd  and
	      use the connections for IPv4, ARP and IPv6 respectively.

       bind pkt
	      Treat  this interface as a packet interface.  Assume a user pro‐
	      gram will read and write the data file to receive	 and  transmit
	      IP  packets  to  the  kernel.   This is used by programs such as
	      ppp(8) to mediate IP packet transfer between the	kernel	and  a
	      PPP encoded device.

       bind netdev path
	      Treat  this  interface  as  a packet interface.  The kernel will
	      open path and read and write the resulting  file	descriptor  to
	      receive and transmit IP packets.

       bind loopback
	      Treat  this  interface as a local loopback.  Anything written to
	      it will be looped back.

       unbind Disassociate the physical device from an IP interface.

       add local [ mask remote mtu proxy ]
       try local [ mask remote mtu proxy ]
	      Add a local IP address to the interface.	 Try  adds  the	 local
	      address  as  a  tentative	 address if it's an IPv6 address.  The
	      mask, remote, mtu, and proxy arguments are  all  optional.   The
	      default  mask  is	 the  class  mask  for the local address.  The
	      default remote address is local ANDed with  mask.	  The  default
	      mtu  (maximum  transmission  unit) is 1514 for Ethernet and 4096
	      for packet media.	 The mtu is the size in bytes of  the  largest
	      packet that this interface can send.  Proxy, if specified, means
	      that this machine should answer  ARP  requests  for  the	remote
	      address.	 Ppp(8) does this to make remote machines appear to be
	      connected to the local Ethernet.

       remove local mask
	      Remove a local IP address from an interface.

       mtu n  Set the maximum transfer unit for this device to n.  The mtu  is
	      the  maximum  size  of  the packet including any medium-specific

	      Reassemble IP fragments before forwarding to this interface

       iprouting n
	      Allow (n is missing or non-zero) or disallow (n is 0) forwarding
	      packets between this interface and others.

       bridge Enable bridging (see bridge(3)).

	      Set  the	interface into promiscuous mode, which makes it accept
	      all incoming packets, whether addressed to it or not.

       connect type
	      marks the Ethernet packet type as being in use, if  not  already
	      in  use on this interface.  A type of -1 means `all' but appears
	      to be a no-op.

       addmulti Media-addr
	      Treat the multicast Media-addr on	 this  interface  as  a	 local

       remmulti Media-addr
	      Remove the multicast address Media-addr from this interface.

       scanbs Make the wireless interface scan for base stations.

	      Set the interface to pass only packet headers, not data too.

       add6 v6addr pfx-len [onlink auto validlt preflt]
	      Add  the local IPv6 address v6addr with prefix length pfx-len to
	      this interface.  See RFC	2461  §6.2.1  for  more	 detail.   The
	      remaining arguments are optional:

	      onlink flag: address is `on-link'

	      auto   flag: autonomous

		     valid life-time in seconds

	      preflt preferred life-time in seconds

       ra6 keyword value ...
	      Set  IPv6	 router	 advertisement (RA) parameter keyword's value.
	      Known keywords and the meanings of their values follow.  See RFC
	      2461 §6.2.1 for more detail.  Flags are true iff non-zero.

	      recvra flag: receive and process RAs.

	      sendra flag: generate and send RAs.

	      mflag  flag: ``Managed address configuration'', goes into RAs.

	      oflag  flag: ``Other stateful configuration'', goes into RAs.

		     ``maximum time allowed between sending unsolicited multi‐
		     cast'' RAs from the interface, in ms.

		     ``minimum time allowed between sending unsolicited multi‐
		     cast'' RAs from the interface, in ms.

		     ``value to be placed in MTU options sent by the router.''
		     Zero indicates none.

		     sets the Reachable Time field in RAs sent by the  router.
		     ``Zero means unspecified (by this router).''

		     sets  the	Retrans Timer field in RAs sent by the router.
		     ``Zero means unspecified (by this router).''

	      ttl    default value of the Cur Hop Limit field in RAs  sent  by
		     the  router.   Should be set to the ``current diameter of
		     the  Internet.''	``Zero	means  unspecified  (by	  this

		     sets  the	Router	Lifetime  field	 of  RAs sent from the
		     interface, in ms.	Zero means the router  is  not	to  be
		     used as a default router.

       Reading	the  interface's  status  file	returns	 information about the
       interface, one line for each local  address  on	that  interface.   The
       first  line  has	 9  white-space-separated  fields:  device, mtu, local
       address, mask, remote or network	 address,  packets  in,	 packets  out,
       input errors, output errors.  Each subsequent line contains all but the
       device and mtu.	See readipifc in ip(2).

       The file iproute controls information about IP routing.	When read,  it
       returns	one  line  per	routing	 entry.	 Each line contains six white-
       space-separated fields: target address, target mask,  address  of  next
       hop,  flags,  tag, and interface number.	 The entry used for routing an
       IP packet is the one  with  the	longest	 mask  for  which  destination
       address	ANDed  with  target  mask equals the target address.  The one-
       character flags are:

       4      IPv4 route

       6      IPv6 route

       i      local interface

       b      broadcast address

       u      local unicast address

       m      multicast route

       p      point-to-point route

       The tag is an arbitrary, up to 4 character,  string.   It  is  normally
       used to indicate what routing protocol originated the route.

       Writing to /net/iproute changes the route table.	 The messages are:

       flush  Remove all routes.

       tag string
	      Associate	 the tag, string, with all subsequent routes added via
	      this file descriptor.

       add target mask nexthop
	      Add the route to the table.  If one already exists with the same
	      target and mask, replace it.

       remove target mask
	      Remove a route with a matching target and mask.

       route target
	      Print  on the console the route to address target, if any.  Pri‐
	      marily a debugging aid.

   Address resolution
       The file /net/arp controls information about address  resolution.   The
       kernel  automatically  updates  the  v4	ARP and v6 Neighbour Discovery
       information for Ethernet interfaces.  When read, the file  returns  one
       line per address containing the type of medium, the status of the entry
       (OK, WAIT), the	IP  address,  and  the	medium	address.   Writing  to
       /net/arp administers the ARP information.  The control messages are:

       flush  Remove all entries.

       add type IP-addr Media-addr
	      Add an entry or replace an existing one for the same IP address.

       del IP-addr
	      Delete an individual entry.

       ARP  entries  do	 not  time  out.  The ARP table is a cache with an LRU
       replacement policy.  The IP stack listens for all ARP requests and,  if
       the  requester is in the table, the entry is updated.  Also, whenever a
       new address is configured onto an Ethernet, an ARP request is  sent  to
       help update the table on other systems.

       Currently, the only medium type is ether.

   Debugging and stack information
       If  any process is holding /net/log open, the IP stack queues debugging
       information to it.  This is intended primarily  for  debugging  the  IP
       stack.	The  information  provided  is implementation-defined; see the
       source for details.  Generally, what  is	 returned  is  error  messages
       about bad packets.

       Writing to /net/log controls debugging.	The control messages are:

       set arglist
	      Arglist  is  a space-separated list of items for which to enable
	      debugging.  The possible items are: ppp, ip, fs, tcp, icmp, udp,
	      compress, gre, tcpwin, tcprxmt, udpmsg, ipmsg, and esp.

       clear arglist
	      Arglist  is a space-separated list of items for which to disable

       only addr
	      If addr is non-zero, restrict debugging to  only	those  packets
	      whose source or destination is that address.

       The  file  /net/ndb can be read or written by programs.	It is normally
       used by ipconfig(8) to leave configuration information for  other  pro‐
       grams such as dns and cs (see ndb(8)).  /net/ndb may contain up to 1024

       The file /net/ipselftab is a  read-only	file  containing  all  the  IP
       addresses  considered  local.   Each  line  in  the file contains three
       white-space-separated fields: IP address, usage count, and flags.   The
       usage  count  is the number of interfaces to which the address applies.
       The flags are the same as for routing entries.	Note  that  the	 `IPv4
       route' flag will never be set.

   Protocol directories
       The  ip	device	supports IP as well as several protocols that run over
       it: TCP, UDP, RUDP, ICMP, GRE, and ESP.	TCP and UDP provide the	 stan‐
       dard  Internet  protocols  for  reliable stream and unreliable datagram
       communication.  RUDP is a locally-developed reliable datagram  protocol
       based on UDP.  ICMP is IP's catch-all control protocol used to send low
       level error messages and to implement ping(8).  GRE is a general encap‐
       sulation	 protocol.   ESP  is the encapsulation protocol for IPsec.  IL
       provided a reliable datagram service for communication between  Plan  9
       machines over IPv4, but is no longer part of the system.

       Each  protocol is a subdirectory of the IP stack.  The top level direc‐
       tory of each protocol contains a clone file, a stats file,  and	subdi‐
       rectories  numbered  from  zero to the number of connections opened for
       this protocol.

       Opening the clone file reserves	a  connection.	 The  file  descriptor
       returned	 from  the open(2) will point to the control file, ctl, of the
       newly allocated connection.  Reading ctl returns a text	string	repre‐
       senting	the  number of the connection.	Connections may be used either
       to listen for incoming calls or to initiate calls to other machines.

       A connection is controlled by writing text strings  to  the  associated
       ctl  file.   After  a  connection has been established data may be read
       from and written to data.  A connection	can  be	 actively  established
       using  the  connect  message  (see  also dial(2)).  A connection can be
       established passively by first using an announce message (see  dial(2))
       to  bind to a local port and then opening the listen file (see dial(2))
       to receive incoming calls.

       The following control messages are supported:

       connect ip-address!port!r local
	      Establish a connection to the remote ip-address  and  port.   If
	      local  is	 specified,  it	 is used as the local port number.  If
	      local is not specified but !r is, the  system  will  allocate  a
	      restricted  port	number	(less than 1024) for the connection to
	      allow communication with Unix login and exec  services.	Other‐
	      wise a free port number starting at 5000 is chosen.  The connect
	      fails if the combination of local and remote address/port	 pairs
	      are already assigned to another port.

       announce X
	      X is a decimal port number or Set the local port number to X and
	      accept calls to X.  If X is accept calls for any	port  that  no
	      process  has  explicitly announced.  The local IP address cannot
	      be set.  Announce fails if the connection is  already  announced
	      or connected.

       bind X X	 is  a	decimal port number or Set the local port number to X.
	      This exists to support emulation	of  BSD	 sockets  by  the  APE
	      libraries (see pcc(1)) and is not otherwise used.

       ttl n  Set the time to live IP field in outgoing packets to n.

       tos n  Set the service type IP field in outgoing packets to n.

	      Don't break (UDP) connections because of ICMP errors.

       addmulti ifc-ip [ mcast-ip ]
	      Treat ifc-ip on this multicast interface as a local address.  If
	      mcast-ip	is  present,  use  it  as  the	interface's  multicast

       remmulti ip
	      Remove the address ip from this multicast interface.

       Port numbers must be in the range 1 to 32767.

       Several	files report the status of a connection.  The remote and local
       files contain the IP address and port number for the remote  and	 local
       side  of	 the  connection.  The status file contains protocol-dependent
       information to help debug network connections.  On receiving and	 error
       or EOF reading or writing the data file, the err file contains the rea‐
       son for error.

       A process may accept incoming  connections  by  open(2)ing  the	listen
       file.   The  open  will	block  until a new connection request arrives.
       Then open will return an open file descriptor which points to the  con‐
       trol file of the newly accepted connection.  This procedure will accept
       all calls for the given protocol.  See dial(2).

       TCP connections are reliable point-to-point byte streams; there are  no
       message delimiters.  A connection is determined by the address and port
       numbers of the two ends.	 TCP ctl files	support	 the  following	 addi‐
       tional messages:

       hangup close down this TCP connection

       keepalive n
	      turn  on	keep alive messages.  N, if given, is the milliseconds
	      between keepalives (default 30000).

       checksum n
	      emit TCP checksums of zero if  n	is  zero;  otherwise,  and  by
	      default, TCP checksums are computed and sent normally.

       tcpporthogdefense onoff
	      onoff  of	 enables  the TCP port-hog defense for all TCP connec‐
	      tions; onoff of disables it.   The  defense  is  a  solution  to
	      hijacked	systems	 staking out ports as a form of denial-of-ser‐
	      vice attack.  To avoid stateless TCP conversation hogs, ip picks
	      a	 TCP sequence number at random for keepalives.	If that number
	      gets acked by the other end, ip shuts down the connection.  Some
	      firewalls,  notably  ones that perform stateful inspection, dis‐
	      card  such  out-of-specification	keepalives,   so   connections
	      through  such firewalls will be killed after five minutes by the
	      lack of keepalives.

       UDP connections carry unreliable and unordered datagrams.  A read  from
       data  will  return  the next datagram, discarding anything that doesn't
       fit in the read buffer.	A write is sent as a single datagram.

       By default, a UDP connection is a point-to-point link.  Either  a  con‐
       nect  establishes  a  local  and	 remote	 address/port pair or after an
       announce, each datagram coming from  a  different  remote  address/port
       pair  establishes  a  new  incoming  connection.	  However, many-to-one
       semantics is also possible.

       If, after an announce, the message is written to ctl, then all messages
       sent  to	 the  announced	 port are received on the announced connection
       prefixed with the corresponding structure, declared in <ip.h>:

	      typedef struct Udphdr Udphdr;
	      struct Udphdr
		   uchar     raddr[16];	    /* V6 remote address and port */
		   uchar     laddr[16];	    /* V6 local address and port */
		   uchar     ifcaddr[16];   /* V6 interface address (receive only) */
		   uchar     rport[2]; /* remote port */
		   uchar     lport[2]; /* local port */

       Before a write, a user must prefix a similar structure to each message.
       The  system  overrides the user specified local port with the announced
       one.  If the user specifies an address that isn't a unicast address  in
       /net/ipselftab,	that  too is overridden.  Since the prefixed structure
       is the same in read and write, it is relatively easy to write a	server
       that responds to client requests by just copying new data into the mes‐
       sage body and then writing back the same buffer that was read.

       In this case (writing to the ctl file), no listen nor accept is needed;
       otherwise,  the usual sequence of announce, listen, accept must be exe‐
       cuted before performing I/O on the corresponding data file.

       RUDP is a reliable datagram protocol based on UDP, currently  only  for
       IPv4.   Packets	are delivered in order.	 RUDP does not support listen.
       One must write either or followed immediately by to ctl.

       Unlike TCP, the reboot of one end of a  connection  does	 not  force  a
       closing	of  the	 connection.   Communications  will  resume  when  the
       rebooted machine resumes talking.  Any  unacknowledged  packets	queued
       before  the  reboot  will be lost.  A reboot can be detected by reading
       the err file.  It will contain the message

	      hangup address!port

       where address and port are of the far side of the connection.  Retrans‐
       mitting	a  datagram  more  than 10 times is treated like a reboot: all
       queued messages are dropped, an error is queued to the  err  file,  and
       the conversation resumes.

       RUDP ctl files accept the following messages:

	      Corresponds to the format of UDP.

       hangup IP port
	      Drop the connection to address IP and port.

       randdrop [ percent ]
	      Randomly drop percent of outgoing packets.  Default is 10%.

       ICMP  is a datagram protocol for IPv4 used to exchange control requests
       and their responses with other machines' IP implementations.   ICMP  is
       primarily  a  kernel-to-kernel protocol, but it is possible to generate
       `echo request' and read `echo reply' packets from user programs.

       ICMPv6 is the IPv6 equivalent of ICMP.  If, after an announce, the mes‐
       sage  is	 written  to ctl, then before a write, a user must prefix each
       message with a corresponding structure, declared in <ip.h>:

	       *  user level icmpv6 with control message "headers"
	      typedef struct Icmp6hdr Icmp6hdr;
	      struct Icmp6hdr {
		   uchar     unused[8];
		   uchar     laddr[IPaddrlen];	 /* local address */
		   uchar     raddr[IPaddrlen];	 /* remote address */

       In this case (writing to the ctl file), no listen nor accept is needed;
       otherwise,  the usual sequence of announce, listen, accept must be exe‐
       cuted before performing I/O on the corresponding data file.

       GRE is the encapsulation protocol used by PPTP.	The kernel  implements
       just enough of the protocol to multiplex it.  Our implementation encap‐
       sulates in IPv4, per RFC 1702.  Announce is not allowed	in  GRE,  only
       connect.	 Since GRE has no port numbers, the port number in the connect
       is actually the 16 bit eproto field in the GRE header.

       Reads and writes transfer a GRE datagram starting at  the  GRE  header.
       On  write,  the	kernel	fills in the eproto field with the port number
       specified in the connect message.

       ESP is the Encapsulating Security Payload (RFC 1827, obsoleted  by  RFC
       4303)  for  IPsec (RFC 4301).  We currently implement only tunnel mode,
       not transport mode.  It is used to set up an encrypted  tunnel  between
       machines.  Like GRE, ESP has no port numbers.  Instead, the port number
       in the connect message is  the  SPI  (Security  Association  Identifier
       (sic)).	 IP  packets  are  written  to and read from data.  The kernel
       encrypts any packets written to data, appends a MAC,  and  prefixes  an
       ESP  header  before  sending  to the other end of the tunnel.  Received
       packets are checked against their  MAC's,  decrypted,  and  queued  for
       reading	from data.  In the following, secret is the hexadecimal encod‐
       ing of a key, without a leading The control messages are:

       esp alg secret
	      Encrypt with the algorithm, alg, using secret as the key.	  Pos‐
	      sible algorithms are: null, des_56_cbc, des3_cbc, and eventually
	      aes_128_cbc, and aes_ctr.

       ah alg secret
	      Use the hash algorithm, alg, with secret as the key for generat‐
	      ing  the	MAC.   Possible	 algorithms  are:  null, hmac_sha1_96,
	      hmac_md5_96, and eventually aes_xcbc_mac_96.

       header Turn on header mode.  Every buffer read from data starts with  4
	      unused  bytes,  and the first 4 bytes of every buffer written to
	      data are ignored.

	      Turn off header mode.

   IP packet filter
       The directory /net/ipmux looks like another protocol directory.	It  is
       a  packet filter built on top of IP.  Each numbered subdirectory repre‐
       sents a different filter.  The connect messages written to the ctl file
       describe	 the  filter.  Packets	matching the filter can be read on the
       data file.  Packets written to the data file are routed to an interface
       and transmitted.

       A  filter  is  a	 semicolon-separated list of relations.	 Each relation
       describes a portion of a packet to match.  The possible relations are:

	      the IP protocol number must be n.

	      bytes n through m following the IP packet must match expr.

	      bytes n through m of the IP packet header must match expr.

	      the packet must have been received on an interface whose address
	      matches expr.

	      The source address in the packet must match expr.

	      The destination address in the packet must match expr.

       Expr is of the form:





       If  a  mask  is given, the relevant field is first ANDed with the mask.
       The result is compared against the value or list of values for a match.
       In  the	case  of  ifc,	dst,  and  src the value is a dot-formatted IP
       address and the mask is a dot-formatted IP mask.	 In the case of	 data,
       iph  and proto, both value and mask are strings of 2 hexadecimal digits
       representing 8-bit values.

       A packet is delivered to only one filter.  The filters are merged  into
       a  single  comparison  tree.  If two filters match the same packet, the
       following rules apply in order (here '>' means is preferred to):

       1)     protocol > data > source > destination > interface

       2)     lower data offsets > higher data offsets

       3)     longer matches > shorter matches

       4)     older > younger

       So far this has just been used  to  implement  a	 version  of  OSPF  in
       Inferno and 6to4 tunnelling.

       The  stats files are read only and contain statistics useful to network

       Reading /net/ipifc/stats returns a list of 19 tagged and	 newline-sepa‐
       rated fields representing:
	 forwarding status (0 and 2 mean forwarding off,
	      1 means on)
	 default TTL
	 input packets
	 input header errors
	 input address errors
	 packets forwarded
	 input packets for unknown protocols
	 input packets discarded
	 input packets delivered to higher level protocols
	 output packets
	 output packets discarded
	 output packets with no route
	 timed out fragments in reassembly queue
	 requested reassemblies
	 successful reassemblies
	 failed reassemblies
	 successful fragmentations
	 unsuccessful fragmentations
	 fragments created

       Reading	/net/icmp/stats	 returns a list of 26 tagged and newline-sepa‐
       rated fields representing:
	 messages received
	 bad received messages
	 unreachables received
	 time exceededs received
	 input parameter problems received
	 source quenches received
	 redirects received
	 echo requests received
	 echo replies received
	 timestamps received
	 timestamp replies received
	 address mask requests received
	 address mask replies received
	 messages sent
	 transmission errors
	 unreachables sent
	 time exceededs sent
	 input parameter problems sent
	 source quenches sent
	 redirects sent
	 echo requests sent
	 echo replies sent
	 timestamps sent
	 timestamp replies sent
	 address mask requests sent
	 address mask replies sent

       Reading /net/tcp/stats returns a list of 11  tagged  and	 newline-sepa‐
       rated fields representing:
	 maximum number of connections
	 total outgoing calls
	 total incoming calls
	 number of established connections to be reset
	 number of currently established connections
	 segments received
	 segments sent
	 segments retransmitted
	 retransmit timeouts
	 bad received segments
	 transmission failures

       Reading /net/udp/stats returns a list of 4 tagged and newline-separated
       fields representing:
	 datagrams received
	 datagrams received for bad ports
	 malformed datagrams received
	 datagrams sent

       Reading /net/gre/stats returns a list of 1 tagged number representing:
	 header length errors

       dial(2), ip(2), bridge(3), ndb(6), listen(8)
	      IPv6 address architecture
       Ipmux has not been heavily used and should be considered	 experimental.
       It  may	disappear  in favor of a more traditional packet filter in the

                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net