PLAN 3.2 Overview and Installation Guide

1. OCaml 3.01, an ML dialect
   See The Caml page for general information, or grab the distribution. Files here are in a number of formats (tarred/gzipped, i386 RH 6.2 RPM, etc.). Note that the PLAN software may not work with versions of OCaml other than 3.01.
2. CamlP4, a preprocessor of Caml, version 3.01
   General information or the distribution.
3. OCaml patch to enable Ethernet access on Linux machines (optional)

You must first install all of these packages. Please follow the installation instructions given at each of the sites. To use the OCaml patch which enables Ethernet access, first download the OCaml distribution. Then, in the ocaml-3.01 directory, enter the command

  patch -p1 < ocaml-patch-3.01

Next, unpack all of the PLAN source. For a UNIX platform, you should have obtained PLAN-ocaml-3.22-src.tar.Z. This can be unpacked simply by doing

    uncompress PLAN-ocaml-3.22-src.tar.Z
    tar -xvf PLAN-ocaml-3.22-src.tar

Note that these operations should be performed in the directory that you would like the source to be unpacked. This shall hereafter be referred to as the ``top level directory.'' This will create one subdirectory ``plan-3.22,'' hereafter referred to as the plan directory.

Building

The default version of the Makefile assumes a couple of things:

• The OCaml distribution is available from your path (i.e., the names of ocamlc, etc. are not fully-quantified in the Makefile).
• OCaml 3.01 has been compiled to use user-level, and not POSIX, threads. In other words, when you built OCaml, you initially called configure without the -with-pthread option. How to build with POSIX threads is described in more detail below. Without POSIX threads, PLAN cannot be compiled to native code (but will compile fine to bytecode).

Compilation options

# WINDOWS = true             ### compile under Windows (not supported yet)
# SUNOS = true               ### compile under SunOS
# USE_QCMGUI = true          ### compile with QCM GUI support
# USE_ANEP = true            ### use ANEP packet formats
# USE_POSIX_THREADS = true   ### OCaml compiled to use POSIX threads
# USE_QCM = true             ### Use QCM as the node policy manager
# USE_KEYNOTE = true         ### Use Keynote as the node policy manager
# USE_PENTIUM_CC = true      ### Use pentium cycle counter for timing
USE_C_CRYPTO = true        ### Use C version of SHA1 code

Another method of customizing how PLAN is built is to modify the compilation flags in the Makefile variable CAMLP4FLAGS. The comments in the makefile have a description of the options you may use:

# Currently supported flags:
# UNIXNET : compile support for Ethernet access (Linux w/ modified Ocaml only)
#           this option is REQUIRED if you are building the loader and
#           have the patch installed.
# PLANPORT_TCP : should use TCP as the underlying socket mechanism
#                for plan ports (rather than UNIX domain sockets)
# PLAN_UNSAFE : eliminates some checks assuming programmer knows
#               what he's doing (yes)
# MULTI_EVAL : forks a thread for each PLAN program so that more
#              than one program can be executed at once
# QUEUE : use a queue between linklayer and network layer (rather than upcalls)
# VERBOSE : shows all messages coming in and going out
# DEBUG : adds extra print messages
# RIP_DEBUG : shows all RIP processing
# FLOW_DEBUG : shows all flow-based routing processing
# TIMERS_ON : prints timing information for various parts of the system
#
# these options will be turned on automatically based on other flags
#
# PTHREAD : should be turned on when POSIX threads are used
# QCM : turned on when using QCM as the policy manager
# ANEP : turned on when using ANEP packet format
# USE_CYCLE_COUNTER : turned on when using the pentium cycle counter
# C_CRYPTO : turned on when using C version of crypto code

The default options are:

CAMLP4FLAGS     = -DPLAN_UNSAFE -DPLANPORT_TCP

CAMLP4FLAGS     = -DPLAN_UNSAFE -DUNIXNET -DPLANPORT_TCP -DQUEUE

Using Ethernet

Compiling to Native Code

We don't have much experience with native-code-based PLAN, so we would appreciate any feedback you have as to better performance, robustness, etc.

PLAN Components

Active Router

• pland
  This is the standard PLAN daemon that uses a fixed (non-loadable) service base. It may also be compiled to native code for performance improvement.
• plan_loader
  Same as pland but with the additional ability to dynamically load new services accessible by PLAN in the form of OCaml bytecodes. This has slightly worse performance and may not be run as native code.

Host Applications

• inject
  This program allows you to inject an arbitrary active packet into the active network and prints any results. Programs in the rout_tests directory form useful examples.
• server
  Demonstrates the use of PLAN ports. See the PLAN Programmer's Guide for more (guide.ps in the docs directory).
• plan_ftp
  A simple client and server that uses PLAN version of FTP.
• authapp
  Demonstrates the use of security features new to PLAN 3.2. See the Security Guide for more. (security.ps in the docs directory).
• plan2snap (experimental)
  This program mimics the interface of the inject program, but compiles the provided PLAN program to SNAP bytecodes. This program can then be injected into a SNAP network. See the SNAP homepage for more information on SNAP.

Utilities

• plan (read-eval-print PLAN)
  this program allows you to test non-network PLAN code by interactively typing in expressions to be evaluated and seeing their printed results. This is useful for verifying that code correctly parses, that expressions behave as you expect them too, etc. Examples in the interp_tests directory may be run in this mode.
• parsetest
  this program parses the given PLAN program and pretty-prints it (though not very well). Is useful for detecting parse errors.
• typetest
  this program performs the full frontend functionality on the given PLAN program: lexing, parsing, internalizing, type inference, conversion to wire format.
• plan_keygen
  this program may be used to generate DSA keys for use by the PLAN security infrastructre. See the Security Guide for more. (security.ps in the docs directory).
• Experiments
  There are a number of programs we used to generate the experimental measurements presented in our paper PLANet: An Active Internetwork.

• The PLAN FAQ (html)
• The PLAN Tutorial (postscript) (html)
• PLAN Programmer's Guide (postscript) (html)
• PLAN Service Programmer's Guide (postscript) (html)
• PLAN Security Guide (postscript) (html)
• PLAN grammar (postscript) (html)
• PLAN Active Router manual (postscript) (html)
• PLAN 3.2 Specification (postscript)

If you are unfamiliar with PLAN, you should begin with the tutorial. Versions of these documents are also available on the PLAN homepage.

Contact Information

Please send bug reports, comments, and suggestions to:
   PLAN-bugs@dsl.cis.upenn.edu

There are also two mailing lists related to PLAN:

PLAN-disc@dsl.cis.upenn.edu	(general discussion about PLAN)
PLAN-announce@dsl.cis.upenn.edu	(bug fixes, new releases, etc.)

To be put on one or both of the mailing lists, please send mail to:
   PLAN-request@dsl.cis.upenn.edu

Supported Architectures

• i586 platforms running
  • Redhat Linux 4.1, 4.2, 5.0, 5.1, 5.2, 6.0, and 6.1. Kernel versions 2.0.28-2.0.36 have been tested; best performance is acheived using Linux kernel 2.0.30 (2.0.33 seems particularly bad). The newer kernel versions also seem OK, in particular 2.2.12. POSIX and non-POSIX threads have been used.
• Sun SPARC's running
  • SunOS 5.5.1-5.7, POSIX and non-POSIX threads.
• IBM Workstations running
  • AIX 4.3.1.0