getting-started.scrbl 7.07 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

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)].
11 12

@itemlist[#:style 'ordered
14 15 16 17 18 19 20 21 22 23
      #:apt @instructionstep["Enter your email address and pick a username"
                       #: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

25 26 27 28 29 30 31
          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.
      #:clab @instructionstep["Log in"]{
33 34 35 36 37 38 39 40 41
          You'll need an account to use CloudLab. If you already have an
          account on @hyperlink[""]{}, you may
          use that username and password. 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["cloudlab-users"]{CloudLab users} for more details about
          user accounts.

Robert Ricci's avatar
Robert Ricci committed
43 44
  @instructionstep["Select a profile"
                   #:screenshot "select-profile.png"]{
45 46 47 48
  Clicking the ``Change Profile'' button will let you select the
  @seclink["profiles"]{profile} that your @seclink["experiments"]{experiment}
  will be built from. 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
50 51 52
  @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
53 54
  specifies the @seclink["disk-images"]{operating system and installed

  Profiles come from two sources. Some of them are provided by @(tb) itself, and
57 58 59 60 61 62 63 64 65
  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}.

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

66 67 68 69 70 71 72 73 74 75
    #:apt "The @tt{OneVM} profile that we've selected here will get you a
        single VM running version 12.04 of the Ubuntu operating system---this
        is a good place to start."
    #:clab "The @tt{OpenStack} profile that we've selected here will give you
        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,
        look for one of the profiles that installs a stock operating sytem on
        physical machines."]
Robert Ricci's avatar
Robert Ricci committed

Robert Ricci's avatar
Robert Ricci committed
78 79
  @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,
84 85 86 87 88 89 90 91
  a @apt-vs-clab[#:apt "VM created and booted" #:clab "set of physical machines
  booted"], accounts created for you, etc.  This process usually takes a couple
  of minutes.

  @apt-only["If you have never used this email address with @(tb) before (or if
      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
92 93 94
  @instructionstep["Use your experiment"
                   #:screenshot "node-list.png"]{
95 96 97
  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.

  The ``Topology View'' shows the network topology of your experiment
99 100 101
  (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
104 105
  details of the resources allocated to your experiment. Any open terminals
  you have to the nodes show up as tabs on this page.
106 107 108 109 110

  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
112 113
  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!
115 116 117 118 119

  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.
  @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}.
124 125
126 127 128 129

@section{Next Steps}

130 131 132 133 134 135
  @;{@apt-only[@item{If you find @(tb) useful, @seclink["register"]{sign up} for
      an @seclink["users"]{account}---having one gives you access to more
      resources and lets you run longer experiments.}]

  @clab-only[@item{Read the @seclink["preview-notes"]{notes on the preview
    version of @(tb)}}]}
136 137 138 139

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

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