3 ip, esp, gre, icmp, icmpv6, ipmux, rudp, tcp, udp, il \- network protocols over IP
7 .B bind -a #I\fIspec\fP /net
13 .BI /net/ipifc/ n /status
14 .BI /net/ipifc/ n /ctl
39 .BI /net/tcp/ n /local
40 .BI /net/tcp/ n /remote
41 .BI /net/tcp/ n /status
42 .BI /net/tcp/ n /listen
49 device provides the interface to Internet Protocol stacks.
51 is an integer from 0 to 15 identifying a stack.
52 Each stack implements IPv4 and IPv6.
53 Each stack is independent of all others:
54 the only information transfer between them is via programs that
55 mount multiple stacks.
56 Normally a system uses only one stack.
57 However multiple stacks can be used for debugging
58 new IP networks or implementing firewalls or proxy
61 All addresses used are 16-byte IPv6 addresses.
62 IPv4 addresses are a subset of the IPv6 addresses and both standard
65 In binary representation, all v4 addresses start with the 12 bytes, in hex:
68 00 00 00 00 00 00 00 00 00 00 ff ff
71 .SS "Configuring interfaces
72 Each stack may have multiple interfaces and each interface
73 may have multiple addresses.
80 file, and numbered subdirectories for each physical interface.
84 file reserves an interface.
85 The file descriptor returned from the
87 will point to the control file,
89 of the newly allocated interface.
92 returns a text string representing the number of the interface.
95 alters aspects of the interface.
98 messages are those described under
99 .B "Protocol directories"
101 .TF "\fLbind loopback\fR"
107 .BI "bind ether " path
108 Treat the device mounted at
110 as an Ethernet medium carrying IP and ARP packets
111 and associate it with this interface.
117 and use the two connections for IPv4 and
121 Treat this interface as a packet interface. Assume
122 a user program will read and write the
124 file to receive and transmit IP packets to the kernel.
125 This is used by programs such as
127 to mediate IP packet transfer between the kernel and
128 a PPP encoded device.
130 .BI "bind netdev " path
131 Treat this interface as a packet interface.
134 and read and write the resulting file descriptor
135 to receive and transmit IP packets.
138 Treat this interface as a local loopback. Anything
139 written to it will be looped back.
145 Disassociate the physical device from an IP interface.
147 .BI add\ "local mask remote mtu " proxy
150 .BI try\ "local mask remote mtu " proxy
152 Add a local IP address to the interface.
156 address as a tentative address
157 if it's an IPv6 address.
164 arguments are all optional.
167 is the class mask for the local address.
176 (maximum transmission unit)
177 is 1514 for Ethernet and 4096 for packet media.
180 is the size in bytes of the largest packet that this interface can send.
182 if specified, means that this machine should answer
183 ARP requests for the remote address.
185 does this to make remote machines appear
186 to be connected to the local Ethernet.
188 .BI remove\ "local mask"
189 Remove a local IP address from an interface.
192 Set the maximum transfer unit for this device to
194 The mtu is the maximum size of the packet including any
195 medium-specific headers.
198 Reassemble IP fragments before forwarding to this interface
203 is missing or non-zero) or disallow
205 is 0) forwarding packets between this interface and
208 .\" remainder from netif.c (thus called from devether.c),
209 .\" except add6 and ra6 from ipifc.c
217 Set the interface into promiscuous mode,
218 which makes it accept all incoming packets,
219 whether addressed to it or not.
222 marks the Ethernet packet
224 as being in use, if not already in use
228 of -1 means `all' but appears to be a no-op.
230 .BI addmulti\ Media-addr
233 on this interface as a local address.
235 .BI remmulti\ Media-addr
236 Remove the multicast address
241 Make the wireless interface scan for base stations.
244 Set the interface to pass only packet headers, not data too.
246 .\" remainder from ipifc.c; tedious, so put them last
249 .BI "add6 " "v6addr pfx-len [onlink auto validlt preflt]"
250 Add the local IPv6 address
255 See RFC 2461 §6.2.1 for more detail.
256 The remaining arguments are optional:
261 flag: address is `on-link'
267 valid life-time in seconds
270 preferred life-time in seconds
274 .BI "ra6 " "keyword value ..."
275 Set IPv6 router advertisement (RA) parameter
280 and the meanings of their values follow.
281 See RFC 2461 §6.2.1 for more detail.
282 Flags are true iff non-zero.
284 .TF "\fLreachtime\fR"
287 flag: receive and process RAs.
290 flag: generate and send RAs.
293 flag: ``Managed address configuration'',
297 flag: ``Other stateful configuration'',
301 ``maximum time allowed between sending unsolicited multicast''
302 RAs from the interface, in ms.
305 ``minimum time allowed between sending unsolicited multicast''
306 RAs from the interface, in ms.
309 ``value to be placed in MTU options sent by the router.''
313 sets the Reachable Time field in RAs sent by the router.
314 ``Zero means unspecified (by this router).''
317 sets the Retrans Timer field in RAs sent by the router.
318 ``Zero means unspecified (by this router).''
321 default value of the Cur Hop Limit field in RAs sent by the router.
322 Should be set to the ``current diameter of the Internet.''
323 ``Zero means unspecified (by this router).''
326 sets the Router Lifetime field of RAs sent from the interface, in ms.
327 Zero means the router is not to be used as a default router.
331 Reading the interface's
333 file returns information about the interface. The first line
334 is composed of white-space-separated fields, the first two
335 fields are: device and maxmtu. Subsequent lines list the
336 ip addresses assigned to that inferface. The colums are:
337 ip address, network mask, network address and valid/preferred
338 life times in milliseconds. See
346 controls information about IP routing.
347 When read, it returns one line per routing entry.
348 Each line contains six white-space-separated fields:
349 target address, target mask, address of next hop, flags,
350 tag, and interface number.
351 The entry used for routing an IP packet is the one with
352 the longest mask for which destination address ANDed with
353 target mask equals the target address.
354 The one-character flags are:
370 local unicast address
379 The tag is an arbitrary, up to 4 character, string. It is normally used to
380 indicate what routing protocol originated the route.
384 changes the route table. The messages are:
385 .TF "\fLtag \fIstring\fR"
394 with all subsequent routes added via this file descriptor.
396 .BI add\ "target mask nexthop"
397 Add the route to the table. If one already exists with the
398 same target and mask, replace it.
400 .BI remove\ "target mask"
401 Remove a route with a matching target and mask.
403 .SS "Address resolution
406 controls information about address resolution.
407 The kernel automatically updates the v4 ARP and v6 Neighbour Discovery
408 information for Ethernet interfaces.
409 When read, the file returns one line per address containing the
410 type of medium, the status of the entry (OK, WAIT), the IP
411 address, and the medium address.
414 administers the ARP information.
415 The control messages are:
416 .TF "\fLdel \fIIP-addr\fR"
422 .BI add\ "type IP-addr Media-addr"
423 Add an entry or replace an existing one for the
427 Delete an individual entry.
429 ARP entries do not time out. The ARP table is a
430 cache with an LRU replacement policy. The IP stack
431 listens for all ARP requests and, if the requester is in
432 the table, the entry is updated.
433 Also, whenever a new address is configured onto an
434 Ethernet, an ARP request is sent to help
435 update the table on other systems.
437 Currently, the only medium type is
442 .SS "Debugging and stack information
443 If any process is holding
445 open, the IP stack queues debugging information to it.
446 This is intended primarily for debugging the IP stack.
447 The information provided is implementation-defined;
448 see the source for details. Generally, what is returned is error messages
453 controls debugging. The control messages are:
454 .TF "\fLclear \fIarglist\fR"
459 is a space-separated list of items for which to enable debugging.
460 The possible items are:
480 is a space-separated list of items for which to disable debugging.
485 is non-zero, restrict debugging to only those
486 packets whose source or destination is that
491 can be read or written by
492 programs. It is normally used by
494 to leave configuration information for other programs
502 may contain up to 1024 bytes.
506 is a read-only file containing all the IP addresses
507 considered local. Each line in the file contains
508 three white-space-separated fields: IP address, usage count,
509 and flags. The usage count is the number of interfaces to which
510 the address applies. The flags are the same as for routing
512 Note that the `IPv4 route' flag will never be set.
516 .SS "Protocol directories
520 supports IP as well as several protocols that run over it:
521 TCP, UDP, RUDP, ICMP, IL, GRE, and ESP.
522 TCP and UDP provide the standard Internet
523 protocols for reliable stream and unreliable datagram
525 RUDP is a locally-developed reliable datagram protocol based on UDP.
526 ICMP is IP's catch-all control protocol used to send
527 low level error messages and to implement
529 GRE is a general encapsulation protocol.
530 ESP is the encapsulation protocol for IPsec.
531 IL provides a reliable datagram service for communication
532 between Plan 9 machines but is now deprecated.
534 Each protocol is a subdirectory of the IP stack.
535 The top level directory of each protocol contains a
539 file, and subdirectories numbered from zero to the number of connections
540 opened for this protocol.
544 file reserves a connection. The file descriptor returned from the
546 will point to the control file,
548 of the newly allocated connection.
552 string representing the number of the
554 Connections may be used either to listen for incoming calls
555 or to initiate calls to other machines.
557 A connection is controlled by writing text strings to the associated
560 After a connection has been established data may be read from
563 A connection can be actively established using the
567 A connection can be established passively by first
572 to bind to a local port and then
577 to receive incoming calls.
579 The following control messages are supported:
580 .TF "\fLremmulti \fIip\fR"
583 .BI connect\ ip-address ! port "!r " local
584 Establish a connection to the remote
590 is specified, it is used as the local port number.
595 is, the system will allocate
596 a restricted port number (less than 1024) for the connection to allow communication
602 Otherwise a free port number starting at 5000 is chosen.
603 The connect fails if the combination of local and remote address/port pairs
604 are already assigned to another port.
608 is a decimal port number or
620 calls for any port that no process has explicitly announced.
621 The local IP address cannot be set.
623 fails if the connection is already announced or connected.
627 is a decimal port number or
629 Set the local port number to
631 This exists to support emulation
632 of BSD sockets by the APE libraries (see
634 and is not otherwise used.
638 .\" Set the maximum number of unanswered (queued) incoming
639 .\" connections to an announced port to
643 .\" is set to five. If more than
645 .\" connections are pending,
646 .\" further requests for a service will be rejected.
649 Set the time to live IP field in outgoing packets to
653 Set the service type IP field in outgoing packets to
657 Don't break (UDP) connections because of ICMP errors.
659 .BI addmulti\ "ifc-ip [ mcast-ip ]"
662 on this multicast interface as a local address.
666 use it as the interface's multicast address.
671 from this multicast interface.
673 Port numbers must be in the range 1 to 32767.
675 Several files report the status of a
681 files contain the IP address and port number for the remote and local side of the
684 file contains protocol-dependent information to help debug network connections.
685 On receiving and error or EOF reading or writing the
689 file contains the reason for error.
691 A process may accept incoming connections by
698 will block until a new connection request arrives.
701 will return an open file descriptor which points to the control file of the
702 newly accepted connection.
703 This procedure will accept all calls for the
709 TCP connections are reliable point-to-point byte streams; there are no
711 A connection is determined by the address and port numbers of the two
715 files support the following additional messages:
716 .TF "\fLkeepalive\fI n\fR"
720 close down this TCP connection
723 turn on keep alive messages.
725 if given, is the milliseconds between keepalives
729 emit TCP checksums of zero if
731 is zero; otherwise, and by default,
732 TCP checksums are computed and sent normally.
734 .BI tcpporthogdefense \ onoff
738 enables the TCP port-hog defense for all TCP connections;
743 The defense is a solution to hijacked systems staking out ports
744 as a form of denial-of-service attack.
745 To avoid stateless TCP conversation hogs,
747 picks a TCP sequence number at random for keepalives.
748 If that number gets acked by the other end,
750 shuts down the connection.
752 notably ones that perform stateful inspection,
753 discard such out-of-specification keepalives,
754 so connections through such firewalls
755 will be killed after five minutes
756 by the lack of keepalives.
759 UDP connections carry unreliable and unordered datagrams. A read from
761 will return the next datagram, discarding anything
762 that doesn't fit in the read buffer.
763 A write is sent as a single datagram.
765 By default, a UDP connection is a point-to-point link.
768 establishes a local and remote address/port pair or
771 each datagram coming from a different remote address/port pair
772 establishes a new incoming connection.
773 However, many-to-one semantics is also possible.
781 then all messages sent to the announced port
782 are received on the announced connection prefixed
783 with the corresponding structure,
788 typedef struct Udphdr Udphdr;
791 uchar raddr[16]; /* V6 remote address and port */
792 uchar laddr[16]; /* V6 local address and port */
793 uchar ifcaddr[16]; /* V6 interface address (receive only) */
794 uchar rport[2]; /* remote port */
795 uchar lport[2]; /* local port */
799 Before a write, a user must prefix a similar structure to each message.
800 The system overrides the user specified local port with the announced
801 one. If the user specifies an address that isn't a unicast address in
803 that too is overridden.
804 Since the prefixed structure is the same in read and write, it is relatively
805 easy to write a server that responds to client requests by just copying new
806 data into the message body and then writing back the same buffer that was
809 In this case (writing
820 the usual sequence of
824 must be executed before performing I/O on the corresponding
829 RUDP is a reliable datagram protocol based on UDP,
830 currently only for IPv4.
831 Packets are delivered in order.
832 RUDP does not support
834 One must write either
838 followed immediately by
843 Unlike TCP, the reboot of one end of a connection does
844 not force a closing of the connection. Communications will
845 resume when the rebooted machine resumes talking. Any unacknowledged
846 packets queued before the reboot will be lost. A reboot can
847 be detected by reading the
849 file. It will contain the message
851 .BI hangup\ address ! port
857 are of the far side of the connection.
858 Retransmitting a datagram more than 10 times
859 is treated like a reboot:
860 all queued messages are dropped, an error is queued to the
862 file, and the conversation resumes.
866 files accept the following messages:
867 .TF "\fLranddrop \fI[ percent ]\fR"
874 .BI "hangup " "IP port"
875 Drop the connection to address
880 .BI "randdrop " "[ percent ]"
887 ICMP is a datagram protocol for IPv4 used to exchange control requests and
888 their responses with other machines' IP implementations.
889 ICMP is primarily a kernel-to-kernel protocol, but it is possible
890 to generate `echo request' and read `echo reply' packets from user programs.
893 ICMPv6 is the IPv6 equivalent of ICMP.
901 a user must prefix each message with a corresponding structure,
907 * user level icmpv6 with control message "headers"
909 typedef struct Icmp6hdr Icmp6hdr;
912 uchar laddr[IPaddrlen]; /* local address */
913 uchar raddr[IPaddrlen]; /* remote address */
917 In this case (writing
928 the usual sequence of
932 must be executed before performing I/O on the corresponding
937 IL is a reliable point-to-point datagram protocol that runs over IPv4.
938 Like TCP, IL delivers datagrams
939 reliably and in order. Also like TCP, a connection is
940 determined by the address and port numbers of the two ends.
941 Like UDP, each read and write transfers a single datagram.
943 IL is efficient for LANs but doesn't have the
944 congestion control features needed for use through
946 It is no longer necessary, except to communicate with old standalone
949 Its use is now deprecated.
952 GRE is the encapsulation protocol used by PPTP.
953 The kernel implements just enough of the protocol
955 Our implementation encapsulates in IPv4, per RFC 1702.
957 is not allowed in GRE, only
959 Since GRE has no port numbers, the port number in the connect
960 is actually the 16 bit
962 field in the GRE header.
964 Reads and writes transfer a
965 GRE datagram starting at the GRE header.
966 On write, the kernel fills in the
968 field with the port number specified
969 in the connect message.
974 ESP is the Encapsulating Security Payload (RFC 1827, obsoleted by RFC 4303)
975 for IPsec (RFC 4301).
976 We currently implement only tunnel mode, not transport mode.
977 It is used to set up an encrypted tunnel between machines.
978 Like GRE, ESP has no port numbers. Instead, the
981 message is the SPI (Security Association Identifier (sic)).
982 IP packets are written to and read from
984 The kernel encrypts any packets written to
986 appends a MAC, and prefixes an ESP header before
987 sending to the other end of the tunnel.
988 Received packets are checked against their MAC's,
989 decrypted, and queued for reading from
993 is the hexadecimal encoding of a key,
996 The control messages are:
997 .TF "\fLesp \fIalg secret\fR"
1000 .BI esp\ "alg secret
1001 Encrypt with the algorithm,
1006 Possible algorithms are:
1016 Use the hash algorithm,
1020 as the key for generating the MAC.
1021 Possible algorithms are:
1026 .BR aes_xcbc_mac_96 .
1029 Turn on header mode. Every buffer read from
1031 starts with 4 unused bytes, and the first 4 bytes
1032 of every buffer written to
1037 Turn off header mode.
1039 .SS "IP packet filter
1042 looks like another protocol directory.
1043 It is a packet filter built on top of IP.
1045 subdirectory represents a different filter.
1046 The connect messages written to the
1048 file describe the filter. Packets matching the filter can be read on the
1050 file. Packets written to the
1052 file are routed to an interface and transmitted.
1054 A filter is a semicolon-separated list of
1055 relations. Each relation describes a portion
1056 of a packet to match. The possible relations are:
1057 .TF "\fLdata[\fIn\fL:\fIm\fL]=\fIexpr\fR "
1061 the IP protocol number must be
1064 .BI data[ n : m ]= expr
1069 following the IP packet must match
1072 .BI iph[ n : m ]= expr
1077 of the IP packet header must match
1081 the packet must have been received on an interface whose address
1086 The source address in the packet must match
1090 The destination address in the packet must match
1098 .IB \ value | value | ...
1102 .IB \ value | value & mask
1104 If a mask is given, the relevant field is first ANDed with
1105 the mask. The result is compared against the value or list
1106 of values for a match. In the case of
1111 the value is a dot-formatted IP address and the mask is a dot-formatted
1112 IP mask. In the case of
1117 both value and mask are strings of 2 hexadecimal digits representing
1120 A packet is delivered to only one filter.
1121 The filters are merged into a single comparison tree.
1122 If two filters match the same packet, the following
1123 rules apply in order (here '>' means is preferred to):
1125 protocol > data > source > destination > interface
1127 lower data offsets > higher data offsets
1129 longer matches > shorter matches
1133 So far this has just been used to implement a version of
1135 and 6to4 tunnelling.
1142 files are read only and contain statistics useful to network monitoring.
1148 returns a list of 19 tagged and newline-separated fields representing:
1153 forwarding status (0 and 2 mean forwarding off,
1158 input address errors
1160 input packets for unknown protocols
1161 input packets discarded
1162 input packets delivered to higher level protocols
1164 output packets discarded
1165 output packets with no route
1166 timed out fragments in reassembly queue
1167 requested reassemblies
1168 successful reassemblies
1170 successful fragmentations
1171 unsuccessful fragmentations
1182 returns a list of 26 tagged and newline-separated fields representing:
1188 bad received messages
1189 unreachables received
1190 time exceededs received
1191 input parameter problems received
1192 source quenches received
1194 echo requests received
1195 echo replies received
1197 timestamp replies received
1198 address mask requests received
1199 address mask replies received
1204 input parameter problems sent
1205 source quenches sent
1210 timestamp replies sent
1211 address mask requests sent
1212 address mask replies sent
1219 returns a list of 11 tagged and newline-separated fields representing:
1224 maximum number of connections
1225 total outgoing calls
1226 total incoming calls
1227 number of established connections to be reset
1228 number of currently established connections
1231 segments retransmitted
1233 bad received segments
1234 transmission failures
1241 returns a list of 4 tagged and newline-separated fields representing:
1247 datagrams received for bad ports
1248 malformed datagrams received
1256 returns a list of 6 tagged and newline-separated fields representing:
1262 header length errors
1263 out of order messages
1264 retransmitted messages
1273 returns a list of 1 tagged number representing:
1277 header length errors
1289 .TF "\fL/lib/rfc/rfc2822"
1295 IPv6 address architecture
1303 has not been heavily used and should be considered experimental.
1304 It may disappear in favor of a more traditional packet filter in the future.
projects / plan9front.git / blob