perfsonar development work

Author: zurawski
Date: 2006-06-28 15:57:26 -0400 (Wed, 28 Jun 2006)
New Revision: 1342

Modified:
   branches/release/perfsonar/releng/perfSONAR-1.0/Readme.txt
   branches/release/perfsonar/releng/perfSONAR-1.0/Readme.txt.pol
Log:
Readme changes to go with e-mail commentary

-jason



Modified: branches/release/perfsonar/releng/perfSONAR-1.0/Readme.txt
===================================================================
--- branches/release/perfsonar/releng/perfSONAR-1.0/Readme.txt  2006-06-28 
13:15:24 UTC (rev 1341)
+++ branches/release/perfsonar/releng/perfSONAR-1.0/Readme.txt  2006-06-28 
19:57:26 UTC (rev 1342)
@@ -31,6 +31,10 @@
        
        http://java.sun.com/j2se/1.5.0/download.jsp
        
+       Any minor version of Java 5 will do, and the user m-
+       ay install the JRE or JDK, but is also free to inst-
+       all EE or NetBeans if so inclined.  
+       
        To install via the binary (replace X and Y with ver-
        sion numbers).  It helps to be root or use sudo as 
        you install:
@@ -96,6 +100,10 @@
        
                tar -zxf jakarta-tomcat-5.0.28.tar.gz
                mv jakarta-tomcat-5.0.28 /usr/local
+               
+       It is helpful to install symbolic links (to shorten
+       relative path names).  To do so:
+               
                cd /usr/local
                ln -s jakarta-tomcat-5.0.28 tomcat-5.0.28
                        or
@@ -124,6 +132,12 @@
                        ;;
                esac
                exit 0
+               
+       This script will need to have execute permissions:
+       
+               chmod 755 /etc/init.d/tomcat
+                       or
+               chmod +x /etc/init.d/tomcat
 
        If this service is to be visible on the outside, en-
        sure that your firewall allows traffic to reach port
@@ -147,10 +161,19 @@
        http://www.apache.org/dist/ws/axis/1_2_1/
        axis-bin-1_2_1.tar.gz
 
+       It is recommended that the 'binary' installation (n-
+       ote the 'bin' in the filename) be installed; the us-
+       er is free to install from source if desired.
+
        Installation is straight forward:
 
                tar -zxf axis-bin-1_2_1.tar.gz
                mv axis-bin-1_2_1 /usr/local/axis-bin-1_2_1
+
+
+       It is helpful to install symbolic links (to shorten
+       relative path names).  To do so:
+
                cd /usr/local
                ln -s axis-bin-1_2_1 axis-1.2.1
                        or
@@ -161,6 +184,9 @@
                cd /usr/local/tomcat/webapps
                ln -s ../../axis/webapps/axis axis
        
+       The user is also free to physical move, or hardlink
+       the directory to the appropriate location.
+       
        If you are currently running tomcat, you must of co-
        urse stop it, and re-start it to ensure axis is rec-
        ognized.
@@ -177,9 +203,14 @@
 
                http://HOSTNAME:8080/axis/happyaxis.jsp
 
-       This should fail because activation.jar is missing. 
-       This is OK for now, because it will be installed as 
-       a part of the deployment process.
+       Unfortunately, at this stage in the installation, t-
+       his will fail.  Why does this fail?  There is a key
+       library (activation.jar) and two optional libraries
+       (xmlsec.jar and mail.jar) that are not included by
+       default in the axis package.  perfSONAR DOES include
+       these libraries, and will install them as a part of
+       deployment.  For now, just be sure that you can acc-
+       ess axis, despite it not being 'happy'.
        
        After setting up axis, it is necessary to adjust so-
        me of your system paths.  This can be done in 
@@ -193,7 +224,8 @@
        Note that each .jar in the axis lib directory needs 
        to be added.  After the installation you will need 
        to to do this again for any new jars that are added 
-       as a part of the installation procedure 
+       as a part of the installation procedure (the user 
+       will be prompted as a part of the installation).
                        
 e) eXist
 ------------------------------------------------------------
@@ -237,7 +269,7 @@
                
        OPTIONS="-Dexist.home=$EXIST_HOME"
                        
-       to look like this:
+               to look like this:
                
        OPTIONS="-Dexist.home=$EXIST_HOME -Djetty.port=8680"
 
@@ -256,6 +288,11 @@
 export EXIST_HOME=/usr/local/eXist
 export PATH=$EXIST_HOME/bin:$PATH
 
+       The perfSONAR installer is now capable of helping to
+       set up eXist to a certain degree.  It is still nece-
+       ssary to follow the following steps up to (but not 
+       including) number 5.
+
        The first several steps of server configuration sho-
        uld be done before installing perfSONAR:
        
@@ -273,38 +310,55 @@
                
        3) Change the connect port to 8680, and press ok.
                
-       4) Click the 'keys' icon to create a new user
+       4a) Set up users (both users are outlined here) 
                
-               4a) Username = 'lookupservice'
+       4b) Click the 'keys' icon to create a new user
                
-               4b) Password = 'sonar'
+               4b-a) Username = 'lookupservice'
                
-               4c) Assign to 'guest' group
+               4b-b) Password = 'sonar'
                
-               4d) Press 'Create User'
+               4b-c) Assign to 'guest' group
                
-               4e) Close the window            
+               4b-d) Press 'Create User'
+               
+               4b-e) Close the window          
 
-       5) Click the 'keys' icon to create a new user
+       4c) Click the 'keys' icon to create a new user
                
-               5a) Username = 'rrdmaservice'
+               4c-a) Username = 'rrdmaservice'
                
-               5b) Password = 'rrdmaservice'
+               4c-b) Password = 'rrdmaservice'
                
-               5c) Assign to 'guest' group
+               4c-c) Assign to 'guest' group
                
-               5d) Press 'Create User'
+               4c-d) Press 'Create User'
                
-               5e) Close the window                    
+               4c-e) Close the window                  
+       
+* THE NEXT STEPS CAN BE INSTANTIATED BY THE INSTALLER *        
                
+       5) At the prompt type 'mkcol ls'
+                       
+       6) Select the 'ls' row from the display and click t-
+       he button with the 'check boxes', to change permiss-
+       ions.     
+       
+       On the new window select:
+               owner: 'lookupservice'    
+               group: 'guest'  
+
+       7) At the prompt type 'mkcol rrdmaconfig'
+                       
+       8) Select the 'rrdmaconfig' row from the display an-
+       d click the button with the 'check boxes', to chang-
+       e permissions.     
+       
+       On the new window select:
+               owner: 'rrdmaservice'    
+               group: 'guest'  
                
-       6) At the prompt type 'mkcol ls'
-               
-       7) Change the permissions to 'lookupservice' and 
-       'guest' for owner and group using the 'Check Box' b-
-       utton.
-               
-       8) Exit the client
+       9) Exit the client
 
        At this point eXist is ready to have an XML collect-
        ion imported, this will be done as a part of the in-
@@ -371,7 +425,16 @@
 
        Prior to installation make sure all previous steps
        are completed and tomcat is running.
+
+       It is important that the CLASSPATH and other envirn-
+       omental variables discussed above are installed cor-
+       rectly.  Verify each by typing:
        
+               echo $VARIABLE_NAME
+               
+       If you get a blank, something is wrong.  If you see
+       values, make sure they are the 'correct' values.
+       
        Common issues that will cause the installation to
        fail include:
        
@@ -382,7 +445,7 @@
                * CLASSPATH Issues - The axis libraries (na-
                mely all libraries in the axis directory as 
                well as what we distribute) must be in your 
-               classpath to properly use the axis administ-
+               CLASSPATH to properly use the axis administ-
                rative interface (deployment and undeployme-
                nt of the service).
                
@@ -397,15 +460,39 @@
                e installer.  If you are running into probl-
                ems consider using the text based installer.
                
+       To run the installation:
+               Graphical (jar):
+                       X access is needed (through the con-
+                       sole or by ssh -X).
+
+                       run 'java -jar perfSONAR-1.0.jar'
+               
+               Textual (perl script):
+                       X access is NOT needed
+                       
+                       unpack in the location you wish to
+                       install (/usr/local/ for example).
+
+                       Change into the unpacked directory
+                       and run 
+
+                               ./install.pl 
+                                       or 
+                               perl install.pl 
+               
+               
 ------------------------------------------------------------
 3) Use
 ------------------------------------------------------------
+       Before proceeding any further, make sure the 
+       CLASSPATH instructions the installer has relayed are
+       followed.  The application will not work correctly 
+       until this is corrected.
 
        Once installed, the services may be tested via the
        client test scripts found in the clients/ directory 
        of the installation.  These tests will verify the s-
-       ervices work.  Future releases will offer more exam-
-       ples.
+       ervices work.  
 
        The client is located in the package:
        
@@ -422,6 +509,10 @@
        Errors indicating the class file cannot be found are
        more than likely related to the CLASSPATH.
        
+       The test scripts we install will include a fabricat-
+       ed CLASSPATH, don't let this stop you from changing
+       the CLASSPATH on your own.
+       
 ------------------------------------------------------------
 4) Problems
 ------------------------------------------------------------
@@ -433,4 +524,3 @@
        And we do encourage the use of this for tracking all
        problems.  The general mailing list is discouraged
        for reporting errors.
-       

Modified: branches/release/perfsonar/releng/perfSONAR-1.0/Readme.txt.pol
===================================================================
--- branches/release/perfsonar/releng/perfSONAR-1.0/Readme.txt.pol      
2006-06-28 13:15:24 UTC (rev 1341)
+++ branches/release/perfsonar/releng/perfSONAR-1.0/Readme.txt.pol      
2006-06-28 19:57:26 UTC (rev 1342)
@@ -31,17 +31,21 @@
        
        http://java.sun.com/j2se/1.5.0/download.jsp
        
+       Any minor version of Java 5 will do, and the user m-
+       ay install the JRE or JDK, but is also free to inst-
+       all EE or NetBeans if so inclined.  
+       
        To install via the binary (replace X and Y with ver-
        sion numbers).  It helps to be root or use sudo as 
        you install:
-       
+
                chmod a+x jdk-1_5_X_Y-linux-i586-rpm.bin
                ./jdk-1_5_X_Y-linux-i586-rpm.bin
        
        If the rpm does not self install, or if you choose 
        to download the rpm attempt this (as root or with s-
        udo):
-       
+
                rpm -ivh jdk-1_5_X_Y-linux-i586.rpm
 
        This should install to /usr/java/jdk1.5.X_Y
@@ -50,10 +54,10 @@
        such as Unbuntu or Debian) you may need to use a pr-
        ogram called 'alien' to convert to debian format. T-
        conversion should look like this:
-       
+
                alien rpm -ivh jdk-1_5_X_Y-linux-i586.rpm
                dpkg -i jdk_1.5.0_07-1_i386.deb
-               
+
        This may (or may not) cause some other problems.  T-
        he basic issue is that 'pack' files are not expanded
        to their jar equivalent. To solve this problem, try 
@@ -96,6 +100,10 @@
        
                tar -zxf jakarta-tomcat-5.0.28.tar.gz
                mv jakarta-tomcat-5.0.28 /usr/local
+               
+       It is helpful to install symbolic links (to shorten
+       relative path names).  To do so:
+               
                cd /usr/local
                ln -s jakarta-tomcat-5.0.28 tomcat-5.0.28
                        or
@@ -124,6 +132,12 @@
                        ;;
                esac
                exit 0
+               
+       This script will need to have execute permissions:
+       
+               chmod 755 /etc/init.d/tomcat
+                       or
+               chmod +x /etc/init.d/tomcat
 
        If this service is to be visible on the outside, en-
        sure that your firewall allows traffic to reach port
@@ -147,10 +161,19 @@
        http://www.apache.org/dist/ws/axis/1_2_1/
        axis-bin-1_2_1.tar.gz
 
+       It is recommended that the 'binary' installation (n-
+       ote the 'bin' in the filename) be installed; the us-
+       er is free to install from source if desired.
+
        Installation is straight forward:
 
                tar -zxf axis-bin-1_2_1.tar.gz
                mv axis-bin-1_2_1 /usr/local/axis-bin-1_2_1
+
+
+       It is helpful to install symbolic links (to shorten
+       relative path names).  To do so:
+
                cd /usr/local
                ln -s axis-bin-1_2_1 axis-1.2.1
                        or
@@ -161,6 +184,9 @@
                cd /usr/local/tomcat/webapps
                ln -s ../../axis/webapps/axis axis
        
+       The user is also free to physical move, or hardlink
+       the directory to the appropriate location.
+       
        If you are currently running tomcat, you must of co-
        urse stop it, and re-start it to ensure axis is rec-
        ognized.
@@ -177,9 +203,14 @@
 
                http://HOSTNAME:8080/axis/happyaxis.jsp
 
-       This should fail because activation.jar is missing. 
-       This is OK for now, because it will be installed as 
-       a part of the deployment process.
+       Unfortunately, at this stage in the installation, t-
+       his will fail.  Why does this fail?  There is a key
+       library (activation.jar) and two optional libraries
+       (xmlsec.jar and mail.jar) that are not included by
+       default in the axis package.  perfSONAR DOES include
+       these libraries, and will install them as a part of
+       deployment.  For now, just be sure that you can acc-
+       ess axis, despite it not being 'happy'.
        
        After setting up axis, it is necessary to adjust so-
        me of your system paths.  This can be done in 
@@ -193,7 +224,8 @@
        Note that each .jar in the axis lib directory needs 
        to be added.  After the installation you will need 
        to to do this again for any new jars that are added 
-       as a part of the installation procedure 
+       as a part of the installation procedure (the user 
+       will be prompted as a part of the installation).
                        
 e) eXist
 ------------------------------------------------------------
@@ -237,7 +269,7 @@
                
        OPTIONS="-Dexist.home=$EXIST_HOME"
                        
-       to look like this:
+               to look like this:
                
        OPTIONS="-Dexist.home=$EXIST_HOME -Djetty.port=8680"
 
@@ -256,10 +288,13 @@
 export EXIST_HOME=/usr/local/eXist
 export PATH=$EXIST_HOME/bin:$PATH
 
+       The perfSONAR installer is now capable of helping to
+       set up eXist to a certain degree.  It is still nece-
+       ssary to follow the following steps up to (but not 
+       including) number 5.
+
        The first several steps of server configuration sho-
-       uld be done before installing perfSONAR (note this 
-       outlines the procedure for the LS, other services t-
-       hat use eXist will work similarly):
+       uld be done before installing perfSONAR:
        
        1) Start eXist (run this in the foreground of a spa-
        re terminal, it may be helpful to see any errors th-
@@ -275,29 +310,59 @@
                
        3) Change the connect port to 8680, and press ok.
                
-       4) Click the 'keys' icon to create a new user
+       4a) Set up users (both users are outlined here) 
                
-               4a) Username = 'lookupservice'
+       4b) Click the 'keys' icon to create a new user
                
-               4b) Password = 'sonar'
+               4b-a) Username = 'lookupservice'
                
-               4c) Assign to 'guest' group
+               4b-b) Password = 'sonar'
                
-               4d) Press 'Create User'
+               4b-c) Assign to 'guest' group
                
-               4e) Close the window            
+               4b-d) Press 'Create User'
                
-       5) At the prompt type 'mkcol ls'
+               4b-e) Close the window          
+
+       4c) Click the 'keys' icon to create a new user
                
-       6) Change the permissions to 'lookupservice' and 
-       'guest' for owner and group using the 'Check Box' b-
-       utton.
+               4c-a) Username = 'rrdmaservice'
                
-       7) Exit the client
+               4c-b) Password = 'rrdmaservice'
+               
+               4c-c) Assign to 'guest' group
+               
+               4c-d) Press 'Create User'
+               
+               4c-e) Close the window                  
+       
+* THE NEXT STEPS CAN BE INSTANTIATED BY THE INSTALLER *        
+               
+       5) At the prompt type 'mkcol ls'
+                       
+       6) Select the 'ls' row from the display and click t-
+       he button with the 'check boxes', to change permiss-
+       ions.     
+       
+       On the new window select:
+               owner: 'lookupservice'    
+               group: 'guest'  
 
+       7) At the prompt type 'mkcol rrdmaconfig'
+                       
+       8) Select the 'rrdmaconfig' row from the display an-
+       d click the button with the 'check boxes', to chang-
+       e permissions.     
+       
+       On the new window select:
+               owner: 'rrdmaservice'    
+               group: 'guest'  
+               
+       9) Exit the client
+
        At this point eXist is ready to have an XML collect-
-       ion imported, this will be done after the actual 
-       installation.
+       ion imported, this will be done as a part of the in-
+       stallation.
 
 
 f) RRDTool
@@ -360,7 +425,16 @@
 
        Prior to installation make sure all previous steps
        are completed and tomcat is running.
+
+       It is important that the CLASSPATH and other envirn-
+       omental variables discussed above are installed cor-
+       rectly.  Verify each by typing:
        
+               echo $VARIABLE_NAME
+               
+       If you get a blank, something is wrong.  If you see
+       values, make sure they are the 'correct' values.
+       
        Common issues that will cause the installation to
        fail include:
        
@@ -368,10 +442,12 @@
                ng as a user, make sure you own or have wri-
                te access to the installation path.
                
-               * CLASSPATH Issues - The axis libraries must
-               be in your classpath to properly use the ax-
-               is administrative interface (deployment and 
-               undeployment of the service).
+               * CLASSPATH Issues - The axis libraries (na-
+               mely all libraries in the axis directory as 
+               well as what we distribute) must be in your 
+               CLASSPATH to properly use the axis administ-
+               rative interface (deployment and undeployme-
+               nt of the service).
                
                * Java Version - Make sure you are using Ja-
                va 5, as the files were developed and packa-
@@ -384,15 +460,39 @@
                e installer.  If you are running into probl-
                ems consider using the text based installer.
                
+       To run the installation:
+               Graphical (jar):
+                       X access is needed (through the con-
+                       sole or by ssh -X).
+
+                       run 'java -jar perfSONAR-1.0.jar'
+               
+               Textual (perl script):
+                       X access is NOT needed
+                       
+                       unpack in the location you wish to
+                       install (/usr/local/ for example).
+
+                       Change into the unpacked directory
+                       and run 
+
+                               ./install.pl 
+                                       or 
+                               perl install.pl 
+               
+               
 ------------------------------------------------------------
 3) Use
 ------------------------------------------------------------
+       Before proceeding any further, make sure the 
+       CLASSPATH instructions the installer has relayed are
+       followed.  The application will not work correctly 
+       until this is corrected.
 
        Once installed, the services may be tested via the
        client test scripts found in the clients/ directory 
        of the installation.  These tests will verify the s-
-       ervices work.  Future releases will offer more exam-
-       ples.
+       ervices work.  
 
        The client is located in the package:
        
@@ -409,6 +509,10 @@
        Errors indicating the class file cannot be found are
        more than likely related to the CLASSPATH.
        
+       The test scripts we install will include a fabricat-
+       ed CLASSPATH, don't let this stop you from changing
+       the CLASSPATH on your own.
+       
 ------------------------------------------------------------
 4) Problems
 ------------------------------------------------------------
@@ -420,4 +524,3 @@
        And we do encourage the use of this for tracking all
        problems.  The general mailing list is discouraged
        for reporting errors.
-