Description
pland is the daemon program that acts as the PLAN active router for
PLAN version 3.2, written in OCaml [ocaml] version 2.02. Currently,
pland only works on UNIX-based systems. There also exists a PLAN active
router written in Java (heretofore referred to as ARMain after its
classfile name), for PLAN version 2.2, which has its own documentation.
Pland and ARMain are not compatible with one another.
Pland communicates with local applications (referred to as host
applications) via UNIX domain sockets by default, or via TCP/IP sockets
using a special compilation option. See the -ip option description
for more.
Depending upon the compilation flags used, pland can make use of any
combination of two link layers: Ethernet and UDP/IP. If there is interest,
we may also enable ATM as a link layer. Currently, only Linux-based
versions of pland can use Ethernet, enabled by a patched version of
OCaml [salex-ocaml] which reveals a special Linux device socket type.
How these link layers are used is decided by the contents of the interface specification file (ifc_spec_file); details on the format
of this file are specified below.
PLAN (network layer) addresses are made up of two components: a 32 bit
address and a 16 bit port number. When running on top of Ethernet the
choice of these two fields is completely arbitrary, while when running on
top of UDP/IP the address portion must match the IP address of the
underlying machine and the port portion must be an unused UDP port. These
two link layers can be used singly or in combination; essentially this
allows separate Ethernet-based PLANet's to be interconnected by `tunnels'
through the Internet. Also, the use of UDP/IP allows multiple routers to
run on the same host, which is useful for testing purposes.
To enable service-level security, a PLAN node may be associated with a
public and private key pair. These keys are stored in a file as base-64
encodings of DSA public and private keys. A tool, plan_keygen, is
provided with the distribution to generate these keys. Additionally, you
may specify a policy file to indicate the node's service access policy at
startup time. This file depends on the policy manager compiled into pland.
Pland can either use static or dynamic routing; the former is set by a table
at startup, while the latter (the default) is realized via a RIP-style
routing protocol.
The `standalone' version of pland does not allow dynamic linking of code.
Also in the distribution is a version of pland which is integrated with the
active loader [activebridge], called plan_loader. This version
is slightly slower.
For a tutorial on using the router (and the injector) please refer to the
PLAN tutorial [tutorial]; for more detailed information, please refer
to the PLAN Programmer's Guide [progguide].
Command-line options
| -router |
 |
|
| -firewall dev1,...,devn |
 |
|
| -l logfile |
 |
| |
|
| -ip incoming port |
 |
|
| -rf routfile |
 |
|
| -hf hostfile |
 |
|
| -key keyfile |
 |
|
| -policy policyfile |
 |
|
| -authlist h1,...,hn |
 |
Interface File Description
The interface file describes the underlying link layer arrangment that pland
should use. In general terms, the interface file consists of a list of
devices which either are (in the case of Ethernet) or represent (in the case
of IP) the network interfaces to be used by pland. Each interface has
broadcast, rather than point-to-point, semantics. This file specifies for
each interface its name, its type, its network address, and an optional list
of neighbors. The list of neighbors is used to simulate broadcast for
IP-based linklayers (i.e., when a PLAN program broadcasts out of a
particular IP device, all of the hosts in the neighbor list shall receive
the message). The grammar for the file is given below.
Lexical definitions
| int |
|
an integer |
| id |
|
an identifier |
| string |
|
a string of characters |
| ip-addr |
= |
[0-9][0-9][0-9].[0-9][0-9][0-9].[0-9][0-9][0-9].[0-9][0-9][0-9] |
| dns-name |
= |
id ( [.] id )* |
| addr |
= |
( ip-addr | dns-name ) |
| |
| |
( ip-addr | dns-name ) ':' int |
| type |
= |
'ethernet' | 'ip' |
Grammar
| file |
::= |
int entry-list |
| entry-list |
::= |
entry | entry entry-list |
| entry |
::= |
string type addr addr-list |
| addr-list |
::= |
addr | addr ',' addr-list |
Consider the following example:
3
ip0 ip kamagarini:3324 kamagarini:3323,kamagarini:3327
ip1 ip kamagarini:3325 kamagarini:3326
eth0 ethernet kamagarini:3326
This file specifies that pland has three interfaces, ip0, ip1,
and eth0, the first two of which are virtual IP interfaces, and the
third is an actual Ethernet interface.
The name of the ethernet interface, eth0, must match the name of an
Ethernet device known by the system1.
The network address of the interface has no restrictions on it (i.e., it
doesn't have to match the IP address of the local machine) other than it
should be different than the address of all of the other interfaces. There
is no need to specify a list of neighbors; broadcasts will actually make use
of Ethernet broadcast to send to all hosts on the same Ethernet LAN as the
device.
The network addresses of IP interfaces ip0 and ip1 are kamagarini:3324 and kamagarini:3325 respectively. Note that if pland
uses one or more IP interfaces then the first portion of the address (the
kamagarini part) must be the IP address of the machine upon which
pland is running (and thus must be the same for all interfaces), and the
second part (here 3324 or 3325) must be different for each
interface. This is because each IP interface results in the creation of a
UDP/IP socket in pland which is bound to the specified port. In this case,
pland will bind to UDP ports 3324 and 3325 when it is running on machine
with domain name kamagarini; UDP packets received on port 3324 will be
attributed to device ip0 and those on 3325 will be attributed to ip1. The neighbor list for each IP device specifies the network layer
addresses of machines to send to if a broadcast message is sent out of the
device. This list is essentially the network addresses of all nodes to be
considered on the same LAN as the interface (minus the address of the
interface itself). Currently, you must specify at least one neighbor.
The device name lo is reserved (it specifies the local pseudo-device).
If the ':' int part of the address is left off, the default port
is used, as specified on the command line with -ip, or 3324. Note
that for the inject program to work properly, the port number given to
-ip when pland is started should match one of the port portions of the
network addresses specified in the interface file. In this example, pland
could be safely started with -ip's argument being one of 3324, 3325,
or 3326.