• Introduction
• Installation
• Prerequisites
• Other Forms of Linux
• YUM
• APT-RPM
• Standalone RPM
• Tar Package
• Subversion
• Configuration
• Configuration File Format
• Daemon Configuration File Options
• Logger Configuration Options
• Suggested Configuration Changes
• Daemon Changes
• Logging Changes
• Service Control
• Service Validation
• Service Maintenance
• Last Updated

Introduction

The perfSONAR-PS Lookup Service (LS) addresses the always challenging problem of resource registration and discovery for the perfSONAR framework. Service instances that manage datasets are only useful when they can be contacted by consumers. Consumers can only function when there is data available. To manage these problems in a dynamic environment such as perfSONAR, it is necessary to register, maintain, and query for the services that may contain interesting data.

The perfSONAR-PS LS relies on an XML database, Oracle DB XML, to store service registration information in a native manner. Using the power of the XPath and XQuery standards it is then possible for client applications and services alike to query for information in a uniform and powerful manner. All perfSONAR services are capable of registering information with an LS instantiation, thus deploying this service within your framework is paramount.

Installation

There are several ways to install this service, the popular methods are listed below. Note that these are from the point of view of installing a particular version - this may or may not be the most recent.

Prerequisites

The LS is packaged as an RPM - a binary installation format that is geared towards use on Red Hat linux based systems. Examples include Fedora, Red Hat Enterprise Linux, CentOS, White Box, Scientific Linux, and others.

These Linux distributions normally rely on Package Management tools to install and maintain software. Examples of these tools include up2Date, YUM, and APT-RPM. Internet2 has created a repository to house the perfSONAR-PS software, related performance tools, and hard to find prerequisites. We encourage adopters of these tools to install a simple RPM package that gives the necessary configuration information for the YUM and APT-RPM tools.

To install this RPM first import the signing key:

rpm --import http://software.internet2.edu/rpms/RPM-GPG-KEY-Internet2

Then install the RPM:

rpm -ivh http://software.internet2.edu/Internet2-repo-0.1-2.noarch.rpm

It is also recommended that an additional repository be installed for hard to find prerequisite software that may not be available in traditional repositories used by the Linux distributions. Two regarded repositories are:

• http://dries.ulyssis.org/rpm/
• http://dag.wieers.com/rpm/

Each site provides configuration instructions and packages similar to the Internet2 repository.

Other Forms of Linux

If using a package management system is not an option, or if your system is not RedHat based (e.g. Debian, Gentoo, etc.) it is still possible to install this software and related requirements by hand. Please see the TarPackage or Subversion sections for more details. This tool uses the following Perl libraries, libraries, and external tools to function:

• Perl Libraries
• Config::General
• Cwd
• Data::UUID
• Data::Validate::IP
• Digest::MD5
• English
• Error
• Exporter
• File::Basename
• File::Temp
• File::stat
• Getopt::Long
• HTTP::Daemon
• Hash::Merge
• IO::File
• LWP::Simple
• LWP::UserAgent
• Log::Dispatch
• Log::Dispatch::FileRotate
• Log::Log4perl
• Module::Load
• Net::CIDR
• Net::IPTrie
• Net::IPv6Addr
• Net::Ping
• Params::Validate
• Sleepycat::DbXml
• Sys::Hostname
• Time::HiRes
• XML::LibXML
• Libraries
• LibXML2
• Tools
• RRDTool

YUM

Like Apt, YUM installation also manages the task of finding dependencies. The following command is all that is needed:

yum install perl-perfSONAR_PS-LookupService

There may be several prerequisites to install depending on the age of your system. To ensure that all are found, please be sure to install one of the alternative repositories above.

APT-RPM

Installation through APT-RPM is easy, simply let the package manager do the work of managing the dependencies:

apt-get update
apt-get install perl-perfSONAR_PS-LookupService-3.1-1.pSPS.noarch.rpm

There may be several prerequisites to install depending on the age of your system. To ensure that all are found, please be sure to install one of the alternative repositories above.

Standalone RPM

If you do not wish to install the Internet2 Repository package, you may simply find the appropriate RPM for your architecture without using a package manger. The first step is to install the signing key:

rpm --import http://software.internet2.edu/rpms/RPM-GPG-KEY-Internet2

Next download the service, for example if you are on an i386 architecture:

wget -c http://software.internet2.edu/rpms/i386/main/RPMS/perl-perfSONAR_PS-LookupService-3.1-1.pSPS.noarch.rpm

To install without package manager help:

rpm -ivh perl-perfSONAR_PS-LookupService-3.1-1.pSPS.noarch.rpm

Note that this RPM may need packages to install correctly: if they are not found on your system manual download and install will be required. An alternate method is to still use a package manager in a local way (YUM only):

yum localinstall perl-perfSONAR_PS-LookupService-3.1-1.pSPS.noarch.rpm

This will still search the available repositories for any necessary packages.

Tar Package

All RPM packages are also available in source packages that may be installed and used in the typical Unix/Linux fashion. There are helper scripts included that may be used to download the necessary prerequisite software packages:

wget -c http://software.internet2.edu/source/perl-perfSONAR_PS-LookupService-3.1-1.tar.gz
tar -zxfv perl-perfSONAR_PS-LookupService-3.1-1.tar.gz
make install
cd perl-perfSONAR_PS-LookupService-3.1-1/scripts
./install_dependencies.sh
./prepare_environment.sh

These two included scripts will configure the machine's users and startup scripts as well as contact CPAN for any necessary perl libraries.

In addition to perl requirements, there are other software requirements that should be installed. These are not controlled via the dependency scripts due to differences in package management. The tools are listed below:

• Oracle DB XML
• Source is available here
• Package management names:
• Debian/Ubuntu: dbxml
• RedHat Systems: dbxml
• LibXML2
• Package management names:
• Debian/Ubuntu: libxml2, libxml2-dev, libxml2-utils
• RedHat Systems: libxml2, libxml2-devel

Subversion

Software may be downloaded directly from our anonymous subversion server. This installation method allows for easy upgrades between versions and access to bugfixes immediately. There are two ways to download from our server, one that retrieves all software and another that retrieves only selective services.

To download the entire release:

svn checkout http://anonsvn.internet2.edu/svn/perfSONAR-PS/tags/RELEASE_3.1 perfSONAR-PS

The instructions are the same here as for the Tar package. Note that installation may require pre-requisite software. Read the preceding sections for necessary items and suggestions on how to install and configure them. When you wish to update the checkout (to retrieve new development or bugfixes):

cd perfSONAR-PS
svn update

If a single service is all that is required, a similar method is used but also note that the service must have access to a "Shared" directory that contains perfSONAR-PS libraries:

svn checkout http://anonsvn.internet2.edu/svn/perfSONAR-PS/tags/RELEASE_3.1/perfSONAR_PS-LookupService/
svn checkout http://anonsvn.internet2.edu/svn/perfSONAR-PS/tags/RELEASE_3.1/Shared

The instructions are also the same as above:

cd Shared
svn update

and

cd perfSONAR_PS-LookupService
svn update

Configuration

The following sections detail the necessary configuration of this service.

Configuration File Format

<port 9995>
    <endpoint /perfSONAR_PS/services/hLS>
        <gls>
				                                # just an hLS ... (ORG, CITY, STATE, COUNTRY)
			root                            0
				                                # data TTL = 4 days
			ls_ttl                          5760
				                                # 180 minute (3hr) registaration window
			ls_registration_interval        180
				                                # 120 miute cleaning/summary window
			maintenance_interval	        120
				                                # Database options (only change path)
			metadata_db_file	            glsstore.dbxml
			metadata_summary_db_file	    glsstore-summary.dbxml
			metadata_db_name	            /var/lib/perfsonar/lookup_service/xmldb
				                                # Service options (please customize)
			service_accesspoint	            http://localhost:9995/perfSONAR_PS/services/hLS
			service_description             ORG Home Lookup Service (CITY, STATE, COUNTRY)
			service_name                    ORG Home Lookup Service
			service_type	                hLS
			
			summarization_granularity       3   #integer between [0;3]; 0 is coarser, 3 is finer (larger summarization)
            summarization_minMask          18   #minimum CIDR mask in summarization; for IPv4, 0 to 32
                                                #summarized IP addresses will not have a mask smaller than minMask

			
		</gls>
		disable	                            0
		module	                            perfSONAR_PS::Services::LS::gLS
	</endpoint>
</port>
	                                            # 180 minute (3hr) registaration window
ls_registration_interval	                180
disable_echo	                            0
	                                            # Root hints info, url + local copy location
root_hints_url	                            http://www.perfsonar.net/gls.root.hints
root_hints_file	                            /var/lib/perfsonar/lookup_service/hls.root.hints
	                                            # Daemon management, shouldn't need changing
reaper_interval	                            20
max_worker_lifetime	                        300
max_worker_processes	                    30
pid_dir                                     /var/run
pid_file	                                lookup_service.pid

Daemon Configuration File Options

There are several Global configuration items, an explanation of each follows:

There are several configuration items that are directly related to the service, an explanation of each follows:

Logger Configuration Options

The following is an explanation of the logging file format.

Suggested Configuration Changes

The LS comes with a base configuration via the installation procedure. This is meant to allow for immediate testing as well as serve as a guide for customizing the service.

There are several files that may be adjusted manually to configure this service for a specific use case:

Daemon Changes

Contains information that identifies the service uniquely and allows it to run in a given environment. There are several options that should be changed:

• service_accesspoint - Change the hostname from localhost
• service_description - Identifying information about the service
• service_name - Service Name (short)

There are also several options that may be changed for a configuration:

• port - Port the service listens on
• endpoint - Endpoint to contact the service
• ls_ttl - How long data can remain before being cleaned Currently set to 5760 minutes (4 days)
• ls_registration_interval - How often to contact gLS, 180 minute (3hr)
• maintenance_interval - How often to summarize the internal data, currently 120 minutes (2 hours)

The rest of the items are normally not to be adjusted.

Logging Changes

Contains information related to logging, there are three modes:

• Log::Dispatch::Screen - Log messages to screen (useful for debugging)
• Log::Dispatch::Syslog - Log messages to syslog facility
• Log::Dispatch::FileRotate - Log messages to specified file

The rest of the items are normally not to be adjusted.

Service Control

The service comes with init scripts that may be used to start and stop operation:

/etc/init.d/lookup_service start
/etc/init.d/lookup_service stop
/etc/init.d/lookup_service restart

The service can also be run in a manual fashion (useful for debugging):

perl bin/daemon.pl --verbose --conf=etc/daemon.conf --logger=etc/daemon_logger.conf

Before doing this, be sure to edit the logging to enable Screen debugging.

Service Validation

The service comes with a client application and several test messages that can be used to test functionality. There are many messages provided as examples, to test the service there are 2 that are recommended:

etc/requests/EchoRequest.xml
etc/requests/hLS/LSQueryRequest.xml

These four will test the major functions of this service. To test:

1. Ensure the service is started, it helps if you have configured logging to use the "Screen" so you may monitor the service's activities.
2. Run the client:

  perl bin/client.pl URL FILENAME

3. Compare the results of the test with the comments in each file. Note there may be some differences (e.g. id values, key values).
4. If everything looks OK, return logging to normal and restart service via the init system.

Service Maintenance

Subscribe to the user mailing lists if you are seeking help on some problem related to this software. Announcements regarding availability of new releases will also be sent to these locations:

Also if you are using package management software and have installed the Internet2 software repository, a typical upgrade should download new releases:

yum update

or

apt-get dist-upgrade

Finally, check the following websites for news of software releases:

• http://software.internet2.edu
• http://www.internet2.edu/performance

Last Updated

$Id: pSPS20090327Release.wiki 656 2009-04-01 11:28:58Z jwzurawski $