IP(3) IP(3)
NAME
ip - network protocols over IP
SYNOPSIS
bind -a #I[ifn] /net
/net/arp
/net/bootp
/net/iproute
/net/ipselftab
/net/iprouter
/net/log
/net/ipifc/clone
/net/ipifc/stats
/net/ipifc/n
/net/ipifc/n/data
/net/ipifc/n/ctl
/net/ipifc/n/local
/net/ipifc/n/status
/net/proto/clone
/net/proto/stats
/net/proto/n
/net/proto/n/ctl
/net/proto/n/data
/net/proto/n/err
/net/proto/n/local
/net/proto/n/remote
/net/proto/n/status
/net/proto/n/listen
...
DESCRIPTION
The IP device serves a directory representing a self-
contained collection of IP interfaces. There may be several
instances, identified by the decimal interface number ifn,
that follows the #I device name; #I0 is assumed by default.
Each instance has a disjoint collection of IP interfaces,
routes and address resolution maps. A physical or virtual
device, or medium, that produces IP packets is associated
with a logical IP network using the mechanisms described
under Physical and logical interfaces below. Commonly all
IP media on a host are assigned to a single instance of #I,
which is conventionally bound to /net, but other configura-
tions are possible: interfaces might be assigned to differ-
ent device instances forming separate logical IP networks to
partition networks in firewall or gateway applications.
Hosted Inferno provides a subset of the interface described
Page 1 Plan 9 (printed 12/21/24)
IP(3) IP(3)
here that gives to the TCP/IP and UDP/IP of the host
system's own IP subsystem. See Hosted interfaces below for
a summary of the differences.
Protocols
Within each instance, the IP device provides an interface to
each IP protocol configured into the system, such as TCP/IP
or UDP/IP.
Each of the protocols is served by the IP device, which rep-
resents a connection by a set of device files. The top
level directory, proto in the SYNOPSIS above, is named after
a protocol (eg, tcp, il, udp) and contains a clone file, a
stats file, and subdirectories numbered from zero to the
number of connections configured for this protocol.
The read-only stats file contains protocol-specific statis-
tics as one or more lines of text. There is no particular
format, but the values are often a superset of those
required by the SNMP MIB.
Opening the clone file reserves a connection, represented by
one of the numbered subdirectories. The resulting file
descriptor will be open on the control file, ctl, of the
newly allocated connection. Reading the ctl file returns a
text string representing the number of the connection. Con-
nections may be used either to listen for 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 the data file.
Before sending data, remote and local addresses must be set
for the connection. For outgoing calls the local port num-
ber will be allocated randomly if none is set. Addresses
are set by writing control messages to the ctl file of the
connection. The connection is not established until the
data file is opened. There are two models depending on the
nature of the protocol. For connection-oriented protocols,
the process will block on open until the remote host has
acknowledged the connection, either accepting it, causing a
successful return from open, or rejecting it, causing open
to return an appropriate error. For connectionless proto-
cols, the open always succeeds; the `connect' request sets
local parameters for the source and destination fields for
use by subsequent read and write requests.
The following control messages are provided by this inter-
face to all protocols. A particular protocol can provide
additional commands, or change the interpretation or even
syntax of those below, as described in the manual page for
Page 2 Plan 9 (printed 12/21/24)
IP(3) IP(3)
that protocol. The description below shows the standard
commands with the default argument syntax and interpreta-
tion:
connect ipaddress!port[!r] [lport]
Set the remote IP address and port number for the con-
nection. If the r flag is supplied and the optional
local port lport has not been specified the system will
allocate a restricted port number (between 600 and
1024) for the connection to allow communication with
Unix machines' login and exec services.
announce [ipaddress!]port
Set the local port number to port and accept calls to
that port. Port is a decimal port number or `*'. If
port is zero, assign a port number (the one assigned
can be read from the local address file). If port is
`*', accept calls for any port that no process has
explicitly announced. If the optional ipaddress is
given, set the local IP address for the connection to
that address, and accept only those incoming calls to
port that are addressed to ipaddress. Announce fails if
the connection is already announced or connected.
bind port
Port is a decimal port number or `*'. Set the local
port number to port. This request exists to support
emulation of of BSD sockets and is otherwise neither
needed nor used in Inferno.
tos [ n ]
Set the type-of-service value in outgooing packets to n
(default: 0).
ttl [ n ]
Set the time-to-live (TTL) value in packets transmitted
on this conversation to n (default: 255).
Port numbers must be in the range 1 to 32767.
Several read-only 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. The first word on the first line
gives the status of the connection.
Having announced, a process may accept incoming connections
by calling open on the listen file. The open will block
until a new connection request arrives; it will then return
an open file descriptor that points to the control file of
the newly accepted connection. Repeating this procedure
Page 3 Plan 9 (printed 12/21/24)
IP(3) IP(3)
will accept all calls for the given protocol.
In general it should not be necessary to use the file system
interface to the networks. The dial, announce, and listen
functions described in sys-dial(2) perform the necessary I/O
to establish and manipulate network connections.
TCP protocol
The TCP protocol is the standard Internet protocol for reli-
able stream communication; it does not preserve read/write
boundaries.
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 the data file.
The TCP protocol provides a stream connection that does not
preserve read/write boundaries.
For outgoing calls the local port number will be allocated
randomly if none is set. Addresses are set by writing con-
trol messages to the ctl file of the connection. The con-
nection is not established until the data file is opened.
For TCP the process will block until the remote host has
acknowledged the connection.
As well as the standard control messages above, TCP accepts
the following:
hangup
Send a TCP reset (RST) to the remote side and end the
conversation, without waiting for untransmitted data to
be acknowledged, unlike a normal close of the device.
keepalive [n]
Enable `keep alive' mode: if no traffic crosses the
link within a given period, send a packet to check that
the remote party is still there, and remind it that the
local connection is still live. The optional value n
gives the keep-alive time in milliseconds (default:
120000).
The status file has many lines, each containing a labelled
number, giving the values of parameters and statistics such
as: maximum allowed connections, outgoing calls, incoming
calls, established but later reset, active calls, input seg-
ments, output segments, retransmitted segments, retransmit-
ted timeouts, input errors, transmitted reset.
UDP protocol
UDP provides the standard Internet protocol for unreliable
datagram communication.
Page 4 Plan 9 (printed 12/21/24)
IP(3) IP(3)
UDP opens always succeed. Before sending data, remote and
local addresses must be set for the connection. Alterna-
tively, the following special control requests can be used:
headers
Set the connection to use an address header with IPv6
addressing on reads and writes of the data file, allow-
ing a single connection to send datagrams to converse
with many different destination addresses and ports.
The 52 byte binary header appears before the data read
or written. It contains: remote IP address, local IP
address, interface IP address, remote port, and local
port. The IP addresses are 16 bytes each in IPv6 for-
mat, and the port addresses are 2 bytes each, all writ-
ten in network (big-endian) order. On reads, the
header gives the values from the incoming datagram,
except that if the remote used a multicast destination
address, the IP address of the receiving interface is
substituted. On writes, the header provides the desti-
nation for the resulting datagram, and if the local IP
address corresponds to a valid local unicast interface,
that address is used, otherwise the IP address of the
transmitting interface is substituted.
headers4
Set the connection to use an address header with IPv4
addresses on reads and writes of the data file, allow-
ing a single connection to send datagrams to converse
with many different destination addresses and ports.
The 12 byte binary header appears before the data read
or written. It contains: remote IP address, local IP
address, remote port, and local port. The IP addresses
are 4 bytes each, the port addresses are 2 bytes each,
all written in network (big-endian) order. On reads,
the header gives the values from the incoming datagram.
On writes, the header provides the destination for the
resulting datagram. This mode is obsolete and destined
for oblivion.
A read of less than the size of the datagram will cause the
entire datagram to be consumed. Each write to the data file
will send a single datagram on the network.
In replies, in connection-oriented mode, if the remote
address has not been set, the first arriving packet sets the
following based on the source of the incoming datagram: the
remote address and port for the conversation, and the local
address is set to the destination address in the datagram
unless that is a multicast address, and then the address of
the receiving interface is used.
If a conversation is in headers mode, only the local port is
Page 5 Plan 9 (printed 12/21/24)
IP(3) IP(3)
relevant.
Connection-oriented UDP is hungup if an ICMP error (eg, host
or port unreachable, or time exceeded) arrives with matching
port.
The udp status file contains four lines, each containing a
labelled number counting an event: input datagrams, data-
grams on unannounced ports, datagrams with wrong checksum,
and output datagrams.
IL Protocol
IL provides a reliable point-to-point datagram service for
communication between Plan 9 and native Inferno machines.
Each read and write transfers a single datagram, as for UDP.
The datagrams are delivered reliably and in order. Conver-
sations are addressed and established as for TCP.
Routing
The iproute file can be read and written. When read, it
returns the contents of the IP routing tables, one line per
entry, with six fields giving the destination host or net-
work address, address mask, gateway address, route type, tag
(see below), and the number of the ipifc interface owning
the route (or `-' if none). The route type is up to four
characters: 4 or 6 (IPv4 or IPv6 route); i (route is inter-
face); one of u (unicast), b (broadcast), or m (multicast);
and lastly p if the route is point-to-point.
Commands can also be written to control the routing:
add ip mask gw [ tag ]
Add a route via the gateway identified by IP address gw
to the address specified by ip and subnet mask mask.
Tag the resulting table entry with the tag provided, or
the current tag (see tag below), or the tag none.
flush [ tag ]
Remove all routes with the given tag that do not corre-
spond to a local interface. If tag is not given, flush
all routes.
remove ip mask
Remove routes to the given address.
tag tag
Tag the routes generated by writes on the current file
descriptor with the given tag of up to 4 characters.
The default is none, set when iproute is opened.
The ipselftab file summarises the addresses and routes that
refer to the local host. It gives an address, the number of
Page 6 Plan 9 (printed 12/21/24)
IP(3) IP(3)
logical interfaces, and the interface type in the same form
as the route type of iproute.
The iprouter file is provided for use by a user-level appli-
cation acting as an IP gateway. It is effective only when
the kernel-level gateway is not enabled (see the iprouting
interface control request below). Once opened, packets that
are not addressed to a local address can be read from this
device. The packet contents are preceded by a 16 byte
binary header that gives the IPv6 address of the local
interface that received the packet.
Bootstrap
The read-only bootp file contains the results of the last
BOOTP request transmitted on any interface (see Physical and
logical interfaces below) as several lines of text, with two
fields each. The first field names an entity and the second
field gives its value in IPv4 address format. The current
entities are:
auip Authentication server address
fsip File server address
gwip Address of an IP gateway out of this (sub)net.
ipaddr Local IP address
ipmask Subnet mask for the local IP address
If any value is unknown (no reply to BOOTP, or value unspec-
ified), the value will be zero, represented as 0.0.0.0.
Address resolution
The arp file can be read and written. When read, it returns
the contents of the current ARP cache as a sequence of
lines, one per map entry, giving type, state, IP address and
corresponding MAC address. Several textual commands can be
written to it:
add [ medium ] ip mac
Add a mapping from IP address ip to the given mac
address (a sequence of bytes in hexadecimal) on the
given medium. It must support address resolution (eg,
Ethernet). If the medium is not specified, find the
one associated with a route to ip (which must be IPv4).
flush
Clear the cache.
Logging
The log file provides protocol tracing and debugging data.
While the file is held open, the system saves, in a small
circular buffer, error messages logged by selected proto-
cols. When read, it returns data not previously read,
Page 7 Plan 9 (printed 12/21/24)
IP(3) IP(3)
blocking until there is data to read. The following com-
mands can be written to determine what is logged:
set proto ...
Enable logging of messages from each source proto, one
or more of: ppp, ip, fs, tcp, il, icmp, udp, compress,
ilmsg, gre, tcpmsg, udpmsg, ipmsg and esp.
clear proto ...
Disable logging of messages from the given sources.
Physical and logical interfaces
The configuration of the physical and logical IP interfaces
in a given instance of #I uses a virtual protocol ipifc
within that instance, that adds, controls and removes IP
interfaces. It is represented by the protocol directory
ipifc. Each connection corresponds to an interface to a
physical or virtual medium on which IP packets can be sent
and received. It has a set of associated values: minimum
and maximum transfer unit, MAC address, and a set of logical
IP interfaces. Each logical IP interface has local and
remote addresses and an address mask.
Opening the clone file returns a file descriptor open on the
ctl file for a new connection. A medium is then attached
using a bind request; logical interfaces are associated by
connect or add; they are removed by remove; and finally
unbind detaches the medium from the connection. For certain
types of media, the unbind is automatic when the connection
itself is closed. With most media, including Ethernet, the
ipifc connection files can be closed after configuration,
and later reopened if need be to add or remove logical
interfaces, or set other parameters.
The ctl file responds to the following text commands,
including interface-specific variants of standard IP device
requests:
bind medium [ name [ arg ... ]
Attach device medium to the interface, which must not
already be bound to a device. The name and subsequent
arguments are interpreted by the driver for the medium.
The device name associated with the interface is name,
if given, or a generated name otherwise.
connect ip [mask [remote [mtu ]]]
Remove all existing logical interfaces and create a new
one as if by add (see below). The connection must be
bound to a medium.
add ip [ mask [ remote [ mtu ] ] ]
Add a logical interface with local IP address ip. The
Page 8 Plan 9 (printed 12/21/24)
IP(3) IP(3)
default for mask is the mask for ip's address class;
for the remote address, ip's network; and for mtu, the
largest MTU allowed by the medium. The new interface
is registered in the IP routing tables.
bootp
Broadcast a BOOTP packet (using udp). If a valid
response is received, set the interface's IP address
and mask, and the IP stack's default gateway to the
results obtained from BOOTP. The results are also
available to applications by reading the bootp file
above. Note that this mechanism is now deprecated in
favour of dhcpclient(2).
remove ip mask
Remove the logical interface determined by ip and mask.
iprouting [n]
Control the use of IP routing on this ip(3) instance.
If n is missing or non-zero, allow use as a gateway,
rerouting via one interface packets received on
another. By default, or if n is zero, use as a gateway
is not allowed: if a packet received is not addressed
to any local interface, either pass it to a gateway
application if active (see iprouter in ip(3)), and oth-
erwise drop the packet.
mtu n
Set the maximum transmit unit (MTU) on this interface
to n bytes, which must be valid for the medium.
addmulti multi
Add the multicast address multi to the interface.
remmulti multi
Remove the multicast address multi from the interface.
unbind
Remove any association between the current medium
(device) and the connection: remove all routes using
this interface, detach the device, stop packet trans-
port, and remove all logical interfaces. The connec-
tion is ready for re-use.
The local file contains one line for each logical interface,
of the form:
local->self...
where local is the local address associated with the inter-
face and each self is a broadcast or multicast address that
can address that interface, including subnet addresses, if
Page 9 Plan 9 (printed 12/21/24)
IP(3) IP(3)
any.
The status file contains many fields: the first two give the
device name and the value of the current MTU, followed by 7
fields per line for each logical interface: local address,
address mask, remote address, packets in, packets out, input
errors, and output errors.
The following sections describe the media drivers available.
Each is separately configurable into a kernel.
Ethernet medium
Ethernet devices as described in ether(3) can be bound to an
IP interface. The bind request has the form:
bind ether device
The interface opens two conversations on the given Ethernet
device, for instance ether0, using an internal version of
dial, with the addresses device!0x800 (IPv4) and
device!0x806 (ARP). See sys-dial(2) for the interpretation
of such addresses. The interface runs until a process does
an explicit unbind. Multicast settings made on the inter-
face are propagated to the device.
Point-to-point medium
An asynchronous serial device as described in eia(3) can be
bound to an interface as a Point-to-Point protocol (PPP)
device. The bind request has the form:
bind ppp serial ip remote mtu framing username secret
All parameters except serial are optional. The character
`-' can appear as a placeholder for any parameter. Except
for authentication data, an attempt is made to negotiate
suitable values for any missing parameter values, including
network addresses. The parameters are interpreted as fol-
lows:
serial Name of the device that will run PPP.
ip Local IP address for the interface.
remote IP address of the other end of the link.
mtu Initial MTU value for negotiation (default:
1450)
framing If framing is zero, do not provide asynch.
framing (on by default). Unimplemented.
username Identification string used in PAP or CHAP
authentication.
secret Secret used in authentication; with CHAP it
never crosses the link.
Page 10 Plan 9 (printed 12/21/24)
IP(3) IP(3)
If the name serial contains `!' a connection will be opened
using dial (see sys-dial(2)). Otherwise the name will be
opened as-is; usually it is the name of a serial device (eg,
#t/eia0). In the latter case, a companion ctl file will
also be opened if possible, to set serial characteristics
for PPP (flow control, 64kbyte queue size, nonblocking
writes). An attempt is made to start the PPP link immedi-
ately. The write of the bind control message returns with
an error if the link cannot be started, or if negotiation
fails. The PPP link is automatically unbound if the line
hangs up (eg, modem drops carrier), or an unrecoverable
error occurs when reading or writing the connection.
The PPP implementation can use either PAP and CHAP authenti-
cation, as negotiated, provided an appropriate username and
secret is given in the bind request. It does not yet sup-
port the Microsoft authentication scheme.
Packet medium
The packet medium allows an application to be source and
sink for IP packets. It is bound to an interface by the
simple request:
bind pkt
All other interface parameters including its IP address are
set using the standard ipifc requests described above. Once
that has been done, the application reads the data file of
the interface to receive packets addressed to the interface,
and it writes to the file to inject packets into the IP net-
work. The interface is automatically unbound when all
interface files are closed.
Hosted interfaces
Native Inferno and Plan 9 have related IP implementations.
Plan 9 emu therefore simply imports Plan 9's /net, and in
the absence of version-specific differences, what is
described above still applies.
On all other hosted platforms, the IP device gives applica-
tions within emu(1) a portable interface to TCP/IP and
UDP/IP, even through it is ultimately using the host
system's own TCP/IP and UDP/IP implementations (usually but
not always socket based). The interface remains the same:
for instance by /net/tcp and /net/udp, but is currently more
limited in the set of services and control requests. Both
IPv4 and IPv6 address syntax may be used, but the IPv6 form
must still map to the IPv4 address space. Only TCP and UDP
are generally available, and a limited interface to ARP on
some platforms (see below). The set of TCP/UDP control
requests is limited to: connect, announce, bind, ttl, tos,
ignoreadvice, headers4, oldheaders, headers, hangup and
Page 11 Plan 9 (printed 12/21/24)
IP(3) IP(3)
keepalive.
The write-only arp file is implemented only on some Unix
systems, and is intended to allow the implementation of the
BOOTP protocol using Inferno, on hosted systems. It accepts
a single textual control request:
add ip ether
Add a new ARP map entry, or replace an existing one,
for IP address ip, associating it with the given ether
MAC address. The ip address is expressed in the usual
dotted address notation; ether is a 12 digit hexadeci-
mal number.
An error results if the host system does not allow the ARP
map to be set, or the current user lacks the privileges to
set it.
SOURCE
/emu/port/devip.c
/os/ip/devip.c
/os/ip/proto.c
/os/ip/ipifc.c
/os/ip/*medium.c
SEE ALSO
sys-dial(2)
Page 12 Plan 9 (printed 12/21/24)