perfsonar development work

[Mario Reale <>]

Deal All,

this is a proposal for a common template to provide feedback and share 
expertise on the deployment of the web services, and to gather the 
installation, configuration, start up experiences and expertise to
contribute to the consolidation of the FAQs.
Comments, corrections and suggestions are very welcome !

Kind Regards,

Mario





         Proposed Template to report problems while deploying the PerfSONAR 
Services GEANT2 JRA-1
                                              version 0.1    20070502         
      
======================================================================================================================

The idea behind this template is that points 0-11 can be filled in also if 
the exact cause of the problem was not identified
   and therefore the issue not solved, just to report about it. ( leaving the 
remaining parts of the template empty).

On the other end, if the problem has been identified and solved (see point 
1), to share this information with others, 
points 12 to 17 have also to be filled in. 

======================================================================================================================
0. My (our) name, organization, contact information.

1. Did I finally manage to solve the problem ( and I want to use this 
template to share this information with others),
   or am I still stuck with this issue ( and I would like to fill in this 
template just to report about this problem
   and eventually ask for help )  ?
           Pls state YES or NO.

            Example: YES
                                                                              
                                   
2. Deployed Service showing problems:  (Name of the Service or the component)

                Example:    PerfSONAR RRD MA JAVA implentation

3. Used operating system specification : i.e. I deployed this service on 
which OS? ( /etc/issue on a Linux box)

            Example:   Fedora Core release 5

4. Corresponding used kernel version : ( output of 'uname -a' on a Linux box )

            Example : 2.6.18-1.2239.fc5smp

5. Source for service set up:
   (i.e. Where did I get the informations from): ( URL, and/or Document Name )

            Example: 
http://wiki.perfsonar.net/jra1-wiki/index.php/PerfSONAR_v2.0#RRD_Measurement_Archive_.28Java.29

6. If the service set up requires the definition of an initial set of ENV 
variables, please specify your settings.

            Example :  INSTALL_DIR = /usr/local/perfsonar

7. Used Linux shell to perform the installation/configuration/start up steps

            Example :   /bin/bash

8. Used Linux user to perform the installation/configuration/start up steps
           
            Example :  root

9. Were the provided instructions (at least in principle, irrespective of the 
specific encountered problem ) 
     clear enough to clearly download, install, configure, start the required 
services or was it necessary to guess
     or use trial-and-error at some stage in the service set up ? Pls state 
YES or NO.

            Example : NO

10. At which step did problems show out ? 
   A problem can be a faulty behaviour of the software or the impossibility 
to proceed
   further in the set up due to lack of information in the documentation

   Generic Steps :
               4.1 Download of initially required files
               4.2 Editing of a required configuration file or editing of an 
auxiliary data file
               4.3 Download of further required files  ( config files, 
templates, libraries, external packages...)
               4.4 Performing web service configuration
               4.5 Starting the service : the service couldn't start or 
started reporting errors
               4.6 Performing the very first minimal smoke and basic black 
box , functional tests  

            Example :  At stage 1 : Initial download of files    


11. Problem symptoms : Phenomenology of the problem. Describe the problem.

   Provide a short description including possibly reported error messages 
from the service or in relevant corresponding log files
   (specify the reference log file)

   Example :  Tomcat is not starting. catalina.out states " impossible to 
find the web application". 
                    
==================================================================================================================================

12. Guessed cause of the problem ( generally to be filled in if answer to 
point 1 is 'YES') : Description.

   Example:

   While debugging the problem I realized that the problem was due to the 
wrong version of the python-ldap package. 

13. Which file did I have to modify or add to solve this problem ( absolute 
path on my node )

   Example:

   /usr/local/perfSONAR-RRD-MA-2.0-RC8/perfsonar/conf/services.properties    
MODIFIED
   /usr/local/apache-tomcat-6.0.7/conf/catalina.properties  MODIFIED
   /var/www/html/repo/app/apps.conf   ADDED

14. Relevant log files I looked at, which have helped me to understand what 
the problem was:

  Example:

  /var/log/messages
  /usr/local/apache-tomcat-6.0.7/logs/catalina.out     
 
15. For each modified file, please report exactly the required modifications 
you have performed on them (see point 13)

 Example:

 file : 
/usr/local/perfSONAR-RRD-MA-2.0-RC8/perfsonar/conf/services.properties : 
 I added 
        service.r.ma.format=rrd
 
  
16. For each added file, please provide an example of the one you used to 
solve the problem. ( see point 13)

   Example:

    I have put on http://www.mydomain.com/myweb/apps.conf   an example for 
the file I had to add.
  

17. Summary/Issue Classification item

    The observed problem can in the end be classified as (items are not 
necessarely mutually exclusive):
    
----------------------------------------------------------------------------------------------------
         1. missing or unclear/wrong set of service setup 
instructions/documentation (i.e. : Just adding a set of instructions steps
             which were not reported has solved the issue)

          If so, i.e. the problem can be related in any mean by a mistake or 
a lack in the install instructions  
          or could anyhow be avoided in future by improving the provided 
documentation,
          please provide a set of instructions you consider actually missing 
from the set of already provided ones to set up the
          specific service, referring to a document on the web or a wiki 
page, providing a set of suggested editing instructions
          like :

              For Example:

          With reference to the doc/instructions at 
           
http://wiki.perfsonar.net/jra1-wiki/index.php/PerfSONAR_v2.0#RRD_Measurement_Archive_.28Java.29

          "(I would) add before line 5 ('.......then issue the command 
"service network restart"......' ) the following sentence
          "Perform now the login as root and then..."

         2. wrong version of the reference operating system used ( no upgrade 
of a specific OS package could solve the problem)
         3. wrong version of a specific package on my OS ( I could correct 
this problem by upgrading package X to version # Y)
            if so, pls provide the exact package names and version which 
proved to let the service work properly.
         4. a specific OS or external package missing on my node. If so, 
please specify the exact package name and version and
            the source you used for it
         5. firewalling or port # issues ( unreachable services, wrong port 
or unaccessible port )
            if so, pls provide the used cure : I configured port #X to be 
accessible on my node for TCP..
         6. unavailable reference services or nodes ( for example, the look 
up service I specified was not up)
         7. wrong version of the Linux kernel I was using or wrong kernel 
configuration.
            if so, please report about which kernel version or which config 
before kernel rebuild have solved the problem.
         8. wrong set of permissions or ownership on a file (for example 
adding 'o+x' on the file $INSTALL_DIR/myservice.config has 
            solved the problem).
         9. wrong set of permissions or ownership on a directory ( for 
example chmod 766 $INSTALL_DIR/logfiles/ has solved the problem)
        10. a clear or probable bug in a provided deployment, download or 
configuration script.
            if so, please make sure you specify here the bug and you post it 
in a reference global bug tracking system 
            if available.
        11. a missing user in the node. If so, please specify which one.
        12. a wrongly set password to access a specific service. If so, pls 
specify where.
        13. missing X509 certificates on a specific location on the 
filesystem, or corresponding missing CA files, or wrongly
            set ownerships or file access modes on these.

        14. any other issue : please specify it. (this will help to define a 
new "issue category" on later versions of this template)
           .............

   Example Answers to point 17:

         Answer 1 
         ========
         Item Category: 4
         The package perl-DBI was mising. I installed version 1.32-9 taken 
from rpmfind.net at this exact link: http://.....

         Answer 2  
         ========
         Item Category: 9
         I had to issue   'chmod 744 /var/www/html'
 
         Answer 3
         ========
         Item Category: 1

         With reference to the doc/instructions at 
         
http://wiki.perfsonar.net/jra1-wiki/index.php/PerfSONAR_v2.0#RRD_Measurement_Archive_.28Java.29

          "(I would) add before line 5 ('.......then issue the command 
"service network restart"......' ) the following sentence
          "Perform now the login as root and then..."