Changes between Version 11 and Version 12 of GIR3.1_GushProto

04/21/11 15:56:28 (9 years ago)



  • GIR3.1_GushProto

    v11 v12  
    2727$ svn co --username guest
    28 }}}
    29 Note: password availaliable upon request.
     28$ cd trunk
     31Using the newly updated README.tx was able to complete all steps as instructed:
     33* Prerequisites
     35This page describes the setup process required to use Gush with
     36PlanetLab. If you want to use Gush with ProtoGENI, please check out
     37the ProtoGeniExample page.
     39Important: Before using Gush with  PlanetLab, you must obtain an
     40account/slice on PlanetLab. In addition, Gush requires the ability to
     41SSH to PlanetLab hosts without typing a passphrase. You should set up
     42an ssh-agent to provide password-free ssh access to PlanetLab
     43hosts. To handle the case where connecting to a new node brings up a
     44fingerprint verification question, add "StrictHostKeyChecking no" to
     45your ~/.ssh/config. We have found that PlanetLab keys change
     46periodically, and by not requiring StrictHostKeyChecking we encounter
     47less errors.
     49** Library Dependencies
     51Gush is written in a mix of C++ and Python, and we intend for it to be
     52runnable on any UNIX-ish OS. That said, we have been using it
     53primarily with Linux and Mac OS. Compiling Gush can be challenging, so
     54please contact us if you experience too many problems. Gush requires
     55the following libraries:
     57    * xmlrpc-c: libxmlrpc_client++, libxmlrpc_client,
     58                libxmlrpc_server_abyss++, libxmlrpc_server++,
     59                libxmlrpc_server_abyss, libxmlrpc_server,
     60                libxmlrpc_abyss, libxmlrpc++, libxmlrpc,
     61                libxmlrpc_util, libxmlrpc_xmlparse, libxmlrpc_xmltok
     63      Note: lbxmlrpc-c3 will not work. xmlrpc-c must be installed, and
     64      to our knowledge, there is no debian package available.
     66    * curl: libcurl
     67    * xml2: libxml2
     68    * zlib compression/decompression: libz
     69    * math: libm
     70    * openssl: libssl, libcrypto
     71    * dynamic linking: libdl
     72    * readline: libreadline
     73    * curses: libcurses
     74    * intl domain names: libidn
     75    * pthreads: libpthread
     77The boost software package is also required, as well as lex and yacc
     78(we use flex and bison).
     80Gush supports the latest version of the  GENI API. It uses a modified
     81version of the Omni client for communication with GENI aggregate
     82managers. More information about Omni can be found on the
     83OmniOverview page and on the  QuickStart guide. Since Omni is written
     84in Python, you must install a few Python libraries in addition to the
     85C++ libraries mentioned above. More details about configuring Python
     86and Omni are explained below.
     88For reference, the following commands were used to install the
     89prerequisite software for Gush (including Omni) on a new machine with
     90a clean installation of Ubuntu 10.04 Desktop 64bit.
     92$ sudo apt-get install openssh-server subversion keychain g++-4.1
     93autoconf2.59 makedepend emacs23
     94$ sudo ln -s /usr/bin/g++-4.1 /usr/bin/g++
     95$ sudo apt-get install curl libcurl3 libcurl4-openssl-dev libboost-dev
     96xutils-dev flex bison libreadline-dev
     97$ sudo apt-get install python-m2crypto python-dateutil
     98python-pyopenssl libxmlsec1 xmlsec1 libxmlsec1-openssl libxmlsec1-dev
     99$ wget
     100$ tar xzf xmlrpc-c-1.16.34.tgz
     101$ cd xmlrpc-c-1.16.34
     102$ ./configure
     103$ make
     104$ sudo make install
     106* Using Gush with PlanetLab
     108After installing the required libraries mentioned above, the first
     109step to using Gush is to download and compile the code. The code can
     110be obtained from the SVN repository linked to this site. You must
     111request an account before obtaining the code. Please email jeannie AT
     112cs dot williams dot edu for access to the repository.
     114After obtaining the password, check out Gush using the following
     117$ svn co --username guest
     119Once the code has been downloaded, follow the instructions found in
     120README.txt to compile and install Gush. These instructions are
     121included here for your reference.
     123NOTE: We have statically compiled versions of both the Gush and Gush
     124client binaries available. If you would like to skip the compilation
     125step (which can be tedious!), most users can simply use the statically
     126compiled binaries. We currently have binaries for 64 bit Ubuntu Linux
     127and an older 32 bit Ubuntu Linux. Other Linux distributions may be
     128able to run these binaries, but this has not been tested fully. To use
     129these binaries, download the appropriate tarball, untar it, and skip
     130ahead to the "Configuring Python for Omni" section below.
     13264 bit Ubuntu Linux: gush-bin-64bit.tgz
     13432 bit Ubuntu Linux: gush-bin-32bit.tgz
     136** Compiling Gush
     138After downloading the code from SVN, follow the instructions below to
     139compile Gush. NOTE: This dynamically compiles Gush and the Gush
     140client. You can compile statically using the --with-static-gush and
     141--with-static-client compile flags. Statically compiling is usually a
     142bit more error prone because of some issues with curl. If static
     143compilation is required, we recommend installing  curl directly from
     144source and using --disable-ldap while compiling curl. For most
     145installations, dynamically compiling should be sufficient.
     147$ cd gush/trunk
     148$ autoconf  (Make sure you use autoconf version 2.50 or higher.)
     149$ ./configure
     150$ make dep
     151$ make
     153** Configuring Python for Omni
     155Python 2.6 is required. In addition, the following Python packages
     156must be installed:  M2Crypto,  dateutil,  OpenSSL, and  xmlsec1.
     158According to the Omni  QuickStart page, the following installation
     159methods may be helpful:
     161    * Debian / Ubuntu
     163      $ sudo apt-get install python-m2crypto python-dateutil
     164      python-pyopenssl libxmlsec1 xmlsec1 libxmlsec1-openssl
     165      libxmlsec1-dev 
     167    * Mac OS X (using MacPorts)
     169      $ sudo port install py26-m2crypto py26-dateutil py26-openssl
     170      xmlsec
     171      $ cd /opt/local/lib
     172      $ sudo ln -s libxmlsec1-openssl.dylib
     174You must configure the omni_config file before using Omni to connect
     175to any control frameworks. Details about omni_config can be found on
     176the  OmniOverview page and  OmniConfiguration page, but a sample
     177omni_config is included for reference in the Gush SVN repository. In
     178the sample omni_config file, your PlanetLab private key is stored in
     179the ~/.gcf directory. Note that this key cannot require a passphrase
     180to work with Gush. You can remove the passphrase of a private key
     181called keyin.pem, for example, by running:
     183$ openssl rsa -in keyin.pem -out keyout.pem
     185In this case, your omni_config file should include a reference to
     186keyout.pem. You can use the script included with Gush
     187(in the helper-scripts directory) to automatically download your
     188certificate. This is also a good way to make sure you have Omni
     189correctly configured to talk to the PLC aggregate manager. To do this,
     190insert your PlanetLab slice name into the following command:
     192$ helper-scripts/ -f plc -a
     193 sliverstatus <slice_name> 
     195If everything is working correctly, you should see something like
     198$ helper-scripts/ -f plc -a
     199 sliverstatus williams_gush 
     201INFO:omni:Loading config file omni_config
     202INFO:omni:Using control framework plc
     203Your certificate file (/home/jeannie/.gcf/plc.williams.jeannie.gid)
     204was not found, would you like me to download it for you to
     205/home/jeannie/.gcf/plc.williams.jeannie.gid? (Y/n)Y
     206INFO:omni.sfa:SFA Registry:
     207INFO:omni.sfa:SFA Slice Manager:
     208INFO:omni:Sliver at
     209<?xml version="1.0"?>
     211        <slice name="williams_gush">
     212                <expires>2011-04-28 13:41:35</expires>
     213                <user name=""/>
     214                <node name=""/>
     215                <node name=""/>
     216                <node name=""/>
     217                <node name=""/>
     218                <node name=""/>
     219                <node name=""/>
     220                <node name=""/>
     221                <node name=""/>
     222        </slice>
     225Please double check and make sure you have a valid key and
     226certificate, and that Omni is correctly configured before moving on!
     228* Setting up Gush
     230You need three configuration files to use Gush: directory.xml,
     231gush.prefs, and omni_config. Details about omni_config are described
     232above. For most installations, gush.prefs should not need to be
     233modified. In directory.xml, you should modify the SVN version of the
     234file to include your slice name instead of williams_gush2. For the
     235port number, choose a port greater than 61000. Please change the port!
     236You probably should reserve a port on the PlanetLab port reservation
     239To summarize, you must modify directory.xml and omni_config before
     240Gush will work!
     242That should be it! Let us know if you have problems. This is still a
     243work in progress!
     245* Gush Commands
     247You can now start Gush with "./gush -P <port number>". Using the
     248default command-line user interface, Gush tries to act like a shell
     249(well, almost -- unfortunately many of the commands are asynchronous,
     250so you don't have the nice background/foreground distinction present
     251in normal shells). A very-partial list of those commands is listed
     252below; the official source is the "terminal_parser.y" YACC file.
     255For instant gratification, try the following commands:
     257 $ ./gush -P 15555
     258   Start Gush on port 15555.
     259   Wait until Gush prints out two messages with your slice in it.
     260 gush> connect
     261   Connect to  This basically installs/starts
     262   the Gush client.
     263   Wait until you see a message about the host joining the mesh.
     264 gush> info mesh
     265   Print out the current connection status of various hosts.
     266 gush> shell "ps aux"
     267   Run "ps aux" on every connected host, and print the results locally.
     268 gush> disconnect
     269   Disconnect hosts from the mesh--this kills remote clients.
     270 gush> quit
     272There are several example application description XML files in the
     273"tests" directory that can be used to experiment with different
     274aspects of Gush.
     276* Additional Commands
     278 gush> load path: Read a project file.
     279 gush> run: Start executing the first experiment in the active project.
     280 gush> connect hostname: Start a Gush client on a remote host.
     281 gush> connect slice slice_name: Connect to all nodes assigned a slice.
     282 gush> connect pat <regex> <num>: Connect to <num> hosts that match
     283 the regular expression pattern <regex>.
     284 gush> debug fail node <hostname>: Mark node as failed and find
     285 replacement (only during experiment).
     286 gush> disconnect: Close all open connections.
     287 gush> disconnect hostname: Disconnect from a host.
     288 gush> info control: Print controller state information.
     289 gush> info nodes: Print summary information on all known nodes.
     290 gush> info node hostname: Print information about a node.
     291 gush> info slices: Print summary information on all known slices.
     292 gush> info slice slice_name: Print information about a slice.
     293 gush> info mesh: Print the mesh status (membership).
     294 gush> prefer <regex>: Tell Gush to increase preference value for
     295 nodes matching regex.  Nodes with higher preference values are used
     296 first.
     297 gush> shell <quoted string>: Run the string as a shell command on all
     298 connected nodes.
     299 gush> slice update slice_name: Get updated information for a slice
     300 from the PLC Database.
     301 gush> slice list slice_name: Show information on a slice.
     302 gush> slice renew slice_name: Renew the given slice.
     303 gush> slice add slice_name regex: Assign hosts that match regex
     304 (regular expression) to the given slice.
     305 gush> slice remove slice_name regex: Unassign hosts that match regex
     306 from the slice. 
     307 gush> quit: Quit Gush.
    31314=== GUSH Binary Package ===