nscommands.html 22.3 KB
Newer Older
Leigh B. Stoller's avatar
Leigh B. Stoller committed
1
2
<!--
   EMULAB-COPYRIGHT
Leigh B. Stoller's avatar
Leigh B. Stoller committed
3
   Copyright (c) 2000-2003 University of Utah and the Flux Group.
Leigh B. Stoller's avatar
Leigh B. Stoller committed
4
5
   All rights reserved.
  -->
Christopher Alfeld's avatar
Christopher Alfeld committed
6
<center>
7
<h1>Emulab - Testbed NS Command Extensions</h1>
Christopher Alfeld's avatar
Christopher Alfeld committed
8
9
10
11
12
</center>


<h2>Contents</h2>
<ul>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
13
14
  <li><a href="#INTRO">Introduction</a>
  <li><a href="#TCL">TCL, NS, and node names</a>
15
  <li><a href="#ORDER">Ordering issues</a>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
16
  <li><a href="#HARD">Hardware Commands</a>
17
  <li><a href="#IP">IP Address Commands</a>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
18
  <li><a href="#OS">OS Commands</a>
19
  <li><a href="#LOSS">Link Characteristic Commands</a>
Christopher Alfeld's avatar
Christopher Alfeld committed
20
  <li><a href="#VTYPE">Virtual Type Commands</a>
21
  <li><a href="#MISC">Misc. Commands</a>
Christopher Alfeld's avatar
Christopher Alfeld committed
22
23
24
25
</ul>

<hr>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
26
<a name="INTRO"></a><h3>Introduction</h3>
Christopher Alfeld's avatar
Christopher Alfeld committed
27
28
29
30
31
32
33
34
35
36

<p>In order to use the testbed specific commands you must include the
following line near the top of your NS file (before any testbed
commands are used):

<pre>
source tb_compat.tcl
</pre>

<p>If you wish to use your file under NS you can use download this <a
Leigh B. Stoller's avatar
Leigh B. Stoller committed
37
38
39
40
href=http://www.emulab.net/tutorial/tb_compat.tcl>tb_compat.tcl</a>.
Place it in the same directory as your NS file.  When run in this way
under NS the testbed commands will have no effect, but NS will be able
to parse your file.
Christopher Alfeld's avatar
Christopher Alfeld committed
41
42
43

<hr>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
44
<a name="TCL"></a><h3>TCL, NS, and node names</h3>
Christopher Alfeld's avatar
Christopher Alfeld committed
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

In your file you will be creating nodes with something like:

<pre>
set node1 [$ns node]
</pre>

What is really going on is that the simulator, represented by
<code>$ns</code> is creating a new node, involving a bunch of internal
data changes, and returning a reference to it which is stored in the
variable <code>node1</code>.  In almost all cases, when you need to
refer to a node you will do it as <code>$node1</code>, the
<code>$</code> indicating that you want the value the variable
<code>node1</code>, i.e. the reference to the node.  Thus you will be
issuing commands like:

<pre>
$ns duplex-link $node1 $node2 100Mb 150ms DropTail
63
tb-set-ip $node1 192.0.0.2
Christopher Alfeld's avatar
Christopher Alfeld committed
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
</pre>

<p>(Note the <code>$</code>'s)

<p>You will notice that when your experiment is setup the node names
and such will be <code>node1</code>.  This happens because the parser
detects what variable you are using to store the node reference and
uses that as the node name.  In the case that you do something like:

<pre>
set node1 [$ns node2]
set A $node1
</pre>

<p>The node will still be called <code>node1</code> as that was the first
variable to contain the reference.

<p>If you are dealing with many nodes you may store them in array,
perhaps like this:

<pre>
for {set i 0} {$i < 4} {incr i} {
   set nodes($i) [$ns node]
}
</pre>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
90
91
92
93
94
95
96
<p>In this case the names of the node will be <code>nodes-0</code>,
<code>nodes-1</code>, <code>nodes-2</code>, <code>nodes-3</code>. (In
other words, the <code>(</code> character is replaced with
<code>-</code>, and <code>)</code> is removed.)  This slightly
different syntax comes is to avoid any problems that <code>()</code>
may cause later in the process. For example, the <code>()</code>
characters cannot appear in DNS entries.
Christopher Alfeld's avatar
Christopher Alfeld committed
97
98
99
100
101

<p>As a final note, everything said above for nodes applies equally to
lans.  I.e.:

<pre>
102
set lan0 [$ns make-lan "$node0 $node1" 100Mb 0ms]
Christopher Alfeld's avatar
Christopher Alfeld committed
103
104
105
106
107
tb-set-lan-loss $lan0 .02
</pre>

<p>(Again, note the <code>$</code>'s)

108
109
<p>Links can also be named just like nodes and lans.  The names can
then be used to set loss rates or IP addresses.  This technique is the
Jay Lepreau's avatar
Jay Lepreau committed
110
only way to set such attributes when there are multiple links between
111
112
113
two nodes.

<pre>
114
set link1 [$ns duplex-link $node0 $node1 100Mb 0ms DropTail]
115
116
117
118
tb-set-link-loss $link1 0.05
tb-set-ip-link $node0 $link1 192.0.0.128
</pre>

Christopher Alfeld's avatar
Christopher Alfeld committed
119
120
<hr>

121
122
123
124
<a name="ORDER"></a><h3>Ordering Issues</h3>

<p>tb- commands have the same status as all other Tcl and NS commands.
Thus the order matters not only relative to each other but also
Jay Lepreau's avatar
typo    
Jay Lepreau committed
125
relative to other commands.  One common example of this is that IP
126
127
128
129
commands must be issued after the links or lans are created.

<hr>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
130
<a name="HARD"></a><h3>Hardware Commands</h3>
Christopher Alfeld's avatar
Christopher Alfeld committed
131
132
133
134
135
136
137

<h4>tb-set-hardware</h4>

<pre>
tb-set-hardware <i>node</i> <i>type</i> [<i>args</i>].

tb-set-hardware $node3 pc
Christopher Alfeld's avatar
Christopher Alfeld committed
138
tb-set-hardware $node4 shark
Christopher Alfeld's avatar
Christopher Alfeld committed
139
140
141
142
143
144
145
146
147
148
</pre>

<dl>
  <dt><i>node</i> - The name of the node.
  <dt><i>type</i> - The type of the node.
</dl>

<p>Notes:

<ul>
149
150
151
  <li>Currently only <code>pc</code>, <code>pc600</code>, 
     <code>pc850</code>, and <code>shark</code> are
     supported types.  <code>pc</code> is the default type.
Christopher Alfeld's avatar
Christopher Alfeld committed
152
  <li>No current types have any additional arguments.
153
</ul>
Christopher Alfeld's avatar
Christopher Alfeld committed
154
155
156

<hr>

157
<a name="IP"></a><h3>IP Address Commands</h3>
Christopher Alfeld's avatar
Christopher Alfeld committed
158

Leigh B. Stoller's avatar
Leigh B. Stoller committed
159
160
161
162
<p>Each node will be assigned an IP address for each interface that is
in use.  The following commands will allow you to explicitly set those
IP addresses.  IP addresses will be automatically generated for all
nodes that you do not explicitly set IP addresses.
Christopher Alfeld's avatar
Christopher Alfeld committed
163
164
165

<p>In the common case the IP addresses on either side of a link must
be in the same subnet.  Likewise, all IP addresses on a LAN should be
Leigh B. Stoller's avatar
Leigh B. Stoller committed
166
167
168
169
170
171
in the same subnet. Generally the same subnet should not be used for
more than one link or LAN in a given experiment, nor should one node
have multiple interfaces in the same subnet. Automatically generated
IP addresses will conform to these requirements.  If part of a link or
lan is explicitly specified with the commands below then the remainder
will be automatically generated under the same subnet.
Christopher Alfeld's avatar
Christopher Alfeld committed
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194

<p>IP address assignment is deterministic and tries to fill lower IP's
first, starting at 2.  Except in the partial specification case (see
above), all automatic IP addresses are in the network
<code>192.168</code>.

<h4>tb-set-ip</h4>

<pre>
tb-set-ip <i>node</i> <i>ip</i>

tb-set-ip $node1 142.3.4.5
</pre>

<dl>
  <dt><i>node</i> - The node to assign the IP address to.
  <dt><i>ip</i> - The IP address.
</dl>

<p>Notes:

<ul>
  <li>This command should only be used for nodes that have a single
195
196
      link.  For nodes with multiple links the next commands should be
      used.  Mixing <code>tb-set-ip</code> and any other IP command on
Christopher Alfeld's avatar
Christopher Alfeld committed
197
198
199
      the same node will result in an error.
</ul>

200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246

<h4>tb-set-ip-link</h4>

<pre>
tb-set-ip-link <i>node</i> <i>link</i> <i>ip</i>

tb-set-ip-link $node0 $link0 142.3.4.6
</pre>

<dl>
  <dt><i>node</i> - The node to set the IP for.
  <dt><i>link</i> - The link to set the IP for.
  <dt><i>ip</i> - The IP address.
</dl>

<p>Notes:
<ul>
  <li>One way to think of the arguments is a link with the node
      specifying which side of the link to set the IP for.
  <li>This command can not be mixed with <code>tb-set-ip</code> on the
      same node.
</ul>


<h4>tb-set-ip-lan</h4>

<pre>
tb-set-ip-lan <i>node</i> <i>lan</i> <i>ip</i>

tb-set-ip-lan $node1 $lan0 142.3.4.6
</pre>

<dl>
  <dt><i>node</i> - The node to set the IP for.
  <dt><i>lan</i> - The lan the IP is on.
  <dt><i>ip</i> - The IP address.
</dl>

<p>Notes:
<ul>
  <li>One way to think of the arguments is a node with the LAN
      specifying which port to set the IP address for.
  <li>This command can not be mixed with <code>tb-set-ip</code> on the
same node.
</ul>


Christopher Alfeld's avatar
Christopher Alfeld committed
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
<h4>tb-set-ip-interface</h4>

<pre>
tb-set-ip-interface <i>node</i> <i>dst</i> <i>ip</i>

tb-set-ip-interface $node2 $node1 142.3.4.6
</pre>

<dl>
  <dt><i>node</i> - The node to set the IP for.
  <dt><i>dst</i> - The destination of the link to set the IP for.
  <dt><i>IP</i> - The IP address.
</dl>

<p>Notes:
<ul>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
263
  <li>This command can not be mixed on the same node with
Christopher Alfeld's avatar
Christopher Alfeld committed
264
265
266
267
      <code>tb-set-ip</code>.  (See above)
  <li>In the case of multiple links between the same pair of nodes
      there is no way to distinguish which link to the set the IP
      for.  This should be fixed soon.
268
269
270
  <li>This command is converted internally to either tb-set-ip-link or
      tb-set-ip-lan.  It is possible that error messages will report
      either of those commands instead of tb-set-ip-interface.
Christopher Alfeld's avatar
Christopher Alfeld committed
271
272
</ul>

273

Christopher Alfeld's avatar
Christopher Alfeld committed
274
275
<hr>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
276
<a name="OS"></a><h3>OS Commands</h3>
Christopher Alfeld's avatar
Christopher Alfeld committed
277
278
279
280
281
282

<h4>tb-set-node-os</h4>

<pre>
tb-set-node-os <i>node</i> <i>os</i>

283
tb-set-node-os $node1 FBSD-STD
Christopher Alfeld's avatar
Christopher Alfeld committed
284
285
286
287
288
289
290
291
292
293
294
tb-set-node-os $node1 MY_OS
</pre>

<dl>
  <dt><i>node</i> - The node to set the OS for.
  <dt><i>os</i> - The id of the OS for that node.
</dl>

<p>Notes:

<ul>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
295
296
  <li>The OSID can either by one of the standard OS's we provide or
      a custom OSID, created via the web interface.
Christopher Alfeld's avatar
Christopher Alfeld committed
297
  <li>If no OS is specified for a node a default OS is chosen based on
298
299
300
      the nodes type.  This is currently RHL-STD for PCs.
  <li>The currently available standard OS types are: FBSD-STD,
      RHL-STD, NBSD14-STD (should not be used on PC nodes), and
Leigh B. Stoller's avatar
Leigh B. Stoller committed
301
302
      NETBOOT-STD (oskit netboot kernel for loading other
      operating systems over the network).
Christopher Alfeld's avatar
Christopher Alfeld committed
303
304
</ul>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
305

306
307
308
309
310
311
312
313
<h4>tb-set-node-rpms</h4>

<pre>
tb-set-node-rpms <i>node</i> <i>rpms...</i>

tb-set-node-rpms $node0 rpm1 rpm2 rpm3
</pre>

Christopher Alfeld's avatar
Christopher Alfeld committed
314
315
<p>Notes:

316
<ul>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
317
  <li>This command sets which rpms are to be installed on the node
318
319
320
  when it first boots after being assigned to an experiment.
  <li>Each rpm file must reside in /proj or /groups. You are not
  allowed to place your rpms in your home directory.
Leigh B. Stoller's avatar
Leigh B. Stoller committed
321
322
  <li>See the <a href="docwrapper.php3?docname=tutorial.html#RPMS">
  tutorial</a> for more information.
323
324
</ul>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
325

326
327
328
329
330
331
332
333
<h4>tb-set-node-startup</h4>

<pre>
tb-set-node-startup <i>node</i> <i>startupcmd</i>

tb-set-node-startup $node0 {mystart.sh -a}
</pre>

Christopher Alfeld's avatar
Christopher Alfeld committed
334
<p>Notes:
335
<ul>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
336
  <li>Specify a script or program to be run when the node is booted.
Leigh B. Stoller's avatar
Leigh B. Stoller committed
337
338
339
  <li>See the
  <a href="docwrapper.php3?docname=tutorial.html#Startupcmd">
  tutorial</a> for more information.
340
341
</ul>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
342

343
344
345
346
347
348
349
350
<h4>tb-set-node-cmdline</h4>

<pre>
tb-set-node-cmdline <i>node</i> <i>cmdline</i>

tb-set-node-cmdline $node0 {???}
</pre>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
351
352
<p>Notes:
<ul>
353
  <li>Set the command line, to be passed to the <i>kernel</i> when it
Leigh B. Stoller's avatar
Leigh B. Stoller committed
354
355
356
357
358
359
360
361
362
363
364
365
366
367
  is booted.
  <li>Currently, this is supported on OSKit kernels only. 
</ul>


<h4>tb-set-node-tarfiles</h4>

<pre>
tb-set-node-tarfiles <i>node</i> <i>dir</i> <i>tarfile</i>

tb-set-node-tarfiles $node0 /bin mybinmods.tar /sbin mysbinmods.tar
</pre>

<p>Notes:
368
<ul>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
369
370
371
372
  <li>This installs tarfiles in specified directories when the node
  first boots after being assigned to an experiment. 
  <li>Each tar file is installed just one. Tarfiles that have been
  loaded, are not reloaded after subsequent reboots.
373
374
  <li>Each tarfile must reside in /proj or /groups. You are not
  allowed to place your tarfiles in your home directory.
375
</ul>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
376
	
Christopher Alfeld's avatar
Christopher Alfeld committed
377
378
<hr>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
379
<a name="LOSS"></a><h3>Link Loss Commands</h3>
Christopher Alfeld's avatar
Christopher Alfeld committed
380

Leigh B. Stoller's avatar
Leigh B. Stoller committed
381
<p>This is the NS syntax for creating a link:
Christopher Alfeld's avatar
Christopher Alfeld committed
382
383
384
385
386

<pre>
$ns duplex-link $node1 $node2 100Mb 150ms DropTail
</pre>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
387
388
389
<p>Note that it does not allow for specifying link loss rates.  Emulab
does, however, support link loss.  The following commands can be used
to specify link loss rates.
Christopher Alfeld's avatar
Christopher Alfeld committed
390
391
392
393
394

<h4>tb-set-link-loss</h4>

<pre>
tb-set-link-loss <i>src</i> <i>dst</i> <i>loss</i>
395
tb-set-link-loss <i>link</i> <i>loss</i>
Christopher Alfeld's avatar
Christopher Alfeld committed
396
397

tb-set-link-loss $node1 $node2 0.05
398
tb-set-link-loss $link1 0.02
Christopher Alfeld's avatar
Christopher Alfeld committed
399
400
401
402
</pre>

<dl>
  <dt><i>src</i>, <i>dst</i> - Two nodes to describe the link.
403
  <dt><i>link</i> - The link to set the rate for.
Christopher Alfeld's avatar
Christopher Alfeld committed
404
405
406
407
408
  <dt><i>loss</i> - The loss rate (between 0 and 1).
</dl>

<p>Notes:
<ul>
409
  <li>There are two syntax's available.  The first specifies a link by
410
411
412
413
414
      a source/destination pair.  The second explicitly specifies the
      link.
  <li>The source/destination pair is incapable of describing an
      individual link in the case of multiple links between two
      nodes.  Use the second syntax for this case.
Christopher Alfeld's avatar
Christopher Alfeld committed
415
416
</ul>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
417

Christopher Alfeld's avatar
Christopher Alfeld committed
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
<h4>tb-set-lan-loss</h4>

<pre>
tb-set-lan-loss <i>lan</i> <i>loss</i>

tb-set-lan-loss $lan1 0.3
</pre>

<dl>
  <dt><i>lan</i> - The lan to set the loss rate for.
  <dt><i>loss</i> - The loss rate (between 0 and 1).
</dl>

<p>Notes:
<ul>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
433
  <li>This command sets the loss rate for the entire LAN.
Christopher Alfeld's avatar
Christopher Alfeld committed
434
</ul>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451

<h4>tb-set-node-lan-delay</h4>

<pre>
tb-set-node-lan-delay <i>node</i> <i>lan</i> <i>delay</i>

tb-set-node-lan-delay $lan0 $node0 40ms
</pre>

<dl>
  <dt><i>node</i> - The node we are modifying the delay for.
  <dt><i>lan</i> - Which LAN the node is in that we are affecting.
  <dt><i>delay</i> - The new node to switch delay (see below).
</dl>

<p>Notes:
<ul>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
452
  <li>This command changes the delay between the node and the
Leigh B. Stoller's avatar
Leigh B. Stoller committed
453
454
455
456
457
458
459
460
461
462
463
464
      switch of the LAN.  This is only half of the trip a packet must
      take.  The packet will also traverse the switch to the
      destination node, possibly incurring additional latency from any
      delay parameters there.
  <li>If this command is not used to overwrite the delay, then the
      delay for a given node to switch link is taken as one half of
      the delay passed to <code>make-lan</code>.  Thus in a LAN where
      no <code>tb-set-node-delay</code> calls are made the node to
      node latency will be the latency passed to
      <code>make-lan</code>.
  <li>The behavior of this command is not defined when used with nodes
      that are in the same LAN multiple times.
465
  <li>Delays of less than 2ms (per trip) are too small to be
466
      accurately modeled at this time, and will be silently ignored.
467
468
469
      As a convenience, a delay of 0ms can be used to indicate that
      you do not want added delay; the two interfaces will be
      "directly" connected to each other.
Leigh B. Stoller's avatar
Leigh B. Stoller committed
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
</ul>

<h4>tb-set-node-lan-bandwidth</h4>

<pre>
tb-set-node-lan-bandwidth <i>node</i> <i>lan</i> <i>bandwidth</i>

tb-set-node-lan-bandwidth $lan0 $node0 20Mb
</pre>

<dl>
  <dt><i>node</i> - The node we are modifying the bandwidth for.
  <dt><i>lan</i> - Which LAN the node is in that we are affecting.
  <dt><i>bandwidth</i> - The new node to switch bandwidth (see below).
</dl>

<p>Notes:
<ul>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
488
  <li>This command changes the bandwidth between the node and the
Leigh B. Stoller's avatar
Leigh B. Stoller committed
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
      switch of the LAN.  This is only half of the trip a packet must
      take.  The packet will also traverse the switch to the
      destination node which may have a lower bandwidth.
  <li>If this command is not used to overwrite the bandwidth, then the
      bandwidth for a given node to switch link is taken directly from
      the bandwidth passed to <code>make-lan</code>.
  <li>The behavior of this command is not defined when used with nodes
      that are in the same LAN multiple times.
</ul>

<h4>tb-set-node-lan-loss</h4>

<pre>
tb-set-node-lan-loss <i>node</i> <i>lan</i> <i>loss</i>

tb-set-node-lan-loss $lan0 $node0 0.05
</pre>

<dl>
  <dt><i>node</i> - The node we are modifying the loss for.
  <dt><i>lan</i> - Which LAN the node is in that we are affecting.
  <dt><i>loss</i> - The new node to switch loss (see below).
</dl>

<p>Notes:
<ul>
Leigh B. Stoller's avatar
Leigh B. Stoller committed
515
  <li>This command changes the loss probability between the node and the
Leigh B. Stoller's avatar
Leigh B. Stoller committed
516
517
518
519
520
521
522
523
524
      switch of the LAN.  This is only half of the trip a packet must
      take.  The packet will also traverse the switch to the
      destination node which may also have a loss chance.  Thus for
      packet going to switch with loss chance <var>A</var> and then
      going on the destination with loss chance <var>B</var> the node
      to node loss chance is
      <code>(1-(1-<var>A</var>)(1-<var>B</var>))</code>.
  <li>If this command is not used to overwrite the loss, then the
      loss for a given node to switch link is taken from the loss rate
525
526
      passed to the <code>make-lan</code> command.  If a loss rate of
      <var>L</var> is passed to <code>make-lan</code> then the node to
Leigh B. Stoller's avatar
Leigh B. Stoller committed
527
528
529
530
531
532
533
534
535
536
537
538
539
      switch loss rate for each node is set to
      <code>(1-sqrt(1-<var>L</var>))</code>.  Thus as each packet will
      have two such chances to be lost the node to loss rate comes out
      as the desired <var>L</var>.
  <li>The behavior of this command is not defined when used with nodes
      that are in the same LAN multiple times.
</ul>

<h4>tb-set-node-lan-params</h4>

<pre>
tb-set-node-lan-params <i>node</i> <i>lan</i> <i>delay</i> <i>bandwidth</i> <i>loss</i>

Leigh B. Stoller's avatar
Leigh B. Stoller committed
540
tb-set-node-lan-params $node0 $lan0 40ms 20Mb 0.05
Leigh B. Stoller's avatar
Leigh B. Stoller committed
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
</pre>

<dl>
  <dt><i>node</i> - The node we are modifying the loss for.
  <dt><i>lan</i> - Which LAN the node is in that we are affecting.
  <dt><i>delay</i> - The new node to switch delay.
  <dt><i>bandwidth</i> - The new node to switch bandwidth.
  <dt><i>loss</i> - The new node to switch loss.
</dl>

<p>Notes:
<ul>
  <li>This command is exactly equivalent to calling each of the above
      three commands appropriately.  See above for more information.
  </li>
</ul>
557

558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
<h4>tb-set-link-simplex-params</h4>

<pre>
tb-set-link-simplex-params <i>link</i> <i>src</i> <i>delay</i> <i>bw</i> <i>loss</i>

tb-set-link-simplex-params $link1 $srcnode 100ms 50Mb 0.2
</pre>

<dl>
  <dt><i>link</i> - The link we are modifying.
  <dt><i>src</i> - The source, defining which direction we are
      modifying.
  <dt><i>delay</i> - The source to destination delay.
  <dt><i>bw</i> - The source to destination bandwidth.
  <dt><i>loss</i> - The source to destination loss.
</dl>

<p>Notes:

<ul>
  <li>This commands modifies the delay characteristics of a link in a
      single direction.  The other direction is unchanged.
  <li>This command only applies to links.  Use
      <code>tb-set-lan-simplex-params</code> below for LANs.
</ul>

<h4>tb-set-lan-simplex-params</h4>

<pre>
tb-set-lan-simplex-params <i>lan</i> <i>node</i> <i>todelay</i> <i>tobw</i> <i>toloss</i> <i>fromdelay</i> <i>frombw</i> <i>fromloss</i>

tb-set-lan-simplex-params $lan1 $node1 100ms 10Mb 0.1 5ms 100Mb 0
</pre>

<dl>
  <dt><i>lan</i> - The lan we are modifying.
  <dt><i>node</i> - The member of the lan we are modifying.
  <dt><i>todelay</i> - Node to lan delay.
  <dt><i>tobw</i> - Node to lan bandwidth.
  <dt><i>toloss</i> - Node to lan loss.
  <dt><i>fromdelay</i> - Lan to node delay.
  <dt><i>frombw</i> - Lan to node bandwidth.
  <dt><i>fromloss</i> - Lan to node loss.
</dl>

<p>Notes:
<ul>
<li>This command is exactly like <code>tb-set-node-lan-params</code>
    except that it allows the characteristics in each direction to be
    chosen separately.  See all the notes for
    <code>tb-set-node-lan-params</code>.
</ul>

<hr>

Christopher Alfeld's avatar
Christopher Alfeld committed
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
<a name="VTYPE"></a><h3>Virtual Type Commands</h3>

<p>Virtual Types are a method of defining fuzzy types.  I.e. types
that can be fulfilled by multiple different physical types.  The
advantage of virtual types (vtypes) is that all nodes of the same
vtype will usually be the same physical type of node.  In this way,
vtypes allows logical grouping of nodes.

<p>As an example, imagine we have network with internal routers
connecting leaf nodes.  We want the routers to all have the same
hardware, and the leaf nods to all have the same hardware, but the
specifics of this hardware do not matter.  We have the following
fragment in our NS file:

<pre>
...
tb-make-soft-vtype router {pc600 pc850}
tb-make-soft-vtype leaf {pc600 pc850}

tb-set-hardware $router1 router
tb-set-hardware $router2 router
tb-set-hardware $leaf1 leaf
tb-set-hardware $leaf2 leaf
</pre>

<p>Here we have set up two soft (see below) vtypes, router and leaf.
Our router nodes are then specified to be of type router, and the leaf
nods of type leaf.  When the experiment is swapped in the testbed will
attempt to make router1 and router2 be of the same type, and
similarly, leaf1 and leaf2 of the same type.  However, the
routers/leafs may be pc600s or they may be pc850s, whichever is easier
to fit in to the available resources.

<p>As a basic use, vtypes can be used to request nodes that are all
the same type, but can be of any available type:

<pre>
...
tb-make-soft-vtype N {pc600 pc850}

tb-set-hardware $node1 N
tb-set-hardware $node2 N
...
</pre>

<p>Vtypes come in two varieties, hard and soft.  With soft vtypes, the
testbed will try to make all nodes of that vtype the same physical
type, but may do otherwise if resources are tight.  Hard vtypes behave
just like soft vtypes except that the testbed will give higher
priority to vtype consistency and swapping in will fail if the vtypes
can not be satisfied.  So, if you use soft vtypes you are more likely
to swap in but there is a chance your node of a specific vtype will
not all be the same.  If you use hard vtypes all nods of a given vtype
will be the same, but swapping in may fail.

<p>Finally, you can have weighted soft vtypes.  Here you assign a
weight from 0 to 1 exclusive to your vtype.  The testbed will give
higher priority to consistency in the higher weighted vtypes.  The
primary use of this in to rank multiple vtypes by importance of
consistency.  Soft vtypes have a weight of 0.5 by default.

<p>As a final note, when specifying the types of a vtype, use the most
specific type possible.  For example: tb-make-soft-vtype router {pc
pc600}, is not very useful, as pc600 is a sub type of pc.  You may
very well end up with two routers as type pc with different hardware,
as pc covers multiple types of hardware.

<h4>tb-make-soft-vtype</h4>

<pre>
tb-make-soft-vtype <i>vtype</i> {<i>types</i>}
tb-make-hard-vtype <i>vtype</i> {<i>types</i>}
tb-make-weighted-vtype <i>vtype</i> <i>weight</i> {<i>types</i>}

tb-make-soft-vtype router {pc600 pc850}
tb-make-hard-vtype leaf {pc600 pc850}
tb-make-weighted-vtype A 0.1 {pc600 pc850}
</pre>

<dl>
  <dt><i>vtype</i> - The name of the vtype to create.
  <dt><i>types</i> - One or more physical types.
  <dt><i>weight</i> - The weight of the vtype, 0 < <i>weight</i> < 1.
</dl>

<p>Notes:
<ul>
  <li>These commands create vtypes.  See notes above for description
      of vtypes and the difference between soft and hard.
  <li><code>tb-make-soft-vtype</code> creates vtypes with weight 0.5.
  <li>vtype commands must appear before <code>tb-set-hardware</code>
      commands that use them.
  <li>Do not used <code>tb-fix-node</code> with nodes that have a vtype.
</ul>

708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
<a name="MISC"></a><h3>Misc. Commands</h3>

<h4>tb-fix-node</h4>

<pre>
tb-fix-node <i>vnode</i> <i>pnode</i>

tb-fix-node $node0 pc42
</pre>

<dl>
  <dt><i>vnode</i> - The node we are fixing.
  <dt><i>pnode</i> - The physical node we want used.
</dl>

<p>Notes:
<ul>
  <li>This command forces the virtual node to be mapped to the
      specified physical node.  Swap in will fail if this can not be
      done.
Christopher Alfeld's avatar
Christopher Alfeld committed
728
  <li>Do not use this command on nodes that are a virtual type.
729
</ul>
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768


<h4>tb-set-uselatestwadata</h4>

<pre>
tb-set-uselatestwadata 0
tb-set-uselatestwadata 1
</pre>

<p>Notes:
<ul>
  <li>This command indicates which widearea data to use when mapping
  widearea nodes to links. The default is 0, which says to use the aged data.
  Setting it to 1 says to use the most recent data. 
</ul>


<h4>tb-set-wasolver-weights</h4>

<pre>
tb-set-wasolver-weights <i>delay bw plr</i>

tb-set-wasolver-weights 1 10 500
</pre>

<dl>
  <dt><i>delay</i> - The weight to give delay when solving.
  <dt><i>bw</i> - The weight to give bandwidth when solving.
  <dt><i>plr</i> - The weight to give lossrate when solving.
</dl>

<p>Notes:
<ul>
  <li>This command sets the relative weights to us when assigning widearea
  nodes to links. Specifying a zero says to ignore that particular
  metric when doing the assignment. Setting all three to zero results
  in an essentially random selection.
</ul>