Subsections

A standard XML format for a scenario representation

The XML scenario format is very simple: it's a list of events. There are four super abstract types that can only be extended: eventType, ASEventType, TMEventType, ASTMEventType. The first one has only one optional attribute time which specifies when the event has to occur. ASEventType and TMEventType define each an other optional attribute (ASID and TMID respectively). ASEventType is intended to be extended by intra-domain events, and TMEventType by traffic-related events. Finally, ASTMEventType combine the two last types. Note that if ASID is not specified, the events use the default domain and if TMID is not specified, the events use the default traffic matrix for the specified domain (or for the default domain).

Some events have to point out to files located on the local hard drive (loadDomain, loadTrafficMatrix, ...). By default, the paths are defined relatively to the TOTEM root folder. This default behaviour can be changed by setting the pathsRelativeTo attribute of the scenario element. The value of this attribute corresponds to the directory from which the relative paths defined in the events must be interpreted. It is even possible to specify a relative path for this attribute. In this case, the path is interpreted relatively to the current scenario file path.

For example, if you want to create a scenario that will load a domain that is in the same folder as the scenario file, you write something like the following.

<scenario pathsRelativeTo="./">
     <loadDomain file="topology.xml"/>
</scenario>

If you did not specify the pathsRelativeTo attribute, TOTEM will look for a file named topology.xml in its root folder.

Here is an example of a short scenario: language=xml, showstringspaces=false
$\begin{lstlisting} <?xml version=''1.0'' encoding=''ISO-8859-1'' standalone=''ye... ...me=''dst''>130.104.230.54</param> </cbgp:CBGPInfo> </scenario> \end{lstlisting}$
Since TOTEM 1.1, it's possible to plug new scenario events into the toolbox at the runtime. This slightly complicates the writing of a scenario file but allows the user to really extend the scripting language defined by the scenarios. In the developer guide, we explain how to write new scenario events. In this user guide, we will only give some XML notions necessary to write scenario files at hand⁸.

The above scenario file illustrates how to write scenario files which use several schemas. In this particular scenario, there are two types of events:

Core events defined in the main scenario schema: loadDomain, startAlgo, etc.
CBGP-related events defined in a separate schema: CBGPInfo, CBGPPeerDown, etc.

The idea is that the toolbox must know in which schema the events are defined. This is done thanks to the attributes of the scenario element. There are four attributes:

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance". This attribute defines a namespace called xsi. In the http://www.w3.org/TR/REC-xml-names/W3C recommandation about XML namespaces, we can read: "...An XML namespace is a collection of names, identified by a URI reference [RFC2396], which are used in XML documents as element types and attribute names...". The URI of a namespace has no special meaning, this is just a way to give a unique name to the namespace. However, as in our case, the URI can be used for a special purpose. Companies often use it as a pointer to a real Web page where you can find information about the namespace. In the toolbox, we use it to identify the package in which the class of an event is defined (as a package name is supposed to be unique, scenario namespaces will also be unique). So this attribute defines the xsi namespace. This definition allows us to use the schemaLocation attribute defined in the xsi namespace.

xsi:schemaLocation="http://jaxb.model.scenario.totem.run.montefiore.ulg.ac.be http://totem.run.montefiore.ulg.ac.be/Schema/Scenario-v1_3.xsd http://jaxb.model.scenario.totem.ingi.ucl.ac.be http://totem.run.montefiore.ulg.ac.be/Schema/CBGP-Scenario-v1_0.xsd". In the
http://www.w3.org/TR/xmlschema-0/XML Schema Part 0: Primer document, we can read: "...In an instance document, the attribute xsi:schemaLocation provides hints from the author to a processor regarding the location of schema documents. The author warrants that these schema documents are relevant to checking the validity of the document content, on a namespace by namespace basis..." and "...The schemaLocation attribute value consists of one or more pairs of URI references, separated by white space. The first member of each pair is a namespace name, and the second member of the pair is a hint describing where to find an appropriate schema document for that namespace. The presence of these hints does not require the processor to obtain or use the cited schema documents, and the processor is free to use other schemas obtained by any suitable means, or to use no schema at all...". So in this example, we use two namespaces: http://jaxb.model.scenario.totem.run.montefiore.ulg.ac.be and

http://jaxb.model.scenario.totem.ingi.ucl.ac.be. The first namespace contains the core elements and the associated schema is located at
http://totem.run.montefiore.ulg.ac.be/Schema/Scenario-v1_2.xsd. The second namespace contains the CBGP-related elements and the associated schema can be found at
http://totem.run.montefiore.ulg.ac.be/Schema/CBGP-Scenariov1_0.xsd.

xmlns:cbgp="http://jaxb.model.scenario.totem.ingi.ucl.ac.be". This attribute indicates that all the elements coming from the http://jaxb.model.scenario.totem.ingi.ucl.ac.be namespace are prefixed with cbgp:. So, as CBGPPeerRecv, CBGPRun, etc. are defined in
http://jaxb.model.scenario.totem.ingi.ucl.ac.be, they are prefixed with cbgp:.

xmlns="http://jaxb.model.scenario.totem.run.montefiore.ulg.ac.be". This attribute indicates which namespace is the default namespace. In this case, this is the namespace associated with the core elements. It means that in the sequel of the document all core elements have no prefix. For example, param and loadDomain are core events defined in
http://jaxb.model.scenario.totem.run.montefiore.ulg.ac.be and have no prefix.

Currently, there are three scenario XML schemas shipped with the toolbox:

Scenario-v1_3.xsd, which contains the core events;
CBGP-Scenario-v1_0.xsd, which contains the CBGP events;
SAMTE-Scenario-v1_0.xsd, which contains the events used by SAMTE;

We now describe two elements used by many events and all the core events classified by functions. Then we give more details about the CBGP-related events and the SAMTE-related events.

Common elements

`routingAlgo`

This element is used by events manipulating routing algorithms' instances. It has one required attribute name which is a string. This attribute is the routing algorithm's name (see 8 for the allowed values and their meaning). You can also specify parameters for the routing algorithm. The maximum number of param elements is unbounded and their type is described in section 9.1.2.

`param`

This element is a general purpose element which is used whenever a general "param-value" scheme is required. It has one required attribute name which is a string and which represents the parameter's name. The content of the element is a string and represents the parameter's value.

Domain Events

`linkDown`

This event extends ASEventType. It has two attributes: linkId which is a string and is required and cause which is a string and is optional.

This event sets the status of the link linkId that belongs to the given domain to DOWN. The cause is just printed using the logger.

`linkMetricChange`

This event extends ASEventType. It has two required attributes: linkId which is a string and metric which is a float.

This event sets the metric of the link linkId that belongs to the given domain to metric.

`linkTeMetricChange`

This event is the same as linkMetricChange described in section 9.2.2 except that it changes the traffic engineering metric instead of the metric.

`linkUp`

This event extends ASEventType. It has one required attribute linkId which is a string.

This event sets the status of the link linkId that belongs to the given domain to UP.

`loadDomain`

This event extends eventType. It has one required attribute file and three optional attributes (defaultDomain, useBWSharing and removeMultipleLinks). file is a string and the three other attributes are booleans. Note that the three booleans attributes are false by default.

This event loads the domain contained in the file file. removeMultipleLinks must be true if you want to force the graph to not be a multigraph and false otherwise. defaultDomain must be true if you want to set the loaded domain as the default domain and false otherwise. useBWSharing must be true if you want to use bandwidth sharing and false otherwise. If backup LSPs need to be calculated, useBWSharing should be set to true.

`nodeDown`

This event extends ASEventType. It has two attributes which are strings. The first one is nodeId which is required and the second one is cause which is optional.

This event sets the status of the node nodeId that belongs to the given domain to DOWN. The cause is just printed using the logger.

`nodeUp`

This event extends ASEventType. It has only one required attribute nodeId which is a string.

This event sets the status of the node nodeId that belongs to the given domain to UP.

`saveDomain`

This event extends ASEventType. It has only one required attribute file which is a string.

This event saves the given domain in the file file.

`topologyGeneration`

This event extends eventType. It accepts an unbounded number of param elements. The param element is described in section 9.1.2. It also accepts two optional attributes: type and path.

This event allows you to use the topology generation capabilities of the toolbox. The type indicates the topology generator to use. Only BRITE generator is implemented in the toolbox. The path indicates the path in which to save the generated files.

In order to make the use of this event simple, all the parameters for BRITE generator are optional and good default values have been defined⁹. So, you can simply type language=xml
$\begin{lstlisting} <topologyGeneration/> \end{lstlisting}$
to generate a topology. We now list in the tables 8 and 9 all the possible parameters and their possible values (you can find more information about the BRITE-specific parameters in http://www.cs.bu.edu/brite/publications/usermanual.pdfthe BRITE user manual).

A example scenario (topologyGeneration.xml) is provided in the examples directory.

Table 8: Topology generation parameters (default values have an asterisk) (part 1).

Parameter	Meaning	Values
BRITE-specific parameters
topologyType	Type of topology	"1 Level: AS Only"
		"1 Level: Router (IP) Only"
		"2 Level: Top-Down"
		"2 Level: Bottom-Up"*
topLevelModel	Model for the top level	"Waxman"
		"Barabasi-Albert 1"
		"Barabasi-Albert 2"
		"GLP"*
bottomLevelModel	Model for the bottom level	"Waxman"
		"Barabasi-Albert 1"
		"Barabasi-Albert 2"
		"GLP"
edgeConnectionModel	See BRITE manual	"Random"
		"Smallest-Degree"
		"Smallest-Degree NonLeaf"
		"Smallest k-Degree"
k	See BRITE manual	integer
groupingModel	See BRITE manual	"Random Walk"
		"Random Pick"*
asAssignment	See BRITE manual	"Constant"
interBWDist		"Uniform"*
intraBWDist		"Exponential"
		"Heavy Tailed"
numAS	See BRITE manual	integer (def.: 9)
interBWMax	See BRITE manual	double (def.: 20000)
interBWMin	See BRITE manual	double (def.: 10000)
intraBWMax	See BRITE manual	double (def.: 1000)
intraBWMin	See BRITE manual	double (def.: 500)
topHS	See BRITE manual	integer (def.: 10)
topLS	See BRITE manual	integer (def.: 1)
topN	See BRITE manual	integer (def.: 15)
topNodePlacement	See BRITE manual	"Random"*
		"Heavy Tailed"
topGrowthType	See BRITE manual	"All"*
		"Incremental"
topPreferentialConnectivity	See BRITE manual	"None"*
		"On"
topAlpha	See BRITE manual	double (def.: 0.42)
topBeta	See BRITE manual	double (def.: 0.65)
topM	See BRITE manual	integer (def.: 2)
bottomHS	See BRITE manual	integer
bottomLS	See BRITE manual	integer
bottomN	See BRITE manual	integer

Table 9: Topology generation parameters (default values have an asterisk) (part 2).

Parameter	Meaning	Values
BRITE-specific parameters
bottomNodePlacement	See BRITE manual	"Random"
		"Heavy Tailed"
bottomGrowthType	See BRITE manual	"All"
		"Incremental"
bottomPreferentialConnectivity	See BRITE manual	"None"
		"On"
bottomAlpha	See BRITE manual	float
bottomBeta	See BRITE manual	float
bottomM	See BRITE manual	integer
General parameters
mustBeConnected	Topology connected or not	boolean (def.: "true")
mustBeDualConnected	At - two links per node	boolean (def.: "true")
maxTrials	Number of generation trials before
	forcing "connected" and "dual connected"	integer (def.: 3)
	on the generated topology
metric	The metric to use	"Hop count"
		"Inverse of BW"*
numTopologies	The number of topologies	integer (def.: 1)

Lsp & Routing Events

This section describes the routing events. You'll find LSP routing events, optimal routing events and IP routing events. To display reservation and calculated load, see section 9.5 under "Display events".

`cplex:ComputeMCNFOptimalRouting`

In order to use this algorithm, the user has to own an ILOG CPLEX licence and compile the toolbox as explained in section 8.13.

This event extends ASTMEventType. It has three optional arguments : verbose and displayTEMetrics which are both of type boolean with default value false, and exportModelToFile which is a string giving the path to a .lp file where the linear programming model has to be exported.

The name argument of the cplex:objectiveFunction element defines the objective function to be optimized. It is a string, and is required. The objective functions that can be optimized are those given in section 8.13, i.e. Fortz, MIRA, Blanchy, MeanDelay, WMeanDelay, InvCap, umax, Degrande and MinHop.

The eventual parameters of the objective functions are defined in param elements, as shown below :

<param name="alpha">0.5</param>

The name argument gives the name of the parameter, and its value is defined between the opening and closing tags.

The formulation element has a required subelement, which can either be nodeLink or linkPath. In the latter case, the user has to set the value of the nbPaths argument, which is of type int.

<cplex:formulation>
    <cplex:linkPath nbPaths="2"/>
</cplex:formulation>

An example scenario file using this event can be found in
/examples/abilene/Scenario/cplexMCNF.xml

`computeMCF`

This event extends ASTMEventType. It has also four optional attributes: llcId, runGLPSOL, dataFile and resultFile. The three latter attributes are strings and the former is a boolean.

This event runs the MCF algorithm on the given domain and traffic matrix. The llcId attribute is used to later refer to the load by using the showLinkLoad event. runGLPSOL must be true if you want to run glpsol and false if you want only to generate the data file. resultFile is the name of the file that glpsol must produce and dataFile is the name of the file that glpsol takes as input.

`IGPRouting`

This event extends ASTMEventType. It has four optional attributes llcId, strategy, ECMP and SPFtype. strategy can be IP, BIS, IS or OVERLAY. ECMP is boolean and SPFtype is a string.

This event initiates a load computation. The llcId attribute is used to later refer to the load by using the showLinkLoad event. If strategy is not specified, it defaults to IP. SPFtype allows you to choose the SPF algorithm used to compute the load or the reservation of links (see the section 8.1 for the possible values). By default, a classical SPF algorithm based on the links' metrics is used. If you want to enable ECMP (Equal Cost MultiPath), ECMP must be true and false otherwise.

The values BIS, IS, OVERLAY are used when part of the traffic is routed with IGP routing (shortest path) while other part of the traffic is routed with MPLS label switched paths. In particular, the values BIS and IS can be used for SAMTE (see section 8.9), but can also be used in other algorithms. The value BIS corresponds to the Basic IGP Shortcut model. In this model, the traffic that is forwarded on the path of an LSP is the whole traffic that crosses the ingress node of the LSP and whose exit point is the egress of the LSP. The value IS is used for IGP Shortcut. In this model, the traffic that is forwarded on the path of an LSP is the whole traffic that crosses both the ingress and egress nodes of the LSP. In this last model, more traffic is forwarded on the LSP (there is no restriction about the exit point of the traffic). Finally, the OVERLAY value corresponds to the overlay model. In this model, the traffic is forwared on a LSP if the source and destination of the traffic match the ingress and egress of the LSP.

If you want to deal with backup LSPs and link/node failures, you should probably want to enable traffic switching in order for the traffic to be routed on some backup path when a failure is encountered on a primary LSP. Traffic switching can be enabled using the enableTrafficSwitching event (see section 9.3.6).

`optDivideTM`

This element launch the optDivideTM algorithm (described in section 8.5).

It has five optional attributes: The llcId attribute is used to later refer to the load by using the showLinkLoad event. N (an int whose default value is 3), objectiveFunction which can be equal to MeanDelay, WMeanDelay or NLFortz, establishMultipleFullMesh which is a boolean and specify if a full-mesh of LSP has to be established or not and finally verbose (a boolean).

`deleteAllLSP`

This event extends ASEventType. It deletes all the LSPs established on the specified domain or on the default domain if no domain is specified.

`enableTrafficSwitching`

This event extends ASEventType. It enables traffic switching on the specified domain or on the default domain. When traffic switching is disabled, routing cannot occur on primary lsps for which some resources are down (nodes, links). When it is enabled, routing can use some of the pre-established backup lsps to route the traffic (see 9.5.4 to see how traffic can be routed on LSPs).

A example is provided in the file examples/bwSharing/Scenario/trafficSwitching.xml.

`IGPWOCalculateWeights`

This event extends ASEventType. It has three optional attributes which are ints: maxPossibleWeight, nbIter and seed. It also has an optional attribute called initialWeightArray which can be CURRENT or RANDOM. The default value for nbIter is 150, 50 for maxPossibleWeight, 0 for seed and RANDOM for initialWeightArray. It also accepts zero or one samplingRate element and an unbounded number of trafficMatrix elements. These trafficMatrix elements have only one required attribute TMID that represents the ID of a traffic matrix. The samplingRate element has three optional attributes which are floats: initial (default value: 0.2), min (default value: 0.01) and max (default value: 0.4).

This event runs the IGPWO algorithm on the given domain and traffic matrices. nbIter is the number of iterations that IGPWO must do and maxPossibleWeight is the maximum weight that IGPWO can produce. seed is used for the random number generator in the algorithm.

The samplingRate element controls the sampling of neighborhoods during local search. At each iteration, a proportion of the neighborhood is evaluated due to the large size of the problems. The initial rate by which the neighborhood is sampled is determined by initial. During the algorithm run, the value of the sampling rate is updated. If the current solution is improved, the sampling rate is divided by three, if not it is multiplied by two. The upper and lower bounds of the sampling rate are determined by max and min.

`LSPBWChange`

This event extends ASEventType. It has two required attributes lspId which is a string and bw which is a float.

This event sets the reservation of the LSP lspId of the given domain to bw.

`LSPBackupCreation`

Deprecated. Please use LSPBypassCreation (9.3.10) or LSPDetourCreation (9.3.13).

This event extends ASEventType. It has two optional attributes: lspId which is a string and bw which is a float. It also accepts the following subelements in sequence:

Detour or Bypass. Exactly one of these two elements must occur exactly one time. The Detour element has one required attribute protectedLSP which is a string and two optional attributes (methodType and protectionType). methodType can be LOCAL or GLOBAL (default value). protectionType can be NODE_DISJOINT (default value) or LINK_DISJOINT. The Bypass element accepts one or several protectedLink elements which have only one required attribute linkId which is a string.
The routingAlgo element that must occur exactly one time. This element is described in section 9.1.1 page .

This event creates a backup LSP on the specified domain using the specified routing algorithm. The ID of the newly created LSP will be lspId and its bandwidth will be bw. If these parameters are not specified, default values will be used (an ID will be automatically generated and the bandwidth will be, for example, the bandwidth of the protected LSP). If the Detour element is present, a detour LSP will be created. Otherwise, we create a bypass LSP. In the case of a detour LSP, protectedLSP must be the ID of the LSP to protect, methodType indicates whether the backup LSP to create must be local (LOCAL) or global (GLOBAL), and protectionType indicates whether the backup LSP must be node disjoint (NODE_DISJOINT) or link disjoint (LINK_DISJOINT) from the protected LSP. In the case of a bypass LSP, the linkId attributes of the protectedLink elements are the IDs of the links to protect.

Important note: do not forget to start the routing algorithm before using it in a LSPBackupCreation event. See the section 9.8.3 for more information.

`LSPBypassCreation`

This event has the same attributes and sub-elements that LSPCreation, apart from the src attribute which is not present. It addition to these properties, the event accepts one or several protectedLink elements which have only one required attribute linkId which is a string.

The dst attribute is optional in this event. If it is not given, the destination node will correspond to the destination node of the last protected link. To define a NNHOP bypass LSP, we must provide the dst node (as NNHOP protects only one link). For NHOP bypasses, only one protected link should be provided and the dst node ommitted.

`LSPCreation`

This event extends ASEventType. It has two required attributes (src and dst) which are strings and three optional attributes (lspId, bw and establishLSP). lspId is a string, bw is a float and establishLSP is a boolean. It also accepts the following subelements in sequence:

A metric element that contains a float and that can occur 0 or 1 time.
A maxRate element that contains a float and that can occur 0 or 1 time.
A diff-serv element that can occur 0 or 1 time. The content of this element is the same as the diff-serv element described in section 6.
A accepted_cos element that can occur 0 or 1 time. The content of this element is a list of cos subelement which are strings.
A path element that can occur 0 or 1 time. The content of this element specifies the route of the LSP. It can be described as a sequence of node ids (<node>node_id</node>) or a sequence of links ids (<link>link_id</link>).
The routingAlgo element that is optional. This element is described in section 9.1.1 page .

This event creates a primary LSP on the specified domain using the specified routing algorithm. The source of the LSP is src and the destination of the LSP is dst. Its reserved bandwidth is bw. If bw is not specified, the reserved bandwidth will be 0. lspId is the ID given to the created LSP (if it is not specified, an ID is automatically generated). metric is the metric of the created LSP and maxRate is the maximum rate at which it will be possible to send data over the LSP. For more information about the diff-serv element, see the section 6.

The accepted_cos defines the LSP accepted classes of service. Each of the given cos element must correspond to a class of service defined in the domain.

The path element is used to establish explicit route LSPs. If it is present, the element routingAlgo will be ignored and the LSP will be established following the given route.

The establishLSP attribute, which is true by default, can be set to false in order to only calculate the LSP route without establishing it. The calculated route will be printed on standard output.

Important note: do not forget to start the routing algorithm before using it in a LSPCreation event. See the section 9.8.3 for more information.

`LSPDeletion`

This event extends ASEventType. It has one required attribute lspId which is a string.

This event deletes the LSP lspId of the given domain.

`LSPDetourCreation`

This event has the same attributes and sub-elements that LSPCreation, apart from the src and dst attributes which are not present. It addition to these properties, the event has one required attribute protectedLSP which is a string and two optional attributes (methodType and protectionType). methodType can be LOCAL or GLOBAL (default value). protectionType can be NODE_DISJOINT (default value) or LINK_DISJOINT.

The protectedLSP must be the ID of the LSP to protect, methodType indicates whether the backup LSP to create must be local (LOCAL) or global (GLOBAL), and protectionType indicates whether the backup LSP must be node disjoint (NODE_DISJOINT) or link disjoint (LINK_DISJOINT) from the protected LSP.

`mplsCosRouting`

This event extends ASEventType. It has one mandatory attribute llcId which is a string and it requires a list of cos element whose content corresponds to a loaded traffic matrix id. It also requires a name attribute correponding to the value of a defined class of service (in the domain).

The llcId attribute is used to later refer to the load by using the showLinkLoad event.

This event routes the given matrices on the LSPs established in the domain, each one with the class of service associated to it. The class of service is used to chose the LSPs on which traffic of this class can be routed.

If you want all traffic to be routed, there must be a fullmesh of LSPs that can accept every class of services.

Traffic matrix Events

`generateIntraTM`

This event extends eventType. This element requires the following attributes: NETFLOWbasedirectory, NETFLOWdirFileName, BGPbasedirectory, BGPdirFileName, clusterFileName, trafficMatrixFileName, minutes and samplingRate. All these attributes are strings, except the last two which are ints.

This event is used to generate an intra-domain traffic matrix from BGP dump information and NetFlow traces. See section 11 for more information about required formats. You will find details about the parameters in section 11. The minutes and samplingRate parameters are used to convert flow sizes (in bytes) found in NetFlow traces in kbps. You must fill minutes with the length (in minutes) of the NetFlow traces period. samplingRate must contain the sampling rate used in the NetFlow traces.

`loadTrafficMatrix`

This event extends TMEventType. It has one required attribute file which is a string.

This event loads the traffic matrix contained in the file file. The traffic matrix ID of the loaded traffic matrix will be the given traffic matrix ID. If you don't specify an ID, it will be generated automatically and the matrix will be set as the default traffic matrix.

`removeTrafficMatrix`

This event extends ASTMEventType. It has no other parameters.

This event removes the traffic matrix from the manager. If the attribute tmId is not provided, the default traffic matrix is removed.

`trafficMatrixGeneration`

This event extends ASTMEventType. It accepts an unbounded number of param elements. The param element is described in section 9.1.2. It also accepts two optional string attributes: path and type.

The type attribute indicates the type of traffic generator to use. Generators included in the toolbox are Constant, Gravity or Random.

This event allows you to use the traffic generation capabilities of the toolbox. A traffic matrix with the specified TMID will be created for the specified domain (if numTrafficMatrices parameter is 1). In order to make the use of this event simple, all the parameters are optional and default values have been defined. So, you can simply type language=xml
$\begin{lstlisting} <trafficMatrixGeneration/> \end{lstlisting}$
to generate a traffic matrix.

We now list in the table 10 all the common parameters and their possible values.

Table 11, 12 and 13 lists model specific parameters for random, gravity and constant generator respectively.

Table 10: Traffic matrix generation parameters (default values have an asterisk). Common values for all generators.

Parameter	Meaning	Values
numTrafficMatrices	Nb of traffic matrices to generate	integer (def.: 1)
shouldBeRoutable	Tell if the generated matrix	boolean (def.: true)
	must be routable on the domain
maxTrials	Number of trials before giving up	integer (def.: 3)
	finding a routable matrix.
generateOnlyEdgeTraffic	If set to true, only traffic to/from	boolean (def.: true)
	non-CORE nodes will be generated.

Table 11: Traffic matrix generation parameters (default values have an asterisk). "Random" specific parameters.

Parameter	Meaning	Values
trafficDistribution	The distribution	"Bimodal"
		"Constant"
		"Normal"
		"Poisson"
		"Uniform (float)"
		"Uniform (integer)"*
		"Inverse normal"
		"Logistic"
		"LogLogistic"
		"LogNormal"
bimodalMean1	First mean of the bimodal distribution	double
bimodalMean2	Snd. mean of the bimodal distribution	double
bimodalStddev1	First std. dev. of the bimodal dis.	double
bimodalStddev2	Snd. std. dev. of the bimodal dis.	double
bimodalCoinFlip	Coin flip of the bimodal dis.	double
constant	Constant of the constant dis.	double
normalMean	Mean of the normal dis.	double
normalStddev	Std. dev. of the normal dis.	double
poissonMean	Mean of the Poisson dis.	double
uniformFloatLower	Lower bound of the unif. float dis.	double
uniformFloatUpper	Upper bound of the unif. float dis.	double
uniformIntLower	Lower bound of the unif. integer dis.	integer (def.: 15)
uniformIntUpper	Upper bound of the unif. integer dis.	integer (def.: 25)
invNormalMu		double (def.:0.0)
invNormalLambda		double (def.:0.0)
logisticMu		double (def.:0.0)
logisticSigma		double (def.:0.0)
logLogisticMu		double (def.:0.0)
logLogisticSigma		double (def.:0.0)
logNormalMu		double (def.:0.0)
logNormalSigma		double (def.:0.0)

Table 12: Traffic matrix generation parameters (default values have an asterisk). "Gravity" specific parameters.

Parameter	Meaning	Values
FrictionFactor	The friction factor	"DistanceFriction"
	of the gravity traffic model	"DistributionFriction"*
ScalingConstant	The scaling constant	double (def.: 0.0001)
	of the gravity traffic model
All parameters specific to "Random" generator if "FrictionFactor" is "DistributionFriction".
(see table 11)

Table 13: Traffic matrix generation parameters. "Constant" specific parameter.

Parameter	Meaning	Values
value	Value of the constant.	double (def.: 0.0)

Display Events

`echo`

This event extends eventType. It has one required attribute msg which is a string.

This event prints the string msg on the standard output stream.

`ECMPAnalysis`

This event extends ASEventType. It accepts no attribute nor element.

This event prints information about existing equal cost paths on the standard output stream. Note that this event uses the standard metrics (not the TE metrics) of the given domain.

`listShortestPaths`

This event extends ASEventType. It has five attributes: src, dst and SPFType which are strings and ECMP and nodeList which are booleans. All these attributes are optional.

This event prints information about shortest paths of the given domain on the standard output stream. If src and dst are specified, it prints only shortest paths between these two nodes. If only src (resp. dst) is specified, the shortest paths from src (resp. to dst) to (resp. from) all the other nodes are listed. If neither is specified, it prints all the shortest paths of the given domain. If you want to take ECMP into account, ECMP must be set to true and false otherwise (note that it is false by default). SPFType is exactly the same attribute as the one described in section 9.5.4. Finally, nodeList specifies whether the paths must be printed under the form of a list of nodes or a list of links. If it is true, a list of nodes is printed. Otherwise, the event prints a list of links. Note that the attribute is true by default.

`ShowLinkInfo`

Deprecated. Use showLinkReservation (9.5.7) or showLinkLoad (9.5.5).

This event extends ASTMEventType. It has four optional attributes type, verbose, ECMP and SPFtype. type can be LOAD, LOAD_BIS, LOAD_IS, RESERVATION and PRIMARY_BACKUP. verbose and ECMP are booleans and SPFtype is a string.

This event prints information about the load or about the reservation of links (if the value of type is LOAD or RESERVATION) on the standard output stream. If type is not specified, it prints information about the load of links by default. verbose must be true if you want to have information about each link of the given domain and false if you just want to print the following values: maximum, mean, standard deviation and percentile 10 (verbose is false by default). SPFtype allows you to choose the SPF algorithm used to compute the load or the reservation of links (see the section 8.1 for the possible values). By default, a classical SPF algorithm based on the links' metrics is used. If you want to enable ECMP (Equal Cost MultiPath), ECMP must be true and false otherwise. By default, ECMP is false.

If the value of type is PRIMARY_BACKUP, the event prints some information about primary and backup link reservation (total primary bandwidth reserved, oversubscription for backup (with or without taking sharing between primary and backup paths into account), mean and max link utilization). In order to use this feature correctly, you have to set the useBWSharing attribute of the loadDomain element to true.

The values LOAD_BIS, LOAD_IS, LOAD_OVERLAY are used when part of the traffic is routed with IGP routing (shortest path based on link weigths) while other part of the traffic is routed with MPLS label switched paths. In particular, the values LOAD_BIS and LOAD_IS can be used for SAMTE (see section 8.9), but can also be used in other algorithms. The value LOAD_BIS corresponds to the Basic IGP Shortcut model. In this model, the traffic that is forwarded on the path of an LSP is the whole traffic that crosses the ingress node of the LSP and whose exit point is the egress of the LSP. The value LOAD_IS is used for IGP Shortcut. In this model, the traffic that is forwarded on the path of an LSP is the whole traffic that crosses both the ingress and egress nodes of the LSP. In this last model, more traffic is forwarded on the LSP (there is no restriction about the exit point of the traffic). Finally, the LOAD_OVERLAY value corresponds to the overlay model. In this model, the traffic is forwared on a LSP if the source and destination of the traffic match the ingress and egress of the LSP.

`showLinkLoad`

This event extends ASEventType. It has one attribute llcId that refers to the load to show. It also has two attributes that indicate which information to show (linkId, classOfService) and two boolean attributes that indicate which aggregation level to use in the display (perLink, perClassOfService).

The event prints load information on the standard outputstream (link capacity, load and utilisation). The attribute llcId is used to refer to a specific load for which computation was initiated earlier by one of the routing events IGPRouting, computeMCF, mplsCosRouting or optDivideTM. If it is not given, the last initiated load is used in the display.

The linkId and classOfService attributes are used to display information about a specific link and/or a specific class of service. The perLink and perClassOfService attributes control the aggregation of the data. If perClassOfService is true, information about all defined classes of service are given separetely, if it is false, only aggregate information about all classes of services are given. If perLink is false, aggregate information is shown in the form max, mean, standard deviation and percentiles values about all links in the networks.

`ShowLinkReservableBandwidth`

Deprecated. Use subsubsec (9.5.7).

This event extends ASEventType. It has two attributes: a string linkId which is required and an int priority which is optional.

This event prints the reservable bandwidth of the link linkId for the given priority level on the standard output stream. If priority is not specified, it uses the minimum priority level of the specified domain.

`showLinkReservation`

This event extends ASEventType. It has three attributes that indicate which information to show (linkId, classtype and preemptionLevel) and three boolean attributes that indicate which aggregation level to use in the display (perLink, perCT and perPrio.

The event prints reservation information on the standard output stream such as link capacity (maximum reservable bandwidth), reserved bandwidth, reservable bandwidth and utilisation ( $1- reserved\_bandwidth/capacity * 100$ ). If linkId is given, information about only one link is shown, else reservation is shown for all links of the network. In this case, if perLink is true information is given for each link separately, else aggregate information is shown instead (max, mean, standard deviation, percentile values). Information can also be shown for a specific classType by specifying the classType attribute or for a specific priority value by specifying both the classType and the preemptionLevel attribute. Aggregation can also be controlled by the perCT and perPrio boolean values.

Charts Events

It is now possible (since version 2.0) to generate some charts from the data in the toolbox. The chart creation uses the JFreeChart¹⁰library. An interface has been created to output charts in graphics files from the scenario XML.

Examples of scenario that use charts can be found in

example/abilene/Scenario/charts1.xml
example/abilene/Scenario/charts2.xml
example/abilene/Scenario/SPF-load-chart.xml

The chart creation process is divided into three parts : selecting the data to collect, collecting the data and outputting the chart.

Each of these steps refers to a specific scenario event detailed hereunder.

`chartCreation`

This is the first event to use when willing to create a chart. This event takes one mandatory attribute id which is the referring name of the chart and has only one mandatory sub-event (collector). The latter specifies the type of data to collect before the chart can be built. The attribute name refers to the name of the java class that is used to collect the data. Specifics parameters can be passed to the collector via an unbounded number of param sub-elements. For now, there are only two types of chart data collectors : LinksLoadDataCollector and LinksReservedBWDataCollector. The first one collects the load of each link computed via a shortest path algorithm and the second one collects the reserved bandwidth of each link. The parameters that can be passed are the domain on which to collect the data (via the parameter asId) and whether the load should be taken as relative or not (via the absoluteLoad parameter which can be true or false). If they are not set, the default domain is taken and relative load is used, i.e. . Note that both collectors uses the same parameters set.

`chartAddSeries`

At the moment when this event is executed, data are added to the currently under construction chart. The chart to which to add the data is specified by the chartId attribute. The seriesName attribute is used to identify the data series. It must have an unique value in a single chart. It might be used by the plotter as the legend name of the data series. Again, parameters can be passed to the collector through the collector sub-element. The LinksReservedBWDataCollector takes no parameters when adding data series and the LinksLoadDataCollector can take up to four parameters (tmId, strategy, routingAlgo and ECMP). These corresponds to IGP routing parameters used to compute the load (see section 10.6). If you do not provide some of the parameters, the default value will be used. The default values for these parameters are SPF routing as strategy with CSPF as routing algo and ECMP disabled. The default traffic matrix will be used when the parameter tmId is not set.

`chartSave`

When the chart is created and contains some data, it can be output to a file. Note that we did not specify the type of chart that we want to build, only the chart data is defined at this point.

The chartSave event takes the mandatory attributes chartId, file and format with obvious mean. The format can be JPG, PNG or EPS. Some other obvious parameters of the chart must be provided through sub-elements. It is title, xAxisTitle, yAxisTitle, width, height. The last element that should be provided is the plotter whose name corresponds to a java class and defines the type of graph to build. Again, specifics parameters can be passed to the plotter.

For now, three kinds of chart plotters are included in the toolbox: LoadIntervalChartPlotter, DecreasingLineChartPlotter and LoadChartPlotter.

The LoadIntervalChartPlotter take two optional parameter: maxValue and nbInterval, default values are respectively 1 and 10. The interval 0-maxValue is divided in a number of disjoint sets. For each of these sets, a bar is represented. The height of the bar corresponds to the frequency of the data for the considerated set.

The DecreasingLineChartPlotter takes no parameters. It is used to plot a line graph where all values in a series are sorted. The plotted point with the highest Y coordinate has the smallest X coordinate, so that the chart represent a decreasing line.

The LoadChartPlotter takes two parameters: asId and allLinks. The asId parameter has no default value. allLinks is false by default. This plotter creates bar charts using links loads. The x-axis represents the links and the y-axis represents the (absolute or relative) load. The plotter has been designed to allow the creation of two different bar charts:

Charts where the load of all links is displayed
Charts where only a statistic about the load of links is displayed

The distinction of the two types of charts is made thanks to the allLinks parameter. If it is true, the first type of charts is created. Otherwise, the second type of charts is created. There is also a distinction in the meaning of the series names. In the first case, they give the name of the algorithm used to compute loads. In the second case, they give the links IDs. Finally, for the first type of plots, a legend will be displayed. This is not the case for the second type of plots. Note that the asId parameter gives the domain on which the data were collected. If it is not provided, the default domain is used.

`chartDeletion`

This event refers to a chart created with chartCreation through the chartId attribute. Use it to free the resources associated with a chart.

On-line events

`loadDistantDomain`

This event takes one required attribute host and one optional attribute port.

Once this event is executed, the toolbox connects to the specified host and port and waits for an XML domain to be sent. See section 7.2 for more information.

`listenToLSPsDemands`

This event is deprecated. It was renamed to startScenarioServer.

`startScenarioServer`

This event starts a server that listens to XML events sent by the network interface (see 7.1). This must be the last event of the scenario since it won't return.

This event extends eventType. It has one optional attribute which is the port on which to listen to. If this attribute is not given, default port will be used (port 1234).

Other core events

`addNetworkController`

This event extends ASTMEventType. It has two required attributes name and className which are strings. It also accepts an unbounded number of param elements.

This event records a new network controller for the specified domain and traffic matrix. The param elements are used to specify parameters specific to the network controller to record. name is a unique name identifying the network controller and className is the class name of the network controller to record.

`removeNetworkController`

This event extends eventType. It has only one required attribute name that is a string.

This event removes the network controller name if it exists.

`startAlgo`

This event extends ASTMEventType. It has one required attribute name which is a string. It also accepts an unbounded number of param elements as subelements.

This event starts the algorithm name on the specified domain and traffic matrix (if the algorithm is independent of one or both of these elements, you are allowed to not specify them). By means of the param elements, you can specify algorithm-specific parameters to start it. The available algorithms (and the possible values for name) are given in section 8.

Important note: you always have to start an algorithm before using it. Note that the started algorithms are automatically stopped when the execution of the scenario is finished.

`stopAlgo`

This event extends ASTMEventType. It has one required attribute name which is a string.

This event stops the algorithm name on the specified domain and traffic matrix (if the algorithm is independent of one or both of these elements, you are allowed to not specify them). The available algorithms (and the possible values for name) are given in section 8.

Important note: this event allows the user to reinitialise an algorithm which doesn't use the observer design pattern. Other uses of this event must be avoided!

CBGP Events

In this section, we describe the events related to the C-BGP simulator. These are defined in the schema available at

http://totem.run.montefiore.ulg.ac.be/Schema/CBGP-Scenario-v1_0.xsd.

`CBGPExecute`

The CBGPExecute element is used to run a single C-BGP command. It requires a single attribute, command, of type string. The parameter contains a C-BGP command which will be executed by C-BGP if it is valid. Please refer to the C-BGP documentation [12] for more information on the available commands.

`CBGPInfo`

The CBGPInfo element is used to extract information from C-BGP. It requires an attribute, info, of type string. This parameter indicates which information type is requested. For each information type, additional parameters are requested. These parameters must be specified using the params attribute. The CBGPInfo currently supports the following information types:

Links : Dumps all the links of the node identified by the parameter router. The router parameter must contain the IP address of the node.
Peers : Dumps all the BGP peers of the router identified by the parameter router. The router parameter must contain the IP address of the router.
AdjRIB : Dumps the BGP adjacent routing information base (Adj-RIB) of the router identified by the parameter router. The router parameter must contain the IP address of the router. The following optional parameters are also understood. First, the peer parameter can be used to only dump the routes related to this peer. Second, the prefix parameter can be used to only dump the routes that match this prefix. Finally, the in parameter can be used to select if the input or output Adj-RIB must be dumped. The default value of in is true, which means that the Adj-RIB-in are dumped.
RecordRoute : Traces the route from a source node specified using the src parameter towards a destination node specified using the dst parameter.
RT : Dumps the routing table of the node identified by the parameter router. The router parameter must contain the IP address of the node.
RIB : Dumps the BGP routing information base (RIB) of the router identified by the parameter router. The router parameter must contain the IP address of the router. Note, the optional prefix parameter described in the AdjRIB information type can also be used for the RIB information type.

Figure 2 shows an example of use of the CBGPInfo element. The example requests the RIB of router 10.0.0.1.

**Figure 2:** Example of the XML CBGPInfo element usage.
$\begin{figure}\begin{center} {\small \begin{tabular}{\vert p{9cm}\vert} \hline \... ...am> </CBGPInfo>\end{verbatim}\\ \hline \end{tabular}} \end{center} \end{figure}$

`CBGPLoadRib`

The CBGPLoadRib element is used to load BGP routes collected on a genuine BGP router in C-BGP. The BGP routes are provided in a file whose format is ASCII MRT (see [12] and [13] for more information). The CBGPLoadRib element requires two attributes: node and file, both of type string. The node attribute specifies the IP address of the router in which the routes must be loaded. The file specifies the name of the file that contains the BGP routes.

`CBGPPeerDown`

The CBGPPeerDown element is used to tear down a BGP session between a router and one of its peers. The CBGPPeerDown element requires two attributes: node and peer, both of type string. The node attribute specifies the IP address of the router and the peer attribute specifies the IP address of the router's peer.

`CBGPPeerRecv`

The CBGPPeerRecv element is used to feed a router with one BGP route. The route will appear to the router as if it was learned from one of its peers. There are a few preconditions in order for this scenario element to be working. First, the peer from which the router will learn the route must have been declared with one neighbor element in the BGP section of the TOTEM XML topology. Second, this peer must be virtual, that is, the peer router must not really exist in the topology, it will be created when the C-BGP algorithm is loaded in the TOTEM toolbox (see Section 9.8.3).

The CBGPPeerRecv element requires three attributes, all of type string. First, the router attribute specifies the IP address of the BGP router that will receive the BGP route. Second, the peer attribute specifies the IP address of the peer of the router. Finally, the msg attribute describes the BGP route, using the MRT format [13]. An example is shown in Fig 3.

**Figure 3:** Example of the XML CBGPPeerRecv element usage.
$\begin{figure}\begin{center} {\small \begin{tabular}{\vert p{13cm}\vert} \hline ... ...\vert\vert'' />\end{verbatim}\\ \hline \end{tabular}} \end{center} \end{figure}$

`CBGPPeerUp`

The CBGPPeerUp element is used to establish a previously configured BGP session between a router and one of its peers. The CBGPPeerDown element requires two attributes: node and peer, both of type string. The node attribute specifies the IP address of the router and the peer attribute specifies the IP address of the router's peer.

`CBGPRun`

The CBGPRun element is used to start the computation of routes. This element does not require any argument. This element must be used after changes such as BGP sessions state changes or after the first topology representation has been built.

SAMTE Events

In this section, we describe the events related to SAMTE (described in section 8.9). These are defined in the schema available at

http://totem.run.montefiore.ulg.ac.be/Schema/SAMTE-Scenario-v1_0.xsd.

`generateCPL`

This event extends ASEventType. It has five optional attributes: nbPath and maxDepth (which are ints), verbose (which is a boolean), fileName (which is a string) and type (which must be SINGLE_PATH). Note that the default value of nbPath and maxDepth is 5, the default value of verbose is false and the default value of fileName is cpl.txt.

This event can be used to generate a candidate path list. nbPath specifies the number of path to generate for each pair of nodes. maxDepth is the maximal size of the paths in term of number of hops. verbose set to true will print more details about the simulation. fileName specifies the file to store the candidate path list. type has now to be set to SINGLE_PATH but could be used differently in future releases.

`SAMTE`

This event extends ASTMEventType. It accepts one optional sub-element simulatedAnnealing (defined in section 9.10.3) and four optional attributes: nbRun and nbLSP (which are ints), cplName (which is a string) and verbose (which is a boolean). Note that the default value of nbRun and nbLSP is 5, the default value of verbose is false and the default value of cplName is cpl.txt.

This event launch the execution of SAMTE. In simulatedAnnealing element, you can specify the parameters of simulated annealing meta-heuristic. nbRun specifies the number of times you want to execute SAMTE (I suggest to start with 1). nbLSP is the number of LSP you want to install in the network. cplName specifies the Candidate path list file to use. verbose can be set to true to print more information about the simulation.

`simulatedAnnealing`

This element accepts three optional sub-elements: objectiveFunction (defined in section 9.10.4), neighbourhood (which must contain ONE_CHANGE) and initialSolution (which must contain RANDOM).

It also has five optional attributes: T0 (which is a float), alpha (which is a float $\in [0,1]$ ), L, E and K (which are ints).

The default value of L and K is 5, the default value of E and T0 is 10 and the default value of alpha is 0.8.

objectiveFunction specifies the objective function used in the algorithm. neighbourhood specifies the neighborhood to search into (only one choice for the moment) and initialSolution specifies how to compute the initial solution (also only one choice for the moment).

T0 is the initial temperature, alpha is the cooling factor, L is the size of the plateaus, and finally, E and K are the parameters of the stopping conditions. The algorithm stops if there are less than E % of accepted moves during the last K plateaus.

`objectiveFunction`

This element accepts an unbounded number of param sub-elements defined in section 9.1.2. It also has one required attribute name which can be MAX_LOAD or LOAD_BAL.

MAX_LOAD can be used for the objective function $\max_{a \in A} u_a$ , if is the set of links of the network and is the utilisation (in %) of link . LOAD_BAL is the objective function $\sum_{a \in A}(u_a-u_{mean})^2 + \alpha \sum_{a \in A}(u_a)^2$ if $u_{mean}$ is the mean link utilisation ( $u_{mean} = \frac{1}{\Vert A\Vert}\sum_{a \in A} u_a$ ).

Simon Balon 2008-06-18