IP(3) IP(3)
NAME
ip - network protocols over IP
SYNOPSIS
bind -a #Ispec /net
/net/ipifc
/net/ipifc/clone
/net/ipifc/stats
/net/ipifc/n
/net/ipifc/n/status
/net/ipifc/n/ctl
...
/net/arp
/net/log
/net/ndb
/net/iproute
/net/ipselftab
/net/esp
/net/gre
/net/icmp
/net/il
/net/ipmux
/net/rudp
/net/tcp
/net/udp
/net/tcp/clone
/net/tcp/stats
/net/tcp/n
/net/tcp/n/data
/net/tcp/n/ctl
/net/tcp/n/local
/net/tcp/n/remote
/net/tcp/n/status
/net/tcp/n/listen
...
DESCRIPTION
The IP device provides the interface to Internet protocol
stacks. 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.
All addresses used are 16-byte IPv6 addresses. Though we
Page 1 Plan 9 (printed 11/22/24)
IP(3) IP(3)
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 stan-
dard ASCII formats are accepted. In binary, all v4
addresses start with the 12 bytes:
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 con-
tains a clone file, a stats file, and numbered subdirecto-
ries for each physical interface.
Opening the clone file reserves an interface. The file
descriptor returned from the open(2) will point to the con-
trol file, ctl, of the newly allocated interface. Reading
ctl returns a text string representing the number of the
interface. Writing ctl alters aspects of the interface.
The possible ctl messages are:
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 and
path!0x806 and use the two connections for IP and ARP
respectively.
bind pkt
Treat this interface as a packet interface. Assume a
user program 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.
unbind
Disassociate the physical device from an IP interface.
add local mask remote mtu proxy
Add a local IP address to the interface. 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 is 1514 for Ethernet and 4096 for
packet media. 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.
Page 2 Plan 9 (printed 11/22/24)
IP(3) IP(3)
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 headers.
iprouting n
Allow (nismissing or non-zero) or disallow (n is 0)
forwarding packets between this interface and others.
addmulti addr
Treat the multicast addr on this interface as a local
address.
remmulti addr
Remove the multicast address addr from this interface.
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).
Routing
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 charac-
ter 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
Page 3 Plan 9 (printed 11/22/24)
IP(3) IP(3)
normally used to indicate what routing protocol originated
the route.
Writing to /net/iproute changes the route table. The mes-
sages 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.
Address resolution
The file /net/arp controls information about address resolu-
tion. 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 /net/arp administers the ARP informa-
tion. 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.
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. Gener-
ally, what is returned is error messages about bad packets.
Page 4 Plan 9 (printed 11/22/24)
IP(3) IP(3)
Writing to /net/log controls debugging. The control mes-
sages are:
set arglist
Arglist is a space-separated list of items for which to
enable debugging. The possible items are: ppp, ip, fs,
tcp, il, icmp, udb, compress, ilmsg, gre, tcpmsg,
udpmsg, ipmsg, and esp.
clear arglist
Arglist is a space-separated list of items for which to
disable debugging.
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 informa-
tion for other programs such as dns and cs (see ndb(8)).
/net/ndb may contain up tp 1024 bytes.
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.
Protocol directories
The 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 ping(8). RUDP is a locally developed reli-
able datagram protocol based on UDP. IL is the protocol of
choice for most Plan 9 services.
Each protocol is a subdirectory of the IP stack. The top
level directory of each protocol contains a clone file, a
stats file, and subdirectories 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 con-
trol file, ctl, of the newly allocated connection. Reading
ctl returns a text string representing the number of the
connection. Connections may be used either to listen for
Page 5 Plan 9 (printed 11/22/24)
IP(3) IP(3)
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 estab-
lished data may be read from and written to data. A connec-
tion can be actively established using the connect message
(see also dial(2)). A connection can be established pas-
sively 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 ipaddress!port!r local
Establish a connection to the remote address ipaddress
and remote port 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. Oth-
erwise 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 byt the APE libraries (see pcc(1)) and is not
otherwise used.
backlog n
Set the maximum number of unanswered (queued) incoming
connections to an announced port to n. By default n is
set to five. If more than n connections are pending,
further requests for a service will be rejected.
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.
Port numbers must be in the range 1 to 32767.
Page 6 Plan 9 (printed 11/22/24)
IP(3) IP(3)
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 reason
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 control file of the newly
accepted connection. This procedure will accept all calls
for the given protocol. See dial(2).
TCP
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 additional messages:
hangup
close down a TCP connection
keepalive n
turn on keep alive messages. N, if given, is the mil-
liseconds between keepalives (default 30000).
UDP
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 connect establishes a local and remote address/port
pair or after an announce, each datagram coming from a dif-
ferent remote address/port pair establishes a new incoming
connection. However, many-to-one semantics is also possi-
ble.
If, after an announce, one of the following messages is
written to ctl, then all messages sent to the announced port
are received on the announced connection prefixed with the
given structure.
headers4
typedef struct Udphdr4 Udphdr4;
struct Udphdr
{
uchar raddr[4]; /* v4 remote address and port */
uchar laddr[4]; /* v4 local address and port */
Page 7 Plan 9 (printed 11/22/24)
IP(3) IP(3)
uchar rport[2];
uchar lport[2];
};
headers
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];
};
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
/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.
RUDP
RUDP is a reliable datagram protocol based on UDP. Packets
are delivered in order. RUDP does not support listen. One
must use either connect or announce followed immediately by
headers or headers4.
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 unac-
knowledged packets queued before the reboot will be lost. A
reboot can be detected by reading the err file. It will
have the message
hangup address!port
where address and port are of the far side of the connec-
tion. Retransmitting 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.
IL
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 num-
bers of the two ends. Like UDP, each read and write trans-
fers a single datagram.
Page 8 Plan 9 (printed 11/22/24)
IP(3) IP(3)
IL is efficient for LANs but doesn't have the congestion
control features needed for use through the Internet.
GRE
GRE is the encapsulation protocol used by PPTP. The kernel
implements just enough of the protocol to multiplex it.
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
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 connect message is the SPI (Security Association Identi-
fier (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.
The control messages are:
esp alg secret
Encrypt with the algorithm, alg, using secret as the
key. Possible algorithms are: null, des_56_cbc, and
rc4_128.
ah alg secret
Use the hash algorithm, alg, with secret as the key for
generating the MAC. Possible algorithms are: null,
hmac_sha1_96, and hmac_md5_96.
header
Turn on header mode. Every buffer read from data
starts with 4 unsued bytes, and the first 4 bytes of
every buffer written to data are ignored.
noheader
Turn off header mode.
IP packet filter
The directory /net/ipmux looks like another protocol direc-
tory. It is a packet filter built on top of IP. Each num-
bered subdirectory represents a different filter. The con-
nect 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.
Page 9 Plan 9 (printed 11/22/24)
IP(3) IP(3)
A filter is a semicolon-separated list of relations. Each
relation describes a portion of a packet to match. The pos-
sible relations are:
proto=n
the IP protocol number must be n.
dat[n:m]=expr
bytes n through m following the IP packet must match
expr.
ifc=expr
the packet must have been received on an interface
whose address matches expr.
src=expr
The source address in the packet must match expr.
dst=expr
The destination address in the packet must match expr.
Expr is of the form:
value
value|value|...
value&mask
value|value&mask
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 dat, both value and mask
are strings of 2 character 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
Page 10 Plan 9 (printed 11/22/24)
IP(3) IP(3)
So far this has just been used to implement a version of
OSPF in Inferno.
Statistics
The stats files are read only and contain statistics useful
to network monitoring.
Reading /net/ipifc/stats returns a list of 19 tagged and new
line separated 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 25 tagged and new
line separated 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
Page 11 Plan 9 (printed 11/22/24)
IP(3) IP(3)
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 new
line separated fields representing:
maximum number of connections
total outgoing calls
total incoming calls
number of established connections to be reset
number of currently esablished 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 new
line separated fields representing:
datagrams received
datagrams received for bad ports
malformed datagrams received
datagrams sent
Reading /net/il/stats returns a list of 7 tagged and new
line separated fields representing:
checksum errors
header length errors
out of order messages
retransmitted messages
duplicate messages
duplicate bytes
Reading /net/gre/stats returns a list of 1 tagged number
representing:
header length errors
SEE ALSO
listen(8), dial(2), ndb(6)
SOURCE
/sys/src/9/ip
BUGS
Ipmux has not been heavily used and should be considered
experimental. It may disappear in favor of a more tradi-
tional packet filter in the future.
Page 12 Plan 9 (printed 11/22/24)