Skip to content

QuickStart

Tom Mitchell edited this page Mar 6, 2017 · 8 revisions

GCF/Omni Installation

These instructions assume geni-tools version 2.10 and a Unix based machine. If you have a different geni-tools version you will need to modify the corresponding filenames. For a Windows or Mac Omni only install, download the appropriate installer from the release page. Then see the Windows or Mac installation instructions. If you are upgrading from an older geni-tools version, follow the Upgrade GCF instructions. In order to install and run gcf/omni you will need to follow these steps.

1. Create the gcf directory

  • If you have downloaded the software from the git repository, you can skip this step.

    tar xvfz gcf-2.10.tar.gz
    
  • Move the gcf directory to the directory where you want to permanently keep gcf. This might be your home directory. If you have sudo privileges in your host, you might want to consider moving the gcf package under /usr/local/bin/ for a cleaner setup.

    [sudo] mv gcf-2.10 <install-dir>
    
  • Create a symbolic link called gcf to your installation directory. This will make the process of upgrading omni easier.

    • If this is your first time installing gcf, do:

      cd <install-dir>
      ln -s gcf-2.10 gcf
      
    • If you are upgrading your gcf, do:

      cd <install-dir>
      rm gcf; ln -s gcf-2.10 gcf
      

2. Add GCF to your path and define aliases

In order to be able to run omni.py, gcf-am.py and any of the scripts (e.g. readyToLogin.py) you will need to modify the PATH and the PYTHONPATH environment variables.

Also it is useful to add aliases to the commonly used commands so that you don't have to specify the .py in your commands; e.g. you can configure omni by just running omni-configure instead of omni-configure.py

It is recommended that you make these modifications in a configuration file so that they are set every time you login to your host. The name of the configuration file is dependent on the shell you are running.

In order to figure out which shell you are using run:

ps -p $$

If you are using a bash shell, copy and paste these lines to the end of your .bashrc file. This file is located in your home directory. If the file does not exist, you can create it. If you are using a different shell, then modify these lines appropriately and add them to the configuration file of your shell. Make sure to replace <PATH-TO-GCF-DIR> with the actual path to your gcf directory. For example if you have installed gcf under /usr/local/bin/ then <PATH-TO-GCF-DIR> is /usr/local/bin/gcf.

# set PATH so it includes geni software if it exists
if [ -d "<PATH-TO-GCF-DIR>/src" ] ; then
    PATH="<PATH-TO-GCF-DIR>/src:<PATH-TO-GCF-DIR>/examples:$PATH"
    export PYTHONPATH="<PATH-TO-GCF-DIR>/src:$PYTHONPATH" 
fi

alias omni='omni.py'
alias omni-configure='omni-configure.py'
alias readyToLogin='readyToLogin.py'
alias clear-passphrases='clear-passphrases.py'
alias stitcher='stitcher.py'
alias remote-execute='remote-execute.py'
alias addMemberToSliceAndSlivers='addMemberToSliceAndSlivers.py'

For the changes to take effect in your current terminal run:

source <configuration_file>

3. Install software dependencies

The GCF package is intended to be run on a recent Unix distribution. Python 2.6 or better is required. This software is not Python 3 compatible. This software requires a number of readily available software packages. Most modern Linux distributions should have these packages available via their native package management suite (eg. yum or apt). BRBRFollow the instructions below for installing all the software dependencies for your platform. If you want to see exactly what is installed you can review the [#SoftwareDependencies Software Dependencies] list below.

NOTE: Windows users, you might want to consider using Cygwin.

4. Configure and test the installation


Upgrade

In order to upgrade gcf, simply follow the instructions about creating a gcf dir.

NOTE: If you have any configuration files (e.g. omni_config or gcf_config) under the directory of your previous gcf installation, make sure you move them under the new directory so that you still have easy access to them.


Platform Installation

To install Omni and gcf software dependencies, follow the instructions for your platform.

Debian / Ubuntu

sudo apt-get install python-m2crypto python-dateutil \
                     python-openssl libxmlsec1 xmlsec1 \
                     libxmlsec1-openssl libxmlsec1-dev

RedHat / Fedora

sudo yum install m2crypto python-dateutil pyOpenSSL xmlsec1 \
                 xmlsec1-devel xmlsec1-openssl xmlsec1-openssl-devel

CentOS

GCF requires Python 2.6. It is possible that overriding Python 2.4 with 2.6 could cause problems on CentOS 5.5, so we provide these directions for a parallel install of Python.

  1. Install python 2.6 as python26:

    $ wget http://mirrors.geekymedia.com/centos/geekymedia.repo 
    $ sudo mv geekymedia.repo /etc/yum.repos.d/ 
    $ sudo yum install python26*
    
  2. Install the 2.6 version of setuptools which has easy_install

    $ wget http://pypi.python.org/packages/2.6/s/setuptools/setuptools-0.6c11-py2.6.egg 
    $ wget http://peak.telecommunity.com/dist/ez_setup.py 
    $ sudo python26 ez_setup.py setuptools-0.6c11-py2.6.egg
    
  3. Use easy_install (make sure it operates on /usr/lib/python2.6)

    $ sudo easy_install python-dateutil==1.4.1 
    $ sudo easy_install pyOpenSSL 
    $ sudo yum install swig
    

    Edit /usr/include/openssl/opensslconf.h, line 13: (a tweak necessary in CentOS, otherwise error given in m2crypto installation)

    #include "/usr/include/openssl/opensslconf-i386.h"
    
    $ sudo easy_install m2crypto
    
  4. Make sure scripts use python26:

    Edit src/gen-certs.py, src/gcf-ch.py and src/gcf-am.py line 1:

    #!/usr/bin/env python26
    

Mac OS X

Pre-built binaries for Mac OS X Omni tools (not including the gcf tools for developers) are available for download from the release page. If that is not appropriate for you, follow the instructions below.

Using Homebrew

These instructions use homebrew.

Please make sure that Xcode is installed before you start the following.

To install:

  • brew install python

  • This will install python at /usr/local/bin but the python that comes with Mac OS is at /usr/bin which takes precedence in the path, so modify your ~/.profile file and add this line:

    export PATH=/usr/local/bin:$PATH
    

    and then run source ~/.profile

  • Type which python to ensure that you are using the right one.

  • brew install swig

  • pip install M2Crypto

    • Note: there can be quite a few warnings during this step, simply ignore them.
  • brew install libxmlsec1

  • pip install python-dateutil

  • brew install xmlsec1

  • pip install pyopenssl

  • It is recommended you move readyToLogin.py from gcf/examples/ to gcf/src/

If you want to test if your python can access the libraries you want, just start python in interactive mode and try to import the module (e.g. import M2Crypto).

Using MacPorts

You must have MacPorts and Xcode installed on your computer.

  • Install the Python modules needed by Omni

    sudo port install py27-m2crypto py27-dateutil py27-openssl xmlsec
    cd /opt/local/lib
    sudo ln -s libxmlsec1-openssl.dylib libxmlsec1-openssl.so
    
  • Make sure your PYTHONPATH includes the directory where these modules were installed. This is typically /opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages.

  • Install pip, if you don't already have it on your computer

    sudo easy-install pip
    
  • Install the Python {{{six}}} package

    sudo pip install six
    
  • Add the following command to your .profile or .bashrc

    export DYLD_LIBRARY_PATH=/opt/local/lib
    
  • It is recommended you move readyToLogin.py from gcf/examples/ to gcf/src/


Software Dependencies

GCF depends on the following packages:

Python M2Crypto

The M2Crypto package provides utilities for handling X.509 certificates and SSL connections. M2Crypto is required by the certificate class in sfa/trust. M2Crypto should be readily available on most Linux distributions.

More information is available at: http://chandlerproject.org/bin/view/Projects/MeTooCrypto

Python dateutil

The dateutil package provides date parsing routines to Python. It should be readily available on most Linux distributions.

More information is available at: http://labix.org/python-dateutil

Python OpenSSL

The OpenSSL package provides a python API to the OpenSSL package. There is an implicit dependency on OpenSSL, but that should be handled by the Linux package manager (yum, apt, etc.)

More information is available at: https://launchpad.net/pyopenssl

xmlsec1

The XML Security Library provides implementations of XML Digital Signatures (RFC 3275) and W3C XML Encryption. The program xmlsec1 from this package is used to sign credentials.

On rpm systems the required packages are:

  • xmlsec1
  • xmlsec1-openssl-devel

On debian systems the packages are

  • libxmlsec1
  • xmlsec1
  • libxmlsec1-openssl
  • libxmlsec1-dev

More information is available at:

You can’t perform that action at this time.