advanced-topics.scrbl 4.65 KB
Newer Older
1 2 3 4
#lang scribble/manual

@(require "defs.rkt")

5 6

@title[#:tag "advanced-topics" #:version apt-version]{Advanced Topics}

Robert Ricci's avatar
Robert Ricci committed
@section[#:tag "disk-images"]{Disk Images}

11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57
Disk images in @(tb) are stored and distributed in the
@hyperlink[""]{Frisbee} disk
image format. They are stored at block level, meaning that, in theory,
any filesystem can be used. In practice, Frisbee's filesystem-aware
compression is used, which causes the image snapshotting and installation
processes to parse the filesystem and skip free blocks; this provides large
performance benefits and space savings. Frisbee has support for filesystems
that are variants of the BSD UFS/FFS, Linux ext, and Windows NTFS formats. The
disk images created by Frisbee are bit-for-bit identical with the original
image, with the caveat that free blocks are skipped and may contain leftover
data from previous users.

Disk images in @(tb) are typically created by starting with one of @(tb)'s
supplied images, customizing the contents, and taking a snapshot of the
resulting disk. The snapshotting process reboots the node, as it boots into an
MFS to ensure a quiesent disk. If you wish to bring in an image from outside
of @(tb) or create a new one from scratch, please
@seclink["getting-help"]{contact us} for help; if this is a common request, we
may add features to make it easier.

@(tb) has default disk image for each node type; after a node is freed by
one experimenter, it is re-loaded with the default image before being released
back into the free pool. As a result, profiles that use the default disk
images typically insantiate faster than those that use custom images, as no
disk loading occurs.

Frisbee loads disk images using a custom multicast protocol, so loading large
numbers of nodes typcially does not slow down the instantiation process

Images may be referred to in requests in three ways: by URN, by an unqualified
name, and by URL. URNs refer to a specific image that may be hosted on any of
the @seclink["hardware"]{@(tb)-affilated clusters}. An unqualified name refers
to the version of the image hosted on the cluster on which the experiment is
instantiated. If you have large images that @(tb) cannot store due to space
constraints, you may host them yourself on a webserver and put the URL for
the image into the profile. @(tb) will fetch your image on demand, and cache
it for some period of time for efficient distribution.

Images in @(tb) are versioned, and @(tb) records the provenance of images.
That is, when you create an image by snapshotting a disk that was previosuly
loaded with another image, @(tb) records which image was used as a base for
the new image, and stores only the blocks that differ between the two. Image
URLs and URNs can contain version numbers, in which case they refer to that
specific version of the image, or they may omit the version number, in which
case they refer to the latest version of the image at the time an experiment
is instantiated.

Robert Ricci's avatar
Robert Ricci committed
@section[#:tag "rspecs"]{RSpecs}

61 62 63 64 65 66 67 68
The resources (nodes, links, etc.) that define a profile are expressed in the
format from the GENI project. In general, RSpec should be thought of as a
sort of ``assembly language''---something it's best not to edit yourself, but
as manipulate with other tools or create as a ``compiled'' target from a
higher-level language.

That said, the tools for manipulating RSpecs are still incomplete. (For a
preview of @(tb)'s plans in this regard, see our section on
70 71 72 73 74
@seclink["planned-easier-profiles"]{planned profile creation features}.) So,
there are still some cases in which it is unfortunately useful to look at or
manipulate RSpecs directly.

@italic{Still to come: documentation of @(tb)'s extensions to the RSpec format.}

77 78

Robert Ricci's avatar
Robert Ricci committed
79 80
@section[#:tag "public-ip-access"]{Public IP Access}

81 82

Robert Ricci's avatar
Robert Ricci committed
83 84
@section[#:tag "markdown"]{Markdown}

@(tb) supports
Robert Ricci's avatar
Robert Ricci committed
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101
in the major text fields in @seclink["rspecs"]{RSpecs}. Markdown is a simple
formatting syntax with a straighforward translation to basic HTML elements
such as headers, lists, and pre-formatted text. You may find this useful in 
the description and instructions attached to your profile.

While editing a profile, you can preview the Markdown rendering of the
Instructions or Description field by double-clicking within the text


You will probably find the
@hyperlink[""]{Markdown manual} to
be useful.

Robert Ricci's avatar
Robert Ricci committed
@section[#:tag "tours"]{Tours}
103 104

@italic{This feature under development}