= DETER ns2 Extensions For Topdl =

The DETER ns2 libraries include some additional commands to produce [TopDl topdl] constructs.  These extensions do not directly affect experiments created and manipulated by the legacy web interface and command line programs, but are used by the [WikiStart federation] and [http://containers.deterlab.net containers] systems.  Specifically, [FeddCommands#fedd_ns2topdl.py fedd_ns2topdl.py] respects all of them.

With these commands, the ns2/tcl interface can create expressive topdl descriptions.

== The commands ==

The vast majority of these commands are for completeness in dealing with later applications.  When working with [WikiStart federation] or [http://containers.deterlab.net containers], {{{tb-add-node-attribute}}} is the most commonly used command, and in most cases the only one needed.  Several other DETER ns2 commands also reflect their operation into the generated topdl and they will be noted below.

=== tb-add-node-attribute ===

Takes a node object, an attribute name, and an attribute value:

{{{
set node [$ns node]
tb-add-node-attribute $node attribute_name attribute_value
}}}

This attaches an attribute to the [TopDl#Elements Computer object] representing the node.  Attribute name and value are both strings.  The attribute is added to the element. Existing attribute/value pairs with the same name are not replaced or removed. Duplicate attribute names will result in application-demepndent behavior and should be avoided.

=== tb-add-network-attribute ===

Takes a link or a LAN object, an attribute name, and an attribute value.  This is the network analog of [NsTopdlExtensions#tb-add-node-attribute tb-add-node-attribute].

{{{
set a [$ns node]
set b [$ns node]
set lan [$ns make-lan "$a $b" 100Mb 0ms]
tb-add-network-attribute $lan attribute_name attribute_value
}}}

This attaches an attribute to the [TopDl#Substrates Substrate object] representing the lan or link.  Attribute name and value are both strings.  The attribute is added to the substrate. Existing attribute/value pairs with the same name are not replaced or removed. Duplicate attribute names will result in application-demepndent behavior and should be avoided.

===  tb-add-interface-attribute ===

Takes a node object, a lan or link object, an attribute, and a value. This is the interface analog of [NsTopdlExtensions#tb-add-node-attribute tb-add-node-attribute].

{{{
set node1 [$ns node]
set node2 [$ns node]
set lan [$ns make-lan "$node1 $node2" 100Mb 0ms]
tb-add-interface-attribute $node1 $lan attribute_name attribute_value
}}}

This attaches an attribute to the [TopDl#Interfacess Interface object] connecting the node to the lan or link.  If the node is attached multiple times to the network, the operation is undefined.  Attribute name and value are both strings.  The attribute is added to the substrate. Existing attribute/value pairs with the same name are not replaced or removed. Duplicate attribute names will result in application-demepndent behavior and should be avoided.

Note that when [https://trac.deterlab.net/wiki/nscommands#tb-set-ip-link tb-set-ip-link] or [https://trac.deterlab.net/wiki/nscommands#tb-set-ip-link tb-set-ip-lan] are used on DETER, they automatically set the '''ip4_address''' and '''ip4_netmask''' attributes on the corresponding interface, so there is no need to attach the attributes using this command.

=== tb-add-node-topdl-os ===

Takes a node object, and a variable number of string arguments.  The first four arguments after the node are the {{{name}}}, {{{version}}}, {{{distribution}}}, and {{{distributionversion}}} members of the [TopdlLibrary#OperatingSystemClass OperatingSystem object].  They can be empty strings.  The remaining arguments are attribute name/value pairs, that are attached to the !OperatingSystem object.

{{{
set node [$ns node]
tb-add-node-topdl-os $node "Linux" "3.0.0" "Ubuntu" "12.04" "attribute1" "one" "attribute2" 2
}}}

Subsequent calls to {{{tb-add-node-topdl-os}}} on the same node add additional !OperatingSystem objects to the node.

Note that the [https://trac.deterlab.net/wiki/nscommands#tb-set-node-os tb-set-node-os] command on DETER already attaches an appropriate !OperatingSystem object to the node.  Adding additional OperatingSystems is probably unnecessary.

=== tb-add-node-topdl-cpu ===

Takes a node object, a CPU name, and a variable number of attribute/value pairs as strings.   The first parameter is the [TopdlLibrary#CPUClass CPU object] {{{type}}} member and the rest are attributes.  These are pairs as in [NsTopdlExtensions#tb-add-node-topdl-os tb-add-node-topdl-os].

{{{
set node [$ns node]
tb-add-node-topdl-cpu $node "Intel x86_64" "attribute1" "one" "attribute2" 2
}}}

Subsequent calls to {{{tb-add-node-topdl-cpu}}} on the same node add additional CPU objects to the node.

=== tb-add-node-topdl-storage ===

Takes a node object, two strings and a variable number of attribute value pairs (strings).  The first string is the value of the {{{amount}}} member of the [Topdl#LibraryStorageClass Storage object] and must convert to a float.  The second is the {{{persistence}}} value for that class and must be "true" or "false".  The rest  are  attribute/value pairs as in [NsTopdlExtensions#tb-add-node-topdl-os tb-add-node-topdl-os].

{{{
set node [$ns node]
tb-add-node-topdl-storage $node 1000.0 "true" "attribute1" "one" "attribute2" 2
}}}

Subsequent calls to {{{tb-add-node-topdl-storage}}} on the same node add additional Storage objects to the node.

=== tb-add-node-topdl-localname ===

Takes a node object and a string.  The string is added to the list of local names of the [TopdlLibrary#ComputerClass Computer] object that represents the node.

{{{
set node [$ns node]
tb-add-node-topdl-localname $node "Bob"
}}}

Subsequent calls add additional names.

=== tb-set-node-topdl-status ===

Takes a node object and a string.  The string is used to set the {{{status}}} member of the [TopdlLibrary#ComputerClass Computer] object that represents the node.  Only the values valid for [TopdlLibrary#ComputerClass status] are valid as arguments.

{{{
set node [$ns node]
tb-set-node-topdl-status $node "active"
}}}

Subsequent calls overwrite teh status.