**
** Setting up a rteval XML-RPC server
**

The XML-RPC server has the purpose of collecting information from
several rteval clients.  All the data in the summary.xml produced by the
rteval script is sent over to the XML-RPC server and registered in a
submission queue.  The XML-RPC server will then send back a submission
ID to the client.

A parser daemon needs to run as well.  This daemon is connected to the
same database as the XML-RPC service and it will wait for new reports in
the submission queue to be parsed.  Look into the README.parser file
for more information on setting up the rteval_parserd process.

Each parsed report will get a unique system ID which then can be used to
track how each system changes behaviour on different kernels.


**
** Requirements
**
   - Apache web server
   - mod_python-3.3.x OR mod_wsgi-3.2 or newer.
   - PostgreSQL v8.3 or later
   - rteval 1.12 or later


**
** Apache preparations
**

The default path used for the rteval client is

    http://{server hostname}/rteval/API1/

If you have a HTTP setup which will follow this scheme, you do not
need to change any URLs at all.

When installing the rteval-xmlrpc-1.4 RPM on a Fedora/RHEL based box,
Apache will be automatically configured.  But the Apache web server
will need to be restarted when you have setup the database.

     # server httpd restart

For manual installations, see the instructions under "Building and
installing from source" further down in this file.


**
** Database preparations
**

** Setting up a new database
All reports are saved in a database.  If you have not used the
rteval-xmlrpc interface before, you need to create the needed database
user and database, execute the following command line:

   # psql < /usr/share/doc/rteval-xmlrpc-1.5/rteval-1.4.sql

This script will first create a database user called 'rtevxmlrpc' and
'rtevparser', assign default password before creating the database called
'rteval'.  The database will be populated with the needed tables and the
'rtevxmlrpc' and 'rtevparser' users will get the needed privileges to do
their job.

Remember to also update the pg_hba.conf file in the PostgreSQL data
directory.  You need to allow the xmlrpc user access from the web
server.

pg_hba.conf entry example:
-----------------------------------------------------------------
# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD
hostssl rteval	    rtevxmlrpc	127.0.0.1/32	      md5
hostssl rteval	    rtevparser	127.0.0.1/32	      md5
-----------------------------------------------------------------

The XML-RPC database connector will always try to connect via SSL.  To
modify the default password, connect to the database with psql and
issue this SQL command:

   rteval=# ALTER USER rtevxmlrpc WITH ENCRYPTED PASSWORD '<newpassword>';
   rteval=# ALTER USER rtevparser WITH ENCRYPTED PASSWORD '<newpassword>';

Or you can use the "safe mode" via the psql command:

   rteval=# \password rtevxmlrpc
   Enter new password:
   Enter it again:
   rteval=# \password rtevparser
   Enter new password:
   Enter it again:


** Update an already existing database
If you already have an rteval database setup, you can run the delta
scripts to only do the pure database schema changes.

To find out which schema version you using, do the following:

   psql rteval -c "SELECT value FROM rteval_info WHERE key='sql_schema_ver'"
   value
   -------
     1.1
   (1 row)

This indicates that the database is at the schema version 1.1.  If you do not
have the rteval_info table, you are for sure on schema version 1.0.

* Update from SQL schema version 1.0 to 1.1
   psql rteval < /usr/share/doc/rteval-xmlrpc-1.1/delta-1.0_1.1.sql

* Update from SQL schema version 1.1 to 1.2
   psql rteval < /usr/share/doc/rteval-xmlrpc-1.1/delta-1.1_1.2.sql

* Update from SQL schema version 1.2 to 1.3
   psql rteval < /usr/share/doc/rteval-xmlrpc-1.1/delta-1.2_1.3.sql

* Update from SQL schema version 1.3 to 1.4
   psql rteval < /usr/share/doc/rteval-xmlrpc-1.1/delta-1.3_1.4.sql

You need to upgrade to the latest SQL schema available, and you must upgrade
sequentially through all the version in between your version and the latest.


**
** Building an installing from source
**

The rteval-xmlrpc uses autotools to configure and build the
rteval-xmlrpc server and parser.

   ./configure [--with-xmlrpc-webroot=<full path>]

If the --with-xmlrpc-webroot is not provided, the mod_python files
needed for the XML-RPC server will not be installed, and only the
report parser will be built and installed.

The path to the --with-xmlrpc-webroot must be a directory which the
Apache web server can access and serve files from (htdocs dir).  On
Fedora/RHEL this path should be:

     ./configure --with-xmlrpc-webroot=/var/www/html/rteval

With this done, you can now do the traditional 'make' and 'make
install'.  The default install prefix is /usr/local, unless you
changed it with --prefix=<path>.  You will then find the
rteval_parserd installed under /usr/local/bin/rteval_parserd and
README files, the SQL scripts and an Apache config file will be found
under /usr/local/share/doc/rteval-parser-1.5/

The Apache configuration file can be copied into the configuration
directory Apache uses for its modules.  On RHEL/Fedora based
distributions, the apache-rteval.conf can be copied into
/etc/httpd/conf.d/

For more information about the report parser (rteval-parserd), please
have a look at the README.parser file.


**
**  Configuration
**

If you are not using any of the default values for
the database configuration, you need to create or modify the
/etc/rteval.conf file.  The XML-RPC service will read the
[xmlrpc_server] section in this file.

This is the default values, if the xmlrpc_server section is not found
or parameters is not set.

     # Paths
     datadir:     /var/lib/rteval

     # Database parameters
     db_server:   localhost
     db_port:     5432
     database:    rteval
     db_username: xmlrpc
     db_password: rtevaldb

The directory the datadir parameter points at must be writable to the
apache process.  Here copies of the received summary.xml files will be
saved before the rteval-parserd process parses the reports.


**
** Testing the setup
**

For a quick test, dig up a summary.xml file from an earlier rteval run and
try sending it to the XML-RPC server by using the testclient_sendreportfile
script:

     ./testclient_sendreportfile --report=summary.xml \
                                 --xmlrpc-submit=localhost

See --help for more info on this utility.  Usually the log files of Apache and
PostgreSQL provides pretty good information if something goes wrong.