[[PageOutline]]

== For up to date information about geni-lib, please refer to the official documentation at [http://geni-lib.readthedocs.org] ==


= How to Setup geni-lib =

[https://bitbucket.org/barnstorm/geni-lib/src geni-lib] is a python library written by Nick Bastin of Barnstormer Softworks. It can be used to create RSpec file for large topology. In this page, we show how to install and configure geni-lib. The installation and configuration of geni-lib has been tested on MacOS 10.9.3, and python27 installed from !MacPort is set to be the default python. 

To use geni-lib, you will first need to download it from the [https://bitbucket.org/barnstorm/geni-lib/src geni-lib repository].


 
== Download geni-lib ==

For MacOS Experimenters:

 * Install Mercurial 
   * If you are using !MacPort, you can Install mercurial with 
{{{
sudo port install mercurial
}}}
   * You can also find the Mercurial download page [http://mercurial.selenic.com/downloads here]

 * Configure Mercurial
   * Create $HOME/.hgrc and add your name and email address
{{{
[ui]
username = Your Name <xxx@xxx.xxx>
}}}

 * Clone geni-lib
{{{
hg clone https://bitbucket.org/barnstorm/geni-lib
}}}

 * Check and Pull Update
{{{
hg pull && hg update default
}}}



Once you have downloaded the geni-lib to your local machine, you will see two directories under ./geni-lib/
{{{
dhcp89-69-127:geni-lib xliu$ ls
geni	samples
}}}

The directory "geni" is the library for RSpec generation and other purposes, and "samples" contains examples of using the library, as well as a sample configuration file that you need to modify it before writing and  testing your scripts.


== Download Dependencies and Configure PYTHONPATH ==

In the system that has been tested, a python package lxml is needed for geni-lib, and you may need to install m2crypto module as well. 

 * Install lxml, m2crypto python packages
 
 If you are using !MacPort, you can use
 {{{
 $ sudo port install py27-lxml
 $ sudo port install py27-m2crypto
 }}} 

 * Add PYTHONPATH:

 For MacOS experimenters, you can add following lines to the end of your ~/.profile
 {{{
 # add python path
 export PYTHONPATH=$PYTHONPATH:<your path to geni-lib>
 }}}
 Then, run 
 {{{
 source ~/.profile
 }}}

  * Optional Step: Switch Python Version
  
 Sometimes you may have problems with python versions if you have two different versions of python installed. If you installed python27 and python modules from !MacPort, so you may need to select python27 installed by !MacPort as your default python. 
{{{
$ sudo port select --set python python27
}}}


== Configure geni-lib ==

 * Modify the configuration file

 To use geni-lib, you will need to create a configuration file that contains your credential to GENI and other information about your experiments. Go to ./geni-lib/samples/, and open the file 

 {{{
dhcp89-69-127:samples xliu$ cat example_config.py
from geni.aggregate import FrameworkRegistry
from geni.aggregate.context import Context
from geni.aggregate.user import User

def buildContext ():
  portal = FrameworkRegistry.get("portal")()
  portal.cert = "/home/nbastin/.ssh/portal-nbastin.pem"
  portal.key = "/home/nbastin/.ssh/portal-nbastin.key"

  nbastin = User()
  nbastin.name = "nbastin"
  nbastin.urn = "urn:publicid:IDN+ch.geni.net+user+nickbas"
  nbastin.addKey("/home/nbastin/.ssh/geni_dsa.pub")

  context = Context()
  context.addUser(nbastin, default = True)
  context.cf = portal
  context.project = "bss-sw-test"

  return context
 }}}

 You will modify this module on from line 7 to line 13, line 16 and line 18 with your own information, and you may want to save it as a different file, for example, with name <your initial>_config.py

 ''Note that portal.cert and portal.key should be the same SSL certificate file that you have downloaded from protal, the extension (either .pem or .key) does not matter ''


 To see examples on how to use geni-lib to generate RSpec, please go to [wiki:HowTo/GenerateRSpecUsingGENILIB RSpec Generation Using geni-lib]