Merge pull request #18 from enolfc/docs

Doc update

Author: alvarolopez

doc/source/configuration.rst

@@ -16,16 +16,16 @@
 Configuration
 *************
 
-Caso configuration
+cASO configuration
 ==================
 
-caso uses a config file (default at ``/etc/caso/caso.conf``) with several
+``cASO`` uses a config file (default at ``/etc/caso/caso.conf``) with several
 sections. A sample file is available at ``etc/caso/caso.conf.sample``.
 
 ``[DEFAULT]`` section
 ---------------------
 
-The ``[DEFAULT]`` section configures the basic behavior of caso. The sample
+The ``[DEFAULT]`` section configures the basic behavior of ``cASO``. The sample
 config file (``/etc/caso/caso.conf.sample``) includes a description
 of every option. You should check at least the following options:
 
@@ -45,16 +45,38 @@ of every option. You should check at least the following options:
 -----------------------
 
 This section specifies the configuration of the extractor (mainly the
-credentials to connect to the API. Check the following:
+credentials to connect to the API). Check the following:
 
 * ``user`` (default: ``accounting``), name of the user. This user needs proper
   permission to query the API for the tenant usages.
 * ``password`` (default: None), password of the user.
 * ``endpoint`` (default: None), keystone endpoint to authenticate with.
 * ``mapping_file`` (default: ``/etc/caso/voms.json``). File containing the
   mapping from VOs to local tenants as configured in Keystone-VOMS. If
-  you are running caso on keystone host, it likely
+  you are running ``cASO`` on keystone host, it likely
   is ``/etc/keystone/voms.json``. Otherwise, you have to sync this file.
+* ``insecure`` (default: ``False``), wether to check or not the server's
+  certificate.
+
+.. important::
+   Your should not use ``insecure=True`` in production! If you get a SSL
+   error ( ``CERTIFICATE_VERIFY_FAILED``), this is probably due to the fact
+   that the request module CA bundle does not contain the CA of your server.
+
+   If you are using the request module of your distribution package, it is
+   normally patched to use the system's default CA bundle
+   (``/etc/ssl/certs/ca-certificates.crt`` from the ``ca-certificates``
+   package on Debian systems and ``/etc/pki/tls/certs/ca-bundle.crt`` from the
+   ``ca-certificates``on RH systems). Check the packages documentation to add a
+   new CA to those bundles.
+
+   If you are not installing request through the distribution packages (e.g.
+   via pip), it uses its own vendorized CA bundle, located in the distribution
+   directory (i.e. requests/cacert.pem). It should be enough to append the
+   correct certificates to the end of the cacert.pem file. In a virtualenv,
+   the bundle should be located at
+   ``$VIRTUAL_ENV/lib/python2.7/site-packages/requests/``
+
 
 ``[ssm]`` section
 -----------------
@@ -81,7 +103,7 @@ OpenStack Configuration
 The user configured in the previous section has to be a member of each of the
 tenants (another option is to convert that user in an administrator, but the
 former option is a safer approach) for which it is extracting the accounting.
-Otherwise, ``caso`` will not be able to get the usages and will fail::
+Otherwise, ``cASO`` will not be able to get the usages and will fail::
 
     keystone role-create --name accounting
     keystone user-create --name accounting --pass <password>

doc/source/index.rst

@@ -14,12 +14,12 @@
       under the License.
 
 =======================================
-caso, an OpenStack Accounting extractor
+cASO, an OpenStack Accounting extractor
 =======================================
 
-caso is a pluggable extractor of `Cloud Accounting Usage Records
+``cASO`` is a pluggable extractor of `Cloud Accounting Usage Records
 <https://wiki.egi.eu/wiki/Fedcloud-tf:WorkGroups:Scenario4#Cloud_Accounting_Usage_Record>`_
-from an OpenStack installation. caso gets usage information from nova or
+from an OpenStack installation. ``cASO`` gets usage information from nova or
 ceilometer APIs and can generate valid output for `Apel SSM
 <https://wiki.egi.eu/wiki/APEL>`_ or `logstash <http://logstash.net/>`_.
 

doc/source/installation.rst

@@ -22,7 +22,7 @@ Installation
 Pre-requisites
 --------------
 
-If you are planning to use caso for generating accounting records for EGI,
+If you are planning to use ``cASO`` for generating accounting records for EGI,
 you will need a valid APEL/SSM configuration. Follow the documentation
 available at the `EGI FedCloud wiki
 <https://wiki.egi.eu/wiki/Fedcloud-tf:WorkGroups:Scenario4#Publishing_Records>`_
@@ -38,3 +38,41 @@ Or, if you have virtualenvwrapper installed::
 
     $ mkvirtualenv caso
     $ pip install caso
+
+CentOS 6
+********
+    
+On CentOS 6, you can use Software Collections to install Python 2.7::
+    
+    $ yum -y install centos-release-SCL
+    $ yum -y install python27
+
+There are also some dependencies of the packages used by ``cASO`` that need to
+be installed (gcc, libffi-devel adn openssl-devel)::
+
+    $ yum -y install gcc libffi-devel openssl-devel
+    
+You can then install pip for that version of Python and use that to install
+``cASO``::
+
+    $ scl enable python27 bash
+    $ easy_install-2.7 pip
+    $ pip install caso
+    $ exit    # this terminates bash with the SCL python2.7
+
+In this case you can later on use ``caso-extract`` with the following command
+line::
+
+    $ scl enable python27 caso-extract
+
+Alternatively, if you want to use a virtualenv::
+
+    $ scl enable python27 bash
+    $ virtualenv caso
+    $ . caso/bin/activate
+    $ pip install caso
+    $ exit    # this terminates bash with the SCL python2.7
+
+Running from the virtualenv::
+
+    $ scl enable python27 caso/bin/caso-extract

doc/source/usage.rst

@@ -20,12 +20,14 @@ Usage
 command line
 ------------
 
-caso provides the ``caso-extract`` command to generate new records from your OpenStack deployment.
+``cASO`` provides the ``caso-extract`` command to generate new records from
+your OpenStack deployment.
 ``caso-extract -h`` will show a complete list of available arguments.
 
-Use the ``--extract_from`` argument to specify the date from when the records should be extracted. If no
-value is set, then caso will extract the records from the last run. If equal to "None", then extract
-records from the beggining of time.  If not time zone is specified, UTC will be used.
+Use the ``--extract_from`` argument to specify the date from when the records
+should be extracted. If no value is set, then ``cASO`` will extract the records
+from the last run. If equal to "None", then extract records from the beggining
+of time.  If not time zone is specified, UTC will be used.
 
 .. important::
    If you are running an OpenStack Nova version lower than Kilo there is a
@@ -41,6 +43,17 @@ records from the beggining of time.  If not time zone is specified, UTC will be
 Running as a cron job
 ---------------------
 
-The best way of running ``caso`` is via a cron job like the following::
+The best way of running ``cASO`` is via a cron job like the following::
 
     10 * * * * caso-extract
+
+Migration from OSSSM
+--------------------
+
+If you had a previous installation of osssm, you can migrate to ``cASO``
+following these steps:
+
+#. Remove the previous osssm installation (e.g. remove apel-ssm-openstack rpm).
+#. Remove any cron jobs related to ``osssm.extract`` or ``osssm.push``, a single
+   cron job as described above is enough. You should keep the cron job that executes
+   ``ssmsend``, this is still needed to send the records to the accounting database.