Commit 3b295c9c authored by Robert Ricci's avatar Robert Ricci

Merge remote-tracking branch 'origin/geni-lib'

parents f3dc1dfe 4bba5a72
......@@ -10,3 +10,4 @@ pdf/
*.aux
*.out
*.png
*~
......@@ -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!
......@@ -62,6 +62,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"]
......
......@@ -2,7 +2,7 @@
@(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[
......@@ -52,6 +52,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 {
display: block;
unicode-bidi: embed;
font-family: "Source Code Pro", monospace;
white-space: pre;
border: 1px solid #000000;
font-size: 12pt;
}
\newcommand{\code-sample}[1]{\fbox{\verbatim{#1}}}
#!/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
"""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
......@@ -29,4 +41,4 @@ link.addInterface(iface2)
rspec.addResource(link)
pc.printRequestRSpec(rspec)
\ No newline at end of file
pc.printRequestRSpec(rspec)
"""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)
\ No newline at end of file
pc.printRequestRSpec(rspec)
"""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)
"""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.
......@@ -12,6 +19,6 @@ rspec = pg.Request()
# Create a raw PC and add it to the RSpec.
node = pg.RawPC("node")
rspec.addResource(node)
# Print the RSpec to the enclosing page.
pc.printRequestRSpec(rspec)
"""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.
......@@ -12,6 +21,6 @@ rspec = pg.Request()
# Create a XenVM and add it to the RSpec.
node = pg.XenVM("node")
rspec.addResource(node)
# Print the RSpec to the enclosing page.
pc.printRequestRSpec(rspec)
\ No newline at end of file
pc.printRequestRSpec(rspec)
"""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
......
"""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")
......@@ -25,4 +32,4 @@ link.addInterface(iface2)
# Add the link to the RSpec.
rspec.addResource(link)
pc.printRequestRSpec(rspec)
\ No newline at end of file
pc.printRequestRSpec(rspec)
......@@ -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"]
......
#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))))
......@@ -40,6 +40,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"]
......
This diff is collapsed.
......@@ -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
......
/*
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;
}
This diff is collapsed.
......@@ -41,6 +41,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"]
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment