Commit fd63e396 authored by Robert Ricci's avatar Robert Ricci

Clean up references

Make all #:tags somewhat consistent

Always use @seclink instead of @secref. The latter is neat, but it's
just too hard to keep track of what the titles are.

Make all @seclinks resolve (in some cases creating stub sections)
parent 982d9d6a
......@@ -6,8 +6,12 @@
@title[#:tag "advanced-topics" #:version apt-version]{Advanced Topics}
@section[#:tag "images"]{Disk Images}
@section[#:tag "disk-images"]{Disk Images}
@section[#:tag "rspec"]{RSpecs}
@section[#:tag "rspecs"]{RSpecs}
@section[#:tag ""]{Public IP Access}
@section[#:tag "public-ip-access"]{Public IP Access}
@section[#:tag "markdown"]{Markdown}
@section[#:tag "tours"]{Tours}
......@@ -15,17 +15,17 @@ Apt is a platform for sharing research; it is open to all researchers,
educators, and students. It is built around @seclink["profiles"]{profiles},
which describe @seclink["experiments"]{experiments}; when you instantiate a
profile, that specification is realized on one of @seclink["hardware"]{Apt's
clusters} using @seclink["vms"]{virtual} or @seclink["phys"]{physical}
machines. The creator of a profile may put code, data, and other resources into
it, and the profile may consist of a single machine or may describe an entire
network.
clusters} using @seclink["virtual-machines"]{virtual} or
@seclink["physical-machines"]{physical} machines. The creator of a profile may
put code, data, and other resources into it, and the profile may consist of a
single machine or may describe an entire network.
Basic access to public profiles on Apt is provided
@seclink["guest-users"]{without the need to register} for an account---this
keeps the barriers to accessing research artifacts low. If you find the limited
resources that are provided to guest users valuable, you should
@seclink["singup"]{sign up for a (free) account} to get access to more resources
and to @seclink["create-profiles"]{create profiles of your own}.
@seclink["register"]{sign up for a (free) account} to get access to more
resources and to @seclink["creating-profiles"]{create profiles of your own}.
Setting up the @bold{software} environment to run research artifacts is often
complicated, potentially requiring a specific version of an operating system,
......@@ -57,3 +57,4 @@ of Utah.
@include-section["creating-profiles.scrbl"]
@include-section["hardware.scrbl"]
@include-section["planned.scrbl"]
@include-section["getting-help.scrbl"]
......@@ -11,32 +11,34 @@ It consists of two main parts: a description of the resources (hardware,
storage, network, etc.) needed to run the experiment, and the software
artifacts that run on those resources.
The resource specification is in the @seclink["rspec"]{RSpec} format. The RSpec
describes an entire @italic{topology}: this includes the nodes (hosts) that the
software will run on, the storage that they are attached to, and the network
that connects them. The nodes may be @seclink["vm"]{virtual machines} or
@seclink["phys"]{physical servers}. The RSpec can specify the properties of
these nodes, such as how much RAM they should have, how many cores, etc., or
can directly reference a specific @seclink["hardware"]{class of hardware}
available in one of Apt's clusters. The network topology can include point to
point links, LANs, etc. can may be either built from Ethernet or Infiniband.
The resource specification is in the @seclink["rspecs"]{RSpec} format. The
RSpec describes an entire @italic{topology}: this includes the nodes (hosts)
that the software will run on, the storage that they are attached to, and the
network that connects them. The nodes may be
@seclink["virtual-machines"]{virtual machines} or
@seclink["physical-machines"]{physical servers}. The RSpec can specify the
properties of these nodes, such as how much RAM they should have, how many
cores, etc., or can directly reference a specific @seclink["hardware"]{class of
hardware} available in one of Apt's clusters. The network topology can include
point to point links, LANs, etc. can may be either built from Ethernet or
Infiniband.
The primary way that software is associated with a profile are through
@seclink["images"]{disk images}. A disk image (often just called an ``image'')
is a block-level snapshot of the contents of a real or virtual disk---and it
can be loaded onto either. A disk image in Apt typically has an installation of
a full operating system on it, plus additional packages, research software,
data files, etc. that comprise the software environment of the profile. Each
node in the RSpec is associated with a disk image, which it boots from; more
than one node in a given profile may reference the same disk image, and more
than one profile may use the same disk image as well.
@seclink["disk-images"]{disk images}. A disk image (often just called an
``image'') is a block-level snapshot of the contents of a real or virtual
disk---and it can be loaded onto either. A disk image in Apt typically has an
installation of a full operating system on it, plus additional packages,
research software, data files, etc. that comprise the software environment of
the profile. Each node in the RSpec is associated with a disk image, which it
boots from; more than one node in a given profile may reference the same disk
image, and more than one profile may use the same disk image as well.
Profiles come from two sources: some are provided by Apt itself; these tend
to be (fairly) standard installation of popular operating systems and software
stacks. Profiles may also be provided by Apt's users, as a way for communities
to share research artifacts.
@subsection[#:tag "on-demand"]{On-demand Profiles}
@subsection[#:tag "on-demand-profiles"]{On-demand Profiles}
Most profiles in Apt are @italic{on-demand profiles}, which means that they are
designed to be instantiated for a relatively short period of time (hours or
......@@ -44,7 +46,7 @@ days). Each person instantiating the profile gets their own
@seclink["experiments"]{experiment}, so everyone using the profile is doing it
independently on their own set of resources.
@subsection[#:tag "persistent"]{Persistent Profiles}
@subsection[#:tag "persistent-profiles"]{Persistent Profiles}
Apt also supports @italic{persistent} profiles, which are longer-lived (weeks
or months) and are set up to be shared by multiple users. A persistent profile
......@@ -70,25 +72,26 @@ users intact with it. Or, a cloud-style profile might directly offer its own
web interface to provisioning virtual machines.
For the time being, allocations for persistent profiles on Apt are handled
by directly @seclink["contact"]{contacting the Apt staff}.
by directly @seclink["getting-help"]{contacting the Apt staff}.
@section[#:tag "experiments"]{Experiments}
@margin-note{See our chapter on @seclink["repeatability"]{repeatability} for
more information on repeatable experimentation in Apt.}
An @italic{experiment} is an instantiation of a @seclink["profile"]{profile}.
An experiment uses resources, @seclink["vms"]{virtual} or
@seclink["phys"]{physical}, on one or more of the @seclink["hardware"]{clusters}
that Apt has access to. In most cases, the resources used by an experiment are
devoted to the individual use of the user who instantiates the experiment. This
means that no one else has an account, access to the filesystems, etc. In the
case of experiments using solely @seclink["physical"] physical machines, this
means strong performance isolation from all other Apt users. In the case of
@seclink["vms"]{virtual machines}, there is still isolation from a security and
accounting standpoint, but weaker performance isolation. (The exceptions to
this rule are @seclink["persistent"]{persistent profiles}, which may offer
resources to .)
@margin-note{See the chapter on @seclink["repeatable-research"]{repeatability}
for more information on repeatable experimentation in Apt.}
An @italic{experiment} is an instantiation of a @seclink["profiles"]{profile}.
An experiment uses resources, @seclink["virtual-machines"]{virtual} or
@seclink["physical-machines"]{physical}, on one or more of the
@seclink["hardware"]{clusters} that Apt has access to. In most cases, the
resources used by an experiment are devoted to the individual use of the user
who instantiates the experiment. This means that no one else has an account,
access to the filesystems, etc. In the case of experiments using solely
@seclink["physical-machines"]{physical machines}, this means strong performance
isolation from all other Apt users. In the case of
@seclink["virtual-machines"]{virtual machines}, there is still isolation from a
security and accounting standpoint, but weaker performance isolation. (The
exceptions to this rule are @seclink["persistent-profiles"]{persistent
profiles}, which may offer resources to .)
Running experiments on Apt consume @bold{real resources}, which are
@bold{limited}. We ask that you be careful about not holding on to experiments
......@@ -96,7 +99,7 @@ when you are not actively using them. If you are are holding on to experiments
because getting your working environment set up takes time, consider
@seclink["creating-profiles"]{creating a profile}.
@future-work["persistent-storage"]
@future-work["planned-persistent-storage"]
The contents of local disk on nodes in an experiment are considered
@italic{ephemeral}---that is, when the experiment ends (either by being
......@@ -104,13 +107,13 @@ explicitly terminated by the user or expiring), the contents of the disk are
lost. So, you should copy important data off before the experiment ends. A
simple way to do this is through @code{scp} or @code{sftp}. You may also
@seclink["creating-profiles"]{create a profile}, which captures the contents of
the disk in a @seclink["image"]{disk image}.
the disk in a @seclink["disk-images"]{disk image}.
All experiments have an @italic{expiration time}. By default, the expiration
time is short (a few hours), but users can use the ``Extend'' button on the
experiment page to request an extension. A request for an extension must
be accompanied by a short description that explains the reason for requesting
an extension, which will be reviewed by Apt staff. @seclink["guests"]{Guest
an extension, which will be reviewed by Apt staff. @seclink["guest-users"]{Guest
users} are not permitted to hold experiments for very long; if you are
using Apt as a guest, and find yourself running out of time frequently, we
recommend @seclink["register"]{registering for an account}. You will
......@@ -145,10 +148,10 @@ belong to. Currently, the only such permission is the ability to make a profile
visible onto to the owning project. We expect to introduce more
project-specific permissions features in the future.
@section[#:tag "vm"]{Virtual Machines}
@section[#:tag "virtual-machines"]{Virtual Machines}
@(under-construction)
@section[#:tag "phys"]{Physical Machines}
@section[#:tag "physical-machines"]{Physical Machines}
@(under-construction)
#lang scribble/manual
@(require "defs.rkt")
@title[#:tag "basic-concepts" #:version apt-version]{Basic Concepts}
@section[#:tag "profiles"]{Profiles}
A @italic{profile} encapsulates everything needed to run an @italic{experiment}.
It consists of two main parts: a description of the resources (hardware,
storage, network, etc.) needed to run the experiment, and the software
artifacts that run on those resources.
The resource specification is in the @seclink["rspec"]{RSpec} format. The RSpec
describes an entire @italic{topology}: this includes the nodes (hosts) that the
software will run on, the storage that they are attached to, and the network
that connects them. The nodes may be @seclink["vm"]{virutal machines} or
@seclink["phys"]{physical servers}. The RSpec can specify the properties of
these nodes, such as how much RAM they should have, how many cores, etc., or
can directly reference a specific @seclink["hardware"]{class of hardware}
availabe in one of Apt's clusters. The network topology can include point to
point links, LANs, etc. can may be either built from Ethernet or Infiniband.
The primary way that software is associated with a profile are through
@seclink["images"]{disk images}. A disk image (often just called an ``image'')
is a block-level snapshot of the contents of a real or virtual disk---and it
can be loaded onto either. A disk image in Apt typically has an installation of
a full operating system on it, plus additional packages, research software,
data files, etc. that comprise the software environment of the profile. Each
node in the RSpec is associated with a disk image, which it boots from; more
than one node in a given profile may reference the same disk image, and more
than one profile may use the same disk image as well.
Profiles come from two sources: some are provided by Apt itself; these tend
to be (fairly) standard installation of popular operating systems and software
stacks. Profiles may also be provided by Apt's users, as a way for communities
to share research artifacts.
@subsection[#:tag "on-demand"]{On-demand Profiles}
Most profiles in Apt are @italic{on-demand profiles}, which means that they are
designed to be instantiated for a relatively short period of time (hours or
days). Each person instantiating the profile gets their own
@seclink["experiments"]{experiment}, so everyone using the profile is doing it
independently on their own set of resources.
@subsection[#:tag "persistent"]{Persistent Profiles}
Apt also supports @italic{persistent} profiles, which are longer-lived (weeks
or months) and are set up to be shared by multiple users. A persistent profile
can be thought of as a ``testbed within a testbed''---a testbed facility built
on top of Apt's hardware and provisioning capabilities. Examples of persistent
profiles include:
@itemlist[
@item{A cluster set up with a specific software stack for a class}
@item{A persistent instance of a database or other resource used by a large
research community}
@item{Machines set up for a contest, giving all particpants access to the same
hardware}
@item{An instance of a cloud software stack, providing VMs to a large community}
@item{An HPC cluster temporarily brought up for the running of a particular
set of jobs}
]
A persistent profile may offer its own user interface, and its users may not
necessarily be aware that they are using Apt. For example, an HPC-style
persistent profile might run a standard cluster scheduler, and this is how
users intact with it. Or, a cloud-style profile might directly offer its own
web interface to provisioning virtual machines.
For the time being, allocations for persistent profiles on Apt are handled
by directly @seclink["contact"]{contacting the Apt staff}.
@section[#:tag "experiments"]{Experiments}
@margin-note{See our chapter on @seclink["repeatability"]{repeatability} for
more information on repeatable experimentation in Apt.}
An @italic{experiment} is an instantiation of a @seclink["profile"]{profile}.
An experiment uses resources, @seclink["vms"]{virtual} or
@seclink["phys"]{physical}, on one or more of the @seclink["hardware"]{clusters}
that Apt has access to. In most cases, the resources used by an experiment are
devoted to the individual use of the user who instanties the experiment. This
means that no one else has an account, access to the filesystems, etc. In the
case of experiments using solely @seclink["physical"] physical meachines, this
means strong performance isolation from all other Apt users. In the case of
@seclink["vms"]{virtual machines}, there is still isolation from a security and
accouting standpoint, but weaker performance isolation. (The exceptions to
this rule are @seclink["persistent"]{persistent profiles}, which may offer
resources to .)
Running experiments on Apt consume @bold{real resources}, which are
@bold{limited}. We ask that you be careful about not holding on to experiments
when you are not actively using them. If you are are holding on to experiments
because getting your working environment set up takes time, consider
@seclink["creating-profiles"]{creating a profile}.
@future-work["persistent-storage"]
The contents of local disk on nodes in an experiment are considered
@italic{ephemeral}---that is, when the eperiment ends (either by being
explicitly terminated by the user or expiring), the contents of the disk are
lost. So, you should copy important data off before the experiment ends. A
simple way to do this is through @code{scp} or @code{sftp}. You may also
@seclink["creating-profiles"]{create a profile}, which captures the contents of
the disk in a @seclink["image"]{disk image}.
All experiments have an @italic{expiration time}. By default, the expiration
time is short (a few hours), but users can use the ``Extend'' button on the
experiment page to request an extension. A request for an extension must
be accompanied by a short description that explains the reason for requesting
an extension, which will be reviewed by Apt staff. @seclink["guests"]{Guest
users} are not permitted to hold experiments for very long; if you are
using Apt as a guest, and find yourself running out of time frequently, we
recommend @seclink["register"]{registering for an account}. You will
receive email a few hours before your experiment expires reminding you to
copy your data off or request an extension.
@TODO{Section on SCP and SFTP}
@TODO{Different time periods for virtual and physical resources.}
@section[#:tag "projects"]{Projects}
Users are grouped into @italic{projects}. A project is, roughly speaking, a
group of people working together on a common research or educational goal. This
may be people in a particular resesearch lab, a distributed set of
collaborators, instructors and students in a class, etc.
A project is headed by a @italic{project leader}. We require that project
leaders be faculty, senior research staff, or others in an authoritative
position. This is because we trust the project leader to approve other members
into the project, ultimately making them responsible for the conduct of the
users they approve. If Apt staff have questions about a project's activities,
its use of resources, etc., these questions will be directed to the project
leader. Some project leaders run a lot of experiments themselves, while some
choose to approve accounts for others in the project, who run most of the
experiments. Either style works just fine in Apt.
@TODO{Create/join project using an existing account}
Permissions for some operations / objects depend on the project that they
belong to. Currently, the only such permission is the ability to make a profile
visible onto to the owning project. We expect to introduce more
project-specific permissions features in the future.
@section[#:tag "vm"]{Virtual Machines}
@(under-construction)
@section[#:tag "phys"]{Physical Machines}
@(under-construction)
......@@ -6,13 +6,14 @@
Using Apt, you can share your research artifacts with others by creating your
own profiles. When you create a new profile, you are creating a new
@secref["rspec"], and, usually, creating one or more @seclink["image"]{disk
images} that are referenced by that RSpec.
@seclink["rspecs"]{RSpec}, and, usually, creating one or more
@seclink["disk-images"]{disk images} that are referenced by that RSpec.
When someone uses your profile, they will get their own @secref["experiment"]
that boots up the resources (virtual or physical) described by the RSpec.
When someone uses your profile, they will get their own
@seclink["experiments"]{experiment} that boots up the resources (virtual or
physical) described by the RSpec.
@section{Creating a profile from an existing one}
@section[#:tag "creating-from-existing"]{Creating a profile from an existing one}
The easiest way to create a new profile is by cloning an existing one and
customizing it to your needs. The basic steps are:
......@@ -25,22 +26,22 @@ customizing it to your needs. The basic steps are:
@item{``Clone'' the experiment to create a new profile}
]
@subsection{Preparation and precautions}
@subsection[#:tag "profile-creation-preparation"]{Preparation and precautions}
To create profiles, you need to be a @seclink["register"]{registered user}.
Creating a profile can take a while, so we recommend that you
@seclink["extend"]{extend your experiment} while creating it, and contact us
if you are worried your experiment might expire before you're done creating
@seclink["experiments"]{extend your experiment} while creating it, and contact
us if you are worried your experiment might expire before you're done creating
your profile. We also strongly recommend testing your profile fully before
terminating the experiment you're creating it from.
If you want your profile to be usable by @seclink["guests"]{guest users}, keep
in mind that there are @seclink["guests"]{several restrictions} placed on them;
among these is the fact that they are not allowed to make outgoing connections,
meaning that the experiment must be self-contained. For example, they will not
be able to download software or datasets from within the experiment---it should
all be contained as part of the profile.
If you want your profile to be usable by @seclink["guest-users"]{guest users},
keep in mind that there are @seclink["guest-users"]{several restrictions}
placed on them; among these is the fact that they are not allowed to make
outgoing connections, meaning that the experiment must be self-contained. For
example, they will not be able to download software or datasets from within the
experiment---it should all be contained as part of the profile.
Your home directory is @bold{not} included in the disk image snapshot! You
will need to install your code and data elsewhere in the image. We recommend
......@@ -75,10 +76,10 @@ add support for multi-node profiles in the future.
will have a ``clone'' button. Clicking this button will create a new
profile based on your running experiment.
Specifically, the button creates a copy of the @secref{"rspec"} used
to create the experiment, passes it to the form used to create new
profiles, and helps you create a @seclink["image"]{disk image} from your
running experiment.
Specifically, the button creates a copy of the @seclink["rspecs"]{RSpec}
used to create the experiment, passes it to the form used to create new
profiles, and helps you create a @seclink["disk-images"]{disk image} from
your running experiment.
}
@instructionstep["Fill out information for the new profile"
......@@ -87,15 +88,15 @@ add support for multi-node profiles in the future.
allows you to view and edit the basic information associated with your
profile.
Each profile must be associated with a @secref["project"]. If you're
a member of more than one project, you'll need to select which one you
want the profile to belong to.
Each profile must be associated with a @seclink["projects"]{project}. If
you're a member of more than one project, you'll need to select which one
you want the profile to belong to.
Make sure to edit the profile's Description and Instructions.
The ``Description'' is the text that users will see when your profile is
listed in Apt, when the user is selecting which profile to use. It is also
displayed when @seclink["proflinks"]{following a direct link to your
displayed when @seclink["sharing-profiles"]{following a direct link to your
profile}. It should give the reader a brief description of what they will
get if they create an experiment with this profile. If the profile is
associated with a paper or other publication, this is a good place to
......@@ -107,7 +108,7 @@ add support for multi-node profiles in the future.
to tell them where the code and data can be found, what scripts they
might want to run, etc. Again, @seclink["markdown"]{Markdown} is allowed.
The ``Steps'' section allows you to create a @secref{"tour"} of your
The ``Steps'' section allows you to create a @seclink["tours"]{tour} of your
profile, which is displayed after a user creates an experiment with it.
This feature is mostly useful if your profile contains more than one
node, and you wish to explain to the user what the purpose of each node
......@@ -116,7 +117,7 @@ add support for multi-node profiles in the future.
You have the option of making your profile usable to anyone, only
registered Apt users, or members of your project. Regardless of the
setting you chose here, Apt will also give you a
@seclink["proflinks"]{direct link} that you can use to share your
@seclink["sharing-profiles"]{direct link} that you can use to share your
profile with others of your choosing.
}
......@@ -138,7 +139,7 @@ add support for multi-node profiles in the future.
also have to use an alternate email address.}
]
@subsection{Sharing a Profile}
@subsection[#:tag "sharing-profiles"]{Sharing Profiles}
@margin-note{We are working on a versioning system for profiles, so in the
future, you will be able to update the profile and still link to specific
......@@ -156,7 +157,7 @@ public, the URL will have the form @code[(apturl "p/<UUID>")], where
share this URLs with anyone you want to have access to the profile---for
example, to give it to a collaborator to try out your work before publishing.
@subsection{Updating a profile}
@subsection[#:tag "updating-profiles"]{Updating a profile}
You can update the metadata associated with a profile at any time by going to
the ``My Profiles'' page and clicking on the name of the profile to go to the
......@@ -175,13 +176,13 @@ get the disk changed the way you want, and click the button.
@screenshot["snapshot-button.png"]
This button kicks off the same image creation process that occurs during
@seclink["cloning"]{cloning a profile}. Once it's finished, any new experiments
created from the profile will use the new image.
@seclink["creating-from-existing"]{cloning a profile}. Once it's finished, any
new experiments created from the profile will use the new image.
As with creating a new profile, we recommend testing the profile before letting
your experiment expire. If something goes wrong, we do keep one previous image
file for each profile; currently, the only way to get access to this backup
is to @seclink["contact"]{contact us}.
is to @seclink["getting-help"]{contact us}.
@section{Creating a profile from scratch}
......
#lang scribble/manual
@(require "defs.rkt")
@title[#:tag "getting-help" #:version apt-version]{Getting Help}
The help forum is the main place to ask questions about Apt, its use, its
default profiles, etc. Users are strongly encouraged to participate in
answering other users' questions. The help forum is handled through Google
Groups, which, by default, sends all messages to the group to your email
address. You may change your settings to receive only digests, or to turn
email off completely.
The forum is searchable, and we recommend doing a search before asking a
question.
The URL for joining or searching the forum is: @url{https://groups.google.com/forum/#!forum/apt-users}
......@@ -30,9 +30,10 @@ Start by pointing your browser to @url[(apturl)].
that your experiment will be built from. A profile describes 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
@seclink["vm"]{virtual machines} or @seclink["phys"]{physical ones}, how many
there are, and what the network between them looks like. On the software
side, the profile specifies the operating system and the installed software.
@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
specifies the operating system and the installed software.
Profiles come from two sources. Some of them are provided by Apt itself, and
provide standard installation of popular operating systems, software stacks,
......
......@@ -8,7 +8,7 @@
Apt can allocate experiments on any one of several federated clusters.
@section[#:tag "aptcluster"]{Apt Cluster}
@section[#:tag "apt-cluster"]{Apt Cluster}
@margin-note{This cluster is in the process of being brought up.}
......@@ -68,7 +68,7 @@ All nodes are connected to three networks with @bold{one interface each}:
]
@section[#:tag "igddc"]{IG-DDC Cluster}
@section[#:tag "ig-ddc"]{IG-DDC Cluster}
@margin-note{This is the cluster that is currently used by default for all
experiments on Apt.}
......@@ -87,8 +87,9 @@ has nodes of only a single type:
It has two network fabrics:
@itemlist[
@item{A 1 Gbps @bold{``control network''}. As with the @secref{aptcluster},
this is used for remote access, and should not be used for experiments.}
@item{A 1 Gbps @bold{``control network''}. As with the
@seclink["apt-cluster"]{Apt cluster} this is used for remote access,
and should not be used for experiments.}
@item{A 1 Gbps @bold{``experiment network''}. Each node has @italic{three}
interfaces on this network, which is built from a single HP Procurve
5406 switch. OpenFlow is available on this network.}
......
......@@ -5,16 +5,17 @@
@title[#:tag "planned" #:version apt-version]{Planned Features}
This chapter describes features that are planned for Apt or under development:
please @secref["contact"] us if you have any feedback or suggestions!
please @seclink["getting-help"]{contact} us if you have any feedback or
suggestions!
@(under-construction)
@section{Versioned Profiles}
@section[#:tag "planned-versioned-profiles"]{Versioned Profiles}
@section{Persistent Block Storage}
@section[#:tag "planned-persistent-storage"]{Persistent Storage}
@section{Easier From-Scratch Profile Creation}
@section[#:tag "planned-easier-profiles"]{Easier From-Scratch Profile Creation}
@section{``Quick'' Profiles}
@section[#:tag "planned-quick-profiles"]{``Quick'' Profiles}
@section[#:tag "virt-switching"]{Simpler Virtual/Physical Profile Switching}
@section[#:tag "planned-virt-switching"]{Simpler Virtual/Physical Profile Switching}
......@@ -31,7 +31,7 @@ environment do the following:
other users of Apt.}
]
@future-work["virt-switching"]
@future-work["planned-virt-switching"]
Similarly, for those who are repeating or building on the work of others, we
recommend:
......@@ -44,9 +44,9 @@ recommend:
compare performance, etc.}
]
Because the @secref{images} that Apt provides boot on both virtual and physical
machines, in most cases, switching means simply modifying one's profile to
request the other type of resource.
Because the @seclink["disk-images"]{disk images} that Apt provides boot on both
virtual and physical machines, in most cases, switching means simply modifying
one's profile to request the other type of resource.
@TODO{This suggests we ought to make it easier at instantiation time to pick
VMs or bare metal.}
......@@ -40,7 +40,7 @@ Guest users are limited in several ways:
]
If you are going to use Apt for much serious work, we encourage you to
@secref{register}.
@seclink["register"]{register for an account}.
@section[#:tag "registered-users"]{Registered Users}
......@@ -58,8 +58,8 @@ are relatively senior positions.
@section[#:tag "register"]{Register for an Account}
To get an account on Apt, you either @seclink["joinproj"]{join an existing
project} or @seclink["newproj"]{create a new one}. In general, if you are
To get an account on Apt, you either @seclink["join-project"]{join an existing
project} or @seclink["create-project"]{create a new one}. In general, if you are
a student, you should join a project led by a faculty member with whom
you're working.
......@@ -68,7 +68,7 @@ If you already have an account on
up for a new account on Apt---simply log in with your Emulab username and
password.
@subsection[#:tag "joinproj"]{Join an existing project}
@subsection[#:tag "join-project"]{Join an existing project}
@TODO{Screen shot here}
......@@ -86,14 +86,14 @@ keypair into GitHub don't apply to Apt.)
You'll be asked to enter the project ID for the project you are asking to
join; you should get this from the leader of the project, likely your advisor
or your class instructor. (If they don't already have a project on Apt, you
can @seclink["newproj"]{ask them to create one}.) The leader of your project
is responsible for approving your account.
can @seclink["create-project"]{ask them to create one}.) The leader of your
project is responsible for approving your account.
@margin-note{Apt will send you email to confirm your address---watch for it (it
might end up in your spam folder), as your request won't be processed until
you've confirmed your address.}
@subsection[#:tag "newproj"]{Create a new project}
@subsection[#:tag "create-project"]{Create a new project}
@screenshot["create-project.png"]
......@@ -108,19 +108,19 @@ by our staff, so please provide enough information for us to understand the
research or educational value of your project. The review process may take
a few days, and you will receive mail informing you of the outcome.
Every person working in your project needs to have @seclink["joinproj"]{their
own account}. You get to approve these additional users yourself (you will
receive email when anyone applies to join.) It is common, for example, for a
faculty member to create a project which is primarily used by his or her
students, who are the ones who run experiments. We still require that the
project leader be the faculty member, as we require that there is someone in a
position of authority we can contact if there are questions about the
activities of the project.
Every person working in your project needs to have
@seclink["join-project"]{their own account}