[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