Emulab-specific sections.

"-transition" is Emulab only.
"-hardware" I made a separate file rather than trying to work out all the
racket-specific "#ifdef" mechanisms to make it work in the main hardware file.

emulab-hardware.scrbl

+#lang scribble/manual
+@(require "defs.rkt")
+
+@title[#:tag "hardware" #:version apt-version]{Hardware}
+
+@section[#:tag "emulab-mothership"]{Emulab Cluster}
+
+The Emulab cluster at the University of Utah contains almost 500 servers across
+four CPU generations with a total of more than 3,800 cores.
+
+@; XXX don't use apturl right now
+More technical details can be found at
+@url["https://www.emulab.net/hardware.php"].
+
+@(nodetype "d430" 160 "Haswell, 16 core, 3 disks"
+    (list "CPU" "Two Intel E5-2630v3 8-Core CPUs at 2.4 GHz (Haswell)")
+    (list "RAM"  "64GB ECC Memory (8x 8 GB DDR4 2133MT/s)")
+    (list "Disk" "One 200 GB 6G SATA SSD")
+    (list "Disk" "Two 1 TB 7.2K RPM 6G SATA HDDs")
+    (list "NIC"  "Two or four Intel I350 1GbE NICs")
+    (list "NIC"  "Two or four Intel X710 10GbE NICs"))
+
+@(nodetype "d820" 16 "Sandy Bridge, 32 core, 7 disks"
+    (list "CPU" "Four Intel E5-4620 8-Core CPUs at 2.2 GHz (Sandy Bridge)")
+    (list "RAM"  "128GB ECC Memory (8x 16 GB DDR3 1333MHz)")
+    (list "Disk" "One 250 GB 7.2K RPM 3G SATA HDD")
+    (list "Disk" "Six 600 GB 10K RPM 3G SAS HDDs")
+    (list "NIC"  "Four Intel X520 10GbE NICs"))
+
+@(nodetype "d710" 160 "Nehalem, 4 core, 2 disks"
+    (list "CPU" "One Intel Xeon E5530 4-Core CPU at 2.4 GHz (Nehalem)")
+    (list "RAM"  "12GB ECC Memory (6x 2 GB DDR2 1066MHz)")
+    (list "Disk" "One 500 GB 7.2K RPM SATA HDD")
+    (list "Disk" "One 250 GB 7.2K RPM SATA HDD")
+    (list "NIC"  "Four Broadcom BCM5709 1GbE NICs"))
+
+@(nodetype "pc3000" 160 "Nocona, 1 core, 2 disks"
+    (list "CPU" "One Intel Xeon single-core CPU at 3.0 GHz (Nocona)")
+    (list "RAM"  "2GB ECC Memory (2x 1 GB DDR2 400MHz)")
+    (list "Disk" "Two 146 GB 10K RPM SCSI HDD")
+    (list "NIC"  "1-4 Intel 1GbE NICs")
+    (list "NIC"  "1-4 Intel 10/100 NICs"))
+
+All nodes are connected to two networks:
+
+@itemlist[
+    @item{A 100Mb and 1 Gb @italic{Ethernet} @bold{``control network''}---this network
+        is used for remote access, experiment management, etc., and is
+        connected to the public Internet. When you log in to nodes in your
+        experiment using @code{ssh}, this is the network you are using.
+        @italic{You should not use this network as part of the experiments you
+        run in Apt.}
+    }
+
+    @item{A 10/100Mb, 1/10Gb Ethernet
+        @bold{``experiment network''}--each node has at least four
+        interfaces on this network.  This network is implemented using multiple
+	Cisco, HP, Arista, and Dell (Force10) switches.
+     }
+]

emulab-transition.scrbl

+#lang scribble/manual
+@(require "defs.rkt")
+
+@title[#:tag "emulab-transition" #:version apt-version]{Transitioning from the ``Classic'' Interface to the ``Portal''}
+
+@(under-construction)
+
+The new Emulab portal interface is a custom version of the
+@hyperlink["http://cloudlab.us"]{CloudLab} interface and as such,
+much of the documentation about, and experiences with, that
+interface apply to the Emulab portal.
+It currently supports the most commonly used features of the classic
+interface, with more features ported on demand.
+The classic interface should be considered deprecated, with no new
+features being added. It will continue to be supported until all important
+features have been moved to the portal interface.
+
+The remainder of this section covers
+@seclink["emulab-cloudlab-term"]{differences in terminology}
+between CloudLab and Emulab that are essential to understanding the
+new interface,
+@seclink["emulab-cloudlab-features"]{new feaures}
+that the portal interface offers over the classic interface,
+@seclink["emulab-missing-features"]{features currently missing}
+from the portal interface, and how to
+@seclink["emulab-conversion"]{convert an existing experiment}
+into a portal experiment.
+
+@section[#:tag "emulab-cloudlab-term"]{New or Changed Concepts in the Portal Interface}
+
+One of the biggest differences between the classic interface and the portal
+interface is that experiment descriptions are now known as
+@seclink["profiles"]{profiles} and the term
+@seclink["experiments"]{experiment} is used to refer to a running instance of
+a profile. Think of a @italic{profile} as a ``swapped out'' classic experiment
+and an @italic{experiment} (or @italic{instance}) as a ``swapped in'' classic
+experiment. Here is the complete list of equivalent actions:
+
+@(tabular #:style 'boxed #:sep (hspace 3) (list
+    (list @bold{Classic interface action} @bold{Equivalent portal action(s)})
+    (list "Create a running experiment" "Create a profile, instantiate the profile")
+    (list "Terminate a running experiment" "Destroy an instance, destroy the profile")
+    (list "Create a swapped-out experiment (``Do Not Swap In'' box checked)" "Create a profile")
+    (list "Swapin an experiment" "Instantiate a profile")
+    (list "Swapout an experiment" "Terminate an instance")
+    (list "Terminate a swapped-out experiment" "Destroy a profile")))
+
+At profile creation time you can select one of two settings for who is
+allowed to instantiate them.
+The default is ``project-only,'' meaning they can only be instantiated by
+members of the containing project (same as for classic experiments).
+You can also select ``Anyone'' to make a profile global, allowing any
+experimenter in any project to instantiate it.
+
+The representation of experiment descriptions has also changed.
+In the classic interface, experiments are described using @tt{ns-2},
+a network simulator scripting language based on @tt{TCL}.
+The portal represents experiments at the base level as GENI
+@seclink["rspecs"]{RSpecs} with the Python-based
+@seclink["geni-lib"]{geni-lib}
+library available for scripting experiments.
+As described in the @seclink["emulab-conversion"]{conversion} section
+below, the portal can automatically convert ns-2 experiment descriptions
+into geni-lib descriptions.
+
+Custom disk images are now created by taking a @italic{snapshot} of an
+experiment node or @italic{cloning} an existing experiment to create
+a new profile.
+The disk image format has not changed, but the way in which images are
+named in an experiment description is different. Instead of using
+@italic{pid}/@italic{imagename} as you would in a classic NS file,
+you would use 
+urn:publicid:IDN+emulab.net+image+@italic{pid}//@italic{imagename}.
+For example, you would use:
+@tt{urn:publicid:IDN+emulab.net+image+emulab-ops//FBSD103-64-STD}
+in a profile where you would use:
+@tt{emulab-ops/FBSD103-64-STD}
+in an NS file.
+See the section on @seclink["disk-images"]{disk images} for more information.
+
+Both profiles and disk images are now versioned.
+(Images are actually versioned in the classic interface as well,
+we just don't advertise it.)
+Whenever you make a change to a profile,
+you create a new version of that profile.
+Whenever you take a snapshot of a node running a custom image,
+you create a new version of that image.
+When using a profile or image and no explicit version is specified,
+you get the most recent version.
+You can delete old versions of images and profiles (subject to some
+constraints).
+Deleting the current version effectively ``rolls back''
+the default version of a profile or image.
+
+The portal interface has a more rigorous procedure for @italic{extending}
+an experiment.
+In the classic interface you can extend a running experiment by modifying
+the ``Max Duration'' setting within a small range (0 - 120 hours).
+Longer extensions require an email exchange with the admins.
+In the portal interface, you request an extension via the web interface
+with shorter extensions being approved automatically.
+Furthermore, extensions work within the framework of the reservation system
+and thus might be constrained by future reservations.
+See the sections on @seclink["extending"]{extending experiments}
+and @seclink["reservations"]{reservations}
+for more information.
+
+@section[#:tag "emulab-cloudlab-features"]{Portal Interfaces Features}
+
+Besides a much updated look and feel, the new inteface offers significant
+new features:
+
+@itemlist[
+@item{
+    A supported web-based GUI for creating experiment descriptions.
+}
+@item{
+    Scripted experiment description creation via Python rather than TCL.
+}
+@item{
+    Profiles can be associated with @tt{git} repositories.
+}
+@item{
+    Experiment parameters and metadata.
+}
+@item{
+    Web-based interaction with nodes (console and ssh).
+}
+@item{
+    Reservation of resources at a future date.
+}
+]
+
+@section[#:tag "emulab-missing-features"]{Classic Features Not Currently Supported in the Portal}
+
+A number of less frequently used features of Emulab and not supported via
+the portal interface:
+
+@itemlist[
+@item{Events.}
+@item{Traffic Generation.}
+@item{Control Network Firewalls.}
+@item{Subgroups within Projects.}
+@item{Batch Experiments.}
+]
+
+@section[#:tag "emulab-conversion"]{Converting an Emulab experiment to a Profile}
+
+Note: if you have no classic Emulab experiments (swapped in or swapped out)
+then you can skip this section. The following assumes you have an existing
+experiment created via the classic interface.
+
+When you login to the new portal interface at @url[(apturl)], you will be
+taken to your @italic{dashboard} on which there are a number of tabs.
+If you have any swapped in experiments you will start on the ``Experiments''
+tab, otherwise you will be on the ``Profiles'' tab.
+In either case you will be presented with a list of ``Classic Emulab
+Experiments.''
+On the right hand side of the Name column, there will be an arrow icon:
+
+@centered{@bold{Screenshot goes here.}}
+
+Clicking on this icon will start the conversion process for that experiment.
+The process will take anywhere from seconds to a minute or more depending
+on the complexity of the experiment description.
+@margin-note{
+    The experiment description will be converted from NS to both a
+    geni-lib script and a GENI RSpec, See @seclink["geni-lib"]{this section}
+    for further details.
+}
+After conversion, you will see:
+
+@centered{@bold{Screenshot goes here.}}
+
+Typically, all you would do at this point is to click ``Create.''
+You may want or need to change the profile name if you don't like the default
+(same as the classic experiment name) or if the creation fails because
+the name is already taken.
+
+You may also want to examine, or even modify, the new profile prior to
+actually creating it. Use either the ``Edit Code'' or ``Edit Topology''
+buttons for this. The former allows you to modify the python/geni-lib script
+representation, the latter fires up the embedded @seclink["jacks"]{Jacks} GUI.
+  
+Once created, you will be taken to a new page:
+
+@centered{@bold{Screenshot goes here.}}
+
+showing details about the new profile (on the left) and allowing you
+to further edit the profile, copy or delete it.
+
+On the bottom right is a button to ``Instantiate'' the profile---the
+equivalent of ``swapping in'' an experiment in the classic interface.
+This takes you to the third and final step of the instantiation wizard:
+
+@centered{@bold{Screenshot goes here.}}
+
+where you can optionally name this instance and then click ``Finish.''
+Once instantiated the state should change to ``ready'' and you will be
+off and running!
+
+Click ``Terminate'' and confirm when you are done.
+
+