ANTS 2.0

Introduction

ANTS, the Active Network Transport System, is a Java-based toolkit for constructing an active network and its applications. This distribution includes supporting utilities, numerous examples and even some documentation.

Contents:

Using ANTS
Hacking ANTS

Using ANTS

The Basics

Read the INSTALL file for instructions on building ANTS.

Before you start using ANTS, you'll need to make sure your JVM and basic libraries are configured correctly. There is a shell script in the scripts directory sanitycheck that will make sure your JVM works, and that the Java NodeOS and basic ANTS startup class are visible in the classpath. If it fails, make sure that the emuJanosVM jar, the Janos Java NodeOS jar, and the ANTS jar are in your classpath.

A script antsvm is created in the scripts directory that will setup the classpath correctly. To use it during the sanitycheck script, set the JVM environment variable to the full path to the antsvm script. For example:

env JVM=/path/to/ants/bin/antsvm ./sanitycheck

(Note that the JVM defaults to ./antsvm.)

There are two simple interfaces for starting ANTS nodes, ants.core.ConfigurationManager and ants.core.NodeConfigure.

ConfigurationManager starts a node based on a text configuration file (see the *.config files in the scripts directory). The configuration file can describe an entire network of machines, so the ConfigurationManager command takes a node address which is used to pick a single node's information out of the file.

NodeConfigure can start a node without as many configuration file dependencies (though you'll still need a file for routing information and for starting complicated applications).

For either one, the javadoc (or source) includes pertinent details. All of the examples in the scripts directory use the ConfigurationManager, while the regression tests tend to use NodeConfigure.

More Information

While there is no "User's Manual" for ANTS, there are several sources of information about Programming for ANTS.

The javadoc-generated documentation provides a lot of specifics and details on the APIs available. (Note that the provided documentation only covers the public interfaces.)
The example programs in the ANTS Applications directory provide a good place to see what can be done and how.
David Wetherall's Thesis contains descriptions of several ANTS APIs (though many APIs have changed since ANTS 1.0).
Two papers on ANTS are included in this distribution:
- ANTS: A Toolkit for Building and Dynamically Deploying network Protocols (postscript). Describes the ANTS architcture. The version of ANTS described is a bit older, and thus contains a number of differences; consult the API reference pages for details.
- Developing Network Protocols with the ANTS Toolkit (postscript). Describes the general design and usage considerations for the ANTS programming model. Some of the details are specific to older versions of ANTS; consult the API reference pages for current usage details.
There are some additional papers on ANTS, available from David Wetherall's home page.

Debugging

First off, setup a configuration file for your app that can be used by the nodesetup.sh script in the scripts directory. Then you can leverage the multiple xterms and JVM cleanup code from that script.

Both the ANTS code and the (debugging version of the) Janos Java NodeOS code are littered with "trace" calls. Traces can be turned on at runtime through a system property. For ANTS, the system property is ants.debugFlags. The value for the property should be a comma-separated list of trace flags (listed below). The most convenient way to specify a system property is via the JVM's command line argument -D, like this:

java -Dants.debugFlags=ALL edu.utah.janos.nodeos.Main ants.core....

The set of flags that are available is defined in ants/src/core/Trace.java and consists of

ANTS_STARTUP
ANTS_DYNLOAD
ANTS_OUTGOING
ANTS_CAPSULECHANNEL
ANTS_APP
ANTS_CONSOLE
ANTS_ROUTEINFO
ANTS_ROUTE_UPDATE
ANTS_ROUTE_TIMER
ANTS_ROUTE_READ_TABLE
ANTS_DANTE
ANTS_NEIGHBOR_TABLE

Additionally, the flags ALL and NONE do what you might expect. Multiple flags can be combined:

java -Dants.debugFlags=ANTS_APP,ANTS_DANTE

In addition to the flags at the ANTS level, the Java NodeOS has a similar selection of flags. NodeOS flags are set with the janos.debugFlags property. The available flags for the NodeOS are defined in the class edu.utah.janos.nodeos.Trace and are:

NODEOS_INCOMING
NODEOS_BUFH
NODEOS_OUTGOING
NODEOS_DISPATCH
NODEOS_CLASSLOAD
NODEOS_DESTROY
NODEOS_THREADS
NODEOS_FLOWSTART

ANTS on the ABONE

Here is some good documentation about ANTS on the ABONE.

Hacking ANTS

For information on hacking ANTS and the internals of ANTS, the source is always your best choice. Additionally, the mailing lists for ANTS are good resources. Again, the javadoc-generated documentation should be quite helpful (if you're hacking ANTS, you may want to re-generate the documentation with -private. See the script developers/docgen.)

Some ANTS coding conventions are spelled out in the file CodeStyle.txt.

Addtionally, there is a description of the ANTS2 security architecture, and a brief overview of how "IDs" are used in the ANTS core ( On_IDs.txt).

Finally, ANTS2 is based on the Janos Java NodeOS so if you're hacking ANTS you will probably want to get the sources to the Java NodeOS (available at the Janos web pages).