PLAN Frequently Asked Questions

Topics

Should I use PLAN-Ocaml or PLAN-Java? Why?

Briefly, here are the advantages and disadvantages of each PLAN version:

PLAN-3.2 (Ocaml)
Advantages: Disadvantages:
PLAN-2.21 (Java)
Advantages:

Disadvantages

Using the loopback address

When I try to specify the loopback address in my network configuration files, I can't get the "Hello World" program to run. What's going on?

Answer: To make this more concrete, consider two pland's running on the same machine, kamagarini, one on port 3340, and the other on 3341. Here's what the two network configuration files for these two pland's:
m1
1
ip0 ip localhost:3340 localhost:3341

m2
1
ip0 ip localhost:3341 localhost:3340

The EXP_IP_ADDRS file has the following entries in it:
127.0.0.1 localhost
158.130.6.143 kamagarini

We would start the nodes with the commands:
pland -l log3340 -ip 3340 m1
and
pland -l log3341 -ip 3341 m2

We then try to run the Hello World program:
inject -p 3340 interp_tests/Helloworld.plan 1
doit()

but in doing so get the following error:
ERROR: <chunk:
doit[]> raised RIPNoRoute on <loopback>

So what happened here? Why is there no route to the localhost? The problem is in how the inject program constructs the evaluation destination of the packet you wish to inject. When you don't specify the evaluation destination of the packet directly (using the -ed flag), the inject program constructs a default evalDest as your_machine_name:port. In this case, the result was kamagarini:3340. Then, this hostname is looked up in EXP_IP_ADDRS, resulting in 158.130.6.143:3340, which is clearly not 127.0.0.1:3340, the address specified in m1. The routing protocol has never heard of 158.130.6.143:3340, and so it complains that it has no route to that destination.

You can fix this problem in two ways. This simplest is to specify the evaluation destination directly to inject:
inject -p 3340 -ed localhost:3340 interp_tests/Helloworld.plan 1
doit()
[(127.0.0.1,3340);<loopback>] says : Hello world!

Alternatively, you could set up your EXP_IP_ADDRS file as follows:
127.0.0.1 kamagarini

Then the default destination will be properly specified, and you will still be using the proper underlying loopback device. This won't cause any sort of clash, because the port names disambiguate which nodes you are running. If you want to specify the loopback address in a PLAN program to indicate the local machine, it corresponds to 127.0.0.1:0.

Why am I getting recvfrom errors?

This "error" is benign. These will show up in the log file as 
Unix error: Connection refused : recvfrom
This occurs when running with IP as a virtual link layer. In your interface file, you specify a virtual ip interface, its address, and its "neighbors," i.e. the nodes to send messages to on a broadcast. When one of these neighbors isn't running, any broadcast messages sent to its address will be dropped. According to an RFC spec for UDP implementations (I'm not sure which one), if a message is knowingly dropped, an ICMP message indicating as much must be sent to the source. This information is propagated to the application by causing the next operation to fail on the file descriptor through which the dropped message was sent. This manifests as a recvfrom error.

plan_loader compilation problems

There is a bug in plan/loader/Makefile. The line 
OCAML_LIB=/usr/local/lib/ocaml
should be 
OCAML_LIB=`ocamlc -v | grep library | awk '{ print $$4 }'`
So that the library location is not installation-dependant. This will result in an error like 
File "loader.ml", line 82, characters 32-50:
Unbound value Crcs.crc_unit_list
This is because the call to extract_crc fails and writes an empty crcs.ml file. After fixing your Makefile, you should remove plan/loader/crcs.ml and then rebuild the loader. This will be fixed in the next release of PLAN.

I cannot properly build Ocaml

If you build Ocaml from the source tarball, you needed to first apply this patch. First untar the Ocaml source, then cd to the ocaml-2.02 directory, and finally do 
patch -p1 < ocaml-2.02-patch1.diffs
You may now build Ocaml as per the instructions in the ocaml-2.02 directory. If you built Ocaml before and want to rebuild it with this patch applied, please clear away your Ocaml installation, and then re-untar the source (doing a make clean doesn't always seem to work).

If you wish to also have ethernet access (for Linux machines only), you need to apply this patch. Apply the other patch first, then this one; i.e. 

patch -p1 < ocaml-2.02-patch1.diffs
patch -p1 < ocaml-patch-2.01
and then build Ocaml. Note that there was a bug in the installation manual that the wrong Ethernet patch was given in the URL. Make sure you are installing ocaml-patch-2.01 and not ocaml-patch-2.0.

Note that if you have installed the Ethernet patch, you must alter the compilation flags in plan/Makefile or things will not build properly. In particular, you should change 

CAMLP4FLAGS     = -DPLAN_UNSAFE -DAUTH_DEBUG
to instead be 
CAMLP4FLAGS     = -DPLAN_UNSAFE -DAUTH_DEBUG -DUNIXNET
before building the PLAN software.

How do I compile to send ANEP packets with PLAN?

PLAN can use ANEP very easily. All you need to do is modify the Makefile so that the line 
# USE_ANEP = true            ### use ANEP packet formats
is uncommented 
USE_ANEP = true            ### use ANEP packet formats
Then recompile everything from scratch. Turning on this flag will set a compilation flag, -DANEP, and will include the Anep module during compilation.

Why doesn't traceNet.plan work?

Here is what I get when I launch PLAN on the demo file traceNet.plan: 

inject -p 3324 /usr/src/plan-3.2/rout_tests/traceNet.plan 10
startDFS();

ERROR:  raised Unknown on
where the log file indicates: 
Spawned thread 29 for session 1 (total = 1) 1
Using query string |{ v | (s,) <- resident, Principal() <- s } ;|
Result was ||
Eval thread 4 exiting with failure:
  Error: uncaught exception: Invalid_argument("String.sub")
Closed session 1 (total = 0).
This is because PLAN is compiled to use QCM by default. As a quick fix to the problem, you can not compile with QCM by changing the line 
USE_QCM = true             ### Use QCM as the node policy manager
to be commented out: 
# USE_QCM = true             ### Use QCM as the node policy manager
The core of the problem is that the resident state service, used by traceNet, checks the node policy to see how much state is allowed to a particular user. If you do not start pland with a policy file that indicates how much should be given to the default user, then allocation of state is not allowed. See the security document for more details, and for information on how to construct such a file.

How do I set up topology XXX?

Most of the problems people have just trying to get ``ping'' to work arise from improperly created topology files. A full description of the interface file format is given in the PLAN active router manual, but we will describe here how to set up a basic topology showing all the features. The topology we will create is shown below:

Example topology, 1K

This is a network with 4 nodes and two LANs. Nodes A, B, and C all reside on one LAN, and nodes B and D reside on the other LAN (thus B is serving as a router). The interfaces of all the nodes have been labelled a1, b1, etc. Notice that B has two interfaces, b1 and b2, because it is on two networks.

Now, most people start by setting up all their PLAN nodes running on one physical machine, so we just need to pick unique port numbers for all the interfaces. In the diagram above, we have chosen:

InterfacePort number
a13324
b13325
b23326
c13327
d13328

If our machine is called "m", then the interface files will look like this:

When you start up the pland processes, for each node you want to choose an input port corresponding to one of the node's interfaces (for nodes A, C, and D above there is only one choice, but either 3325 or 3326 would work for B).

One more topology

With less detail, here's the other topology most people try to set up:

Example ``box'' topology, 1K

The interface files should look like this:

How do I build PLAN applications?

An example of a PLAN application (that is, a user-program that communicates with the PLAN active network) is the server application. It waits for connections of PLAN ports and the prints any of the data it receives. For example, you start it by doing 
% bin/server 7777
Server waiting to receive connections
(where % is the prompt). It then waits for connections on PLAN port 7777, and prints out any data it receives. Therefore, if there was a pland running on your machine (the same as the server program, that is), you could inject deliver.plan to it, and have it communicate with server by doing: 
% bin/inject rout_tests/deliver.plan 10
stuff(7777);
Then you would see output from server, like: 
Spawning thread for conn 1
Received PLAN value |158.130.6.143:3324|
Received PLAN value |100323|
Received PLAN value |hello|
Received PLAN value ||
Closed conn 1
Take a look at the PLAN programmer's manual, in the services section, for more information on PLAN ports and the deliver primitive.