Commit cf7c701c authored by Gary Wong's avatar Gary Wong

Update geni-lib documentation and examples.

parent 28ab9d71
......@@ -8,3 +8,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!
#!/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
import geni.portal as portal
import geni.rspec.pg as pg
import geni.rspec.igext as ext
pc = portal.Context()
rspec = pg.Request()
......@@ -29,4 +30,8 @@ link.addInterface(iface2)
rspec.addResource(link)
pc.printRequestRSpec(rspec)
\ No newline at end of file
tour = ext.Tour()
tour.Description( ext.Tour.TEXT, "An example of constructing a profile with node IP addresses specified manually." )
rspec.addTour( tour )
pc.printRequestRSpec(rspec)
import geni.portal as portal
import geni.rspec.pg as pg
import geni.rspec.igext as ext
pc = portal.Context()
rspec = pg.Request()
......@@ -14,4 +15,9 @@ node1.addService(pg.Install(url="<URL to the tarball file>", path="local"))
node1.addService(pg.Execute(shell="bash", command="<Path to executable>"))
rspec.addResource(node1)
pc.printRequestRSpec(rspec)
\ No newline at end of file
tour = ext.Tour()
tour.Description( ext.Tour.TEXT, "An example of constructing a profile with install and execute services." )
rspec.addTour( tour )
pc.printRequestRSpec(rspec)
......@@ -2,6 +2,8 @@
import geni.portal as portal
# Import the ProtoGENI library.
import geni.rspec.pg as pg
# Import the extension library (used for the profile description).
import geni.rspec.igext as ext
# Create the Portal context.
pc = portal.Context()
......@@ -12,6 +14,11 @@ rspec = pg.Request()
# Create a raw PC and add it to the RSpec.
node = pg.RawPC("node")
rspec.addResource(node)
# Create a profile description, and add it to the RSpec.
tour = ext.Tour()
tour.Description( ext.Tour.TEXT, "An example of constructing a profile with a single raw PC." )
rspec.addTour( tour )
# Print the RSpec to the enclosing page.
pc.printRequestRSpec(rspec)
......@@ -2,6 +2,8 @@
import geni.portal as portal
# Import the ProtoGENI library.
import geni.rspec.pg as pg
# Import the extension library (used for the profile description).
import geni.rspec.igext as ext
# Create the Portal context.
pc = portal.Context()
......@@ -12,6 +14,11 @@ rspec = pg.Request()
# Create a XenVM and add it to the RSpec.
node = pg.XenVM("node")
rspec.addResource(node)
# Create a profile description, and add it to the RSpec.
tour = ext.Tour()
tour.Description( ext.Tour.TEXT, "An example of constructing a profile with a single Xen VM." )
rspec.addTour( tour )
# Print the RSpec to the enclosing page.
pc.printRequestRSpec(rspec)
\ No newline at end of file
pc.printRequestRSpec(rspec)
import geni.portal as portal
import geni.rspec.pg as pg
import geni.rspec.igext as ext
pc = portal.Context()
rspec = pg.Request()
......@@ -29,4 +30,9 @@ link.addInterface(iface2)
# Add the link to the RSpec.
rspec.addResource(link)
# Create a profile description, and add it to the RSpec.
tour = ext.Tour()
tour.Description( ext.Tour.TEXT, "An example of constructing a profile with two ARM64 nodes connected by a LAN." )
rspec.addTour( tour )
pc.printRequestRSpec(rspec)
import geni.portal as portal
import geni.rspec.pg as pg
import geni.rspec.igext as ext
pc = portal.Context()
rspec = pg.Request()
......@@ -25,4 +26,9 @@ link.addInterface(iface2)
# Add the link to the RSpec.
rspec.addResource(link)
pc.printRequestRSpec(rspec)
\ No newline at end of file
# Create a profile description, and add it to the RSpec.
tour = ext.Tour()
tour.Description( ext.Tour.TEXT, "An example of constructing a profile with two VMs connected by a LAN." )
rspec.addTour( tour )
pc.printRequestRSpec(rspec)
......@@ -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 scribble/manual
@(require "defs.rkt")
@title[#:tag "geni-lib" #:version apt-version]{Describing a profile with python and @tt{geni-lib}}
@tt{geni-lib} is a tool that allows users to generate @seclink["rspecs"]{RSpec} files from Python
code. @(tb) offers 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"]
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