1 | | REady for documentation |
| 1 | Tmix |
| 2 | |
| 3 | This is a quick start guide for the GCF software package. Run these steps to get the sample API implementations running. |
| 4 | |
| 5 | We recommend that users who only want Omni still run these steps to verify that all dependencies are met. Omni shares at least the Python, PyOpenSSL, and dateutil dependencies. |
| 6 | |
| 7 | Software Dependencies |
| 8 | GCF depends on the following packages: |
| 9 | |
| 10 | Python M2Crypto |
| 11 | |
| 12 | 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. |
| 13 | |
| 14 | More information is available at: http://chandlerproject.org/bin/view/Projects/MeTooCrypto |
| 15 | |
| 16 | Python dateutil |
| 17 | |
| 18 | The dateutil package provides date parsing routines to Python. It should be readily available on most Linux distributions. |
| 19 | |
| 20 | More information is available at: http://labix.org/python-dateutil |
| 21 | |
| 22 | Python OpenSSL |
| 23 | |
| 24 | 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.) |
| 25 | |
| 26 | More information is available at: https://launchpad.net/pyopenssl |
| 27 | |
| 28 | xmlsec1 |
| 29 | |
| 30 | 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. |
| 31 | |
| 32 | On rpm systems the required packages are: |
| 33 | |
| 34 | xmlsec1 |
| 35 | xmlsec1-openssl-devel |
| 36 | On debian systems the packages are |
| 37 | |
| 38 | libxmlsec1 |
| 39 | xmlsec1 |
| 40 | libxmlsec1-openssl |
| 41 | libxmlsec1-dev |
| 42 | More information is available at: |
| 43 | |
| 44 | http://www.aleksey.com/xmlsec/ |
| 45 | http://www.w3.org/TR/xmlenc-core/ |
| 46 | http://www.ietf.org/rfc/rfc3275.txt |
| 47 | Platform Installation |
| 48 | The GCF package is intended to be run on a modern Unix distribution (circa 2010 or 2009). Python 2.6 or better is required. This software is not Python 3 compatible. |
| 49 | |
| 50 | 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). |
| 51 | |
| 52 | Debian / Ubuntu |
| 53 | |
| 54 | sudo apt-get install python-m2crypto python-dateutil \ |
| 55 | python-openssl libxmlsec1 xmlsec1 \ |
| 56 | libxmlsec1-openssl libxmlsec1-dev |
| 57 | RedHat / Fedora |
| 58 | |
| 59 | sudo yum install m2crypto python-dateutil pyOpenSSL xmlsec1 \ |
| 60 | xmlsec1-devel xmlsec1-openssl xmlsec1-openssl-devel |
| 61 | CentOS |
| 62 | |
| 63 | Please see InstallCentOs. |
| 64 | |
| 65 | Mac OS X |
| 66 | |
| 67 | Using homebrew |
| 68 | |
| 69 | These instructions use homebrew. |
| 70 | |
| 71 | To install: |
| 72 | |
| 73 | brew install python |
| 74 | This will install python at /usr/local/bin but the python that comes with Mac OS is at /usr/bin which takes precedent in the path, so modify your ~/.profile file and add this line: |
| 75 | export PATH=/usr/local/bin:$PATH |
| 76 | and then run source ~/.profile |
| 77 | |
| 78 | Type which python to ensure that you are using the right one. |
| 79 | brew install swig |
| 80 | pip install M2Crypto |
| 81 | brew install libxmlsec1 |
| 82 | pip install python-dateutil |
| 83 | brew install xmlsec1 |
| 84 | pip install pyopenssl |
| 85 | omni-configure.py and omni.py assume that your python is at /usr/bin/python so you have two options: |
| 86 | always invoke them using python, e.g. python src/omni-configure.py and python src/omni.py |
| 87 | modify the first line in each of the files to be #!/usr/local/bin/python |
| 88 | 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). |
| 89 | |
| 90 | MacPorts Instructions |
| 91 | |
| 92 | These instructions have not recently been tested. You may need to edit your PATH or PYTHONPATH to ensure all installed modules are properly found. |
| 93 | |
| 94 | You must have MacPorts already installed. |
| 95 | |
| 96 | sudo port install py26-m2crypto py26-dateutil py26-openssl xmlsec |
| 97 | cd /opt/local/lib |
| 98 | sudo ln -s libxmlsec1-openssl.dylib libxmlsec1-openssl.so |
| 99 | In each terminal that you wish to run GCF, run this command first for xmlsec1: |
| 100 | |
| 101 | export DYLD_LIBRARY_PATH=/opt/local/lib |
| 102 | Windows / Cygwin |
| 103 | |
| 104 | The necessary libraries are likely available but we have no experience running in this environment. |
| 105 | |
| 106 | Test Run |
| 107 | Here is a 4 step test install of this software. Full usage instructions for each step are in README.txt |
| 108 | |
| 109 | Create gcf_config |
| 110 | cd gcf |
| 111 | cp gcf_config.sample gcf_config |
| 112 | Optional: Edit gcf_config if you want to change settings from the default. |
| 113 | |
| 114 | Note: for a test run edits are not needed. Do this only if you want to change settings from the defaults. |
| 115 | |
| 116 | Create certificates and run the GENI Clearinghouse In terminal one: |
| 117 | cd gcf |
| 118 | python src/gen-certs.py |
| 119 | python src/gcf-ch.py |
| 120 | Run the GENI Aggregate Manager in a second terminal: |
| 121 | python src/gcf-am.py |
| 122 | Run the gcf client test script in a third terminal window: |
| 123 | python src/gcf-test.py |
| 124 | You should see output like this: |
| 125 | |
| 126 | $ python src/gcf-test.py |
| 127 | INFO:gcf-test:CH Server is https://localhost:8000/. Using keyfile /home/jkarlin/dev/gcf/alice-key.pem, certfile /home/jkarlin/dev/gcf/alice-cert.pem |
| 128 | INFO:gcf-test:AM Server is https://localhost:8001/. Using keyfile /home/jkarlin/dev/gcf/alice-key.pem, certfile /home/jkarlin/dev/gcf/alice-cert.pem |
| 129 | Slice Creation SUCCESS: URN = urn:publicid:IDN+geni:gpo:gcf+slice+1468-659:127.0.0.1%3A8000 |
| 130 | Testing GetVersion... passed |
| 131 | Testing ListResources... passed |
| 132 | Testing CreateSliver... passed |
| 133 | Testing SliverStatus... passed |
| 134 | Testing ListResources... passed |
| 135 | Testing RenewSliver... passed. (Result: False) |
| 136 | Testing DeleteSliver... passed |
| 137 | Testing ListResources... passed |
| 138 | Second Slice URN = urn:publicid:IDN+geni:gpo:gcf+slice+065e-c63:127.0.0.1%3A8000 |
| 139 | Testing ListResources... passed |
| 140 | Testing CreateSliver... passed |
| 141 | Testing Shutdown... passed |
| 142 | Next Steps |
| 143 | If you ran in to issues or your output looks different |
| 144 | |
| 145 | Confirm you followed the install instructions including dependencies |
| 146 | See the Omni Troubleshooting page for more detailed help |
| 147 | Look at the source for the reference aggregate manager to understand how the API and credentials are used, or to implement your own AM. |
| 148 | |
| 149 | See README-omni.txt to try the Omni client for talking to multiple aggregate managers and control frameworks. |
| 150 | |
| 151 | Try federating your test GCF aggregate manager with another clearinghouse. For details, see README.txt |
| 152 | |
| 153 | Further reading is on the GENI Wiki, as listed in README.txt. |