Last Updated: Sunday, October
How To Use NetScript 0.10
This page describes:
What is NetScript?
What is included in this release; what we plan for
How the distribution is organized
How to build and install the NetScript distribution
How to start a NetScript engine
How to program and control remote engines
How to create and compile your own NetScript programs
How to run the IP router and firewall examples
What is NetScript?
NetScript is a language and environment for implementing protocols or services.
NetScript programs can be deployed into network nodes to dynamically extend
the network with new protocols and services.
A NetScript network consists of a collection of network nodes (e.g.
PCs, switches, routers) each of which runs one or more NetScript engines.
A NetScript engine is a software abstraction of a programmable packet-processing
device. Each NetScript engine consists of dataflow components that
process packet-streams that flow through them. These dataflow programs,
called boxes in NetScript, can be dispatched to remote NetScript
engines, and dynamically composed with other resident boxes. NetScript
uses interconnection to achieve protocol composition: composite packet-processing
protocols are built by connecting together the typed ports of boxes.
Packets that flow through a NetScript node are processed by successive
boxes to perform various protocol functions. Typical NetScript boxes do
packet header analysis, packet demultipexing, or other protocol functions.
NetScript boxes can be dispatched to remote network engines and dynamically
connected to boxes that reside there to extend the network with new communication
functions. For example, an IP router implemented in NetScript could be
dynamically extended with firewall functions. Or such a router might be
extended to monitor traffic, support content-filtering on the edge of a
network domain, or perform load balancing and traffic shaping. NetScript
is useful in any application that process packet-streams.
Features of this Release
The NetScript system consists of two components: NetScript, a textual dataflow
language for composing and a the NetScript Toolkit, a set of Java classes
to which the textual language compiles. This release of NetScript includes
the NetScript Toolkit but not the front-end language language. Even without
the language, we hope the NetScript Toolkit proves useful as a framework
for building active and conventional protocols.
A tutorial included with this distribution
describes the base NetScript language and shows how to program with the
The distribution includes a RIP-based IP router and a simple programmable
firewall implemented by students in the Computer Networks course at Columbia.
This routing firewall can be deployed on remote nodes to perform all routing
functions from the datalink (Ethernet) and above.
The NetScript language will be introduced in the next version of the
system. The language consists of three integrated components -- a dataflow
composition language, a presentation language for defining the format of
network packets, and a classification language for building packet classifiers.
The next release will also support NetScript's Virtual Active Network
(VAN) architecture. A VAN lets one program, configure, and manage a large
collection of active nodes as a single unit, rather than handle each node
The current version of NetScript runs under Linux
kernels version 2.0 and later. NetScript also depends on Java JDK v1.1.6
or later. You can download the latest JDK port to Linux from here.
NetScript will also run under the free Kaffe
virtual machine. To run the example applications, your machine must have
one or more Ethernet cards installed on it. Because NetScript accesses
the Ethernet devices in promisquous mode, you will need root privileges
to run the NetScript router and firewall application. The client programs
that control and program a remote NetScript engine do not need root.
How the Distribution is Organized
||Various wrapper scripts to start and control a NetScript
||Javadoc documentation for the main kernel packages
||To build the NetScript distribution
||All the source code for the NetScript system
||The netscript package hierarchy
||Example NetScript applications -- the IP router and firewall
||NetScript client programs for controlling a remote engine
||The NetScript engine sources
||Various NetScript implementations of protocols -- Ethernet,
IP, ARP, etc
||Implements NetScript remote control protocol
||Per Bothner's bytecode package for working with Java class
||Features planned for future releases
||A tutorial introduction to using the NetScript Toolkit
How to Install NetScript
Download and untar the NetScript distribution. This will create a directory
The distribution includes the both the source and pre-compiled binary files.
To run NetScript you need to define three environment variables: NETSCRIPT_HOME,
JAVA_HOME, and your shell PATH. The variable NETSCRIPT_HOME
is the location of the top-level NetScript directory, netscript-0.10.
If you untar'ed NetScript to your home directory, say /home/bob/,
NETSCRIPT_HOME should point to /home/bob/netscript-0.10/.
The variable JAVA_HOME points to the base directory of your JDK installation.
For example, JAVA_HOME should be set to /usr/local/java/jdk1.1.6/
if you have the JDK installed there. Under bash, ksh, or zsh, you can make
these definitions with the following lines:
Users of csh and its variants should add equivalent setenv definitions
to their startup files. Note that the scripts in the bin directory require
on the PATH variable include $NETSCRIPT_HOME/bin.
You are now ready to run NetScript.
How to Compile the NetScript Sources
The NetScript distribution both precompiled binaries and complete sources.
Should you need to recompile the sources, do the following:
Please note that most of the relevant NetScript classes are in the packages
netscript and netscript.kernel. You will not need to
use the classes in any of the other packages in the source distribution.
Change directory to netscript-0.10.
Type the command 'make'.
How to Run a NetScript Engine
NetScript consists of two components, a NetScript engine and a number of
client programs to program and control the engine from across the network.
In the following, it will be helpful to open two terminal sessions, one
terminal for the machine on which you want to run a NetScript engine, the
other on a machine from which you wish to send commands to the remote NetScript
engine. In the examples below, the NetScript engine runs on the machine
called jane and the client programs run from a host called
How to Start the NetScript Engine
To start the NetScript engine, use the program ns-engine. The
syntax of ns-engine is:
The optional name argument distinguishes NetScript engines running on the
same machine from each another. If you omit the name argument, NetScript
assigns the default name "EngineServer" to the new engine. Client commands
use the name to identify a particular engine on a host. The port argument,
an integer, is used by the engine in listening for commands that come from
clients. If you skip the port, NetScript uses the default port (1099).
The final -load argument tells the engine
ns-engine [-enginename name] [-port port] [-load box-url box-name args]
The -load argument tells the NetScript engine to load and instantiate
a particular box at startup time. Here, the first parameter box-url
is a URL that specifies the location of the NetScript code to load. This
URL must point to a Java .class file, for example ftp://www.cs.columbia.edu/netscript/test.class.
The second parameter, box-name, specifies the name to give the
new box. The final parameter args is a list of arguments to pass
the instantiated box.
For example, log into the machine where you want start a NetScript engine
and type the command
This will start an engine called my-engine on the host jane.
NetScript should print the following message:
jane> ns-engine -enginename my-engine
NetScript engine "my-engine" started on port 1099
Initially, no boxes are loaded at this engine. The engine waits idle until
a remote client issues commands to instantiate and run NetScript boxes.
You are now ready to send a box to the server. In what follows we will
send to boxes to the engine, connect them together, start them up, and
then stop them. The first box, an Ethernet driver, will generate packets
that arrive from the network on its single output port. The output port
of the Ethernet box will connect to the input port of the second box, which
will simply print the Ethernet packets that arrive at its inport port.
How to Send Commands to the EngineServer
Once started, the engine will wait for commands sent to it from remote
stations. These commands include ns-instantiate,
to dispatch a NetScript program to an engine and create a named instance
of it; ns-connect, to connect the ports
of two boxes; ns-disconnect to disconnect
two ports; ns-start, to run an instantiated
box; ns-kill, to halt and remove a running
box; ns-suspend, to temporarily suspend
an instantiated box; and ns-resume to
re-start a suspended box.
The ns-instantiate command sends a NetScript box to a remote engine
and creates a named instance of it on that engine.
ns-instantiate <engine-url> <box-url> [<args>]
where <engine-url> is a URL that identifies the remote engine
to which the box referenced by <box-url> should be sent. Any
additional arguments are passed to the new box after it is instantiated.
NetScript uses a special URL for identifying remote engines and boxes.
The syntax for a NetScript URL is:
Here host-name is the DNS name of the remote host that is running
the NetScript engine and port identifies the port on which the engine is
listening for commands. If the port is omitted, NetScript assumes the default
(1099). engine-name identifies a particular NetScript engine on the remote
host. The last part of a NetScript URL, box-name a particular NetScript
box to operate on. Since NetScript boxes nested within each other, the
box-name is a slash-delimited string that can refer to a deeply nested
box. For example, the URL ns://jane.cs.columbia.edu/my-engine/box1/box2
refers to a box called box2 nested inside box1 at the
engine my-engine on host jane.cs.columbia.edu.
The second argument to ns-instantiate is either the full class
name of NetScript box or a standard URL (e.g., http://, ftp:// file://)
that points to location where the NetScript box code is stored. If the
full class name (e.g., netscript.protocol.ethernet.EthernetBox)of
a NetScript box is specified, then the remote NetScript engine assumes
the box class is located within its CLASSPATH. If a URL is given,
the remote engine makes an appropriate connection and retrieves the class
file (and all its dependencies) from the network. The engine then creates
a local instance of the box and calls it box-name. Note that if
the box-name specifies a hierarchically nested box, the engine will create
attempt to create the new box at the appropriate point in the box hierarchy.
(If one of the boxes in the hierarchy does not exist, or if a box of the
specified name already exists, the engine will return an error.)
The final argument to ns-instaniate is an optional list of
arguments to pass to the newly instantiated box. The box uses these arguments
to configure itself at instatiation time.
Note that an instantiated does not begin to process messages until it
has been started with the ns-start command.
Let's instantiate a couple of boxes on the above engine. To do this,
type the following commands from a remote machine:
The first command creates an instance of the box netscript.protocol.ethernet.EthernetBox
called eth0 on the engine my-engine. It passes the last
two arguments (eth 0) to the instantiated box. These arguments
tell the EthernetBox which device to open.
sally> ns-instantiate \
ns://jane.cs/my-engine/eth0 netscript.protocol.ethernet.EthernetBox eth 0
sally> ns-instantiate \
The second command instantiates an instance of EthPrinterBox
Note that in this example, the code for the instantiated boxes already
exists somewhere in the CLASSPATH used by the remote engine. In
general, the second argument to ns-instantiate can refer to any
Now that we have to boxes at the remote engine, we need need to connect
them together, and start them up.
The command ns-connect connects the ports of two boxes together. This command
has four forms:
The first form connects the output port (abbreviated outport) of one box
to the input port (or inport) of another. Both boxes must share the same
parent. Messages sent by the first outport are delivered to the all connected
outport <src-outport-name> <src-box-url> inport <dst-inport-name> <dst-box-url>
outport <src-outport> <src-box-url>> outport <dst-outport>
inport <src-inport> <src-box-url> inport <dst-inport> <dst-box-name>
inport <src-inport> <src-box-url> outport <dst-outport>
Note that in order for two ports to connect successfully, their type
signatures must match. More information on the specific semantics of interconnection
is provided in the accompanying tutorial and programming manual.
The second form for connects the outport of one box to the outport of
its enclosure. Messages produced by the first box are simply forwarded
directly out of the port of the enclosing box.
The third form connects the inport of an enclosing box to the inport
of an internal box. Messages that arrive on the inport of the enclosing
box are forwarded to all connected internal inports.
The last form is simply a short-circuit from an inport of a box to an
outport of the same box.
In our example, we will connect the out1 outport of the ethernet
driver box eth0 to the in1 inport of the printer
box. Here is the command to type:
This connects the two boxes. We now need to start the two boxes. (Although
this example connects the ports before starting the two boxes, this is
not necessary. You can connect ports of boxes of two running boxes.)
sally> ns-connect \
outport out1 ns://jane/my-engine/eth0 inport in1 printer
Note that syntax for ns-connect allows the user to specify
NetScript URLs for both the source and destination boxes. The next release
of NetScript, will use this syntax and the Virtual Active Network(VAN)
architecture to create connections between engines that reside on different
hosts on a network.
This command starts (i.e., runs) an instantiated box at a remote NetScript
engine. Once started, a box can process packets that flow through it. If
the specified box does not exist at the remote engine, an error is returned.
For example, we use the commands
Once started, the Ethernet box eth0 begins to deliver packets
that arrive from the network on its out1 outport. The printer
will now print packets that arrive at its in1 inport.
sally> ns-start ns://jane/my-engine/eth0
sally> ns-start ns://jane/my-engine/printer
ns-kill stops and removes the box identified by ns-box-url. This command
effectively deletes the box from the remote engine. All internal boxes
are stopped and connections to and from this box are removed. A box can
be killed even if has not yet been started
For example, the following command will stop the eth0 box:
This command delets eth0 from the engine and disconnects it from
the printer box. The printer box will stop printing packets on the engine
sally> ns-kill ns://jane/my-engine/eth0
This command suspends a box and its contents; a suspended cannot accept
or generate messages until it is later resumed with the resume command.
It is legal to suspend a box before it has been started.
When the box is eventually started, it will suspend immediately.
This command resumes a suspended box and, recursively,
all of its contents. The command has no effect on a running box.
The command ns-disconnect removes a connection between two box
ports. Like ns-connect, this ns-disconnect has
four forms, one to disconnect an outport from an inport, one to disconnect
an outport from an outport, one to disconnect an inport from an inport,
and one to disconnect an inport from an outport.
How to Compile and Build Your Own Boxes
The NetScript Language and Toolkit Tutorial included with this distribution
describes the underlying principles of the NetScript language and shows
how to program with the Java classes that come with the NetScript Toolkit.
The NetScript Toolkit requires that you follow a small number of simple
stylized rules for creating a box in Java.
This section describes in practical terms how to use the Toolkit to
build your own boxes. First, read the tutorial, and examine the source
code in the distribution. For further information on the APIs, look at
Javadoc directory which covers all the classes netscript.kernel
package hierarchy. The directory netscript/protocol/ contains
a number of example boxes for various protocols including Ethernet, ARP,
IP, and RIP. You might want to use one of these boxes as a template.
To compile your box, add the file $NETSCRIPT_HOME/netscript.jar
to your CLASSPATH, and use Javac to compile the file(s). Next,
either put the compiled classes in a directory that is in the classpath
of the host that is to run ns-engine, or put the
classes in any directory that is accessible through an http://, ftp://,
or file:// URL. (Note that a file:// URL refers to file on the remote engine,
not the client!) Next, use the client commands described above to send
your boxes to a remote engine or you can use the -load command-line
argument of ns-engine to load and instantiate a box when the engine is
How to Run the Example IP Router and Firewall
The NetScript distribution includes a RIP-based IP router written in NetScript
and a simple firewall application which can be installed as an add-on component
to the router. The router is organized as a collection of NetScript boxes,
each of which performs a separate protocol function (e.g., Ethernet, IP,
ARP, UDP, RIP, etc).
The example router and firewall show how one could plug in components
to customize the behavior of any given NetScript node.
The following instructions describe how to install the NetScript router
on your machine. Essentially, you will start a engine and load NetScript
code so that it will function as an IP router. Finally, you can extend
this router with simple firewalling functions. A GUI tool lets you configure
filtering rules from a remote station.
How to Configure, Install and Run the Router
Before beginning, you will need a PC with at least two Ethernet cards,
each connected to a separate network. Your local network should use RIP
as its routing protocol. You might also want to read about limitations
of the router implementation.
For each card, you will need the following information:
Name of Ethernet device connected to the network (e.g., eth0, eth1, etc)
IP address associated with card
Broadcast address of this network
Address of next hop router
Log in to the root account or to an account with equivalent privileges
(the router needs promisquous access
Edit the file $NETSCRIPT_HOME/netscript/application/router/ns-router.config.
This file is used by the router to configure itself when it is started.
You can use the example configuration as a template for your network.
Make sure that kernel routing is turned off. Under Redhat Linux you can
do this by writing the value 0 to the file /proc/sys/net/IPv4/ip_forward.
Use the command ns-router to start an NetScript engine on the
router machine. ns-router is a script that starts a NetScript
engine and then loads, instantiates, and starts a collection of NetScript
boxes to perform IP routing.
The router should now begin forwarding packets
How to Install and Run the Firewall
The firewall application consists of a graphical front-end that communicates
with the NetScript router. The front-end dispatches NetScript boxes to
the router to perform various filtering functions. The firewall currently
filters IP, TCP, and UDP traffic. You can extend it to support filtering
of other protocols. For more details on how add new filtering capabilities
to the firewall please see the readme
file in the src/netscript/application/firewall directory.
The GUI component of the firewall uses Swing, version 1.1, which you can
download from Sun.
To start the firewall, first start up a router, as shown in the above
section. Next, log into any machine on which NetScript is installed and
type the command, ns-firewall. This will start up the firewall
Choose the File->New menu to bring up a firewall selection dialog. The
fields in the top part of the dialog box tell the firewall console how
to locate the firewall engine. Fill in these fields.
The bottom part of the dialog is a standard file chooser which lets
you choose the firewall configuration file 'firewall.conf'. This
file is located in $NETSCRIPT_HOME/src/netscript/application/firewall.
Use the file chooser dialog to find and select the firewall.conf
file. The configuration file tells the firewall console application what
filters to install and how to configure them. You can edit the configuration
file to add filters of your own. A readme file in the firewall directory
explains how to edit the configuration file.
Select the firewall.conf file and then press the 'Create' button.
The firewall console will attempt to dispatch a firewall to the remote
router. If successful, the console will display a frame that shows the
current firewall configuration. Initially, the firewall lets all packets
pass through the router. You can use the buttons at the bottom of the firewall
frame to add or remove various filters.
The current firewall is organized as a pipeline of filter boxes layered
directly above IP. Each filter box passes through or drops incoming packets
based on some filtering criteria. The next version will support placing
firewall filters anywhere in the protocol stack.
Liza Loinaz, a Masters student in Computer Science at Columbia, wrote the
NetScript IP router.
The firewall was written by Hao Huang, a DCC Lab research associate,
and Janek Parek, a Columbia undergraduate who was a student in our Computer