xmlrpcapi.php3 46.4 KB
Newer Older
1 2
<?php
#
3
# Copyright (c) 2004-2010 University of Utah and the Flux Group.
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
# 
# {{{EMULAB-LICENSE
# 
# This file is part of the Emulab network testbed software.
# 
# This file is free software: you can redistribute it and/or modify it
# under the terms of the GNU Affero General Public License as published by
# the Free Software Foundation, either version 3 of the License, or (at
# your option) any later version.
# 
# This file is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public
# License for more details.
# 
# You should have received a copy of the GNU Affero General Public License
# along with this file.  If not, see <http://www.gnu.org/licenses/>.
# 
# }}}
23 24 25
#
require("defs.php3");

Leigh Stoller's avatar
Leigh Stoller committed
26 27 28 29
#
# Verify page arguments.
#
$optargs = OptionalPageArguments("printable",  PAGEARG_BOOLEAN);
30

Leigh Stoller's avatar
Leigh Stoller committed
31
if (!isset($printable)) {
32
    $printable = 0;
Leigh Stoller's avatar
Leigh Stoller committed
33
}
34 35 36 37 38

#
# Standard Testbed Header
#
if (!$printable) {
39
    PAGEHEADER("Emulab Tutorial: XMLRPC Interface to Emulab");
40 41 42 43 44 45 46 47 48 49 50
}

if (!$printable) {
    echo "<b><a href=$REQUEST_URI?printable=1>
             Printable version of this document</a></b><br>\n";
}

#
# Drop into html mode
#
?>
51 52 53 54
<center>
<h2>Emulab Tutorial - XMLRPC Interface to Emulab</h2>
</center>

55
<p>
56 57
This page describes the <a href="http://www.xmlrpc.com">XMLRPC</a> interface
to Emulab. Currently, the
Leigh Stoller's avatar
Leigh Stoller committed
58
interface mainly supports experiment creation, modification, swapping,
59
and termination. We also provide interfaces to several other common
Robert Ricci's avatar
Robert Ricci committed
60
operations on nodes end experiments such as rebooting, reloading, link
61 62 63
delay configuration, etc. This interface is a work in progress; it
will improve and grow over time. If there is something missing you
need, please send us email.
64 65 66
</p>

<p>
67 68 69 70 71 72 73 74
The Emulab XMLRPC server can be accessed via an SSL based server. 
You need to request a certificate from the Emulab website in order to
use the SSL based server. Go to the "My Emulab" portion of the Emulab
website, and click on the "Create SSL Certificate" link. You will
be prompted for a passphrase to use to encrypt the private key.
Once the key has been created, you will be given a link to
download a text version (PEM format). Simply provide this
certificate as an input to your SSL client.
75 76

<p>
77
The API is described in detail below. A demonstration client written in
78 79 80 81
Python is also available that you can use on your desktop to invoke
commands from the shell. For example:

    <code><pre>
82
    sslxmlrpc_client.py startexp batch=false wait=true proj="myproj" exp="myexp" nsfilestr="`cat ~/nsfile.ns`"</code></pre>
83

84
which says to create an experiment called "myexp" in the "myproj" project,
85
swap it in immediately, wait for the exit status (instead of running
86
asynchronously), passing inline the contents of <tt>nsfile.ns</tt> in your
87
home directory on your desktop.  By default, the client will contact the RPC
88
server at <tt><?php echo $BOSSNODE ?></tt>, but you can override that by
89
using the <tt>-s hostname</tt> option. For example:
90 91

    <code><pre>
92
    sslxmlrpc_client.py -s boss.emulab.net startexp ...</code></pre>
93

94 95
which would invoke the RPC server on <tt>boss.emulab.net</tt>.
You will be prompted for your SSL passphrase.
96 97 98
</p>

<p>
99
The <a href="downloads/xmlrpc/"><tt>sslxmlrpc_client</tt></a>
100 101 102 103 104 105
python program is a simple demonstration of how to use Emulab's RPC
server. If you do not provide a method and arguments on the command
line, it will enter a command loop where you can type in commands (method
and arguments) and wait for responses from the server. It converts your
command lines into RPCs to the server, and prints out the results that the
server sends back (exiting with whatever status code the server
106 107 108
returned).f You can use this client program as is, or you can write your own
client program in whatever language you like. Remember to
use the <tt>--cert=</tt> option to tell the demonstration
109
client where to find your certificate. You will be prompted for the
110
private key passphrase when it attempts to contact the server.
111

112 113 114
<p>
A more sophisticated client called
<a href="downloads/xmlrpc/"><tt>script_wrapper.py</tt></a> provides a
115
traditional command line interface to Emulab, using the SSL transport
116
described above. The client should run on any machine that has Python
117
installed. For example, to swap the <tt>myexp</tt>
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
experiment in the <tt>testbed</tt> project in:

    <code><pre>
    script_wrapper.py --server=boss.emulab.net swapexp -e testbed,myexp in</code></pre>

Each command has its own --help option:

    <code><pre>
    script_wrapper.py swapexp --help
    
    swapexp -e pid,eid in|out
    swapexp pid eid in|out
    where:
         -w   - Wait for experiment to finish swapping
         -e   - Project and Experiment ID
         in   - Swap experiment in  (must currently be swapped out)
        out   - Swap experiment out (must currently be swapped in)</code></pre>

A complete list of Emulab commands available via the script wrapper is
available with the --help command:

    <code><pre>
    script_wrapper.py --help
    Usage: wrapper [wrapper options] command [command args and opts]
    
    Commands:
        readycount   Get readycounts for nodes in experiment (deprecated).
        startexp     Start an Emulab experiment.
        savelogs     Save console tip logs to experiment directory.
        endexp       Terminate an experiment.
        eventsys_control Start/Stop/Restart the event system.
        batchexp     Synonym for startexp.
        node_list    Print physical mapping of nodes in an experiment.
        expinfo      Get information about an experiment.
        node_admin   Boot selected nodes into FreeBSD MFS.
        create_image Create a disk image from a node.
        delay_config Change the link shaping characteristics for a link or lan.
        modexp       Modify experiment.
        nscheck      Check and NS file for parser errors.
        swapexp      Swap experiment in or out.
        os_load      Reload disks on selected nodes or all nodes.
        portstats    Get portstats from the switches.
        link_config  Change interface parameters for a wireless link.
        node_reboot  Reboot selected nodes or all nodes in an experiment.</code></pre>

As a convenience, you can symlink <tt>script_wrapper.py</tt> to each of the
commands listed above, and avoid having to type the wrapper name:

    <code><pre>
    ln -s script_wrapper.py swapexp

    swapexp --server=boss.emulab.net -e testbed,myexp in</code></pre>

This has already been done in <tt>users.emulab.net:/usr/testbed/bin</tt>,
so each of the above commands is already on your path.

<h3>Server API</h3>
175 176 177 178
<p>
The API for the server is broken into several different modules that
export a number of methods, each of which is described below. Each
method is of the form (in Python speak):
179 180

    <code><pre>
181
    def startexp(version, arguments):
182
        return EmulabResponse(RESPONSE_SUCCESS, value=0, output="Congratulations")</code></pre>
183

184
The arguments to each method:
185 186 187 188 189 190 191 192 193 194 195 196
<ul>
<li><tt>version</tt>: a numeric argument that the server uses to
determine if the client is really capable of speaking to the server.

<li><tt>arguments</tt>: a <em>hash table</em> of argument/value pairs,
which in Python is a <tt>Dictionary</tt>. In Perl or PHP this would be a
hashed array. Any client that supports such a datatype will be able to use
this interface directly. For example, to swap out an experiment a client
might:

    <code><pre>
    args = {};
197 198
    args["proj"] = "myproj"
    args["exp"] = "myexp"
Leigh Stoller's avatar
Leigh Stoller committed
199
    args["direction"]  = "out"
200
    response = server.swapexp(CURRENTVERSION, args)</code></pre>
201 202
</ul>

203
The client specifies the <tt>proj</tt> and <tt>exp</tt> of the experiment
204
he/she wants to swap, as well as the actual swap operation, in this case
205 206 207 208 209 210 211 212 213 214 215 216 217 218
<tt>out</tt>. The response from the server is another hashed array (Python
Dictionary) of the form:

<blockquote>
    <ul>
     <li><tt>code</tt>: An integer code as defined in
     <a href="downloads/xmlrpc/"><tt>emulabclient.py</tt></a>.
     <li><tt>value</tt>: A return value. May be any valid data type that
     can be transfered in XML. 
     <li><tt>output</tt>: A string (with embedded newlines) to print out.
     This is useful for debugging and for guiding users through the perils
     of XMLRPC programming. 
    </ul>
</blockquote>
219

220 221
Unless specifically stated, the return value of most commands is a
simple integer reflecting an exit code from the server, and some
222
output to help you determine what went wrong. Otherwise, the
223 224
return value is documented in each method description. 

Timothy Stack's avatar
Timothy Stack committed
225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461
<p>
Finally, a quick note about the types accepted and returned by methods.  Most
methods will accept a real XML-RPC type and try to coerce a string into that
type.  For example, in python, passing <code>True</code> is equivalent to
passing the string, "true".  When returning data, the methods will prefer to
return typed values, rather than formatted strings.

<ul>
<li><b>/XMLRPC/emulab</b>
<p>
The <tt>emulab</tt> module provides general information about this Emulab
installation.

  <ul>
  <li><tt><b>news</b></tt>: Get news item headers.  The optional
  arguments are:<br><br>

  <table cellpadding=2>
    <tr>
      <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
    </tr>
    <tr></tr>
    <tr>
      <td><tt>starting</tt></td>
      <td>date</td>
      <td>-Inf.</td>
      <td>The date to start searching for news items (e.g. "2003-07-23
      10:13:00").</td>
    </tr>
    <tr>
      <td><tt>ending</tt></td>
      <td>date</td>
      <td>+Inf.</td>
      <td>The date to stop searching for news items.</td>
    </tr>
  </table>

  <br>The return value is a list of hash tables with the following
  elements:<br><br>

  <table cellpadding=2>
    <tr>
      <th>Name</th><th>Type</th><th>Description</th>
    </tr>
    <tr>
      <td><tt>subject</tt></td>
      <td>string</td>
      <td>The item's subject.</td>
    </tr>
    <tr>
      <td><tt>author</tt></td>
      <td>string</td>
      <td>The item's author.</td>
    </tr>
    <tr>
      <td><tt>date</tt></td>
      <td>date</td>
      <td>The date the item was posted.</td>
    </tr>
    <tr>
      <td><tt>msgid</tt></td>
      <td>integer</td>
      <td>The item's unique identifier.  This value should be used as the
      anchor when redirecting to the web site
      (e.g. http://www.emulab.net/news.php3#32).</td>
    </tr>
  </table>

  </ul>
</ul>

<ul>
<li><b>/XMLRPC/user</b>
<p>
The <tt>user</tt> module provides access to user-specific information.

  <ul>
  <li><tt><b>nodecount</b></tt>: Get the number of nodes you have allocated.
  There are no arguments and the method returns an integer.<br>

  <br>
  <li><tt><b>membership</b></tt>: Get the list of projects and subgroups of
  which you are a member.  The return value is a hash table where each entry is
  the name of a project and a list of subgroups.  The optional arguments
  are:<br><br>

  <table cellpadding=2>
    <tr>
      <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
    </tr>
    <tr>
      <td>permission</td>
      <td>string</td>
      <td>readinfo</td>
      <td>The name of an action that the user would like to take.  The result
      will then be narrowed to those groups where this action is possible.
      Supported values:
      <ul>
      <li>readinfo - Read information about the project/group.
      <li>createexpt - Create an experiment.
      <li>makegroup - Create a sub-group.
      <li>makeosid - Create an OS identifier.
      <li>makeimageid - Create an image identifier.
      </ul>
      </td>
    </tr>
  </table>

  </ul>
</ul>

<ul>
<li><b>/XMLRPC/fs</b>
<p>
The <tt>fs</tt> module lets you examine the parts of the Emulab file system
that can be exported to your experimental nodes.

  <ul>
  <li><tt><b>access</b></tt>: Check the accessibility of a path.  The path
    must lie on an exported file system or the call will fail.  The return
    value is true or false.  The required arguments are:<br><br>
    <table cellpadding=2>
      <tr>
        <th>Name</th><th>Type</th><th>Description</th>
     </tr>
     <tr></tr>
     <tr>
      <td><tt>path</tt></td>
      <td>string</td>
      <td>The path to check</td>
     </tr>
     <tr>
      <td><tt>permission</tt></td>
      <td>string</td>
      <td>The access permission to check.  Value should be one of: "read",
      "write", "execute", "exists".</td>
     </tr>
    </table>

  <br>
  <li><tt><b>listdir</b></tt>: Get a directory list for a given path.  The path
    must lie on an exported file system of the call will fail.  The return
    value is a list of tuples for each entry, described in detail below.  The
    required arguments are:<br><br>
    <table cellpadding=2>
      <tr>
        <th>Name</th><th>Type</th><th>Description</th>
     </tr>
     <tr></tr>
     <tr>
      <td><tt>path</tt></td>
      <td>string</td>
      <td>The path to check</td>
     </tr>
    </table>

    <br>
    The return value is a list of tuples where each entry is organized as
    follows:<br><br>

    <table cellpadding=2>
      <tr>
        <th>Index</th><th>Type</th><th>Description</th>
     </tr>
     <tr></tr>
     <tr>
      <td>0</td>
      <td>string</td>
      <td>The name of the entry.</td>
     </tr>
     <tr>
      <td>1</td>
      <td>character</td>
      <td>The entry type, where:
      <ul>
      <li>'d' - directory
      <li>'c' - character device
      <li>'b' - block device
      <li>'f' - regular file
      <li>'l' - link
      <li>'s' - socket
      <li>'u' - unknown
      </td>
     </tr>
     <tr>
      <td>2</td>
      <td>integer</td>
      <td>Unix permission mask.</td>
     </tr>
     <tr>
      <td>3</td>
      <td>string</td>
      <td>Name of the user owner.</td>
     </tr>
     <tr>
      <td>4</td>
      <td>string</td>
      <td>Name of the group owner.</td>
     </tr>
     <tr>
      <td>5</td>
      <td>integer</td>
      <td>The size of the file.</td>
     </tr>
     <tr>
      <td>6</td>
      <td>integer</td>
      <td>The last access time as the number of seconds since the epoch.</td>
     </tr>
     <tr>
      <td>7</td>
      <td>integer</td>
      <td>The last modified time as the number of seconds since the epoch.</td>
     </tr>
     <tr>
      <td>8</td>
      <td>integer</td>
      <td>The creation time as the number of seconds since the epoch.</td>
     </tr>
    </table>

    <br>
    <li><tt><b>exports</b></tt>: Get the root list of file system exports
    available to you.  This method takes no arguments and returns a list of
    strings that represent the set of paths that are potentially accessible by
    your experimental nodes.<br><br>

    Note 1: The list does <i>not</i> include other user directories even though
    they may be accessible.<br><br>

    Note 2: The list <i>does</i> include all project and group directories that
    you are a member of, even though the nodes will only be able to access the
    project/group directories the experiment was created under.

  </ul>
</ul>

462
<ul>
463
<li><b>/XMLRPC/experiment</b>
464
<p>
465
The <tt>experiment</tt> module lets you start, control, and terminate
466 467 468
experiments.

  <ul>
Timothy Stack's avatar
Timothy Stack committed
469 470 471 472 473 474 475 476 477 478 479 480 481 482 483
  <li><tt><b>constraints</b></tt>: Get the physical/policy constraints for
  experiment parameters.  There are no arguments and the return value is a hash
  table with the following elements:<br><br>

  <table cellpadding=2>
  <tr>
    <th>Name</th><th>Type</th><th>Description</th>
  </tr>
  <tr>
    <td>idle/threshold</td>
    <td>integer</td>
    <td>The maximum number of hours allowed for the idleswap parameter.</td>
  </tr>
  </table>
  
484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505
  <br>
  <li><tt><b>getlist</b></tt>: Get the list of experiments created by a
  user.  There are no required arguments and the optional arguments
  are:<br><br>
  
  <table cellpadding=2>
   <tr>
    <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
   </tr>
   <tr></tr>
   <tr>
    <td><tt>format</tt></td>
    <td>string</td>
    <td>"brief"</td>
    <td>The format of the data to return.  The "brief" format contains a nested
    mapping of project names to group names and group names to a list of
    experiment names.  The "full" format expands the experiment listing to
    include structures containing extra information about each experiment,
    instead of just the name.
    </td>
   </tr>
  </table>
Timothy Stack's avatar
Timothy Stack committed
506

507
  
Timothy Stack's avatar
Timothy Stack committed
508
  <br>
509
  <li><tt><b>startexp</b></tt>: Create an experiment. By default, the experiment
510
  is started as a <a href="<? echo "$WIKIDOCURL/Tutorial#BatchMode" ?>"><em>batch</em></a>
511
  experiment, but you can use the <tt>batchmode</tt> option described below to
512
  alter that behavior. You can pass an NS file inline, or you can give the
513 514 515
  path of a file already on the Emulab fileserver.
  <br>
  <br>
516 517 518
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
519
    <th>Name</th><th>Type</th><th>Description</th>
520 521 522
  </tr>
  <tr></tr>
  <tr>
523
    <td><tt>proj</tt></td>
524 525 526 527
    <td>string</td>
    <td>The Emulab project ID in which to create the experiment</td>
  </tr>
  <tr>
528
    <td><tt>exp</tt></td>
529 530 531 532 533 534 535 536 537 538 539 540 541 542
    <td>string</td>
    <td>The unique ID to call the experiment</td>
  </tr>
  <tr>
    <td><tt>nsfilestr</tt></td>
    <td>string</td>
    <td> A string representing the NS file to use, with embedded newlines,
         <b>or</b>,</td>
  </tr>
  <tr>
    <td><tt>nsfilepath</tt></td>
    <td>string</td>
    <td>The pathname of a NS file on the Emulab file
         server, within the project directory<br>
543
	 (example: /proj/myproj/foo.ns)</td>
544 545
  </tr>
  </table>
546
  <br>
547 548 549
  The optional arguments are:<br><br>
  <table cellpadding=2>
   <tr>
550
    <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
551 552 553
   </tr>
   <tr></tr>
   <tr>
554
    <td><tt>group</tt></td>
555
    <td>string</td>
556
    <td>proj</td>
557 558 559 560 561 562 563 564
    <td>The Emulab subgroup ID in which to create the experiment<br>
        (defaults to project id)</td>
   </tr>
   <tr>
    <td><tt>batch</tt></td>
    <td>boolean</td>
    <td>true</td>
    <td>Create a
565
         <a href="<? echo "$WIKIDOCURL/Tutorial#BatchMode" ?>"><em>batch</em></a>
566 567 568 569 570
         experiment. Value is either "true" or "false"</td>
   </tr>
   <tr>
    <td><tt>description</tt></td>
    <td>string</td>
571
    <td>&nbsp;</td>
572 573 574 575 576 577 578 579 580 581 582 583
    <td>A pithy sentence describing your experiment</td>
   </tr>
   <tr>
    <td><tt>swappable</tt></td>
    <td>boolean</td>
    <td>true</td>
    <td>Experiment may be swapped at any time. If false, you must provide a
        reason in <tt>noswap_reason</tt></td> 
   </tr>
   <tr>
    <td><tt>noswap_reason</tt></td>
    <td>string</td>
584
    <td>&nbsp;</td>
585 586 587 588 589 590 591
    <td>A sentence describing why your experiment cannot be swapped</td> 
   </tr>
   <tr>
    <td><tt>idleswap</tt></td>
    <td>integer</td>
    <td>variable</td>
    <td>How long (in minutes) before your idle experiment can be 
592
         <a href="<? echo "$WIKIDOCURL/Swapping#idleswap" ?>">idle
593 594 595 596 597 598 599
	 swapped</a>. Defaults to a value between two and four hours.  A
	 value of zero means never idleswap (you must provide a reason in
	 <tt>noidleswap_reason</tt>)</td>
   </tr>
   <tr>
    <td><tt>noidleswap_reason</tt></td>
    <td>string</td>
600
    <td>&nbsp;</td>
601 602 603
    <td>A sentence describing why your experiment cannot be idle swapped</td> 
   </tr>
   <tr>
604
    <td><tt>max_duration</tt></td>
605 606 607
    <td>integer</td>
    <td>0</td>
    <td>How long (in minutes) before your experiment
608
     should be <a href="<? echo "$WIKIDOCURL/Swapping#autoswap" ?>">
609 610
     unconditionally swapped</a>. A value of zero means never
     unconditionally swap this experiment.
611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627
   </tr>
   <tr>
    <td><tt>noswapin</tt></td>
    <td>boolean</td>
    <td>false</td>
    <td>If true, do not swap the experiment in immediately; just "preload"
    the NS file. The experiment can be swapped in later with swapexp.</td>
   </tr>
   <tr>
    <td><tt>wait</tt></td>
    <td>boolean</td>
    <td>false</td>
    <td>If true, wait synchronously for the experiment to finish swapping.
    By default, control returns immediately, and you must wait for email
    notification to determine if the operation succeeded</td>
   </tr>
  </table>
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
  <br>
  <li><tt><b>metadata</b></tt>: Get any metadata associated with the given
  experiment.  The return value is a hashtable containing fields such as the
  experiment's description and creation date.
  <br>
  <br>
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
    <th>Name</th><th>Type</th><th>Description</th>
  </tr>
  <tr></tr>
  <tr>
    <td><tt>proj</tt></td>
    <td>string</td>
    <td>The Emulab project ID of the experiment</td>
  </tr>
  <tr>
    <td><tt>exp</tt></td>
    <td>string</td>
    <td>The Emulab experiment ID</td>
  </tr>
  </table>

  <br>
  <li><tt><b>nsfile</b></tt>: Get the NS file associated with the given
  experiment.
  <br>
  <br>
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
    <th>Name</th><th>Type</th><th>Description</th>
  </tr>
  <tr></tr>
  <tr>
    <td><tt>proj</tt></td>
    <td>string</td>
    <td>The Emulab project ID of the experiment</td>
  </tr>
  <tr>
    <td><tt>exp</tt></td>
    <td>string</td>
    <td>The Emulab experiment ID</td>
  </tr>
  </table>

676 677 678 679 680 681 682 683
  <br>
  <li><tt><b>swapexp</b></tt>: Swap an experiment in or out. The experiment
  must, of course, be in the proper state for requested operation.
  <br>
  <br>
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
684
    <th>Name</th><th>Type</th><th>Description</th>
685 686 687
  </tr>
  <tr></tr>
  <tr>
688
    <td><tt>proj</tt></td>
689 690 691 692
    <td>string</td>
    <td>The Emulab project ID of the experiment</td>
  </tr>
  <tr>
693
    <td><tt>exp</tt></td>
694 695 696 697 698 699 700 701 702 703 704 705 706
    <td>string</td>
    <td>The Emulab experiment ID</td>
  </tr>
  <tr>
    <td><tt>direction</tt></td>
    <td>string</td>
    <td>The direction in which to swap; one of "in" or "out"
  </tr>
  </table>
  <br>
  The optional arguments are:<br><br>
  <table cellpadding=2>
   <tr>
707
    <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729
   </tr>
   <tr></tr>
   <tr>
    <td><tt>wait</tt></td>
    <td>boolean</td>
    <td>false</td>
    <td>If true, wait synchronously for the experiment to finish swapping
    in (or preloading if <tt>noswapin</tt> is true). By default, control
    returns immediately, and you must wait for email notification to
    determine if the operation succeeded</td>
   </tr>
  </table>

  <br>
  <li><tt><b>modify</b></tt>: Modify an experiment, either while it is
  swapped in or out. You must provide an NS file to direct the
  modification. 
  <br>
  <br>
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
730
    <th>Name</th><th>Type</th><th>Description</th>
731 732 733
  </tr>
  <tr></tr>
  <tr>
734
    <td><tt>proj</tt></td>
735 736 737 738
    <td>string</td>
    <td>The Emulab project ID of the experiment</td>
  </tr>
  <tr>
739
    <td><tt>exp</tt></td>
740 741 742 743 744 745 746 747 748 749 750 751 752 753
    <td>string</td>
    <td>The Emulab experiment ID</td>
  </tr>
  <tr>
    <td><tt>nsfilestr</tt></td>
    <td>string</td>
    <td> A string representing the NS file to use, with embedded newlines,
         <b>or</b>,</td>
  </tr>
  <tr>
    <td><tt>nsfilepath</tt></td>
    <td>string</td>
    <td>The pathname of a NS file on the Emulab file
         server, within the project directory<br>
754
	 (example: /proj/myproj/foo.ns)</td>
755 756 757 758 759 760
  </tr>
  </table>
  <br>
  The optional arguments are:<br><br>
  <table cellpadding=2>
   <tr>
761
    <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793
   </tr>
   <tr></tr>
   <tr>
    <td><tt>wait</tt></td>
    <td>boolean</td>
    <td>false</td>
    <td>If true, wait synchronously for the experiment to finish swapping
    in (or preloading if <tt>noswapin</tt> is true). By default, control
    returns immediately, and you must wait for email notification to
    determine if the operation succeeded</td>
   </tr>
   <tr>
    <td><tt>reboot</tt></td>
    <td>boolean</td>
    <td>false</td>
    <td>If true and the experiment is swapped in, reboot all nodes in the
    experiment</td>
   </tr>
   <tr>
    <td><tt>restart_eventsys</tt></td>
    <td>boolean</td>
    <td>false</td>
    <td>If true and the experiment is swapped in, restart the event system
    (all events are rerun from time zero)</td>
   </tr>
  </table>

  <br>
  <li><tt><b>endexp</b></tt>: Terminate an experiment.
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
794
    <th>Name</th><th>Type</th><th>Description</th>
795 796 797
  </tr>
  <tr></tr>
  <tr>
798
    <td><tt>proj</tt></td>
799 800 801 802
    <td>string</td>
    <td>The Emulab project ID in which the experiment was created</td>
  </tr>
  <tr>
803
    <td><tt>exp</tt></td>
804 805 806 807 808 809 810 811 812
    <td>string</td>
    <td>The Emulab ID of the experiment to terminate</td>
  </tr>
  </table>
  
  <br>
  The optional arguments are:<br><br>
  <table cellpadding=2>
   <tr>
813
    <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
814 815 816 817 818 819 820 821 822 823 824 825
   </tr>
   <tr></tr>
   <tr>
    <td><tt>wait</tt></td>
    <td>boolean</td>
    <td>false</td>
    <td>If true, wait synchronously for the experiment to finish terminating.
    By default, control returns immediately, and you must wait for email
    notification to determine if the operation succeeded</td>
   </tr>
  </table>
  
826 827 828 829 830 831
  <br>
  <li><tt><b>state</b></tt>: Get the current state of the experiment.
  The return value is a string; one of active, swapped, activating, etc.
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
832
    <th>Name</th><th>Type</th><th>Description</th>
833 834 835 836 837 838 839 840 841 842 843 844 845
  </tr>
  <tr></tr>
  <tr>
    <td><tt>proj</tt></td>
    <td>string</td>
    <td>The Emulab project ID in which the experiment was created</td>
  </tr>
  <tr>
    <td><tt>exp</tt></td>
    <td>string</td>
    <td>The Emulab ID of the experiment</td>
  </tr>
  </table>
846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867

  <br>
  <li><tt><b>waitforactive</b></tt>: Wait for an experiment to reach
  the <em>active</em> state. Typically, you would use this if you
  launched a swapin asynchronously, and then wanted to wait later for
  the swapin to complete. 
  <table cellpadding=2>
  <tr>
    <th>Name</th><th>Type</th><th>Description</th>
  </tr>
  <tr></tr>
  <tr>
    <td><tt>proj</tt></td>
    <td>string</td>
    <td>The Emulab project ID in which the experiment was created</td>
  </tr>
  <tr>
    <td><tt>exp</tt></td>
    <td>string</td>
    <td>The Emulab ID of the experiment</td>
  </tr>
  </table>
868
  
869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887
  <br>
  The optional arguments are:<br><br>
  <table cellpadding=2>
   <tr>
    <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
   </tr>
   <tr></tr>
   <tr>
    <td><tt>timeout</tt></td>
    <td>integer</td>
    <td><i>forever</i></td>
    <td>Timeout after this many <b>seconds</b>. The return code is
        is <tt>RESPONSE_SUCCESS</tt> if experiment reaches the active state or
	<tt>RESPONSE_TIMEDOUT</tt> if the timer expires.
    </td>
   </tr>
  </table>
    

888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911
  <br>
  <li><tt><b>statewait</b></tt>: Wait for an experiment to reach a particular
  state. State is one of swapped, active, swapping, activating, etc. If the
  experiment is already in desired state, returns immediately, otherwise
  blocks indefinitely until the experiment reaches the state. Use the timeout
  option below to terminate the wait early. The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
    <th>Name</th><th>Type</th><th>Description</th>
  </tr>
  <tr></tr>
  <tr>
    <td><tt>proj</tt></td>
    <td>string</td>
    <td>The Emulab project ID in which the experiment was created</td>
  </tr>
  <tr>
    <td><tt>exp</tt></td>
    <td>string</td>
    <td>The Emulab ID of the experiment</td>
  </tr>
  <tr>
    <td><tt>state</tt></td>
    <td>string</td>
912 913 914 915 916
    <td>The experiment state(s) to wait for.  If a single string is specified
    the call will block until the experiment has reached that state.  If a list
    of states is given, the call will block until the experiment has reached
    any of the states in the list.  Finally, if an empty list is given, the
    call will block until the experiment undergoes a state change.</td>
917 918 919 920 921 922 923 924 925 926 927 928 929
  </tr>
  </table>
    
  <br>
  The optional arguments are:<br><br>
  <table cellpadding=2>
   <tr>
    <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
   </tr>
   <tr></tr>
   <tr>
    <td><tt>timeout</tt></td>
    <td>integer</td>
930
    <td><i>forever</i></td>
931 932 933 934 935 936 937
    <td>Timeout after this many <b>seconds</b>. The return code is
        is <tt>RESPONSE_SUCCESS</tt> if the state is reached or
	<tt>RESPONSE_TIMEDOUT</tt> if the timer expires.
    </td>
   </tr>
  </table>

938 939 940
  <br>The return value is the current state of the experiment.
  <br>

941 942 943 944 945 946 947 948
  <br>
  <li><tt><b>info</b></tt>: Get information about an experiment. The
  return value is a hash table (Dictionary) of hash tables. For example,
  the <tt>mapping</tt> request will return a hash indexed by node name, where
  each entry is another hash table of name=value pairs, such as type=pc850
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
949
    <th>Name</th><th>Type</th><th>Description</th>
950 951 952 953 954 955 956 957 958 959 960 961 962 963 964
  </tr>
  <tr></tr>
  <tr>
    <td><tt>proj</tt></td>
    <td>string</td>
    <td>The Emulab project ID in which the experiment was created</td>
  </tr>
  <tr>
    <td><tt>exp</tt></td>
    <td>string</td>
    <td>The Emulab ID of the experiment</td>
  </tr>
  <tr>
    <td><tt>aspect</tt></td>
    <td>string</td>
965
    <td>Request information about specific aspect of the experiment.</td>
966 967 968 969 970 971 972
  </tr>
  </table>
  
  <br>
  The <tt>aspect</tt> is one of:
  <table cellpadding=2>
   <tr>
973
    <th>Name</th><th>Description</th>
974 975 976 977 978 979 980 981 982 983
   </tr>
   <tr></tr>
   <tr>
    <td><tt>mapping</tt></td>
    <td>Request the mapping of nodes in your NS file, to physical testbed
    nodes. This request is ignored if the experiment is not swapped in</td>
   </tr>
   <tr>
    <td><tt>links</tt></td>
    <td>Request information about all of the links in your experiment,
984
    including delay characteristics, IP address and mask</td>
985 986 987
   </tr>
  </table>
  
988 989 990 991 992 993
  <br>
  <li><tt><b>nscheck</b></tt>: Check an NS file for obvious parser errors.
  The return code is <tt>RESPONSE_SUCCESS</tt> or <tt>RESPONSE_ERROR</tt>.
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
994
    <th>Name</th><th>Type</th><th>Description</th>
995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007
  </tr>
  <tr></tr>
  <tr>
    <td><tt>nsfilestr</tt></td>
    <td>string</td>
    <td> A string representing the NS file to use, with embedded newlines,
         <b>or</b>,</td>
  </tr>
  <tr>
    <td><tt>nsfilepath</tt></td>
    <td>string</td>
    <td>The pathname of a NS file on the Emulab file
         server, within the project directory<br>
1008
	 (example: /proj/myproj/foo.ns)</td>
1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020
  </tr>
  </table>

  <br>
  <li><tt><b>delay_config</b></tt>: Change the link characteristics for a
  delayed link or lan. Note that the link/lan <b>must</b> already be
  delayed; you cannot convert a non-delayed link into a delayed link. When
  operating on a delayed lan, all nodes (links to the nodes) in the lan
  will be changed.
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
1021
    <th>Name</th><th>Type</th><th>Description</th>
1022 1023 1024
  </tr>
  <tr></tr>
  <tr>
1025
    <td><tt>proj</tt></td>
1026 1027 1028 1029
    <td>string</td>
    <td>The Emulab project ID in which the experiment was created</td>
  </tr>
  <tr>
1030
    <td><tt>exp</tt></td>
1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049
    <td>string</td>
    <td>The Emulab ID of the experiment</td>
  </tr>
  <tr>
    <td><tt>link</tt></td>
    <td>string</td>
    <td>The name of the link or lan to change; see your NS file</td>
  </tr>
  <tr>
    <td><tt>params</tt></td>
    <td>Dictionary</td>
    <td>A hashed array (Dictionary) of parameters to change; see below</td>
  </tr>
  </table>
  
  <br>
  The optional arguments are:<br><br>
  <table cellpadding=2>
   <tr>
1050
    <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063
   </tr>
   <tr></tr>
   <tr>
    <td><tt>persist</tt></td>
    <td>boolean</td>
    <td>false</td>
    <td>If true, the base experiment is changed in the Emulab Database;
    changes will persist across swapin and swapout. By default, just the
    physical experiment is changed, and changes are lost at swapout</td>
   </tr>
   <tr>
    <td><tt>src</tt></td>
    <td>string</td>
1064
    <td>&nbsp;</td>
1065
    <td>If specified, change a duplex link asymmetrically; just the link from
1066
    the node specified will be changed. <em>This option is ignored on lans; the
1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079
    entire lan must be changed</em></td>
   </tr>
  </table>

  <br>
  In addition to the required arguments, you must also supply at least
  one parameter to change in the <tt>params</tt> argument. The reader is
  encouraged to read the <tt>ipfw</tt> and <tt>dummynet</tt> man pages on
  <tt>users.emulab.net</tt>. It is important to note that Emulab supports a
  smaller set of tunable parameters then NS does; please read the
  aforementioned manual pages:<br><br>
  <table cellpadding=2>
   <tr>
1080
    <th>Name</th><th>Type</th><th>Range</th><th>Description</th>
1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091
   </tr>
   <tr></tr>
   <tr>
    <td><tt>bandwidth</tt></td>
    <td>integer</td>
    <td>10-100000</td>
    <td>Bandwidth in <b>Kbits</b>/second</td>
   </tr>
   <tr>
    <td><tt>plr</tt></td>
    <td>number</td>
1092
    <td>0 &lt;= plr &lt; 1</td>
1093 1094 1095 1096 1097
    <td>Packet Loss Rate as a number between 0 and 1</td>
   </tr>
   <tr>
    <td><tt>delay</tt></td>
    <td>integer</td>
1098
    <td>&gt; 0</td>
1099 1100 1101 1102 1103
    <td>Delay in milliseconds</td>
   </tr>
   <tr>
    <td><tt>limit</tt></td>
    <td>integer</td>
1104
    <td>&nbsp;</td>
1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118
    <td>Queue size in bytes or packets. Default is 50 ethernet sized packets</td>
   </tr>
   <tr>
    <td><tt>queue-in-bytes</tt></td>
    <td>integer</td>
    <td>0,1</td>
    <td>Limit is expressed in bytes or packets (slots); default is packets</td>
   </tr>
   <tr></tr>
   <td colspan=4 align=center>These are valid for RED/GRED links only</td>
   <tr></tr>
   <tr>
    <td><tt>maxthresh</tt></td>
    <td>integer</td>
1119
    <td>&nbsp;</td>
1120 1121 1122 1123 1124
    <td>Maximum threshold for the average queue size</td>
   </tr>
   <tr>
    <td><tt>thresh</tt></td>
    <td>integer</td>
1125
    <td>&nbsp;</td>
1126 1127 1128 1129 1130
    <td>Minimum threshold for the average queue size</td>
   </tr>
   <tr>
    <td><tt>linterm</tt></td>
    <td>integer</td>
1131
    <td>&gt; 0</td>
1132 1133 1134 1135 1136
    <td>Packet dropping probability expressed as an integer (1/linterm)</td>
   </tr>
   <tr>
    <td><tt>q_weight</tt></td>
    <td>number</td>
1137
    <td>0 &lt;= plr &lt; 1</td>
1138 1139 1140 1141
    <td>For calculating average queue size</td>
   </tr>
  </table>

1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168

  <br>
  <li><tt><b>eventsys_control</b></tt>: Control the experiment event scheduler.
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
    <th>Name</th><th>Type</th><th>Description</th>
  </tr>
  <tr></tr>
  <tr>
    <td><tt>proj</tt></td>
    <td>string</td>
    <td>The Emulab project ID in which the experiment was created</td>
  </tr>
  <tr>
    <td><tt>exp</tt></td>
    <td>string</td>
    <td>The Emulab ID of the experiment</td>
  </tr>
  <tr>
    <td><tt>op</tt></td>
    <td>string</td>
    <td>One of start, stop, or replay (stop and then start))</td>
  </tr>
  </table>
  

1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229
  <br>
  <li><tt><b>link_config</b></tt>: Change the link characteristics for a
  wireless lan. Note that the lan must already be a wireless link; you
  cannot convert wired link to a wireless link! 
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
    <th>Name</th><th>Type</th><th>Description</th>
  </tr>
  <tr></tr>
  <tr>
    <td><tt>proj</tt></td>
    <td>string</td>
    <td>The Emulab project ID in which the experiment was created</td>
  </tr>
  <tr>
    <td><tt>exp</tt></td>
    <td>string</td>
    <td>The Emulab ID of the experiment</td>
  </tr>
  <tr>
    <td><tt>link</tt></td>
    <td>string</td>
    <td>The name of the lan to change; see your NS file</td>
  </tr>
  <tr>
    <td><tt>params</tt></td>
    <td>Dictionary</td>
    <td>A hashed array (Dictionary) of parameters to change; see below</td>
  </tr>
  </table>
  
  <br>
  The optional arguments are:<br><br>
  <table cellpadding=2>
   <tr>
    <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
   </tr>
   <tr></tr>
   <tr>
    <td><tt>persist</tt></td>
    <td>boolean</td>
    <td>false</td>
    <td>If true, the base experiment is changed in the Emulab Database;
    changes will persist across swapin and swapout. By default, just the
    physical experiment is changed, and changes are lost at swapout</td>
   </tr>
   <tr>
    <td><tt>src</tt></td>
    <td>string</td>
    <td>&nbsp;</td>
    <td>If specified, change a duplex link asymmetrically; just the link from
    the node specified will be changed. <em>This option is ignored on lans; the
    entire lan must be changed</em></td>
   </tr>
  </table>

  <br>
  In addition to the required arguments, you must also supply at least
  one parameter to change in the <tt>params</tt> argument. The reader is
  encouraged to read the
1230
  <a href="<? echo "$WIKIDOCURL/wireless" ?>">wireless
1231 1232 1233
  tutorial</a> to see what parameters can be changed.
  <br>

1234

1235 1236 1237 1238 1239
  <br>
  <li><tt><b>reboot</b></tt>: Reboot all nodes in an experiment.
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
1240
    <th>Name</th><th>Type</th><th>Description</th>
1241 1242 1243
  </tr>
  <tr></tr>
  <tr>
1244
    <td><tt>proj</tt></td>
1245 1246 1247 1248
    <td>string</td>
    <td>The Emulab project ID in which the experiment was created</td>
  </tr>
  <tr>
1249
    <td><tt>exp</tt></td>
1250 1251 1252 1253 1254 1255 1256 1257 1258
    <td>string</td>
    <td>The Emulab ID of the experiment</td>
  </tr>
  </table>
  
  <br>
  The optional arguments are:<br><br>
  <table cellpadding=2>
   <tr>
1259
    <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
1260 1261 1262 1263 1264 1265 1266 1267
   </tr>
   <tr></tr>
   <tr>
    <td><tt>wait</tt></td>
    <td>boolean</td>
    <td>false</td>
    <td>If true, wait synchronously for all nodes to complete their reboot</td>
   </tr>
1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280
   <tr>
    <td><tt>reconfig</tt></td>
    <td>boolean</td>
    <td>false</td>
    <td>If true, do a soft reconfiguration instead of rebooting</td>
   </tr>
   <tr>
    <td><tt>power</tt></td>
    <td>boolean</td>
    <td>false</td>
    <td>If true, power cycle the node; do not try to reboot cleanly.
        Be very careful with this option!</td>
   </tr>
1281 1282
  </table>
  
1283 1284 1285 1286 1287 1288 1289
  <br>
  <li><tt><b>reload</b></tt>: Reload the disks on all nodes in an
  experiment. You may specify an imageid to use for all nodes, or you can
  allow the system to load the default imageid for each node. 
  The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
1290
    <th>Name</th><th>Type</th><th>Description</th>
1291 1292 1293
  </tr>
  <tr></tr>
  <tr>
1294
    <td><tt>proj</tt></td>
1295 1296 1297 1298
    <td>string</td>
    <td>The Emulab project ID in which the experiment was created</td>
  </tr>
  <tr>
1299
    <td><tt>exp</tt></td>
1300 1301 1302 1303
    <td>string</td>
    <td>The Emulab ID of the experiment</td>
  </tr>
  </table>
1304
  
1305 1306 1307 1308
  <br>
  The optional arguments are:<br><br>
  <table cellpadding=2>
   <tr>
1309
    <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320
   </tr>
   <tr></tr>
   <tr>
    <td><tt>wait</tt></td>
    <td>boolean</td>
    <td>true</td>
    <td>If true, wait synchronously for all nodes to complete their
    reload. The default is to wait; you must turn this off if you want
    the reload to proceed in the background (not a good idea)</td>
   </tr>
   <tr>
1321
    <td><tt>imagename</tt></td>
1322
    <td>string</td>
1323
    <td>&nbsp;</td>
1324 1325
    <td>Specify the imagename to load on all of the nodes. See next
    option for more info</td>
1326 1327
   </tr>
   <tr>
1328
    <td><tt>imageproj</tt></td>
1329
    <td>string</td>
1330
    <td>&nbsp;</td>
1331 1332 1333 1334
    <td>Specify the Emulab project ID of the imageid. By default the
    system will look in the project of the experiment, and then in the
    system project for globally shared images.</td>
   </tr>
1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347
   <tr>
    <td><tt>imageid</tt></td>
    <td>string</td>
    <td>&nbsp;</td>
    <td>Specify image to load using Emulab internal ID for the image</td>
   </tr>
   <tr>
    <td><tt>reboot</tt></td>
    <td>boolean</td>
    <td>true</td>
    <td>If false, the nodes will not be rebooted; you will need to do
    that yourseld. The default is true (reboot nodes)</td>
   </tr>
1348
  </table>
1349 1350

  
1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377
  <br>
  <li><tt><b>savelogs</b></tt>: Save off the console tip logs for all of the
  physical nodes in your experiment. The logs are place in a subdir of your
  experiment directory. The required arguments are:<br><br>
  <table cellpadding=2>
  <tr>
    <th>Name</th><th>Type</th><th>Description</th>
  </tr>
  <tr></tr>
  <tr>
    <td><tt>proj</tt></td>
    <td>string</td>
    <td>The Emulab project ID in which the experiment was created</td>
  </tr>
  <tr>
    <td><tt>exp</tt></td>
    <td>string</td>
    <td>The Emulab ID of the experiment</td>
  </tr>
  <tr>
    <td><tt>action</tt></td>
    <td>string</td>
    <td>One of start, stop, or replay (stop and then start))</td>
  </tr>
  </table>
  

1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400
  <br>
  <li><tt><b>thumbnail</b></tt>: Get the thumbnail image of the experiment
  topology.  The required arguments are:<br><br>
  
  <table cellpadding=2>
  <tr>
    <th>Name</th><th>Type</th><th>Description</th>
  </tr>
  <tr></tr>
  <tr>
    <td><tt>proj</tt></td>
    <td>string</td>
    <td>The Emulab project ID in which the experiment was created</td>
  </tr>
  <tr>
    <td><tt>exp</tt></td>
    <td>string</td>
    <td>The Emulab ID of the experiment</td>
  </tr>
  </table>

  <br>The return value is a byte array containing a PNG image.
  <br>
1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412
  </ul>

<br>
<li><b>/XMLRPC/node</b>
<p>
The <tt>node</tt> module lets you control nodes in your experiments.
  <ul>
   <li><tt><b>reboot</b></tt>: Reboot nodes. The caller must have
   permission to reboot all of the nodes in the list, or the entire request
   fails. The required arguments are:<br><br>
    <table cellpadding=2>
     <tr>
1413
      <th>Name</th><th>Type</th><th>Description</th>
1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426
     </tr>
     <tr></tr>
     <tr>
      <td><tt>nodes</tt></td>
      <td>string</td>
      <td>A comma separated list of nodes to reboot</td>
     </tr>
    </table>
  
    <br>
    The optional arguments are:<br><br>
    <table cellpadding=2>
     <tr>
Timothy Stack's avatar
Timothy Stack committed
1427
      <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
1428 1429 1430 1431 1432 1433
     </tr>
     <tr></tr>
     <tr>
      <td><tt>wait</tt></td>
      <td>boolean</td>
      <td>false</td>
1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448
      <td>If true, wait synchronously for all nodes to complete their
          reboot</td>
     </tr>
     <tr>
      <td><tt>reconfig</tt></td>
      <td>boolean</td>
      <td>false</td>
      <td>If true, do a soft reconfiguration instead of rebooting</td>
     </tr>
     <tr>
      <td><tt>power</tt></td>
      <td>boolean</td>
      <td>false</td>
      <td>If true, power cycle the node; do not try to reboot cleanly.
          Be very careful with this option!</td>
1449 1450
     </tr>
    </table>
1451 1452 1453 1454 1455 1456 1457 1458

   <br>
   <li><tt><b>create_image</b></tt>: Create an image from a node using
   a previously created
   <a href="<?php echo $TBBASE ?>/newimageid_ez.php3">imageid</a>. The 
   The required arguments are:<br><br>
    <table cellpadding=2>
     <tr>
1459
      <th>Name</th><th>Type</th><th>Description</th>
1460 1461 1462 1463 1464 1465 1466 1467
     </tr>
     <tr></tr>
     <tr>
      <td><tt>node</tt></td>
      <td>string</td>
      <td>The node to create the image from</td>
     </tr>
     <tr>
1468
      <td><tt>imagename</tt></td>
1469
      <td>string</td>
1470
      <td>The image name (descriptor)</td>
1471 1472 1473 1474 1475 1476 1477
     </tr>
    </table>

    <br>
    The optional arguments are:<br><br>
    <table cellpadding=2>
     <tr>
1478
      <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
1479 1480 1481 1482 1483 1484
     </tr>
     <tr></tr>
     <tr>
      <td><tt>wait</tt></td>
      <td>boolean</td>
      <td>false</td>
1485 1486
      <td>If true, wait synchronously for all nodes to complete their
       reboot</td>
1487 1488
     </tr>
     <tr>
1489
      <td><tt>imageproj</tt></td>
1490 1491 1492 1493 1494 1495 1496 1497 1498 1499
      <td>string</td>
      <td>emulab-ops</td>
      <td>The project ID in which the imageid was created; defaults to
      the system project</td>
     </tr>
    </table>

    <br>
    <li><tt><b>reload</b></tt>: Reload the disks on all nodes specified.
    You may specify an imageid to use for all nodes, or you can
1500
    allow the system to load the default imageid for each node.
1501 1502 1503
    The required arguments are:<br><br>
    <table cellpadding=2>
     <tr>
1504
      <th>Name</th><th>Type</th><th>Description</th>
1505 1506 1507 1508 1509 1510 1511 1512
     </tr>
     <tr></tr>
     <tr>
      <td><tt>nodes</tt></td>
      <td>string</td>
      <td>A comma separated list of nodes to reload</td>
     </tr>
    </table>
1513
  
1514 1515 1516 1517
    <br>
    The optional arguments are:<br><br>
    <table cellpadding=2>
     <tr>
1518
      <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529
     </tr>
     <tr></tr>
     <tr>
      <td><tt>wait</tt></td>
      <td>boolean</td>
      <td>true</td>
      <td>If true, wait synchronously for all nodes to complete their
      reload. The default is to wait; you must turn this off if you want
      the reload to proceed in the background (not a good idea)</td>
     </tr>
     <tr>
1530
      <td><tt>imagename</tt></td>
1531
      <td>string</td>
1532
      <td>&nbsp;</td>
1533 1534 1535
      <td>Specify the imageid to load on all of the nodes</td>
     </tr>
     <tr>
1536
      <td><tt>imageproj</tt></td>
1537
      <td>string</td>
1538
      <td>&nbsp;</td>
1539 1540 1541
      <td>Specify the Emulab project ID of the imageid. By default the
      system will look in the system project for globally shared images.</td>
     </tr>
1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554
     <tr>
      <td><tt>imageid</tt></td>
      <td>string</td>
     <td>&nbsp;</td>
      <td>Specify image to load using Emulab internal ID for the image</td>
     </tr>
     <tr>
      <td><tt>reboot</tt></td>
      <td>boolean</td>
      <td>true</td>
      <td>If false, the nodes will not be rebooted; you will need to do
      that yourseld. The default is true (reboot nodes)</td>
     </tr>
1555 1556
    </table>
    
1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601
    <br>
    <li><tt><b>adminmode</b></tt>: Boot node into <em>administration</em>
    mode. The node is rebooted, and its OSID is set to boot FreeBSD
    from a memory resident filesystem. This allows you to operate on
    the disk while the disk is offline, say to install a new OS, take a
    snapshot,etc. The required arguments are:<br><br>
    <table cellpadding=2>
     <tr>
      <th>Name</th><th>Type</th><th>Description</th>
     </tr>
     <tr></tr>
     <tr>
      <td><tt>mode</tt></td>
      <td>string</td>
      <td>One of "on" or "off". Off returns the node to its previous OSID</td>
     </tr>
     <tr>
      <td><tt>node</tt></td>
      <td>string</td>
      <td>Node name (pcXXX)</td>
     </tr>
    </table>
  
    <br>
    The optional arguments are:<br><br>
    <table cellpadding=2>
     <tr>
      <th>Name</th><th>Type</th><th>Default</th><th>Description</th>
     </tr>
     <tr></tr>
     <tr>
      <td><tt>reboot</tt></td>
      <td>boolean</td>
      <td>true</td>
      <td>If true, reboot the node. If false, reset the OSID, but do
      not reboot the node; you must do that yourself.
     </tr>
     <tr>
      <td><tt>wait</tt></td>
      <td>boolean</td>
      <td>false</td>
      <td>If true, wait synchronously for node to complete its reboot</td>
     </tr>
    </table>
      
1602
  </ul>
1603 1604
</ul>

Timothy Stack's avatar
Timothy Stack committed
1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632
<br>
<ul>
<li><b>/XMLRPC/osid</b>
<p>
The <tt>osid</tt> module lets you operate on OS descriptors.

  <ul>
  <li><tt><b>getlist</b></tt>: Get the list of OS identifiers you can access.
  There are no arguments and the return value is a hash table containing the OS
  IDs and their descriptions.

  </ul>
</ul>

<br>
<ul>
<li><b>/XMLRPC/imageid</b>
<p>
The <tt>imageid</tt> module lets you operate on Image descriptors.

  <ul>
  <li><tt><b>getlist</b></tt>: Get the list of Image identifiers you can
  access.  There are no arguments and the return value is a hash table
  containing the Image IDs and their descriptions.

  </ul>
</ul>

1633 1634 1635 1636 1637 1638 1639 1640 1641
<?php
#
# Standard Testbed Footer
# 
if (!$printable) {
    PAGEFOOTER();
}
?>