diff options
Diffstat (limited to 'static/plan9-4e/man3/ip.3')
| -rw-r--r-- | static/plan9-4e/man3/ip.3 | 926 |
1 files changed, 926 insertions, 0 deletions
diff --git a/static/plan9-4e/man3/ip.3 b/static/plan9-4e/man3/ip.3 new file mode 100644 index 00000000..84be502f --- /dev/null +++ b/static/plan9-4e/man3/ip.3 @@ -0,0 +1,926 @@ +.TH IP 3 +.SH NAME +ip \- network protocols over IP +.SH SYNOPSIS +.nf +.B bind -a #I\fIspec\fP /net + +.B /net/ipifc +.B /net/ipifc/clone +.B /net/ipifc/stats +.BI /net/ipifc/ n +.BI /net/ipifc/ n /status +.BI /net/ipifc/ n /ctl +\&... + +.B /net/arp +.B /net/log +.B /net/ndb +.B /net/iproute +.B /net/ipselftab + +.B /net/esp +.B /net/gre +.B /net/icmp +.B /net/il +.B /net/ipmux +.B /net/rudp +.B /net/tcp +.B /net/udp + +.B /net/tcp/clone +.B /net/tcp/stats +.BI /net/tcp/ n +.BI /net/tcp/ n /data +.BI /net/tcp/ n /ctl +.BI /net/tcp/ n /local +.BI /net/tcp/ n /remote +.BI /net/tcp/ n /status +.BI /net/tcp/ n /listen +\&... +.fi +.SH DESCRIPTION +The IP device provides the interface to Internet protocol stacks. +.I Spec +is an integer from 0 to 15 identifying a stack. +Each stack is physically 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 firewalls or proxy +services. +.PP +All addresses used are 16-byte IPv6 addresses. Though +we currently implement only IPv4, the IPv6 format is intended to +prepare the way for an IPv6 implementation. IPv4 addresses +are a subset of the IPv6 addresses and both standard +.SM ASCII +formats +are accepted. In binary, all v4 addresses start with the +12 bytes: +.EX + 00 00 00 00 00 00 00 00 00 00 ff ff +.EE +.SS "Configuring interfaces +.PP +Each stack may have multiple interfaces and each interface +may have multiple addresses. +The +.B /net/ipifc +directory contains a +.B clone +file, a +.B stats +file, and numbered subdirectories for each physical interface. +.PP +Opening the +.B clone +file reserves an interface. +The file descriptor returned from the +.IR open (2) +will point to the control file, +.BR ctl , +of the newly allocated interface. +Reading +.B ctl +returns a text string representing the number of the interface. +Writing +.B ctl +alters aspects of the interface. +The possible +.I ctl +messages are: +.TP +.BI "bind ether " path +Treat the device mounted at +.I path +as an Ethernet medium carrying IP and ARP packets +and associate it with this interface. +The kernel will +.IR dial (2) +.IR path !0x800 +and +.IR path !0x806 +and use the two connections for IP and +ARP respectively. +.TP +.B "bind pkt +Treat this interface as a packet interface. Assume +a user program will read and write the +.I data +file to receive and transmit IP packets to the kernel. +This is used by programs such as +.IR ppp (8) +to mediate IP packet transfer between the kernel and +a PPP encoded device. +.TP +.BI "bind netdev " path +Treat this interface as a packet interface. +The kernel will open +.I path +and read and write the resulting file descriptor +to receive and transmit IP packets. +.TP +.BI "bind loopback " +Treat this interface as a local loopback. Anything +written to it will be looped back. +.TP +.B "unbind +Disassociate the physical device from an IP interface. +.TP +.BI add\ "local mask remote mtu " proxy +Add a local IP address to the interface. The +.IR mask , +.IR remote , +.IR mtu , +and +.B proxy +arguments are all optional. The default mask is +the class mask for the local address. The default +remote address is +.I local +ANDed with +.IR mask . +The default mtu is 1514 for Ethernet and 4096 for packet +media. +.IR Proxy , +if specified, means that this machine should answer +ARP requests for the remote address. +.IR Ppp (8) +does this to make remote machines appear +to be connected to the local Ethernet. +.TP +.BI remove\ "local mask" +Remove a local IP address from an interface. +.TP +.BI mtu\ n +Set the maximum transfer unit for this device to +.IR n . +The mtu is the maximum size of the packet including any +medium-specific headers. +.TP +.BI reassemble +Reassemble IP fragments before forwarding to this interface +.TP +.BI iprouting\ n +Allow +.RI ( n is missing +or non-zero) or disallow +.RI ( n +is 0) forwarding packets between this interface and +others. +.TP +.BI addmulti\ addr +Treat the multicast +.I addr +on this interface as a local address. +.TP +.BI remmulti\ addr +Remove the multicast address +.I addr +from this interface. +.PP +Reading the interface's +.I 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 +.B readipifc +in +.IR ip (2). +.SS "Routing +.PP +The file +.I 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: +.TP +.B 4 +IPv4 route +.TP +.B 6 +IPv6 route +.TP +.B i +local interface +.TP +.B b +broadcast address +.TP +.B u +local unicast address +.TP +.B m +multicast route +.TP +.B p +point-to-point route +.PP +The tag is an arbitrary, up to 4 character, string. It is normally used to +indicate what routing protocol originated the route. +.PP +Writing to +.B /net/iproute +changes the route table. The messages are: +.TP +.B flush +Remove all routes. +.TP +.BI tag\ string +Associate the tag, +.IR string , +with all subsequent routes added via this file descriptor. +.TP +.BI add\ "target mask nexthop" +Add the route to the table. If one already exists with the +same target and mask, replace it. +.TP +.BI remove\ "target mask" +Remove a route with a matching target and mask. +.SS "Address resolution +.PP +The file +.B /net/arp +controls information about address resolution. +The kernel automatically updates the ARP 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 +.B /net/arp +administers the ARP information. The control messages are: +.TP +.B flush +Remove all entries. +.TP +.BI add\ "type IP-addr Media-addr" +Add an entry or replace an existing one for the +same IP address. +.PP +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. +.PP +Currently, the only medium type is +.BR ether . +.SS "Debugging and stack information +.PP +If any process is holding +.B /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. +.PP +Writing to +.B /net/log +controls debugging. The control messages +are: +.TP +.BI set\ arglist +.I Arglist +is a space-separated list of items for which to enable debugging. +The possible items are: +.BR ppp , +.BR ip , +.BR fs , +.BR tcp , +.BR il , +.BR icmp , +.BR udb , +.BR compress , +.BR ilmsg , +.BR gre , +.BR tcpmsg , +.BR udpmsg , +.BR ipmsg , +and +.BR esp . +.TP +.BI clear\ arglist +.I Arglist +is a space-separated list of items for which to disable debugging. +.TP +.BI only\ addr +If +.I addr +is non-zero, restrict debugging to only those +packets whose source or destination is that +address. +.PP +The file +.B /net/ndb +can be read or written by +programs. It is normally used by +.IR ipconfig (8) +to leave configuration information for other programs +such as +.B dns +and +.B cs +(see +.IR ndb (8)). +.B /net/ndb +may contain up tp 1024 bytes. +.PP +The file +.B /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. +.SS "Protocol directories +.PP +The +.I ip +device +supports IP as well as several protocols that run over it: +TCP, IL, UDP, GRE, ESP, ICMP, and RUDP. +TCP and UDP provide the standard Internet +protocols for reliable stream and unreliable datagram +communication. +IL provides a reliable datagram service for communication +between Plan 9 machines. +GRE is a general encapsulation protocol. +ESP is the encapsulation protocol for IPSEC. +ICMP is IP's catch-all control protocol used to send +low level error messages and to implement +.IR ping (8). +RUDP is a locally developed reliable datagram protocol based on +UDP. +.PP +Each protocol is a subdirectory of the IP stack. +The top level directory of each protocol contains a +.B clone +file, a +.B stats +file, and subdirectories numbered from zero to the number of connections +opened for this protocol. +.PP +Opening the +.B clone +file reserves a connection. The file descriptor returned from the +.IR open (2) +will point to the control file, +.BR ctl , +of the newly allocated connection. +Reading +.B ctl +returns a text +string representing the number of the +connection. +Connections may be used either to listen for incoming calls +or to initiate calls to other machines. +.PP +A connection is controlled by writing text strings to the associated +.B ctl +file. +After a connection has been established data may be read from +and written to +.BR data . +A connection can be actively established using the +.B connect +message (see also +.IR dial (2)). +A connection can be established passively by first +using an +.B announce +message (see +.IR dial (2)) +to bind to a local port and then +opening the +.B listen +file (see +.IR dial (2)) +to receive incoming calls. +.PP +The following control messages are supported: +.TP +.BI connect\ ipaddress ! port "!r " local +Establish a connection to the remote address +.I ipaddress +and remote port +.IR port . +If +.I local +is specified, it is used as the local port number. +If +.I local +is not specified but +.B !r +is, the system will allocate +a restricted port number (less than 1024) for the connection to allow communication +with Unix +.B login +and +.B exec +services. +Otherwise 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. +.TP +.BI announce\ X +.I X +is a decimal port number or +.LR * . +Set the local port +number to +.I X +and accept calls to +.IR X . +If +.I X +is +.LR * , +accept +calls for any port that no process has explicitly announced. +The local IP address cannot be set. +.B Announce +fails if the connection is already announced or connected. +.TP +.BI bind\ X +.I X +is a decimal port number or +.LR * . +Set the local port number to +.IR X . +This exists to support emulation +of BSD sockets by the APE libraries (see +.IR pcc (1)) +and is not otherwise used. +.TP +.BI backlog\ n +Set the maximum number of unanswered (queued) incoming +connections to an announced port to +.IR n . +By default +.I n +is set to five. If more than +.I n +connections are pending, +further requests for a service will be rejected. +.TP +.BI ttl\ n +Set the time to live IP field in outgoing packets to +.IR n . +.TP +.BI tos\ n +Set the service type IP field in outgoing packets to +.IR n . +.PP +Port numbers must be in the range 1 to 32767. +.PP +Several files report the status of a +connection. +The +.B remote +and +.B local +files contain the IP address and port number for the remote and local side of the +connection. The +.B status +file contains protocol-dependent information to help debug network connections. +On receiving and error or EOF reading or writing the +.B data +file, the +.B err +file contains the reason for error. +.PP +A process may accept incoming connections by +.IR open (2)ing +the +.B listen +file. +The +.B open +will block until a new connection request arrives. +Then +.B open +will return an open file descriptor which points to the control file of the +newly accepted connection. +This procedure will accept all calls for the +given protocol. +See +.IR dial (2). +.SS TCP +.PP +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 +.B ctl +files support the following additional messages: +.TP +.B hangup +close down a TCP connection +.TP +.BI keepalive \ n +turn on keep alive messages. +.IR N , +if given, is the milliseconds between keepalives +(default 30000). +.SS UDP +.PP +UDP connections carry unreliable and unordered datagrams. A read from +.B data +will return the next datagram, discarding anything +that doesn't fit in the read buffer. +A write is sent as a single datagram. +.PP +By default, a UDP connection is a point-to-point link. +Either a +.B connect +establishes a local and remote address/port pair or +after an +.BR announce , +each datagram coming from a different remote address/port pair +establishes a new incoming connection. +However, many-to-one semantics is also possible. +.PP +If, after an +.BR announce , +one of the following messages is written to +.BR ctl , +then all messages sent to the announced port +are received on the announced connection prefixed with the given structure. +.TP +.B headers4 +.EX +typedef struct Udphdr4 Udphdr4; +struct Udphdr +{ + uchar raddr[4]; /* v4 remote address and port */ + uchar laddr[4]; /* v4 local address and port */ + uchar rport[2]; + uchar lport[2]; +}; +.EE +.TP +.B headers +.EX +typedef struct Udphdr Udphdr; +struct Udphdr +{ + uchar raddr[16]; /* v6 remote address and port */ + uchar laddr[16]; /* v6 local address and port */ + uchar rport[2]; + uchar lport[2]; +}; +.EE +.PP +The only difference in the two is the type of address, IPv4 or IPv6. +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 +.BR /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 message body and then writing back the same buffer that was +written. +.SS RUDP +.PP +RUDP is a reliable datagram protocol based on UDP. +Packets are delivered in order. +RUDP does not support +.BR listen . +One must use either +.B connect +or +.B announce +followed immediately by +.B headers +or +.BR headers4 . +.PP +Unlike IL or 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 +.B err +file. It will have the message +.IP +.BI hangup\ address ! port +.PP +where +.I address +and +.I port +are of the far side of the connection. +Retransmitting a datagram more than 10 times +is treated like a reboot: +all queued messages are dropped, an error is queued to the +.B err +file, and the conversation resumes. +.SS IL +.PP +IL is a reliable point-to-point datagram protocol. Like TCP, IL delivers datagrams +reliably and in order. Also like TCP, a connection is +determined by the address and port numbers of the two ends. +Like UDP, each read and write transfers a single datagram. +.PP +IL is efficient for LANs but doesn't have the +congestion control features needed for use through +the Internet. +.SS GRE +.PP +GRE is the encapsulation protocol used by PPTP. +The kernel implements just enough of the protocol +to multiplex it. +.B Announce +is not allowed in GRE, only +.BR connect . +Since GRE has no port numbers, the port number in the connect +is actually the 16 bit +.B eproto +field in the GRE header. +.PP +Reads and writes transfer a +GRE datagram starting at the GRE header. +On write, the kernel fills in the +.B eproto +field with the port number specified +in the connect message. +.SS ESP +.PP +ESP is the Encapsulating Security Payload (RFC 1827). +It is used to set up an encrypted tunnel between machines. +Like GRE, ESP has no port numbers. Instead, the +port number in the +.B connect +message is the SPI (Security Association Identifier (sic)). +IP packets are written to and read from +.BR data . +The kernel encrypts any packets written to +.BR 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 +.BR data . +The control messages are: +.TP +.BI esp\ "alg secret +Encrypt with the algorithm, +.IR alg , +using +.I secret +as the key. +Possible algorithms are: +.BR null , +.BR des_56_cbc , +and +.BR rc4_128 . +.TP +.BI ah\ "alg secret +Use the hash algorithm, +.IR alg , +with +.I secret +as the key for generating the MAC. +Possible algorithms are: +.BR null , +.BR hmac_sha1_96 , +and +.BR hmac_md5_96 . +.TP +.B header +Turn on header mode. Every buffer read from +.B data +starts with 4 unsued bytes, and the first 4 bytes +of every buffer written to +.B data +are ignored. +.TP +.B noheader +Turn off header mode. +.SS "IP packet filter +.PP +The directory +.B /net/ipmux +looks like another protocol directory. +It is a packet filter built on top of IP. Each numbered +subdirectory represents a different filter. +The connect messages written to the +.I ctl +file describe the filter. Packets matching the filter can be read on the +.B data +file. Packets written to the +.B data +file are routed to an interface and transmitted. +.PP +A filter is a semicolon-separated list of +relations. Each relation describes a portion +of a packet to match. The possible relations are: +.TP +.BI proto= n +the IP protocol number must be +.IR n . +.TP +.BI dat[ n : m ]= expr +bytes +.I n +through +.I m +following the IP packet must match +.IR expr . +.TP +.BI ifc= expr +the packet must have been received on an interface whose address +matches +.IR expr . +.TP +.BI src= expr +The source address in the packet must match +.IR expr . +.TP +.BI dst= expr +The destination address in the packet must match +.IR expr . +.PP +.I Expr +is of the form: +.TP +.I \ value +.TP +.IB \ value | value | ... +.TP +.IB \ value & mask +.TP +.IB \ value | value & mask +.PP +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 +.BR ifc , +.BR dst , +and +.B src +the value is a dot-formatted IP address and the mask is a dot-formatted +IP mask. In the case of +.BR dat , +both value and mask are strings of 2 character hexadecimal digits representing +8 bit values. +.PP +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): +.IP 1) +protocol > data > source > destination > interface +.IP 2) +lower data offsets > higher data offsets +.IP 3) +longer matches > shorter matches +.IP 4) +older > younger +.PP +So far this has just been used to implement a version of +OSPF in Inferno. +.SS Statistics +.PP +The +.B stats +files are read only and contain statistics useful to network +monitoring. +.PP +Reading +.B /net/ipifc/stats +returns a list of 19 tagged and new line separated fields representing: +.EX +.ft 1 + 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 +.ft +.EE +.PP +Reading +.B /net/icmp/stats +returns a list of 25 tagged and new line separated fields representing: +.EX +.ft 1 + 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 +.EE +.PP +Reading +.B /net/tcp/stats +returns a list of 11 tagged and new line separated fields representing: +.EX +.ft 1 + 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 +.EE +.PP +Reading +.B /net/udp/stats +returns a list of 4 tagged and new line separated fields representing: +.EX +.ft 1 + datagrams received + datagrams received for bad ports + malformed datagrams received + datagrams sent +.EE +.PP +Reading +.B /net/il/stats +returns a list of 7 tagged and new line separated fields representing: +.EX +.ft 1 + checksum errors + header length errors + out of order messages + retransmitted messages + duplicate messages + duplicate bytes +.EE +.PP +Reading +.B /net/gre/stats +returns a list of 1 tagged number representing: +.EX +.ft 1 + header length errors +.EE +.SH "SEE ALSO" +.IR listen (8), +.IR dial (2), +.IR ndb (6) +.SH SOURCE +.B /sys/src/9/ip +.SH BUGS +.I Ipmux +has not been heavily used and should be considered experimental. +It may disappear in favor of a more traditional packet filter in the future. |