-
Notifications
You must be signed in to change notification settings - Fork 0
Topology Format
The topology files included in Shadow were generated from a variety of data sources, including iPlane, Net Index, and our own PlanetLab traces. The format is general enough so that it is easy to swap out specific measurements of latency, jitter, packetloss, etc, if desired. See our Tor modeling paper for all the details.
For the cluster elements, the format of the id attributes is as follows: For US and CA, the cluster ID is the two letter country code followed by the two letter state/territory code (e.g. USMN or CAON). For other countries, the two letter country code is given twice (e.g. DEDE). This gives a unique ID for each cluster. Cluster packetloss rates, and bandwidth down and up are taken from Net Index data.
Links are directed, connecting the given clusters. Link latency and packetloss are assigned by querying the iPlane interface as well as our own PlanetLab measurements, as the median of all measurements between the given clusters. Jitter was computed as the average difference of the first and third quartiles from the median, i.e.:
q1, latency, q3 = getQuartiles()
jitter = ((latency-q1) + (q3-latency)) / 2.0
if jitter >= latency: jitter = min(latency-q1, q3-latency)
assert jitter < latencyThe following are valid elements and their attributes:
<cdf id="STRING" path="STRING" center="INTEGER" width="INTEGER" tail="INTEGER" />Required attributes: id, path or center
Optional attributes: width, tail
The cdf element instructs Shadow to either generate an empirical Cumulative Distribution Function, or load the representation of one from a file. The id attribute identifies this cdf and must be a string that is unique among all id attributes for any element in the XML file.
If no path is given, it will generate a CDF using center - width as the 10th percentile, center as the 80th percentile, center + width as the 90th percentile, and center + width + tail as the 95th percentile.
If path is given, it should specify the location of a file from which Shadow should extract a CDF. If path begins with ~/, the path will be considered relative to the current user's home directory. The file should be in the following format:
1000.000 0.2000000000
2000.000 0.4000000000
3000.000 0.6000000000
4000.000 0.8000000000
5000.000 1.0000000000
Where the first column represents the value, and the second represents the percentile.
<cluster id="STRING" bandwidthdown="INTEGER" bandwidthup="INTEGER" packetloss="FLOAT" />Required attributes: id, bandwidthdown, bandwidthup
Optional attribute: packetloss
The cluster element represents a vertex in the network topology, i.e., the entity to which we will attach virtual hosts. The id attribute identifies this cluster and must be a string that is unique among all id attributes for any element in the XML file.
bandwidthdown and bandwidthup represent the default downstream and upstream bandwidth capacities for hosts attached to this cluster. The default values are used for nodes that do not supply their own bandwidth overrides.
The packetloss attribute is optional and represents the percentage chance that any given packet traveling through this cluster will be lost (independent of link packetloss rates, i.e., there are 3 end-to-end chances to drop a packet).
<kill time="INTEGER" />Required attribute: time
The time attribute represents the number of virtual seconds to simulate, after which the experiment will be killed and resources released.
<link clusters="STRING STRING" latency="INTEGER" jitter="INTEGER" packetloss="FLOAT" />Required attributes: clusters, latency
Optional attributes: id, jitter, packetloss
The link element represents an edge in the network topology, and is used to connect two clusters. The id attribute identifies this link and must be a string that is unique among all id attributes for any element in the XML file.
The clusters attribute is a string that specifies the ids of the two clusters the link is connecting, separated by a space. So, to connect <cluster id="c1" ... and <cluster id="c2" ..., you would set clusters="c1 c2".
The packet delay across this link in is specified with the latency attribute, and the average variation in packet delay is specified with the jitter attribute. Both latency and jitter are specified in milliseconds.
The packetloss attribute is optional and represents the percentage chance that any given packet traveling through this link will be lost (independent of cluster packetloss rates, i.e., there are 3 end-to-end chances to drop a packet).
<node id="STRING" software="STRING" cluster="STRING" quantity="INTEGER" bandwidthdown="INTEGER" bandwidthup="INTEGER" loglevel="STRING" heartbeatloglevel="STRING" heartbeatfrequency="INTEGER" cpufrequency="INTEGER" logpcap="STRING" pcapdir="STRING" />Required attributes: id, software
Optional attributes: cluster, quantity, bandwidthdown, bandwidthup, loglevel, heartbeatloglevel, heartbeatfrequency, cpufrequency, logpcap, pcapdir
The node element represents a node or virtual host in the simulation. The id attribute identifies this node and must be a string that is unique among all id attributes for any element in the XML file. id will also be used as the network hostname of this node. The software attribute should be set to the id of the software that this host should run during the simulation.
The cluster attribute optionally specifies to which network vertex this node should be assigned. If not given, a random vertex will be chosen internally. The quantity attribute specifies the number of hosts of this type to start. If quantity is greater than 1, each host's hostname will be prefixed with a counter. For example, a node with an id of host and quantity=2 would produce nodes with hostnames 1.host and 2.host.
bandwidthdown and bandwidthup optionally specify the downstream and upstream bandwidth capacities for this node, and override any default bandwidth values set in the cluster element corresponding to the cluster attribute. If not given, the default bandwidth values from the assigned cluster element are used.
loglevel and heartbeatloglovel are node-specific overrides for the simulator default log levels (the defaults are adjustable with shadow arguments --log-level and --heartbeat-log-level). Valid strings include 'error', 'critical', 'warning', 'message', 'info', and 'debug'. heartbeatfrequency is a node-specific override for the default number of seconds between which heartbeat messages are logged (the default is adjustable with shadow argument --heartbeat-frequency). Each heartbeat message contains useful statistics about the node.
cpufrequency is the speed of this node's virtual CPU in kilohertz. Along with the CPU processing requirements of the plug-in application, this determines how often events for this node are delayed during simulation.
logpcap is a case insenstive boolean string (e.g. "true") that specifies that Shadow should log all network input and output for this node in PCAP format (for viewing in e.g. wireshark). pcapdir is the directory to which the logs should be saved for this node.
<plugin id="STRING" path="STRING" />Required attributes: id, path
The plugin element represents a library plug-in that Shadow should dynamically load. The id attribute identifies this plugin and must be a string that is unique among all id attributes for any element in the XML file.
The path attribute holds the system path to the plug-in *.so library. If path begins with ~/, the path will be considered relative to the current user's home directory.
<software id="STRING" plugin="STRING" time="INTEGER" arguments="STRING" />Required attributes: id, plugin, time, arguments
The software element represents an application the node will run. The id attribute identifies this software and must be a string that is unique among all id attributes for any element in the XML file. The plugin attribute should be set to the id of the plugin element that represents the plug-in that should be used to launch this application at time virtual seconds from the beginning of the simulation.
The arguments attribute should be set to a string holding the required plug-in arguments. This string will be passed to the plug-in in an argv-style array, similar to how arguments are passed to the main function in a C program. Please see the plug-in documentation for usage and format of the argument string.