[Osaas-commits] r82 - in trunk: . doc/source

scm-commit@wald.intevation.org scm-commit at wald.intevation.org
Wed Nov 3 14:19:14 CET 2010


Author: iweinzierl
Date: 2010-11-03 14:19:14 +0100 (Wed, 03 Nov 2010)
New Revision: 82

Modified:
   trunk/ChangeLog
   trunk/doc/source/about.rst
   trunk/doc/source/contrib.rst
   trunk/doc/source/index.rst
   trunk/doc/source/installation.rst
   trunk/doc/source/running.rst
Log:
Reviewed the documentation.

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog	2010-11-02 11:36:51 UTC (rev 81)
+++ trunk/ChangeLog	2010-11-03 13:19:14 UTC (rev 82)
@@ -1,3 +1,11 @@
+2010-11-03  Ingo Weinzierl <ingo at intevation.de>
+
+	* doc/source/about.rst,
+	  doc/source/running.rst,
+	  doc/source/contrib.rst,
+	  doc/source/installation.rst,
+	  doc/source/index.rst: Reviewed the documentation.
+
 2010-11-02  Ingo Weinzierl <ingo at intevation.de>
 
 	* doc/make.bat,

Modified: trunk/doc/source/about.rst
===================================================================
--- trunk/doc/source/about.rst	2010-11-02 11:36:51 UTC (rev 81)
+++ trunk/doc/source/about.rst	2010-11-03 13:19:14 UTC (rev 82)
@@ -28,20 +28,29 @@
 The main goal of *OSAAS* is to track access to your OGC web services for the
 purpose of statistics. In addition to that, its integrated user authentication
 enables you to take account for accessing OGC services.
+
 For this reason, an *OSAAS* client (e.g. deegree OWS-Proxy with *OSAAS* hook)
-communicates with an *OSAAS* server. The client works as Proxy in front of the
-actual OWS and recieves OGC requests and forwards them to the actual OWS. In
-addition to that, it sends information about each request to *OSAAS* server.
+communicates with an *OSAAS* server. The client works as proxy in front of the
+actual OWS. It recieves the OGC requests and forwards them to the actual OWS, as
+well as it sends information about each of those requests to *OSAAS* server.
 Currently, the only way of communication between client and server takes place
-via HTTP-POST based on HTTP-BasicAuth. Finally, *OSAAS* server logs the OGC requests to a database, that
-makes these information available for other tools - *OWS Web-Statistics* is one
-of this tools.
+via HTTP-POST using HTTP-BasicAuth to authenticate *OSAAS* clients.
 
+.. note::
+
+    The goal of *OSAAS* user authentication is to grant an *OSAAS* client
+    access to *OSAAS* server. It is absolutely independent from the user
+    authentication of OWS-Proxy.
+
+Finally, *OSAAS* server logs the OGC requests to a database, that makes these
+information available for other tools - *OWS Web-Statistics* is one of this
+tools.
+
 .. image:: img/osaas_diagram.png
 
 Some tools of *OSAAS* server have been created with the aim to make the
 installation and configuration as easy as possible. For example, there is a tool
 that creates new users, another one creates the whole data model based on the
 configuration file. So it is not necessary for the user to know about the
-database schema in detail. For more information see the chapter `Installing OSAAS Server`.
+database schema in detail. For more information see :ref:`OSAAS Installation <installation-label>`.
 

Modified: trunk/doc/source/contrib.rst
===================================================================
--- trunk/doc/source/contrib.rst	2010-11-02 11:36:51 UTC (rev 81)
+++ trunk/doc/source/contrib.rst	2010-11-03 13:19:14 UTC (rev 82)
@@ -2,7 +2,7 @@
 Contrib
 =======
 
-Currently, the contrib directory contains a two scripts - a python script named
+Currently, the contrib directory contains two scripts - a python script named
 *billing.py* and an init script named *osaas*.
 
 Init script
@@ -24,10 +24,10 @@
 logging to. Each GetFeature request that could be found is sent to the WFS
 service again - with a little difference: the script doesn't query for the
 features itself, but for the number of features that would have been retrieved
-by this GetFeature request. Finally, the retrieved number is written into the
-database.
+by this GetFeature request (the *resultType=hits* parameter is set in this
+GetFeature request). Finally, the retrieved number is written into the database.
 
-The following sections describe the configuration and usage of *billing.py*.
+The next sections describe the configuration and usage of *billing.py*.
 
 
 PostgreSQL Configuration

Modified: trunk/doc/source/index.rst
===================================================================
--- trunk/doc/source/index.rst	2010-11-02 11:36:51 UTC (rev 81)
+++ trunk/doc/source/index.rst	2010-11-03 13:19:14 UTC (rev 82)
@@ -9,7 +9,7 @@
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    about.rst
    installation.rst

Modified: trunk/doc/source/installation.rst
===================================================================
--- trunk/doc/source/installation.rst	2010-11-02 11:36:51 UTC (rev 81)
+++ trunk/doc/source/installation.rst	2010-11-03 13:19:14 UTC (rev 82)
@@ -21,24 +21,27 @@
 - cx_Oracle >= 4.3.1 (see http://www.python.net/crew/atuining/cx_Oracle/)
 - psycopg2 >= 2.0.5.1 (see http://www.initd.org/pub/software/psycopg/)
 
-After downloading and installing the requirements, you should download *OSAAS*.
-You can do this using *Subversion* (see http://svnbook.red-bean.com/) with the
-following command::
+After downloading and installing the required software, you should download
+*OSAAS* from `wald.intevation.org <http://wald.intevation.org/frs/?group_id=33&release_id=158/>`_
+or using *Subversion* (see http://svnbook.red-bean.com/) with the following
+command::
 
   svn checkout https://svn.wald.intevation.org/svn/osaas/trunk osaas-trunk
 
-or download the tarball from `wald.intevation.org <http://wald.intevation.org/frs/?group_id=33&release_id=158/>`_.
+.. note::
 
+   The recommended way of getting *OSAAS* is to download the tarball of an
+   official release instead of checking out the development branch via SVN.
 
 PostgreSQL Configuration
 ------------------------
 
-The next step it to configure your PostgreSQL database. If you have installed
-PostgreSQL from packages, the path definitions of the next steps should fit to
-your environment. Otherwise, the pathes may differ.
+The next step is to set up your PostgreSQL database. If you have installed
+PostgreSQL from Debian packages, the path definitions of the next steps should
+go with your environment. Otherwise, the pathes may differ.
 
 At first, you should create a user *osaas* and the database *osaas_logging* with
-the following commands::
+the commands below::
 
   su postgres -c "createuser -SDRleP osaas"
   su postgres -c "createdb -O osaas osaas_logging"
@@ -56,52 +59,52 @@
 
   host osaas_logging osaas  127.0.0.1/32 md5
 
-The PostgreSQL configuration is finished. Restart PostgreSQL with the command::
+Now, the PostgreSQL database is ready. Restart it with the command::
 
   /etc/init.d/postgresql restart
 
 
+.. _installation-label:
+
 OSAAS Server Installation
 -------------------------
 
 *OSAAS* server is written in python and needs no explicit installation.
-Downloading the sources from SVN or tarball is all you need to do. But there
-are some things you need to initialize before you are able to run *OSAAS*.
+Downloading the tarball from `wald.intevation.org <http://wald.intevation.org/frs/?group_id=33&release_id=158/>`_
+or via SVN is all you need to do. But there are some things you need to
+initialize before you are able to run *OSAAS*.
 
-First of all: *OSAAS* server requires authentication. Use the ``adduser.py`` script
-to create new users. The following command will create a new user *osaas*.
-Executing this command, you will be asked for a password for the user *osaas*.
-Afterwards, the user and its hashed password are stored in the user database
-file given with the -f option. In this case, users and passwords are stored in
-*my-osaas-users*::
+First of all: *OSAAS* server requires a user authentication. Use the
+``adduser.py`` script to create new users. The following command will create a
+new user *osaas* and ask you for a password for this user. Afterwards, the user
+and its hashed password are stored in the user database file given with the -f
+option. In this case, users and passwords are stored in *my-osaas-users*::
 
   ./server/adduser.py -f my-osaas-users osaas
 
-*OSAAS* itself reads a configuration file. ``server/demo-config.xml`` is a demo
-configuration. See `Configuration`_ for more details on possible configuration
-options.
+*OSAAS* itself reads a configuration file that contains the database connection
+parameters, server settings and information about *OSAAS* datamodel.
+``server/demo-config.xml`` is a demo configuration. See `Configuration`_ for
+more details on possible configuration options.
 
 After creating a new user and a configuration file, you are ready to initialize
 the database using ``initosaasdb.py``. ``initosaasdb.py`` reads your
 configuration and creates all necessary database tables - independent of which
-database (Oracle or PostgreSQL) you use. Initialize the database with the
-following command::
+database (Oracle or PostgreSQL) you use. Initialize the database with::
 
   ./server/initosaasdb.py --config-file=my-osaas-config.xml
 
-If everything was fine, you can start *OSAAS* server with the following line::
+If everything was fine, you can start *OSAAS* server (see
+:ref:`Start\/Stop OSAAS Server <running-label>`).
 
-  ./server/startosaas.py --config-file=my-osaas-config.xml
 
-
-
 =============
 Configuration
 =============
 
 As already mentioned above, you can find a demo configuration in
 ``server/demo-config.xml``. To understand the config options, please read the
-comments inline the demo configuration::
+comments inline this configuration::
 
     <?xml version="1.0"?>
     <OSAASConfig>
@@ -197,13 +200,13 @@
 the OSAAS server. The build process uses ant. So, you need to make clear that
 you have ant installed (http://ant.apache.org/).
 
-Now, if you have ant installed on your machine, you can change to the the
+Now, if you have ant installed on your machine, you can change to the
 ``client/java/`` directory and enter the following command::
 
   ant
 
-The default target builds a jar file in the ``dist/`` subdirectory. Use this
-file in your client.
+The default ant target builds a ``osaas-client.jar`` file in the ``dist/``
+subdirectory. Use this file in your client.
 
 
 Integration in *deegree OWSProxy*
@@ -211,8 +214,8 @@
 
 First of all, you need to download the deegree2 sources in a specific version,
 apply the patch ``client/java/owsproxy/owsproxy.diff`` and make *OSAAS* client
-available to deegree. Finally you are ready to build *deegree OWSProxy*. Follow
-the instructions below to do so:
+available to deegree. After this, you are ready to build *deegree OWSProxy*.
+Follow the instructions below:
 
 1. Download the sources using deegree::
 
@@ -223,7 +226,8 @@
     cd deegree-osaas
     patch -p 0 < owsproxy.diff
 
-3. Make the osaas client code available to deegree::
+3. Make the osaas client code available to deegree (``$DIST_HOME_OSAAS_CLIENT``
+   is the directory where ``osaas-client.jar`` is located)::
 
     cd deegree-osaas/lib
     ln -s $DIST_HOME_OSAAS_CLIENT/ osaas
@@ -237,7 +241,9 @@
 WEB-INF/web.xml file as the *OWSProxy* configuration. Add the following lines to
 this file and replace the url, username, password and faillog::
 
-    <!-- The URL to which the OSAAS logging information is to be posted --> 
+    <!-- The URL to which the OSAAS logging information is to be posted
+         Note: The url has to end with a '/'.
+    --> 
     <init-param>
        <param-name>OSAAS_URL</param-name>
        <param-value>http://localhost:8989/owsaccounting/</param-value>

Modified: trunk/doc/source/running.rst
===================================================================
--- trunk/doc/source/running.rst	2010-11-02 11:36:51 UTC (rev 81)
+++ trunk/doc/source/running.rst	2010-11-03 13:19:14 UTC (rev 82)
@@ -1,3 +1,6 @@
+
+.. _running-label:
+
 =======================
 Start/Stop OSAAS Server
 =======================
@@ -13,6 +16,7 @@
 
 - the script requires your configuration at ``/etc/osaas/osaas-config.xml``
 - the script needs to have executable permissions
+- the script requires an osaas-user to run under
 
 If both points are clear, you are able to start *OSAAS* server with the
 following command::
@@ -23,25 +27,79 @@
 
     /etc/init.d/osaas stop
 
-**NOTE**: By default, the init script requires an osaas-user to run under.
 
-
 Start/Stop *OSAAS* from sources
 -------------------------------
 
-To start *OSAAS* server from sources, you just need to use the ``startosaas.py``
+To start *OSAAS* server from sources, you will have to use the ``startosaas.py``
 script. Change to the directory where the script is located and type::
 
     ./startosaas.py --config-file=your-config.xml
 
-Run::
+This line starts *OSAAS* server with a configuration located in
+``your-config.xml``. Note, that all of the settings from config file, except of
+the DBRules, can be specified on the command line as well. You can find a list
+of all available command line options below:
 
-    ./startosaas.py --help
+--config-file=CONFIG_FILE\
+  Use this option to specify the osaas configuration that should be used to run
+  *OSAAS*.
 
-to see all command line options of the start script. All of the settings from
-config file, except of the DBRules, can be specified on the command line as
-well.
 
+--port=PORT\
+  Use this option to specify the port the *OSAAS* server will listen on.
+
+
+--access-log=ACCESS_LOG\
+  This option specifies the destination of the access log. *ACCESS_LOG* is the
+  path to a file. Note, that the user that runs *OSAAS* needs to have write
+  permissions for this file.
+
+
+--error-log=ERROR_LOG\
+  This option specifies the destination of the error log. *ERROR_LOG* is the
+  path to a file. Note, that the user that runs *OSAAS* needs to have write
+  permissions for this file.
+
+
+--pid-file=PID_FILE\
+  This option specifies the file where to write the PID.
+
+
+--log-level=LOG_LEVEL\
+  This option specifies the detail level of the logging. Supported log levels
+  are *CRITICAL*, *ERROR*, *WARNING*, *INFO* and *DEBUG*.
+
+
+--userdb-file=USERDB_FILE\
+  This option specifies the user database file that is used for the user
+  authentication of *OSAAS*. *USERDB_FILE* is a path to a valid *OSAAS* user
+  database file.
+
+
+--db-type=DB_TYPE\
+  This option specifies the database type. Currently, the supported types are
+  *oracle* and *postgresql*.
+
+
+--db-parameter=DB_PARAMETERS\
+  This option specifies the parameters used to connect to a PostgreSQL database.
+  *DB_PARAMETERS* is a single string.
+
+
+--db-user=DB_USER\
+  This option specifies the user that is used to connect to a Oracle database.
+
+
+--db-password=DB_PASSWORD\
+  This option specifies the password that is used to connect to a Oracle
+  database.
+
+
+--db-dsn=DB_DSN\
+  This option specifies the dsn that is used to connect to a Oracle database.
+
+
 To stop *OSAAS* server, just kill the process (Ctrl+C). *OSAAS* will stop listening in
 the socket, wait until any pending requests have been processed and then
 terminates.



More information about the Osaas-commits mailing list