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.
118 and use the three connections for IPv4, IPv6 and
122 Treat this interface as a packet interface. Assume
123 a user program will read and write the
125 file to receive and transmit IP packets to the kernel.
126 This is used by programs such as
128 to mediate IP packet transfer between the kernel and
129 a PPP encoded device.
131 .BI "bind netdev " path
132 Treat this interface as a packet interface.
135 and read and write the resulting file descriptor
136 to receive and transmit IP packets.
139 Treat this interface as a local loopback. Anything
140 written to it will be looped back.
146 Disassociate the physical device from an IP interface.
148 .BI add\ "local mask remote mtu " proxy
151 .BI try\ "local mask remote mtu " proxy
153 Add a local IP address to the interface.
157 address as a tentative address
158 if it's an IPv6 address.
165 arguments are all optional.
168 is the class mask for the local address.
177 (maximum transmission unit)
178 is 1514 for Ethernet and 4096 for packet media.
181 is the size in bytes of the largest packet that this interface can send.
183 if specified, means that this machine should answer
184 ARP requests for the remote address.
186 does this to make remote machines appear
187 to be connected to the local Ethernet.
189 .BI remove\ "local mask"
190 Remove a local IP address from an interface.
193 Set the maximum transfer unit for this device to
195 The mtu is the maximum size of the packet including any
196 medium-specific headers.
199 Set the maximum transmit speed in bits per second.
202 Set the maximum burst delay in milliseconds. (Default is 40ms)
205 has been set and packets in flight exceed the maximum burst
206 delay then packets send on the interface are discarded until
207 the load drops below the maximum.
212 is missing or non-zero) or disallow
214 is 0) forwarding packets between this interface and others.
217 When forwarding, allow packets from this interface to be
218 echoed back on the same interface.
221 Reassemble IP fragments before forwarding to this interface
223 .\" remainder from netif.c (thus called from devether.c),
224 .\" except add6 and ra6 from ipifc.c
232 Set the interface into promiscuous mode,
233 which makes it accept all incoming packets,
234 whether addressed to it or not.
237 marks the Ethernet packet
239 as being in use, if not already in use
243 of -1 means `all' but appears to be a no-op.
245 .BI addmulti\ Media-addr
248 on this interface as a local address.
250 .BI remmulti\ Media-addr
251 Remove the multicast address
256 Make the wireless interface scan for base stations.
259 Set the interface to pass only packet headers, not data too.
261 .\" remainder from ipifc.c; tedious, so put them last
264 .BI "add6 " "v6addr pfx-len [onlink auto validlt preflt]"
265 Add the local IPv6 address
270 See RFC 2461 §6.2.1 for more detail.
271 The remaining arguments are optional:
276 flag: address is `on-link'
282 valid life-time in seconds
285 preferred life-time in seconds
290 Remove local IPv6 addresses that have expired ther
293 .BI "ra6 " "keyword value ..."
294 Set IPv6 router advertisement (RA) parameter
299 and the meanings of their values follow.
300 See RFC 2461 §6.2.1 for more detail.
301 Flags are true iff non-zero.
303 .TF "\fLreachtime\fR"
306 flag: receive and process RAs.
309 flag: generate and send RAs.
312 flag: ``Managed address configuration'',
316 flag: ``Other stateful configuration'',
320 ``maximum time allowed between sending unsolicited multicast''
321 RAs from the interface, in ms.
324 ``minimum time allowed between sending unsolicited multicast''
325 RAs from the interface, in ms.
328 ``value to be placed in MTU options sent by the router.''
332 sets the Reachable Time field in RAs sent by the router.
333 ``Zero means unspecified (by this router).''
336 sets the Retrans Timer field in RAs sent by the router.
337 ``Zero means unspecified (by this router).''
340 default value of the Cur Hop Limit field in RAs sent by the router.
341 Should be set to the ``current diameter of the Internet.''
342 ``Zero means unspecified (by this router).''
345 sets the Router Lifetime field of RAs sent from the interface, in ms.
346 Zero means the router is not to be used as a default router.
350 Reading the interface's
352 file returns information about the interface. The first line
353 is composed of white-space-separated fields, the first two
354 fields are: device and maxmtu. Subsequent lines list the
355 ip addresses assigned to that inferface. The colums are:
356 ip address, network mask, network address and valid/preferred
357 life times in milliseconds. See
365 controls information about IP routing.
366 When read, it returns one line per routing entry.
367 Each line contains eight white-space-separated fields:
368 target address, target mask, address of next hop, flags,
369 tag, interface number, source address, source mask.
370 The entry used for routing an IP packet is the one with
371 the longest destination and source mask for which
372 destination address ANDed with target mask equals the
373 target and also the source ANDed with the source mask equals
375 The one-character flags are:
391 local unicast address
400 The tag is an arbitrary, up to 4 character, string. It is normally used to
401 indicate what routing protocol originated the route.
405 changes the route table. The messages are:
406 .TF "\fLtag \fIstring\fR"
410 Remove routes of the specified tag, or all routes if
417 with all subsequent routes added via this file descriptor.
419 .BI add\ "target mask nexthop"
421 .BI add\ "target mask nexthop interface"
423 .BI add\ "target mask nexthop source smask"
425 .BI add\ "target mask nexthop interface source smask"
427 .BI add\ "target mask nexthop tag interface source smask"
429 .BI add\ "target mask nexthop type tag interface source smask"
430 Add the route to the table. If one already exists with the
431 same target and mask, replace it. The
433 can be given as eigther the interface number or a local
434 IP address on the desired interface.
436 .BI remove\ "target mask"
438 .BI remove\ "target mask nexthop"
440 .BI remove\ "target mask source smask"
442 .BI remove\ "target mask nexthop source smask"
444 .BI remove\ "target mask nexthop interface source smask"
446 .BI remove\ "target mask nexthop tag interface source smask"
448 .BI remove\ "target mask nexthop type tag interface source smask"
449 Remove the matching route.
451 .SS "Address resolution
454 controls information about address resolution.
455 The kernel automatically updates the v4 ARP and v6 Neighbour Discovery
456 information for Ethernet interfaces.
457 When read, the file returns one line per address containing the
458 type of medium, the status of the entry (OK, WAIT), the IP
459 address, the medium address and the IP address of the interface
460 where the entry is valid.
463 administers the ARP information.
464 The control messages are:
465 .TF "\fLdel \fIIP-addr\fR"
471 .BI add\ "type IP-addr Media-addr Interface-IP-addr"
472 Add an entry or replace an existing one for the
473 same IP address. The optional interface IP address specifies the
474 interface where the ARP entry will be valid. This is needed
475 for IPv6 link local addresses.
478 Delete an individual entry.
480 ARP entries do not time out. The ARP table is a
481 cache with an LRU replacement policy. The IP stack
482 listens for all ARP requests and, if the requester is in
483 the table, the entry is updated.
484 Also, whenever a new address is configured onto an
485 Ethernet, an ARP request is sent to help
486 update the table on other systems.
488 Currently, the only medium type is
493 .SS "Debugging and stack information
494 If any process is holding
496 open, the IP stack queues debugging information to it.
497 This is intended primarily for debugging the IP stack.
498 The information provided is implementation-defined;
499 see the source for details. Generally, what is returned is error messages
504 controls debugging. The control messages are:
505 .TF "\fLclear \fIarglist\fR"
510 is a space-separated list of items for which to enable debugging.
511 The possible items are:
531 is a space-separated list of items for which to disable debugging.
536 is non-zero, restrict debugging to only those
537 packets whose source or destination is that
542 can be read or written by
543 programs. It is normally used by
545 to leave configuration information for other programs
553 may contain up to 1024 bytes.
557 is a read-only file containing all the IP addresses
558 considered local. Each line in the file contains
559 three white-space-separated fields: IP address, usage count,
560 and flags. The usage count is the number of interfaces to which
561 the address applies. The flags are the same as for routing
566 .SS "Protocol directories
570 supports IP as well as several protocols that run over it:
571 TCP, UDP, RUDP, ICMP, IL, GRE, and ESP.
572 TCP and UDP provide the standard Internet
573 protocols for reliable stream and unreliable datagram
575 RUDP is a locally-developed reliable datagram protocol based on UDP.
576 ICMP is IP's catch-all control protocol used to send
577 low level error messages and to implement
579 GRE is a general encapsulation protocol.
580 ESP is the encapsulation protocol for IPsec.
581 IL provides a reliable datagram service for communication
582 between Plan 9 machines but is now deprecated.
584 Each protocol is a subdirectory of the IP stack.
585 The top level directory of each protocol contains a
589 file, and subdirectories numbered from zero to the number of connections
590 opened for this protocol.
594 file reserves a connection. The file descriptor returned from the
596 will point to the control file,
598 of the newly allocated connection.
602 string representing the number of the
604 Connections may be used either to listen for incoming calls
605 or to initiate calls to other machines.
607 A connection is controlled by writing text strings to the associated
610 After a connection has been established data may be read from
613 A connection can be actively established using the
617 A connection can be established passively by first
622 to bind to a local port and then
627 to receive incoming calls.
629 The following control messages are supported:
630 .TF "\fLremmulti \fIip\fR"
633 .BI connect\ ip-address ! port "!r " local
634 Establish a connection to the remote
640 is specified, it is used as the local port number.
645 is, the system will allocate
646 a restricted port number (less than 1024) for the connection to allow communication
652 Otherwise a free port number starting at 5000 is chosen.
653 The connect fails if the combination of local and remote address/port pairs
654 are already assigned to another port.
658 is a decimal port number or
670 calls for any port that no process has explicitly announced.
671 The local IP address cannot be set.
673 fails if the connection is already announced or connected.
677 is a decimal port number or
679 Set the local port number to
681 This exists to support emulation
682 of BSD sockets by the APE libraries (see
684 and is not otherwise used.
688 .\" Set the maximum number of unanswered (queued) incoming
689 .\" connections to an announced port to
693 .\" is set to five. If more than
695 .\" connections are pending,
696 .\" further requests for a service will be rejected.
699 Set the time to live IP field in outgoing packets to
703 Set the service type IP field in outgoing packets to
707 Don't break (UDP) connections because of ICMP errors.
709 .BI addmulti\ "ifc-ip [ mcast-ip ]"
712 on this multicast interface as a local address.
716 use it as the interface's multicast address.
721 from this multicast interface.
723 Port numbers must be in the range 1 to 32767.
725 Several files report the status of a
731 files contain the IP address and port number for the remote and local side of the
734 file contains protocol-dependent information to help debug network connections.
735 On receiving and error or EOF reading or writing the
739 file contains the reason for error.
741 A process may accept incoming connections by
748 will block until a new connection request arrives.
751 will return an open file descriptor which points to the control file of the
752 newly accepted connection.
753 This procedure will accept all calls for the
759 TCP connections are reliable point-to-point byte streams; there are no
761 A connection is determined by the address and port numbers of the two
765 files support the following additional messages:
766 .TF "\fLkeepalive\fI n\fR"
770 close down this TCP connection
773 turn on keep alive messages.
775 if given, is the milliseconds between keepalives
779 emit TCP checksums of zero if
781 is zero; otherwise, and by default,
782 TCP checksums are computed and sent normally.
784 .BI tcpporthogdefense \ onoff
788 enables the TCP port-hog defense for all TCP connections;
793 The defense is a solution to hijacked systems staking out ports
794 as a form of denial-of-service attack.
795 To avoid stateless TCP conversation hogs,
797 picks a TCP sequence number at random for keepalives.
798 If that number gets acked by the other end,
800 shuts down the connection.
802 notably ones that perform stateful inspection,
803 discard such out-of-specification keepalives,
804 so connections through such firewalls
805 will be killed after five minutes
806 by the lack of keepalives.
809 UDP connections carry unreliable and unordered datagrams. A read from
811 will return the next datagram, discarding anything
812 that doesn't fit in the read buffer.
813 A write is sent as a single datagram.
815 By default, a UDP connection is a point-to-point link.
818 establishes a local and remote address/port pair or
821 each datagram coming from a different remote address/port pair
822 establishes a new incoming connection.
823 However, many-to-one semantics is also possible.
831 then all messages sent to the announced port
832 are received on the announced connection prefixed
833 with the corresponding structure,
838 typedef struct Udphdr Udphdr;
841 uchar raddr[16]; /* V6 remote address and port */
842 uchar laddr[16]; /* V6 local address and port */
843 uchar ifcaddr[16]; /* V6 interface address (receive only) */
844 uchar rport[2]; /* remote port */
845 uchar lport[2]; /* local port */
849 Before a write, a user must prefix a similar structure to each message.
850 The system overrides the user specified local port with the announced
851 one. If the user specifies an address that isn't a unicast address in
853 that too is overridden.
854 Since the prefixed structure is the same in read and write, it is relatively
855 easy to write a server that responds to client requests by just copying new
856 data into the message body and then writing back the same buffer that was
859 In this case (writing
870 the usual sequence of
874 must be executed before performing I/O on the corresponding
879 RUDP is a reliable datagram protocol based on UDP,
880 currently only for IPv4.
881 Packets are delivered in order.
882 RUDP does not support
884 One must write either
888 followed immediately by
893 Unlike TCP, the reboot of one end of a connection does
894 not force a closing of the connection. Communications will
895 resume when the rebooted machine resumes talking. Any unacknowledged
896 packets queued before the reboot will be lost. A reboot can
897 be detected by reading the
899 file. It will contain the message
901 .BI hangup\ address ! port
907 are of the far side of the connection.
908 Retransmitting a datagram more than 10 times
909 is treated like a reboot:
910 all queued messages are dropped, an error is queued to the
912 file, and the conversation resumes.
916 files accept the following messages:
917 .TF "\fLranddrop \fI[ percent ]\fR"
924 .BI "hangup " "IP port"
925 Drop the connection to address
930 .BI "randdrop " "[ percent ]"
937 ICMP is a datagram protocol for IPv4 used to exchange control requests and
938 their responses with other machines' IP implementations.
939 ICMP is primarily a kernel-to-kernel protocol, but it is possible
940 to generate `echo request' and read `echo reply' packets from user programs.
943 ICMPv6 is the IPv6 equivalent of ICMP.
951 a user must prefix each message with a corresponding structure,
957 * user level icmpv6 with control message "headers"
959 typedef struct Icmp6hdr Icmp6hdr;
962 uchar laddr[IPaddrlen]; /* local address */
963 uchar raddr[IPaddrlen]; /* remote address */
967 In this case (writing
978 the usual sequence of
982 must be executed before performing I/O on the corresponding
987 IL is a reliable point-to-point datagram protocol that runs over IPv4.
988 Like TCP, IL delivers datagrams
989 reliably and in order. Also like TCP, a connection is
990 determined by the address and port numbers of the two ends.
991 Like UDP, each read and write transfers a single datagram.
993 IL is efficient for LANs but doesn't have the
994 congestion control features needed for use through
996 It is no longer necessary, except to communicate with old standalone
999 Its use is now deprecated.
1002 GRE is the encapsulation protocol used by PPTP.
1003 The kernel implements just enough of the protocol
1005 Our implementation encapsulates in IPv4, per RFC 1702.
1007 is not allowed in GRE, only
1009 Since GRE has no port numbers, the port number in the connect
1010 is actually the 16 bit
1012 field in the GRE header.
1014 Reads and writes transfer a
1015 GRE datagram starting at the GRE header.
1016 On write, the kernel fills in the
1018 field with the port number specified
1019 in the connect message.
1024 ESP is the Encapsulating Security Payload (RFC 1827, obsoleted by RFC 4303)
1025 for IPsec (RFC 4301).
1026 We currently implement only tunnel mode, not transport mode.
1027 It is used to set up an encrypted tunnel between machines.
1028 Like GRE, ESP has no port numbers. Instead, the
1031 message is the SPI (Security Association Identifier (sic)).
1032 IP packets are written to and read from
1034 The kernel encrypts any packets written to
1036 appends a MAC, and prefixes an ESP header before
1037 sending to the other end of the tunnel.
1038 Received packets are checked against their MAC's,
1039 decrypted, and queued for reading from
1043 is the hexadecimal encoding of a key,
1046 The control messages are:
1047 .TF "\fLesp \fIalg secret\fR"
1050 .BI esp\ "alg secret
1051 Encrypt with the algorithm,
1056 Possible algorithms are:
1066 Use the hash algorithm,
1070 as the key for generating the MAC.
1071 Possible algorithms are:
1076 .BR aes_xcbc_mac_96 .
1079 Turn on header mode. Every buffer read from
1081 starts with 4 unused bytes, and the first 4 bytes
1082 of every buffer written to
1087 Turn off header mode.
1089 .SS "IP packet filter
1092 looks like another protocol directory.
1093 It is a packet filter built on top of IP.
1095 subdirectory represents a different filter.
1096 The connect messages written to the
1098 file describe the filter. Packets matching the filter can be read on the
1100 file. Packets written to the
1102 file are routed to an interface and transmitted.
1104 A filter is a semicolon-separated list of
1105 relations. Each relation describes a portion
1106 of a packet to match. The possible relations are:
1107 .TF "\fLdata[\fIn\fL:\fIm\fL]=\fIexpr\fR "
1111 the IP protocol number must be
1114 .BI data[ n : m ]= expr
1119 following the IP packet must match
1122 .BI iph[ n : m ]= expr
1127 of the IP packet header must match
1131 the packet must have been received on an interface whose address
1136 The source address in the packet must match
1140 The destination address in the packet must match
1148 .IB \ value | value | ...
1152 .IB \ value | value & mask
1154 If a mask is given, the relevant field is first ANDed with
1155 the mask. The result is compared against the value or list
1156 of values for a match. In the case of
1161 the value is a dot-formatted IP address and the mask is a dot-formatted
1162 IP mask. In the case of
1167 both value and mask are strings of 2 hexadecimal digits representing
1170 A packet is delivered to only one filter.
1171 The filters are merged into a single comparison tree.
1172 If two filters match the same packet, the following
1173 rules apply in order (here '>' means is preferred to):
1175 protocol > data > source > destination > interface
1177 lower data offsets > higher data offsets
1179 longer matches > shorter matches
1183 So far this has just been used to implement a version of
1185 and 6to4 tunnelling.
1192 files are read only and contain statistics useful to network monitoring.
1198 returns a list of 19 tagged and newline-separated fields representing:
1203 forwarding status (0 and 2 mean forwarding off,
1208 input address errors
1210 input packets for unknown protocols
1211 input packets discarded
1212 input packets delivered to higher level protocols
1214 output packets discarded
1215 output packets with no route
1216 timed out fragments in reassembly queue
1217 requested reassemblies
1218 successful reassemblies
1220 successful fragmentations
1221 unsuccessful fragmentations
1232 returns a list of 26 tagged and newline-separated fields representing:
1238 bad received messages
1239 unreachables received
1240 time exceededs received
1241 input parameter problems received
1242 source quenches received
1244 echo requests received
1245 echo replies received
1247 timestamp replies received
1248 address mask requests received
1249 address mask replies received
1254 input parameter problems sent
1255 source quenches sent
1260 timestamp replies sent
1261 address mask requests sent
1262 address mask replies sent
1269 returns a list of 11 tagged and newline-separated fields representing:
1274 maximum number of connections
1275 total outgoing calls
1276 total incoming calls
1277 number of established connections to be reset
1278 number of currently established connections
1281 segments retransmitted
1283 bad received segments
1284 transmission failures
1291 returns a list of 4 tagged and newline-separated fields representing:
1297 datagrams received for bad ports
1298 malformed datagrams received
1306 returns a list of 6 tagged and newline-separated fields representing:
1312 header length errors
1313 out of order messages
1314 retransmitted messages
1323 returns a list of 1 tagged number representing:
1327 header length errors
1339 .TF "\fL/lib/rfc/rfc2822"
1345 IPv6 address architecture
1353 has not been heavily used and should be considered experimental.
1354 It may disappear in favor of a more traditional packet filter in the future.