sfa/iotlab/docs/source/index.rst

   1 .. Iotlab SFA driver documentation master file, created by
   2    sphinx-quickstart on Tue Jul  2 11:53:15 2013.
   3    You can adapt this file completely to your liking, but it should at least
   4    contain the root `toctree` directive.
   5
   6 Welcome to Iotlab SFA driver's documentation!
   7 =============================================
   8
   9 ===================
  10 Code tree overview
  11 ===================
  12
  13 ------------
  14 Installation
  15 ------------
  16 **Using git**
  17
  18 git clone git://git.onelab.eu/sfa.git
  19 cd sfa
  20 git checkout <version>
  21 make version
  22 python setup.py install
  23
  24 <version> can be either geni-v2 or geni-v3.
  25 ------
  26 Driver
  27 ------
  28 **Folder**:/sfa/sfa/iotlab/
  29
  30 The Iotlab driver source code is under the folder /sfa, along with the other
  31 testbeds driver folders. The /iotlab directory contains the necessary files
  32 defining API for OAR, LDAP, the postgresql table which is hosted in the SFA
  33 database as well as for the SFA managers.
  34
  35 The OAR API enables the user to get information regarding nodes and jobs:
  36 nodes properties (hostnames, radio, mobility type, position with GPS
  37 coordinates  and so on), jobs and the associated username and nodes.
  38 These are used when querying the testbed about resources
  39 and leases. In order to add a new node property in the iotlab Rspec format,
  40 the new property must be defined and parsed beforehand from OAR in the OAR
  41 API file.
  42
  43 In the LDAP file, the LDAPapi class supposes the unix schema is used.
  44 If this class is reused in another context, it might not work without some bit
  45 of customization. The naming (turning a hostname into a sfa hrn, a LDAP login
  46 into a hrn ) is also done in this class.
  47
  48 The iotlabpostgres file defines a dedicated lease table, hosted in the SFA
  49 database (in SFA version geni-v3) or in a separated and dedicated Iotlab
  50 database(in SFA geni-v2). Its purpose is to hold information that we
  51 can't store anywhere given the Iotlab architecture with OAR and LDAP, namely the
  52 association of a job and the slice hrn for which the job is supposed to run.
  53 Indeed, one user may register on another federated testbed then use his
  54 federated slice to book iotlab nodes. In this case, an Iotlab LDAP account will
  55 be created. Later on, when new users will be imported from the LDAP to the SFA
  56 database, an Iotlab slice will be  created for each new user found in the LDAP.
  57 Thus leading us to the situation where one user may have the possibility to use
  58 different slices to book Iotlab nodes.
  59
  60 ----------------------------
  61 RSpec specific Iotlab format
  62 ----------------------------
  63 **Folder**:/sfa/rspecs/versions , /sfa/rpecs/elements
  64
  65 There is a specific Iotlab Rspec format. It aims at displaying information that
  66 is not hadled in the SFA Rspec format. Typically, it adds the nodes' mobility
  67 and its mobility type, the hardware architecture as well as the radio
  68 chipset used. This is done by defining a iotlabv1 rspec version format file
  69 under /rspecs/versions. Definitions of an iotlab rspec lease, node and sliver
  70 are done in the associated files under /rspecs/elements/versions.
  71 If a property has to be added to the nodes in the Iotlab Rspec format, it
  72 should be added in the iotlabv1Node file, using the other properties as example.
  73
  74 Future work:
  75 The Rspec format has to be validated and stored on a website, as the header
  76 of the return Rspec defines it, which is not the case with the Iotlab rspec
  77 format. It has been discussed with Mohamed Larabi (Inria Sophia) once, never to
  78 be mentionned again. Although this does not prevent the SFA server from working,
  79 maybe it would be nice to be completely compliantand clean in this aspect also.
  80 -SA Dec 2013-
  81
  82 --------
  83 Importer
  84 --------
  85 **Folder**: /sfa/importer/
  86
  87 The iotlab importer task is to populate the SFA database with records created
  88 from the information given by OAR and LDAP. Running the importer periodically
  89 enables the SFA database to be in sync with the LDAP by deleting/ adding records
  90 in the database corresponding to newly deleted/ added users in LDAP.
  91
  92 --------------
  93 Documentation
  94 --------------
  95 **Folder** : /sfa/sfa/iotlab/docs
  96
  97 Thsi folder contains the sphinx files needed to generate this documentation.
  98 As of Dec 2013, and because of the SFA database connexion methods, generating
  99 the documentation fails if the database is not accessible. In this case,
 100 Iotlabimporter will not be documented.
 101 A possible workaround is to build the documentation on the SFA server hosting
 102 the SFA database (which is not a really clean way to this...).
 103 To ngenerate the documentation, do "make html" in the /docs folder, where the
 104 Makefile is located. The package python-sphinx must be installed in order
 105 for this command to work.
 106
 107
 108 --------
 109 Testing
 110 --------
 111 Two scripts have been written to help with the testing. One is dedicated for
 112 testing the Iotlab driver, OAR and LDAP classes. The second is to check if the
 113 client commands work well.
 114
 115 **Folder** : /sfa/testbeds/iotlab/tests
 116
 117 * driver_tests.py : python script to test OAR, LDAP and Iotlabdriver/ IotlabShell
 118   methods. Modify the script to add more tests if needed.
 119
 120     **starting the script** :python ./driver_tests <-option value> <option>
 121     example : python ./driver_tests -10 OAR (10 is the job_id in this case)
 122     option can be : OAR, sql, shell, LDAP , driver, all.
 123
 124 * sfi_client_tests.py : python script to test all the sfi client commands :
 125   resources, list, allocate (geni-v3), provision(geni-v3), resources, show, status
 126   and delete. In the geni-v2 branch, this script uses create_sliver instead.
 127
 128     **starting the script** : python ./sfi_client_tests.py <absolute path to the
 129     rspecs>.
 130     The Rspecs are included in the git repository under ./sfa/testbeds/iotlab/tests/tests_rspecs.
 131
 132
 133
 134 .. toctree::
 135    :maxdepth: 2
 136
 137 Code Documentation
 138 ==================
 139
 140 .. toctree::
 141    :maxdepth: 2
 142
 143    iotlab.rst
 144    versions.rst
 145    importer.rst
 146
 147
 148
 149 Indices and tables
 150 ==================
 151
 152 * :ref:`genindex`
 153 * :ref:`modindex`
 154 * :ref:`search`
 155