getting-started.scrbl 10 KB
Newer Older
Robert Ricci's avatar
Robert Ricci committed
1 2 3 4
#lang scribble/manual

@(require "defs.rkt")

@title[#:tag "getting-started" #:version apt-version]{Getting Started}
Robert Ricci's avatar
Robert Ricci committed

7 8 9 10 11 12 13 14 15
@bold{Note:} if you are a current user of Emulab and are accustomed to the
@italic{classic} Emulab interface (@url[""]),
you may first want to read the @seclink["emulab-transition"]{Emulab transition}
section that discusses differences between that interface and this new
CloudLab-based interface and how to convert your current Emulab experiments
for use via the new interface.

This chapter will walk you through a simple experiment on @(tb) and
introduce you to some of its @seclink["basic-concepts"]{basic concepts}.

Start by pointing your browser at @url[(apturl)].
20 21

@itemlist[#:style 'ordered
22 23
      @instructionstep["Enter your email address and pick a username"
24 25 26 27 28 29 30 31 32
                       #:screenshot "instantiate-empty.png"]{
          If you don't have an account, or are not logged in, you'll be using
          @(tb) as a @seclink["guest-users"]{guest user}. Guest users have some
          @seclink["guest-users"]{restrictions} placed on them, but this is a
          quick way to get started. Enter your email address and pick a
          username. This username will be the one you'll use to log into your
          nodes (eg. via @(ssh)), and if you @seclink["register"]{sign up} for
          an account on @(tb) later, it will become your @(tb) username as

34 35 36 37 38 39
          You may leave the @(ssh) key portion of the form blank---if you do,
          the only way to log into your nodes will be through a browser-based
          terminal that we provide. We recommend that if you use @(tb) heavily,
          you upload a public key, which will enable you to use a regular
          @(ssh) client.
40 41 42

43 44
      @instructionstep["Log in"
                       #:screenshot "log-in.png"]{
Robert Ricci's avatar
Robert Ricci committed
          You'll need an account to use @(tb). If you already have an
          account on @hyperlink[""]{}, you may
Robert Ricci's avatar
Robert Ricci committed
47 48 49 50 51
          use that username and password. Or, if you have an account at the
          @hyperlink[""]{GENI portal}, you may use the
          ``GENI User'' button to log in using that account.
          If not, you can apply to start a new
          project at @(url (apturl "signup.php")) and
          taking the "Start New Project" option. See the chapter about
          @seclink["users"]{@(tb) users} for more details about
54 55
          user accounts.

58 59 60 61 62 63 64 65 66 67
  @instructionstep["Start Experiment"]{
    From the top menu, click “Experiments” and then “Start Experiment” to begin.

  @instructionstep["Experiment Wizard"
                   #:screenshot "begin-experiment.png"]{
  Experiments must be configured before they can be instantiated.
  A short wizard guides you through the process.
  The first step is to pick a profile for your experiment. 
  A profile describes @seclink["rspecs"]{a set of
  resources} (both hardware and software) that will be used to start your
  experiment. On the hardware side, the profile will control whether you get
Robert Ricci's avatar
Robert Ricci committed
70 71 72
  @seclink["virtual-machines"]{virtual machines} or
  @seclink["physical-machines"]{physical ones}, how many there are, and what
  the network between them looks like. On the software side, the profile
73 74
  specifies the @seclink["disk-images"]{operating system and installed

  Profiles come from two sources. Some of them are provided by @(tb) itself, and
77 78 79 80 81 82
  provide standard installation of popular operating systems, software stacks,
  etc. Others are @seclink["creating-profiles"]{created by other researchers}
  and may contain research software, artifacts and data used to gather published
  results, etc. Profiles represent a powerful way to enable
  @seclink["repeatable-research"]{repeatable research}.

83 84 85 86 87 88 89 90 91 92 93
  Clicking the ``Change Profile'' button will let you select the
  @seclink["profiles"]{profile} that your @seclink["experiments"]{experiment}
  will be built from.

  @instructionstep["Select a profile"
                   #:screenshot "select-profile.png"]{

  On the left side is the profile selector which lists the profiles you can choose.
  The list contains both globally accessible profiles and profiles accessible to the projects you are part of.

94 95 96
  The large display in this dialog box shows the network topology of the
  profile, and a short description sits below the topology view.

  @apt-only{The @tt{OneVM} profile will get you a
        single VM running version 12.04 of the Ubuntu operating system---this
        is a good place to start.}
  @clab-only{The @tt{OpenStack} profile will give you
101 102 103
        a small OpenStack installation with one master node and one compute
        node. It provides a simple example of how complex software stacks can
        be packaged up within @(tb). If you'd prefer to start from bare metal,
Robert Ricci's avatar
Robert Ricci committed
        look for one of the profiles that installs a stock operating system on
        physical machines.}
Robert Ricci's avatar
Robert Ricci committed

108 109 110 111 112 113 114 115 116 117 118 119 120
  @instructionstep["Choose Parameters"
                   #:screenshot "choose-parameters.png"]{

    Some profiles are simple and provide the same topology every time they are instantiated.
    But others, like the OpenStack profile, are parameterized and allow users to make choices about how they are instantiated.
    The OpenStack profile allows you to pick the number of compute nodes, the hardware to use, and many more options.
    The creator of the profile chooses which options to allow and provides information on what those options mean.
    Just mouse over a blue ’?’ to see a description of an option.
    For now, stick with the default options and click “Next” to continue.

Robert Ricci's avatar
Robert Ricci committed
121 122 123 124 125 126 127 128 129 130
    @instructionstep["Pick a cluster"
                      #:screenshot "pick-datacenter.png"]{
      CloudLab can instantiate profiles on several different
      @seclink["hardware"]{backend clusters}. The cluster selector is located
      right above the ``Create'' button; the the cluster most suited to
      the profile you've chosen will be selected by default.

Robert Ricci's avatar
Robert Ricci committed
131 132
  @instructionstep["Click Create!"
                   #:screenshot "please-wait.png"]{
  When you click the ``Create'' button, @(tb) will start preparing your experiment
  by selecting nodes, installing software, etc. as described in the profile.
  What's going on behind the scenes is that on one (or more) of the machines
  in one of the @seclink["hardware"]{@(tb) clusters}, a disk is being imaged,
  VMs and/or physical machines booted, accounts created for you, etc.
Gary Wong's avatar
Gary Wong committed
  This process usually takes a couple of minutes.

  @apt-only{If you have never used this email address with @(tb) before (or if
141 142
      you switch computers or browsers), @(tb) will send a verification email.
      Watch your email and enter the code into @(tb) when prompted. (If it
      doesn't arrive in a few minutes, check your spam folder!)}
Robert Ricci's avatar
Robert Ricci committed
  @instructionstep["Use your experiment"]{
147 148 149
  When your experiment is ready to use, the progress bar will be complete, and
  you'll be given a lot of new options at the bottom of the screen.

150 151

  The ``Topology View'' shows the network topology of your experiment
153 154 155
  (which may be as simple as a single node). Clicking on a node in this
  view brings up a terminal in your browser that gives you a shell on the node.
  The ``List View'' lists all nodes in the topology, and in addition to 
  the in-browser shell, gives you the command to @(ssh) login to the node
  (if you provided a public key). The ``Manifest'' tab shows you the technical
158 159
  details of the resources allocated to your experiment. Any open terminals
  you have to the nodes show up as tabs on this page.
160 161 162 163 164

  Clicking on the ``Profile Instructions'' link (if present) will show
  instructions provided by the profile's creator regarding its use.

  Your experiment is yours alone, and you have full ``root'' access (via
  the @tt{sudo} command). No one else has access to the nodes in your
166 167
  experiment, and you may do anything at all inside of it, up to and including
  making radical changes to the operating system itself. We'll clean it all
  up when you're done!

170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186
    If you used our default OpenStack profile, the instructions will contain a
    link to the OpenStack web interface. The instructions will also give you
    a username and password to use.


    Since you gave @(tb) an @tt{ssh} public key as part of account creation,
    you can log in using the @tt{ssh} client on your laptop or desktop. The
    contoller node is a good place to start, since you can poke around with the
    OpenStack admin commands. Go to the "list view" on the experiment page to
    get a full command line for the @tt{ssh} command.



187 188 189 190
  Your experiment will @bold{terminate automatically after a few
  hours.} When the experiment terminates, you will @bold{lose anything on
  disk} on the nodes, so be sure to copy off anything important early and
  often.  You can use the ``Extend'' button to submit a request to hold it
Robert Ricci's avatar
Robert Ricci committed
  longer, or the ``Terminate'' button to end it early.
192 193 194
  @apt-only{@seclink["registered-users"]{Registered users} get to hold their
      experiments for longer, so if you want to use @(tb) for much serious
      work, we recommend @seclink["register"]{registering for an account}.}
195 196
197 198 199 200

@section{Next Steps}

  @apt-only{@item{If you find @(tb) useful, @seclink["register"]{sign up} for
      an @seclink["users"]{account}---having one gives you access to more
203 204 205 206
      resources and lets you run longer experiments.}}

  @clab-only{@item{Try a profile that runs bare metal and set up a cloud stack
207 208 209 210

  @item{Making your own profiles is easy: see the
  @seclink["creating-profiles"]{chapter on profile creation} for instructions.}

211 212 213 214
  @elab-only{@item{If you want to run an existing Emulab experiment: see the
      @seclink["emulab-transition"]{chapter on transitioning from the Emulab Classic
      interface} for instructions.}}

  @item{If you need help, or have questions or comments about @(tb)'s features,
216 217
  @seclink["getting-help"]{contact us}!}