Getting started...

The toolbox comes in two archives : a binary one with a precompiled toolbox and a source one with all the Java sources. These archives contain the following directories :

• dist contains the executable JAR (Java Archive File) totem-<version>.jar (only for binary package)
• documentation contains this UserGuide
• example contains examples of topology, traffic matrix and scenario
• licence contains the licence of the third libraries
• lib contains the libraries needed to compile and execute the toolbox
• src contains the source code (only for source package)

Currently, the toolbox has been tested only on linux platforms.

Installation

To use the toolbox, you need a Java Virtual Machine ² (J2SE 5.0 or newer). If you haven't a Java Virtual machine you have to download and install it. Don't forget to set the JAVA_HOME environment variable to your JVM installation directory.

Decompress the TOTEM archive with

tar -xzvf totem-<version>.tar.gz

With the binary archive, the installation is finished. You can go to section 2.3 to briefly see how to use the toolbox. With the source release, you need to compile the toolbox as described in the next section.

Compilation

The source archive contains all the Java source files and you need to compile them before running the toolbox. To compile the toolbox, we need Ant ³ (release 1.6.2 or newer) provided by the Apache project. Ant is a Java-based build tool. It is kind of tool like Make. If you haven't Ant installed, download and install it. Don't forget to set the ANT_HOME environment variable.

The Ant build file (build.xml) contains the following interesting targets :

• build builds the TOTEM project
• clean cleans the project and prepares the directory
• doc generates the javadoc in doc directory

By using :

ant clean build

You compile and build the whole toolbox in the dist/totem-<version>.jar file. If you compile for the first time the toolbox, you need to call ant clean to create the needed directories. More information can be found in the README file.

The "totem.sh" command

This shell script runs the toolbox setting the maximum heap size to 512Mb. The following options are available to the command line. If no option is set, the GUI will be launched (see section 10).

-demo. Launch the GUI with increased font size (so that it can be projected for a live demo).

-s <scenario.xml> [stopOnError]. Executes the scenario scenario.xml (see section 9 for more information about scenarios). If stopOnerror is true, the scenario will stop executing after the first errror. In the example directory, you can see some scenarios examples highlighting the main functionalities of the toolbox ⁴.

-dir <dirname>. Executes all the scenario files contained in the directory dirname.

-validate <file.xml> [<schemaLocation>]. Validates the XML file file.xml.
schemaLocation is optional (if not present, the validator uses the schema specified in the XML file).

-gs <type> -f <scen.xml> -d <domain.xml> -t <tm.xml> -m <method>. Generates a scenario XML file scen.xml using the XML domain file domain.xml and the XML traffic matrix file tm.xml. The generated scenario depends on type which can be wca or fullmesh.
wca generates a scenario which simulates the failure of each link and displays the resulting load. If wca scenario is chosen, an additional parameter which is -c <chartname> can be added. If specified, a chart will be created in the file chartname in eps, jpg or png format depending on the given file extension.
fullmesh generates a scenario which establishes a full mesh of LSPs. The method used to route the traffic is given by method which can be CSPF, CSPFInvFreeBw, CSPFHopCount, CSPFInvCap, CSPFTEMetric and DAMOTE.

For example, the following command line

./totem.sh -s examples/abilene/scenario/CSPF-fullmesh.xml

execute the scenario file CSPF-fullmesh.xml of the directory examples/abilene/scenario. This scenario computes an LSP between each nodes with a reservation corresponding to the demand given by TM0-abilene.xml using CSPF. At the end, it displays the bandwidth reservation on each links. This scenario has been generated using ./totem.sh -gs fullmesh.