3 ip, esp, gre, icmp, icmpv6, ipmux, rudp, tcp, udp \- network protocols over IP
7 .B bind -a #I\fIspec\fP /net
13 .BI /net/ipifc/ n /status
14 .BI /net/ipifc/ n /ctl
38 .BI /net/tcp/ n /local
39 .BI /net/tcp/ n /remote
40 .BI /net/tcp/ n /status
41 .BI /net/tcp/ n /listen
48 device provides the interface to Internet Protocol stacks.
50 is an integer from 0 to 15 identifying a stack.
51 Each stack implements IPv4 and IPv6.
52 Each stack is independent of all others:
53 the only information transfer between them is via programs that
54 mount multiple stacks.
55 Normally a system uses only one stack.
56 However multiple stacks can be used for debugging
57 new IP networks or implementing firewalls or proxy
60 All addresses used are 16-byte IPv6 addresses.
61 IPv4 addresses are a subset of the IPv6 addresses and both standard
64 In binary representation, all v4 addresses start with the 12 bytes, in hex:
67 00 00 00 00 00 00 00 00 00 00 ff ff
70 .SS "Configuring interfaces
71 Each stack may have multiple interfaces and each interface
72 may have multiple addresses.
79 file, and numbered subdirectories for each physical interface.
83 file reserves an interface.
84 The file descriptor returned from the
86 will point to the control file,
88 of the newly allocated interface.
91 returns a text string representing the number of the interface.
94 alters aspects of the interface.
97 messages are those described under
98 .B "Protocol directories"
100 .TF "\fLbind loopback\fR"
106 .BI "bind ether " path
107 Treat the device mounted at
109 as an Ethernet medium carrying IP and ARP packets
110 and associate it with this interface.
116 and use the two connections for IPv4 and
120 Treat this interface as a packet interface. Assume
121 a user program will read and write the
123 file to receive and transmit IP packets to the kernel.
124 This is used by programs such as
126 to mediate IP packet transfer between the kernel and
127 a PPP encoded device.
129 .BI "bind netdev " path
130 Treat this interface as a packet interface.
133 and read and write the resulting file descriptor
134 to receive and transmit IP packets.
137 Treat this interface as a local loopback. Anything
138 written to it will be looped back.
144 Disassociate the physical device from an IP interface.
146 .BI add\ "local mask remote mtu " proxy
149 .BI try\ "local mask remote mtu " proxy
151 Add a local IP address to the interface.
155 address as a tentative address
156 if it's an IPv6 address.
163 arguments are all optional.
166 is the class mask for the local address.
175 (maximum transmission unit)
176 is 1514 for Ethernet and 4096 for packet media.
179 is the size in bytes of the largest packet that this interface can send.
181 if specified, means that this machine should answer
182 ARP requests for the remote address.
184 does this to make remote machines appear
185 to be connected to the local Ethernet.
187 .BI remove\ "local mask"
188 Remove a local IP address from an interface.
191 Set the maximum transfer unit for this device to
193 The mtu is the maximum size of the packet including any
194 medium-specific headers.
197 Reassemble IP fragments before forwarding to this interface
202 is missing or non-zero) or disallow
204 is 0) forwarding packets between this interface and
207 .\" remainder from netif.c (thus called from devether.c),
208 .\" except add6 and ra6 from ipifc.c
216 Set the interface into promiscuous mode,
217 which makes it accept all incoming packets,
218 whether addressed to it or not.
221 marks the Ethernet packet
223 as being in use, if not already in use
227 of -1 means `all' but appears to be a no-op.
229 .BI addmulti\ Media-addr
232 on this interface as a local address.
234 .BI remmulti\ Media-addr
235 Remove the multicast address
240 Make the wireless interface scan for base stations.
243 Set the interface to pass only packet headers, not data too.
245 .\" remainder from ipifc.c; tedious, so put them last
248 .BI "add6 " "v6addr pfx-len [onlink auto validlt preflt]"
249 Add the local IPv6 address
254 See RFC 2461 §6.2.1 for more detail.
255 The remaining arguments are optional:
260 flag: address is `on-link'
266 valid life-time in seconds
269 preferred life-time in seconds
273 .BI "ra6 " "keyword value ..."
274 Set IPv6 router advertisement (RA) parameter
279 and the meanings of their values follow.
280 See RFC 2461 §6.2.1 for more detail.
281 Flags are true iff non-zero.
283 .TF "\fLreachtime\fR"
286 flag: receive and process RAs.
289 flag: generate and send RAs.
292 flag: ``Managed address configuration'',
296 flag: ``Other stateful configuration'',
300 ``maximum time allowed between sending unsolicited multicast''
301 RAs from the interface, in ms.
304 ``minimum time allowed between sending unsolicited multicast''
305 RAs from the interface, in ms.
308 ``value to be placed in MTU options sent by the router.''
312 sets the Reachable Time field in RAs sent by the router.
313 ``Zero means unspecified (by this router).''
316 sets the Retrans Timer field in RAs sent by the router.
317 ``Zero means unspecified (by this router).''
320 default value of the Cur Hop Limit field in RAs sent by the router.
321 Should be set to the ``current diameter of the Internet.''
322 ``Zero means unspecified (by this router).''
325 sets the Router Lifetime field of RAs sent from the interface, in ms.
326 Zero means the router is not to be used as a default router.
330 Reading the interface's
332 file returns information about the interface, one line for each
333 local address on that interface. The first line
334 has 9 white-space-separated fields: device, mtu, local address,
335 mask, remote or network address, packets in, packets out, input errors,
336 output errors. Each subsequent line contains all but the device and mtu.
345 controls information about IP routing.
346 When read, it returns one line per routing entry.
347 Each line contains six white-space-separated fields:
348 target address, target mask, address of next hop, flags,
349 tag, and interface number.
350 The entry used for routing an IP packet is the one with
351 the longest mask for which destination address ANDed with
352 target mask equals the target address.
353 The one-character flags are:
369 local unicast address
378 The tag is an arbitrary, up to 4 character, string. It is normally used to
379 indicate what routing protocol originated the route.
383 changes the route table. The messages are:
384 .TF "\fLtag \fIstring\fR"
393 with all subsequent routes added via this file descriptor.
395 .BI add\ "target mask nexthop"
396 Add the route to the table. If one already exists with the
397 same target and mask, replace it.
399 .BI remove\ "target mask"
400 Remove a route with a matching target and mask.
402 .SS "Address resolution
405 controls information about address resolution.
406 The kernel automatically updates the v4 ARP and v6 Neighbour Discovery
407 information for Ethernet interfaces.
408 When read, the file returns one line per address containing the
409 type of medium, the status of the entry (OK, WAIT), the IP
410 address, and the medium address.
413 administers the ARP information.
414 The control messages are:
415 .TF "\fLdel \fIIP-addr\fR"
421 .BI add\ "type IP-addr Media-addr"
422 Add an entry or replace an existing one for the
426 Delete an individual entry.
428 ARP entries do not time out. The ARP table is a
429 cache with an LRU replacement policy. The IP stack
430 listens for all ARP requests and, if the requester is in
431 the table, the entry is updated.
432 Also, whenever a new address is configured onto an
433 Ethernet, an ARP request is sent to help
434 update the table on other systems.
436 Currently, the only medium type is
441 .SS "Debugging and stack information
442 If any process is holding
444 open, the IP stack queues debugging information to it.
445 This is intended primarily for debugging the IP stack.
446 The information provided is implementation-defined;
447 see the source for details. Generally, what is returned is error messages
452 controls debugging. The control messages are:
453 .TF "\fLclear \fIarglist\fR"
458 is a space-separated list of items for which to enable debugging.
459 The possible items are:
477 is a space-separated list of items for which to disable debugging.
482 is non-zero, restrict debugging to only those
483 packets whose source or destination is that
488 can be read or written by
489 programs. It is normally used by
491 to leave configuration information for other programs
499 may contain up to 1024 bytes.
503 is a read-only file containing all the IP addresses
504 considered local. Each line in the file contains
505 three white-space-separated fields: IP address, usage count,
506 and flags. The usage count is the number of interfaces to which
507 the address applies. The flags are the same as for routing
509 Note that the `IPv4 route' flag will never be set.
513 .SS "Protocol directories
517 supports IP as well as several protocols that run over it:
518 TCP, UDP, RUDP, ICMP, GRE, and ESP.
519 TCP and UDP provide the standard Internet
520 protocols for reliable stream and unreliable datagram
522 RUDP is a locally-developed reliable datagram protocol based on UDP.
523 ICMP is IP's catch-all control protocol used to send
524 low level error messages and to implement
526 GRE is a general encapsulation protocol.
527 ESP is the encapsulation protocol for IPsec.
528 IL provided a reliable datagram service for communication
529 between Plan 9 machines over IPv4, but is no longer part of the system.
531 Each protocol is a subdirectory of the IP stack.
532 The top level directory of each protocol contains a
536 file, and subdirectories numbered from zero to the number of connections
537 opened for this protocol.
541 file reserves a connection. The file descriptor returned from the
543 will point to the control file,
545 of the newly allocated connection.
549 string representing the number of the
551 Connections may be used either to listen for incoming calls
552 or to initiate calls to other machines.
554 A connection is controlled by writing text strings to the associated
557 After a connection has been established data may be read from
560 A connection can be actively established using the
564 A connection can be established passively by first
569 to bind to a local port and then
574 to receive incoming calls.
576 The following control messages are supported:
577 .TF "\fLremmulti \fIip\fR"
580 .BI connect\ ip-address ! port "!r " local
581 Establish a connection to the remote
587 is specified, it is used as the local port number.
592 is, the system will allocate
593 a restricted port number (less than 1024) for the connection to allow communication
599 Otherwise a free port number starting at 5000 is chosen.
600 The connect fails if the combination of local and remote address/port pairs
601 are already assigned to another port.
605 is a decimal port number or
617 calls for any port that no process has explicitly announced.
618 The local IP address cannot be set.
620 fails if the connection is already announced or connected.
624 is a decimal port number or
626 Set the local port number to
628 This exists to support emulation
629 of BSD sockets by the APE libraries (see
631 and is not otherwise used.
635 .\" Set the maximum number of unanswered (queued) incoming
636 .\" connections to an announced port to
640 .\" is set to five. If more than
642 .\" connections are pending,
643 .\" further requests for a service will be rejected.
646 Set the time to live IP field in outgoing packets to
650 Set the service type IP field in outgoing packets to
654 Don't break (UDP) connections because of ICMP errors.
656 .BI addmulti\ "ifc-ip [ mcast-ip ]"
659 on this multicast interface as a local address.
663 use it as the interface's multicast address.
668 from this multicast interface.
670 Port numbers must be in the range 1 to 32767.
672 Several files report the status of a
678 files contain the IP address and port number for the remote and local side of the
681 file contains protocol-dependent information to help debug network connections.
682 On receiving and error or EOF reading or writing the
686 file contains the reason for error.
688 A process may accept incoming connections by
695 will block until a new connection request arrives.
698 will return an open file descriptor which points to the control file of the
699 newly accepted connection.
700 This procedure will accept all calls for the
706 TCP connections are reliable point-to-point byte streams; there are no
708 A connection is determined by the address and port numbers of the two
712 files support the following additional messages:
713 .TF "\fLkeepalive\fI n\fR"
717 close down this TCP connection
720 turn on keep alive messages.
722 if given, is the milliseconds between keepalives
726 emit TCP checksums of zero if
728 is zero; otherwise, and by default,
729 TCP checksums are computed and sent normally.
731 .BI tcpporthogdefense \ onoff
735 enables the TCP port-hog defense for all TCP connections;
740 The defense is a solution to hijacked systems staking out ports
741 as a form of denial-of-service attack.
742 To avoid stateless TCP conversation hogs,
744 picks a TCP sequence number at random for keepalives.
745 If that number gets acked by the other end,
747 shuts down the connection.
749 notably ones that perform stateful inspection,
750 discard such out-of-specification keepalives,
751 so connections through such firewalls
752 will be killed after five minutes
753 by the lack of keepalives.
756 UDP connections carry unreliable and unordered datagrams. A read from
758 will return the next datagram, discarding anything
759 that doesn't fit in the read buffer.
760 A write is sent as a single datagram.
762 By default, a UDP connection is a point-to-point link.
765 establishes a local and remote address/port pair or
768 each datagram coming from a different remote address/port pair
769 establishes a new incoming connection.
770 However, many-to-one semantics is also possible.
778 then all messages sent to the announced port
779 are received on the announced connection prefixed
780 with the corresponding structure,
785 typedef struct Udphdr Udphdr;
788 uchar raddr[16]; /* V6 remote address and port */
789 uchar laddr[16]; /* V6 local address and port */
790 uchar ifcaddr[16]; /* V6 interface address (receive only) */
791 uchar rport[2]; /* remote port */
792 uchar lport[2]; /* local port */
796 Before a write, a user must prefix a similar structure to each message.
797 The system overrides the user specified local port with the announced
798 one. If the user specifies an address that isn't a unicast address in
800 that too is overridden.
801 Since the prefixed structure is the same in read and write, it is relatively
802 easy to write a server that responds to client requests by just copying new
803 data into the message body and then writing back the same buffer that was
806 In this case (writing
817 the usual sequence of
821 must be executed before performing I/O on the corresponding
826 RUDP is a reliable datagram protocol based on UDP,
827 currently only for IPv4.
828 Packets are delivered in order.
829 RUDP does not support
831 One must write either
835 followed immediately by
840 Unlike TCP, the reboot of one end of a connection does
841 not force a closing of the connection. Communications will
842 resume when the rebooted machine resumes talking. Any unacknowledged
843 packets queued before the reboot will be lost. A reboot can
844 be detected by reading the
846 file. It will contain the message
848 .BI hangup\ address ! port
854 are of the far side of the connection.
855 Retransmitting a datagram more than 10 times
856 is treated like a reboot:
857 all queued messages are dropped, an error is queued to the
859 file, and the conversation resumes.
863 files accept the following messages:
864 .TF "\fLranddrop \fI[ percent ]\fR"
871 .BI "hangup " "IP port"
872 Drop the connection to address
877 .BI "randdrop " "[ percent ]"
884 ICMP is a datagram protocol for IPv4 used to exchange control requests and
885 their responses with other machines' IP implementations.
886 ICMP is primarily a kernel-to-kernel protocol, but it is possible
887 to generate `echo request' and read `echo reply' packets from user programs.
890 ICMPv6 is the IPv6 equivalent of ICMP.
898 a user must prefix each message with a corresponding structure,
904 * user level icmpv6 with control message "headers"
906 typedef struct Icmp6hdr Icmp6hdr;
909 uchar laddr[IPaddrlen]; /* local address */
910 uchar raddr[IPaddrlen]; /* remote address */
914 In this case (writing
925 the usual sequence of
929 must be executed before performing I/O on the corresponding
934 GRE is the encapsulation protocol used by PPTP.
935 The kernel implements just enough of the protocol
937 Our implementation encapsulates in IPv4, per RFC 1702.
939 is not allowed in GRE, only
941 Since GRE has no port numbers, the port number in the connect
942 is actually the 16 bit
944 field in the GRE header.
946 Reads and writes transfer a
947 GRE datagram starting at the GRE header.
948 On write, the kernel fills in the
950 field with the port number specified
951 in the connect message.
956 ESP is the Encapsulating Security Payload (RFC 1827, obsoleted by RFC 4303)
957 for IPsec (RFC 4301).
958 We currently implement only tunnel mode, not transport mode.
959 It is used to set up an encrypted tunnel between machines.
960 Like GRE, ESP has no port numbers. Instead, the
963 message is the SPI (Security Association Identifier (sic)).
964 IP packets are written to and read from
966 The kernel encrypts any packets written to
968 appends a MAC, and prefixes an ESP header before
969 sending to the other end of the tunnel.
970 Received packets are checked against their MAC's,
971 decrypted, and queued for reading from
975 is the hexadecimal encoding of a key,
978 The control messages are:
979 .TF "\fLesp \fIalg secret\fR"
983 Encrypt with the algorithm,
988 Possible algorithms are:
998 Use the hash algorithm,
1002 as the key for generating the MAC.
1003 Possible algorithms are:
1008 .BR aes_xcbc_mac_96 .
1011 Turn on header mode. Every buffer read from
1013 starts with 4 unused bytes, and the first 4 bytes
1014 of every buffer written to
1019 Turn off header mode.
1021 .SS "IP packet filter
1024 looks like another protocol directory.
1025 It is a packet filter built on top of IP.
1027 subdirectory represents a different filter.
1028 The connect messages written to the
1030 file describe the filter. Packets matching the filter can be read on the
1032 file. Packets written to the
1034 file are routed to an interface and transmitted.
1036 A filter is a semicolon-separated list of
1037 relations. Each relation describes a portion
1038 of a packet to match. The possible relations are:
1039 .TF "\fLdata[\fIn\fL:\fIm\fL]=\fIexpr\fR "
1043 the IP protocol number must be
1046 .BI data[ n : m ]= expr
1051 following the IP packet must match
1054 .BI iph[ n : m ]= expr
1059 of the IP packet header must match
1063 the packet must have been received on an interface whose address
1068 The source address in the packet must match
1072 The destination address in the packet must match
1080 .IB \ value | value | ...
1084 .IB \ value | value & mask
1086 If a mask is given, the relevant field is first ANDed with
1087 the mask. The result is compared against the value or list
1088 of values for a match. In the case of
1093 the value is a dot-formatted IP address and the mask is a dot-formatted
1094 IP mask. In the case of
1099 both value and mask are strings of 2 hexadecimal digits representing
1102 A packet is delivered to only one filter.
1103 The filters are merged into a single comparison tree.
1104 If two filters match the same packet, the following
1105 rules apply in order (here '>' means is preferred to):
1107 protocol > data > source > destination > interface
1109 lower data offsets > higher data offsets
1111 longer matches > shorter matches
1115 So far this has just been used to implement a version of
1117 and 6to4 tunnelling.
1124 files are read only and contain statistics useful to network monitoring.
1130 returns a list of 19 tagged and newline-separated fields representing:
1135 forwarding status (0 and 2 mean forwarding off,
1140 input address errors
1142 input packets for unknown protocols
1143 input packets discarded
1144 input packets delivered to higher level protocols
1146 output packets discarded
1147 output packets with no route
1148 timed out fragments in reassembly queue
1149 requested reassemblies
1150 successful reassemblies
1152 successful fragmentations
1153 unsuccessful fragmentations
1164 returns a list of 26 tagged and newline-separated fields representing:
1170 bad received messages
1171 unreachables received
1172 time exceededs received
1173 input parameter problems received
1174 source quenches received
1176 echo requests received
1177 echo replies received
1179 timestamp replies received
1180 address mask requests received
1181 address mask replies received
1186 input parameter problems sent
1187 source quenches sent
1192 timestamp replies sent
1193 address mask requests sent
1194 address mask replies sent
1201 returns a list of 11 tagged and newline-separated fields representing:
1206 maximum number of connections
1207 total outgoing calls
1208 total incoming calls
1209 number of established connections to be reset
1210 number of currently established connections
1213 segments retransmitted
1215 bad received segments
1216 transmission failures
1223 returns a list of 4 tagged and newline-separated fields representing:
1229 datagrams received for bad ports
1230 malformed datagrams received
1238 returns a list of 1 tagged number representing:
1242 header length errors
1254 .TF "\fL/lib/rfc/rfc2822"
1260 IPv6 address architecture
1268 has not been heavily used and should be considered experimental.
1269 It may disappear in favor of a more traditional packet filter in the future.
projects / plan9front.git / blob