XTesting/powder-control/README.md

   1 # About
   2
   3 This project shows how to instantiate a Powder experiment
   4 programmatically via the Powder portal API.
   5
   6 In [powder/experiment.py](powder/experiment.py), there is a class
   7 `PowderExperiment`, which serves as the main abstraction for starting,
   8 interacting with, and terminating a single Powder experiment. It relies on
   9 [powder/rpc.py](powder/rpc.py) for interacting with the Powder RPC server
  10
  11 In [start-profile.py](start-profile.py), you can see how one might use it
  12 to instantiate a Powder experiment by specifying a given profile name
  13
  14 ## Getting Started
  15
  16 In order to run [start-profile.py](start-profile.py) or otherwise use the tools in this
  17 project, you'll need a Powder account to which you've added your public `ssh`
  18 key. If you haven't already done this, you can find instructions
  19 [here](https://docs.powderwireless.net/users.html#%28part._ssh-access%29).
  20 You'll also need to download your Powder credentials. You'll find a button to do
  21 so in the drop-down menu accessed by clicking on your username after logging
  22 into the Powder portal. This will download a file called `cloudlab.pem`, which
  23 you will need later.
  24
  25 You will need to make sure the machine you are using has `python3` installed, as well as
  26 the packages in [requirements.txt](requirements.txt). You can install the
  27 packages by doing
  28
  29 ```bash
  30 pip install -r requirements.txt
  31 ```
  32
  33 Whatever machine you are using to run [start-profile.py](start-profile.py), it will need a
  34 local copy of the `cloudlab.pem` file you downloaded earlier.
  35
  36 ### Running the Example
  37
  38 The RPC client that `PowderExperiment` relies on to interact with the Powder RPC
  39 server expects some environment variables to be set. If your private `ssh` key
  40 is encrypted, the key password needs to be set in an environment variable as
  41 well, unless you have already started `ssh-agent`.
  42
  43 If your ssh key is encrypted:
  44
  45 ```bash
  46 set +o history
  47 PROJECT=your_project_name PROFILE=your_profile_name \
  48 USER=your_powder_username PWORD=your_powder_password \
  49 CERT=/path/to/your/cloulab.pem KEYPWORD=your_ssh_key_password ./start-profile.py
  50 ```
  51
  52 If not:
  53
  54 ```bash
  55 set +o history
  56 PROJECT=your_project_name PROFILE=your_profile_name \
  57 USER=your_powder_username PWORD=your_powder_password \
  58 CERT=/path/to/your/cloulab.pem ./start-profile.py
  59 ```
  60
  61 The `set +o history` command will keep these passwords out of your `bash`
  62 history (assuming you're using `bash`). The PROJECT and PROFILE environment
  63 variables are optional, as by default it will use the 'osc' project which is
  64 dedicated to the OSC community usage, and 'ubuntu-20' profile for the widely
  65 used Ubuntu 20.04 image.
  66
  67 It can take more than 30 minutes for instantiating a profile provided to
  68 [start-profile.py](start-profile.py) to complete, but you'll see intermittent messages on
  69 `stdout` indicating progress and logging results. In some cases, the Powder
  70 resources required by [start-profile.py](start-profile.py) might not be available. If so,
  71 you'll see a log message that indicates as much and the script will exit; you
  72 can look at the [Resource Availability](https://www.powderwireless.net/resinfo.php)
  73 page on the Powder portal to see the status of the required instance. After
  74 completion, the script will exit with a message about failure/success.