Merge branch 'chef-tutorial' of...

Merge branch 'chef-tutorial' of https://gitlab.flux.utah.edu/emulab/testbed-manual into chef-tutorial

.gitignore

@@ -10,3 +10,4 @@ pdf/
 *.aux
 *.out
 *.png
+*~

GNUmakefile

@@ -44,7 +44,7 @@ pdf/emulab-manual.pdf: $(SOURCES)
 
 each: apt cloudlab phantomnet emulab
 
-.PHONY: apt cloudlab phantomnet emulab all each clean install-live install-cloudlab install-phantomnet install-emulab
+.PHONY: apt cloudlab phantomnet emulab all each clean install-live install-cloudlab install-phantomnet install-emulab install-all
 
 clean:
 	-rm -rf $(TOPLEVEL)/
@@ -59,18 +59,16 @@ clean:
 	-rm *.out
 	-rm *.png
 
-install-live: apt pdf/apt-manual.pdf
+install-all: install-live install-cloudlab install-phantomnet install-emulab
+
+install-live: apt
 	-rsync -v -az -e ssh --delete apt-manual/ $(INSTALL_LIVE)
-	scp pdf/apt-manual.pdf $(INSTALL_LIVE)/manual.pdf
 
-install-cloudlab: cloudlab pdf/cloudlab-manual.pdf
+install-cloudlab: cloudlab
 	-rsync -v -az -e ssh --delete cloudlab-manual/ $(INSTALL_CLAB)
-	scp pdf/cloudlab-manual.pdf $(INSTALL_CLAB)/manual.pdf
 
-install-phantomnet: phantomnet pdf/phantomnet-manual.pdf
+install-phantomnet: phantomnet
 	-rsync -v -az -e ssh --delete phantomnet-manual/ $(INSTALL_PNET)
-	scp pdf/phantomnet-manual.pdf $(INSTALL_PNET)/manual.pdf
 
-install-emulab: emulab pdf/emulab-manual.pdf
+install-emulab: emulab
 	-rsync -v -az -e ssh --delete emulab-manual/ $(INSTALL_ELAB)
-	scp pdf/emulab-manual.pdf $(INSTALL_ELAB)/manual.pdf

advanced-topics.scrbl

@@ -157,7 +157,7 @@ you can add the @tt{geni-get} client from
 @hyperlink["https://www.emulab.net/downloads/geni-get.tar.gz"]{its
 repository}.)
 
-While @tt{geni-get} supports many options, there are three commands most
+While @tt{geni-get} supports many options, there are four commands most
 useful in the @(tb) context.
 
 @subsection[#:tag "geni-get-client-id"]{Client ID}
@@ -185,3 +185,17 @@ manifest to standard output, including any annotations added during
 instantiation.  For instance, this is an appropriate technique to use to
 query the allocation of a @seclink["dynamic-public-ip"]{dynamic public
 IP address pool}.
+
+@subsection[#:tag "geni-get-key"]{Private key}
+
+As a convenience, @(tb) will automatically generate an RSA private
+key unique to each profile instance.  @tt{geni-get key} will retrieve
+the private half of the keypair, which makes it a useful command for
+profiles bootstraping an authenticated channel.  For instance:
+
+@code-sample["geni-get-key.sh"]
+
+Please note that the private key will be accessible to any user who
+can invoke @tt{geni-get} from within the profile instance.  Therefore, it
+is NOT suitable for an authentication mechanism for privilege within
+a multi-user instance!

apt-manual.scrbl

@@ -9,9 +9,11 @@
     "Robert Ricci" "Leigh Stoller" "Kirk Webb" "Jon Duerig" "Gary Wong" "Keith Downie" "Mike Hibler" "Eric Eide"
 ]
 
+@;{
 @italic[(if (equal? doc-mode 'pdf)
     (list "The HTML version of this manual is available at " (hyperlink apt-doc-url apt-doc-url))
     (list "This manual is also available as a " (hyperlink "http://docs.aptlab.net/manual.pdf" "PDF")))]
+}
 
 
 Apt is a platform for sharing research; it is open to all researchers,
@@ -62,6 +64,7 @@ of Utah.
 @include-section["repeatable-research.scrbl"]
 @include-section["creating-profiles.scrbl"]
 @include-section["basic-concepts.scrbl"]
+@include-section["geni-lib.scrbl"]
 @include-section["advanced-topics.scrbl"]
 @include-section["hardware.scrbl"]
 @include-section["planned.scrbl"]

cloudlab-manual.scrbl

@@ -2,23 +2,18 @@
 @(require racket/date)
 @(require "defs.rkt")
 
-@title[#:version apt-version
+@title[#:version apt-version #:style main-style
        #:date (date->string (current-date))]{The CloudLab Manual}
 
 @author[
     "The CloudLab Team"
 ]
 
-@bold{CloudLab is up and running, but in active development.
-    For more information on the deployment schedule for the full version of
-    CloudLab, see @hyperlink[(apturl)]{the CloudLab website}. Please also see
-    the @seclink["status-notes"]{"Status Notes"} chapter of this document
-    for notes regarding the status of the facility.}
-
+@;{
 @italic[(if (equal? doc-mode 'pdf)
     (list "The HTML version of this manual is available at " (hyperlink apt-doc-url apt-doc-url))
     (list "This manual is also available as a " (hyperlink "http://docs.cloudlab.us/manual.pdf" "PDF")))]
-
+}
 
 CloudLab is a "meta-cloud"---that is, it is not a cloud itself; rather, it is a
 facility for building clouds. It provides bare-metal access and control over
@@ -52,6 +47,7 @@ Take a look at the @seclink["status-notes"]{status notes}, and then
 @include-section["repeatable-research.scrbl"]
 @include-section["creating-profiles.scrbl"]
 @include-section["basic-concepts.scrbl"]
+@include-section["geni-lib.scrbl"]
 @include-section["advanced-topics.scrbl"]
 @include-section["hardware.scrbl"]
 @include-section["planned.scrbl"]

code-sample.css

+.code-sample {
+    display: block;
+    unicode-bidi: embed;
+    font-family: "Source Code Pro", monospace;
+    white-space: pre;
+    border: 1px solid #000000;
+    font-size: 12pt;
+}

code-sample.tex

+\newcommand{\code-sample}[1]{\fbox{\verbatim{#1}}}

code-samples/geni-get-key.sh

+#!/bin/sh
+
+# Create the user SSH directory, just in case.
+mkdir $HOME/.ssh && chmod 700 $HOME/.ssh
+
+# Retrieve the server-generated RSA private key.
+geni-get key > $HOME/.ssh/id_rsa
+chmod 600 $HOME/.ssh/id_rsa
+
+# Derive the corresponding public key portion.
+ssh-keygen -y -f $HOME/.ssh/id_rsa > $HOME/.ssh/id_rsa.pub
+
+# If you want to permit login authenticated by the auto-generated key,
+# then append the public half to the authorized_keys file:
+grep -q -f $HOME/.ssh/id_rsa.pub $HOME/.ssh/authorized_keys || cat $HOME/.ssh/id_rsa_pub >> $HOME/.ssh/authorized_keys

code-samples/geni-lib-node-ips.py

+"""An example of constructing a profile with node IP addresses specified
+manually.
+
+Instructions:
+Wait for the profile instance to start, and then log in to either VM via the
+ssh ports specified below.  (Note that even though the EXPERIMENTAL
+data plane interfaces will use the addresses given in the profile, you
+will still connect over the control plane interfaces using addresses
+given by the testbed.  The data plane addresses are for intra-experiment
+communication only.)
+"""
+
 import geni.portal as portal
 import geni.rspec.pg as pg 
 

code-samples/geni-lib-os-install-scripts.py

+"""An example of constructing a profile with install and execute services.
+manually.
+
+Instructions:
+Wait for the profile instance to start, and then log in to the VM via the
+ssh port specified below.  The install and execute services are handled
+automatically during profile instantiation, with no manual intervention
+required.
+"""
+
 import geni.portal as portal
 import geni.rspec.pg as pg 
 
@@ -10,8 +20,9 @@ node1 = pg.XenVM("node1")
 node1.disk_image = "<URL to disk image>"
 
 # Install and execute scripts on the VM
-node1.addService(pg.Install(url="<URL to the tarball file>", path="local"))
-node1.addService(pg.Execute(shell="bash", command="<Path to executable>"))
+node1.addService(pg.Install(url="http://example.org/sample.tar.gz", path="/local"))
+node1.addService(pg.Execute(shell="bash", command="/local/example.sh"))
 
 rspec.addResource(node1)
+
 pc.printRequestRSpec(rspec)

code-samples/geni-lib-parameters.py

+"""An example of using parameters to construct a profile with a variable
+number of nodes.
+
+Instructions:
+Wait for the profile instance to start, and then log in to one or more of
+the VMs via the ssh port(s) specified below.
+"""
+
+# Import the Portal object.
+import geni.portal as portal
+# Import the ProtoGENI library.
+import geni.rspec.pg as pg
+
+# Create the Portal context.
+pc = portal.Context()
+
+# Describe the parameter(s) this profile script can accept.
+pc.defineParameter( "n", "Number of VMs", portal.ParameterType.INTEGER, 1 )
+
+# Retrieve the values the user specifies during instantiation.
+params = pc.bindParameters()
+
+# Create a Request object to start building the RSpec.
+rspec = pg.Request()
+
+# Check parameter validity.
+if params.n < 1 or params.n > 8:
+    pc.reportError( portal.ParameterError( "You must choose at least 1 and no more than 8 VMs." ) )
+
+for i in range( params.n ):
+    # Create a XenVM and add it to the RSpec.
+    node = pg.XenVM( "node" + str( i ) )
+    rspec.addResource( node )
+
+# Print the RSpec to the enclosing page.
+pc.printRequestRSpec(rspec)

code-samples/geni-lib-single-pc.py

+"""An example of constructing a profile with a single raw PC.
+
+Instructions:
+Wait for the profile instance to start, and then log in to the host via the
+ssh port specified below.
+"""
+
 # Import the Portal object.
 import geni.portal as portal
 # Import the ProtoGENI library.

code-samples/geni-lib-single-vm.py

+"""An example of constructing a profile with a single Xen VM.
+
+Instructions:
+Wait for the profile instance to start, and then log in to the VM via the
+ssh port specified below.  (Note that in this case, you will need to access
+the VM through a high port on the physical host, since we have not requested
+a public IP address for the VM itself.)
+"""
+
 # Import the Portal object.
 import geni.portal as portal
 # Import the ProtoGENI library.

code-samples/geni-lib-two-arm-lan.py

+"""An example of constructing a profile with two ARM64 nodes connected by a LAN.
+
+Instructions:
+Wait for the profile instance to start, and then log in to either host via the
+ssh ports specified below.
+"""
+
 import geni.portal as portal
 import geni.rspec.pg as pg 
 

code-samples/geni-lib-two-vm-lan.py

+"""An example of constructing a profile with two VMs connected by a LAN.
+
+Instructions:
+Wait for the profile instance to start, and then log in to either VM via the
+ssh ports specified below.
+"""
+
 import geni.portal as portal
 import geni.rspec.pg as pg 
 
 pc = portal.Context()
 rspec = pg.Request()
 
-# Create a XenVM nodes.
+# Create two XenVM nodes.
 node1 = pg.XenVM("node1")
 node2 = pg.XenVM("node2")
 

creating-profiles.scrbl

@@ -69,7 +69,7 @@ be rebooted in order to take consistent snapshots of the disk.
 For the time being, this process only works for single-node profiles; we will
 add support for multi-node profiles in the future.
 
-@subsection{Creating the Profile}
+@subsection[#:tag "creating-the-profile"]{Creating the Profile}
 
 @itemlist[ #:style 'ordered
     @instructionstep["Create an experiment"]{Create an experiment using the
@@ -216,63 +216,6 @@ for the node, set commands to be run when the node boots, etc. To unselect
 the current node or link, and return to the palette on the left, simply
 click a blank area of the canvas.
 
-@section[#:tag "geni-lib"]{Describing a profile with python and @tt{geni-lib}}
-
-@margin-note{This feature is currently in @bold{alpha testing} and may change
-in the future.}
-
-@tt{geni-lib} is a tool that allows users to generate @seclink["rspecs"]{RSpec} files from Python
-code.  An @bold{experimental} feature of @(tb) is the ability to use @tt{geni-lib}
-scripts as the definition of a profile, rather then the more primitive
-RSpec format. When you supply a @tt{geni-lib} script on the
-@seclink["creating-profiles"]{Create Profile} page, your script is uploaded
-to the server so that it can be executed in the @tt{geni-lib} environment. This
-allows the script to be verified for correctness, and also produces the 
-equivalent RSpec representation that you can view if you so desire.
-
-@screenshot["create-geni-lib-empty.png"]
-
-When you provide a @tt{geni-lib} script, you will see a slightly different set
-of buttons on the @seclink["creating-profiles"]{Create Profile} page; next
-to the ``Source'' button there is an ``XML'' button that will pop up the
-RSpec XML for you to look at. The XML is read-only; if you want to change
-the profile, you will need to change the python source code that is
-displayed when you click on the ``Source'' button. Each time you change the
-python source code, the script is uploaded to the server and processed. Be
-sure to save your changes if you are 
-@seclink["updating-profiles"]{updating an existing profile}.
-
-The following examples demonstrate basic @tt{geni-lib} usage. More information
-about @tt{geni-lib} and additional examples, can be found in the
-@hyperlink["https://bitbucket.org/barnstorm/geni-lib/src"]{@tt{geni-lib} repository}. Its full documentation is online at
-@link["http://geni-lib.readthedocs.org/"]{geni-lib.readthedocs.org}.
-
-@subsection[#:tag "geni-lib-example-single-vm"]{A single XEN VM node}
-
-@code-sample["geni-lib-single-vm.py"]
-
-@subsection[#:tag "geni-lib-example-single-pc"]{A single physical host}
-
-@code-sample["geni-lib-single-pc.py"]
-
-@subsection[#:tag "geni-lib-example-two-vm-lan"]{Two XenVM nodes with a LAN between them}
-
-@code-sample["geni-lib-two-vm-lan.py"]
-
-@subsection[#:tag "geni-lib-example-two-arm-lan"]{Two ARM64 servers in a LAN}
-
-@code-sample["geni-lib-two-arm-lan.py"]
-
-@subsection[#:tag "geni-lib-example-node-ips"]{Set a specific IP address on each node}
-
-@code-sample["geni-lib-node-ips.py"]
-
-
-@subsection[#:tag "geni-lib-example-os-install-scripts"]{Specify an operating system and set install and execute scripts}
-
-@code-sample["geni-lib-os-install-scripts.py"]
-
-
 @section[#:tag "creating-from-scratch"]{Creating a profile from scratch}
 
 @future-work["planned-easier-profiles"]

defs.rkt

 #lang racket/base
 (require scribble/base)
+(require scribble/core)
 (require scribble/decode)
 (require scribble/manual)
+(require scribble/private/defaults)
+(require scribble/html-properties)
+(require scribble/latex-properties)
 (require racket/class)
 (require racket/draw)
 (require racket/system)
@@ -11,6 +15,11 @@
 
 (provide (all-defined-out))
 
+(define main-style
+  (make-style "main-body"
+              (list (js-style-addition "highlight.pack.js")
+                    (make-css-addition "highlight-default.css"))))
+
 ; Check to see if we are building Apt or CloudLab documentation
 (define tb-mode
   (cond
@@ -156,5 +165,10 @@
 (define (ssh)
   (tt "ssh"))
 
+(define code-sample-style
+  (make-style "code-sample"
+              (list (make-css-addition "code-sample.css")
+                    (make-tex-addition "code-sample.tex"))))
+
 (define (code-sample filename)
-  (code-inset (verbatim (file->string (string-append "code-samples/" filename)))))
+  (elem #:style code-sample-style (file->string (string-append "code-samples/" filename))))

emulab-manual.scrbl

@@ -9,10 +9,11 @@
      "Eric Eide" "Robert Ricci" "Jacobus (Kobus) Van der Merwe" "Leigh Stoller" "Kirk Webb" "Jon Duerig" "Gary Wong" "Keith Downie" "Mike Hibler"
 ]
 
+@;{
 @italic[(if (equal? doc-mode 'pdf)
     (list "The HTML version of this manual is available at " (hyperlink apt-doc-url apt-doc-url))
     (list "This manual is also available as a " (hyperlink "http://docs.emulab.net/manual.pdf" "PDF")))]
-
+}
 
 Emulab is a network testbed, giving researchers a wide range of
 environments in which to develop, debug, and evaluate their
@@ -40,6 +41,7 @@ you can apply to start a new project.
 @include-section["repeatable-research.scrbl"]
 @include-section["creating-profiles.scrbl"]
 @include-section["basic-concepts.scrbl"]
+@include-section["geni-lib.scrbl"]
 @include-section["advanced-topics.scrbl"]
 @include-section["hardware.scrbl"]
 @include-section["planned.scrbl"]

getting-started.scrbl

@@ -102,7 +102,7 @@ Start by pointing your browser at @url[(apturl)].
   @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!)"}
+      doesn't arrive in a few minutes, check your spam folder!)}
   }
   @instructionstep["Use your experiment"]{
   When your experiment is ready to use, the progress bar will be complete, and

highlight-default.css

+/*
+
+Original style from softwaremaniacs.org (c) Ivan Sagalaev <Maniac@SoftwareManiacs.Org>
+
+*/
+
+.hljs {
+  display: block;
+  overflow-x: auto;
+  padding: 0.5em;
+  background: #f0f0f0;
+  -webkit-text-size-adjust: none;
+}
+
+.hljs,
+.hljs-subst,
+.hljs-tag .hljs-title,
+.nginx .hljs-title {
+  color: black;
+}
+
+.hljs-string,
+.hljs-title,
+.hljs-constant,
+.hljs-parent,
+.hljs-tag .hljs-value,
+.hljs-rule .hljs-value,
+.hljs-preprocessor,
+.hljs-pragma,
+.hljs-name,
+.haml .hljs-symbol,
+.ruby .hljs-symbol,
+.ruby .hljs-symbol .hljs-string,
+.hljs-template_tag,
+.django .hljs-variable,
+.smalltalk .hljs-class,
+.hljs-addition,
+.hljs-flow,
+.hljs-stream,
+.bash .hljs-variable,
+.pf .hljs-variable,
+.apache .hljs-tag,
+.apache .hljs-cbracket,
+.tex .hljs-command,
+.tex .hljs-special,
+.erlang_repl .hljs-function_or_atom,
+.asciidoc .hljs-header,
+.markdown .hljs-header,
+.coffeescript .hljs-attribute,
+.tp .hljs-variable {
+  color: #800;
+}
+
+.smartquote,
+.hljs-comment,
+.hljs-annotation,
+.diff .hljs-header,
+.hljs-chunk,
+.asciidoc .hljs-blockquote,
+.markdown .hljs-blockquote {
+  color: #888;
+}
+
+.hljs-number,
+.hljs-date,
+.hljs-regexp,
+.hljs-literal,
+.hljs-hexcolor,
+.smalltalk .hljs-symbol,
+.smalltalk .hljs-char,
+.go .hljs-constant,
+.hljs-change,
+.lasso .hljs-variable,
+.makefile .hljs-variable,
+.asciidoc .hljs-bullet,
+.markdown .hljs-bullet,
+.asciidoc .hljs-link_url,
+.markdown .hljs-link_url {
+  color: #080;
+}
+
+.hljs-label,
+.ruby .hljs-string,
+.hljs-decorator,
+.hljs-filter .hljs-argument,
+.hljs-localvars,
+.hljs-array,
+.hljs-attr_selector,
+.hljs-important,
+.hljs-pseudo,
+.hljs-pi,
+.haml .hljs-bullet,
+.hljs-doctype,
+.hljs-deletion,
+.hljs-envvar,
+.hljs-shebang,
+.apache .hljs-sqbracket,
+.nginx .hljs-built_in,
+.tex .hljs-formula,
+.erlang_repl .hljs-reserved,
+.hljs-prompt,
+.asciidoc .hljs-link_label,
+.markdown .hljs-link_label,
+.vhdl .hljs-attribute,
+.clojure .hljs-attribute,
+.asciidoc .hljs-attribute,
+.lasso .hljs-attribute,
+.coffeescript .hljs-property,
+.hljs-phony {
+  color: #88f;
+}
+
+.hljs-keyword,
+.hljs-id,
+.hljs-title,
+.hljs-built_in,
+.css .hljs-tag,
+.hljs-doctag,
+.smalltalk .hljs-class,
+.hljs-winutils,
+.bash .hljs-variable,
+.pf .hljs-variable,
+.apache .hljs-tag,
+.hljs-type,
+.hljs-typename,
+.tex .hljs-command,
+.asciidoc .hljs-strong,
+.markdown .hljs-strong,
+.hljs-request,
+.hljs-status,
+.tp .hljs-data,
+.tp .hljs-io {
+  font-weight: bold;
+}
+
+.asciidoc .hljs-emphasis,
+.markdown .hljs-emphasis,
+.tp .hljs-units {
+  font-style: italic;
+}
+
+.nginx .hljs-built_in {
+  font-weight: normal;
+}
+
+.coffeescript .javascript,
+.javascript .xml,
+.lasso .markup,
+.tex .hljs-formula,
+.xml .javascript,
+.xml .vbscript,
+.xml .css,
+.xml .hljs-cdata {
+  opacity: 0.5;
+}

phantomnet-manual.scrbl

@@ -9,10 +9,11 @@
     "Jacobus (Kobus) Van der Merwe" "Robert Ricci" "Leigh Stoller" "Kirk Webb" "Jon Duerig" "Gary Wong" "Keith Downie" "Mike Hibler" "Eric Eide"
 ]
 
+@;{
 @italic[(if (equal? doc-mode 'pdf)
     (list "The HTML version of this manual is available at " (hyperlink apt-doc-url apt-doc-url))
     (list "This manual is also available as a " (hyperlink "http://docs.phantomnet.org/manual.pdf" "PDF")))]
-
+}
 
 PhantomNet is a mobility testbed, providing researchers with a set of
 hardware and software resources that they can use to develop, debug,
@@ -41,6 +42,7 @@ The PhantomNet facility is built on top of
 @include-section["repeatable-research.scrbl"]
 @include-section["creating-profiles.scrbl"]
 @include-section["basic-concepts.scrbl"]
+@include-section["geni-lib.scrbl"]
 @include-section["advanced-topics.scrbl"]
 @include-section["hardware.scrbl"]
 @include-section["planned.scrbl"]