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

@(require "defs.rkt")

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

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

10
Start by pointing your browser at @url[(apturl)].
11 12

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

25 26 27 28 29 30
          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.
      }
31 32 33
  }

  @clab-only{
34 35
      @instructionstep["Log in"
                       #:screenshot "log-in.png"]{
Robert Ricci's avatar
Robert Ricci committed
36
          You'll need an account to use @(tb). If you already have an
37
          account on @hyperlink["http://www.emulab.net"]{Emulab.net}, you may
Robert Ricci's avatar
Robert Ricci committed
38 39 40 41 42
          use that username and password. Or, if you have an account at the
          @hyperlink["http://portal.geni.net"]{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
43
          taking the "Start New Project" option. See the chapter about
44
          @seclink["users"]{@(tb) users} for more details about
45 46
          user accounts.
      }
47
  }
48

Robert Ricci's avatar
Robert Ricci committed
49 50
  @instructionstep["Select a profile"
                   #:screenshot "select-profile.png"]{
51 52 53 54
  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
55
  experiment. On the hardware side, the profile will control whether you get
Robert Ricci's avatar
Robert Ricci committed
56 57 58
  @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
59 60
  specifies the @seclink["disk-images"]{operating system and installed
  software}.
61

62
  Profiles come from two sources. Some of them are provided by @(tb) itself, and
63 64 65 66 67 68 69 70 71
  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.

72
  @apt-only{The @tt{OneVM} profile that we've selected here will get you a
73
        single VM running version 12.04 of the Ubuntu operating system---this
74 75
        is a good place to start.}
  @clab-only{The @tt{OpenStack} profile that we've selected here will give you
76 77 78
        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
79
        look for one of the profiles that installs a stock operating system on
80
        physical machines.}
Robert Ricci's avatar
Robert Ricci committed
81
  }
82

Robert Ricci's avatar
Robert Ricci committed
83 84 85 86 87 88 89 90 91 92
  @clab-only{
    @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
93 94
  @instructionstep["Click Create!"
                   #:screenshot "please-wait.png"]{
95
  When you click the ``Create'' button, @(tb) will start preparing your experiment
96
  by selecting nodes, installing software, etc. as described in the profile.
97
  What's going on behind the scenes is that on one (or more) of the machines
98
  in one of the @seclink["hardware"]{@(tb) clusters}, a disk is being imaged,
99
  a @apt-vs-clab[#:apt "VM created and booted" #:clab "set of physical machines
Gary Wong's avatar
Gary Wong committed
100 101
  booted" #:pnet "VM created and booted"], accounts created for you, etc.
  This process usually takes a couple of minutes.
102

103
  @apt-only{If you have never used this email address with @(tb) before (or if
104 105
      you switch computers or browsers), @(tb) will send a verification email.
      Watch your email and enter the code into @(tb) when prompted. (If it
106
      doesn't arrive in a few minutes, check your spam folder!)"}
Robert Ricci's avatar
Robert Ricci committed
107
  }
108
  @instructionstep["Use your experiment"]{
109 110 111
  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.

112 113
  @screenshot["node-list.png"]

114
  The ``Topology View'' shows the network topology of your experiment
115 116 117
  (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 
118
  the in-browser shell, gives you the command to @(ssh) login to the node
119
  (if you provided a public key). The ``Manifest'' tab shows you the technical
120 121
  details of the resources allocated to your experiment. Any open terminals
  you have to the nodes show up as tabs on this page.
122 123 124 125 126

  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
127
  the @tt{sudo} command). No one else has access to the nodes in your
128 129
  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
130
  up when you're done!
131

132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
  @clab-only{
    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.

    @screenshot["openstack-admin.png"]

    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.

    @screenshot["openstack-shell.png"]

  }

149 150 151 152
  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
153
  longer, or the ``Terminate'' button to end it early.
154 155 156
  @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}.}
157 158
  }
]
159 160 161 162

@section{Next Steps}

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

167 168
  @clab-only{@item{Read the @seclink["status-notes"]{notes on the status of
    @(tb)}}}
169

170 171
  @clab-only{@item{Try a profile that runs bare metal and set up a cloud stack
    yourself}}
172 173 174 175

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

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