Last Updated: Sunday, October 11, 1998

How To Use NetScript 0.10

This page describes:

  • What is NetScript?
  • System Requirements
  • What is included in this release; what we plan for future releases
  • 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
  • Credits


    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 Toolkit.

    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 separately.

    System Requirements

    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

    bin Various wrapper scripts to start and control a NetScript engine
    doc Javadoc documentation for the main kernel packages
    Makefile To build the NetScript distribution
    readme.html This file
    src All the source code for the NetScript system
    src/netscript The netscript package hierarchy
    src/netscript/application Example NetScript applications -- the IP router and firewall
    src/netscript/client NetScript client programs for controlling a remote engine
    src/netscript/kernel The NetScript engine sources
    src/netscript/protocol Various NetScript implementations of protocols -- Ethernet, IP, ARP, etc
    src/netscript/server Implements NetScript remote control protocol
    src/netscript/util Utility package
    src/gnu Per Bothner's bytecode package for working with Java class files
    todo.html Features planned for future releases
    tutorial.html A tutorial introduction to using the NetScript Toolkit 

    How to Install NetScript

    1. Download and untar the NetScript distribution. This will create a directory called netscript-0.10.
    2. 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/.
    3. 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:

      export NETSCRIPT_HOME=/home/bob/netscript-0.10/
      export JAVA_HOME=/usr/local/java/jdk1.1.6/
      export PATH=$NETSCRIPT_HOME/bin:$PATH
      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:
    1. Change directory to netscript-0.10.
    2. Type the command 'make'.
    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.

    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 sally.

    How to Start the NetScript Engine

    To start the NetScript engine, use the program ns-engine. The syntax of ns-engine is:
    ns-engine [-enginename name] [-port port] [-load box-url box-name args]
    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

    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 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

    jane> ns-engine -enginename my-engine
    This will start an engine called my-engine on the host jane. NetScript should print the following message:
    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:// refers to a box called box2 nested inside box1 at the engine my-engine on host

    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:

    sally> ns-instantiate \
      ns://jane.cs/my-engine/eth0 netscript.protocol.ethernet.EthernetBox eth 0
    sally> ns-instantiate \
      ns://jane.cs/my-engine/printer netscript.protocol.ethernet.EthPrinterBox
    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.

    The second command instantiates an instance of EthPrinterBox called printer.

    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 URL-accessible object.

    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:
    ns-connect \
      outport <src-outport-name> <src-box-url> inport <dst-inport-name> <dst-box-url>
    ns-connect \ 
      outport <src-outport> <src-box-url>> outport <dst-outport>
    ns-connect \
      inport <src-inport> <src-box-url> inport <dst-inport> <dst-box-name>
    ns-connect \
      inport <src-inport> <src-box-url> outport <dst-outport>
    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 downstream ports.

    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:

    sally> ns-connect \
      outport out1 ns://jane/my-engine/eth0 inport in1 printer
    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.)

    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.


    ns-start <ns-box-url>
    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

    sally> ns-start ns://jane/my-engine/eth0
    sally> ns-start ns://jane/my-engine/printer
    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.


    ns-kill <ns-box-url>
    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:

    sally> ns-kill ns://jane/my-engine/eth0
    This command delets eth0 from the engine and disconnects it from the printer box. The printer box will stop printing packets on the engine console.


    ns-suspend <ns-box-url>
    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.


    ns-resume <ns-box-url>
    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 started.

    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
    • Net mask
    • Address of next hop router
    1. Log in to the root account or to an account with equivalent privileges (the router needs promisquous access
    2. 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.
    3. 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.
    4. 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.
    5. 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 console.

    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 Networks course.




    [NetScript] [Publications] [People] [Download] [Links]

    Distributed Computing and Communications Lab
    Columbia University
    New York, NY 10027