server/README.xmlrpc - pub/scm/linux/kernel/git/jkacur/rteval - Git at Google

 **
 ** 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.
	**
	** 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.