README

ARC Middleware
==============

The Advanced Resource Connector (ARC) middleware, introduced by
NorduGrid (www.nordugrid.org), is an open source software solution
enabling production quality computational and data grids.

Since the first release (May 2002) the middleware has been deployed and
been used in production environments. Emphasis is put on scalability,
stability, reliability and performance of the middleware. A growing
number of grid projects, like Swegrid, DCGC, NDGF has chosen ARC as their
middleware.

This release (October 2007) is a technology preview version of the
next generation of ARC. It is based on a service container - the
Hosting Environment Daemon (HED) - and different grid capabilities are
implemented as Web Services residing in HED. Currently, an OGSA BES
compliant execution service - ARC Resource-coupled EXecution service
(A-REX) - and an echo service (for testing purposes) are included, but
the set of services is rapidly growing.


Dependencies
============

The middleware is written in C/C++ and some smaller part in Perl. ARC
builds upon standard Open Source libraries and solutions. Building the
software from source or installing a precompiled binary requires
different external packages, furthermore the client and server
packages have different dependencies too. The detailed compile and
runtime external dependencies are given in the INSTALL file, below a
merged list of the explicit requirements (build, install, server, 
client) is shown:

  Mandatory (on client as well as server side):
    o gnu make, autotools (autoconf>=2.56)
    o C++ compiler and library
    o libtool
    o pkg-config
    o gthread-2.0 version 2.4.7 or later
    o glibmm-2.4 version 2.4.7 or later
    o libxml-2.0 version 2.4.0 or later
    o openssl version 0.9.7a or later
    o e2fsprogs-devel
    o doxygen

  Optional (mainly applicable on server side):
    o swig version 1.3.28 or later
    o java sdk 1.4 or later for Java bindings
    o python-devel for Python bindings
    o Grid Packaging Tools (GPT) (http://www.gridpackagingtools.org/)
    o Globus Toolkit 4 (http://www.globus.org/) which contains
      - Globus RLS client
      - Globus FTP client
      - Globus RSL


Getting the software
====================

The middleware is free to deploy anywhere by anybody. Pre-built binary
releases for a dozen of Linux platforms can be downloaded from the
NorduGrid software repository at download.nordugrid.org.

The software is released under the GNU General Public License (GPL)
(see the LICENSE file).

The NorduGrid repository hosts the source code, and provides most of
the required external software which are not part of a standard Linux
distribution.


Building & Installation
=======================

The ARC middleware can be built from the openly available source code
provided as a tarball. The build uses the GNU autotools. This
means that a standard installation into /usr/local can be made with:

  ./configure
  make
  make install

If you wish to install into <directory>, use the following instead:

  ./configure --prefix=<directory>
  make
  make install


Grid Certificates
=================

In order to use ARC, a grid certificate is necessary. More information
about grid certificates in general and how to get them can be found on
http://www.nordugrid.org/documents/certificate_howto.html


Please make sure correctly configure the certificates on client and service 
sides. The configuration about certificate for MCCTLS in the service.xml 
should like this:  
      <KeyPath>./key.pem</KeyPath>
      <CertificatePath>./cert.pem</CertificatePath>
      <CACertificatePath>./ca.pem</CACertificatePath>
or this:
      <KeyPath>/etc/grid-security/hostkey.pem</KeyPath>
      <CertificatePath>/etc/grid-security/hostcert.pem</CertificatePath>
      <CACertificatesDir>/etc/grid-security/certificates</CACertificatesDir>
Note if you configure <CACertificatePath>, that implicitly means the certificates
for client and service sides are signed by one specific CA.
The key file can be with or without passphrase.

If you would test ARC with TLS support, the certificate generated by yourself ("untrusted"
certificate) is recommended; or you can also use some certificate genertated by authorized CA, 
such as NorduGrid CA. 
For testing, you can use the same certificates for the client and service sides.


For testing purposes, an "untrusted" self-signed certificate can be generated by
the following commands:

  openssl genrsa 1024 > key.pem
  openssl req -config ./openssl.cnf -new -x509 -nodes -sha1 -days 365 -key key.pem > cert.pem
  cp cert.pem ca.pem


ARC Server Setup & Configuration
================================

The configuration of the ARC server is specified in an XML file, the
location of which is specified as a command line argument with the -c
option. An example of a configuration file that sets up an A-REX
execution service and an echo service (intended for testing purposes)
is shown below:

<?xml version="1.0"?>
<ArcConfig 
  xmlns="http://www.nordugrid.org/schemas/ArcConfig/2007"
  xmlns:tcp="http://www.nordugrid.org/schemas/ArcMCCTCP/2007"
  xmlns:arex="http://www.nordugrid.org/schemas/a-rex/Config"
  xmlns:echo="urn:echo_config"
>
  <Server>
    <Foreground/>
    <Pidfile>./arched.pid</Pidfile>
    <Logger level="WARNING">./logfile</Logger>
  </Server>
  <ModuleManager>
    <Path>/usr/local/lib/arc/</Path>
  </ModuleManager>
  <Plugins><Name>mcctcp</Name></Plugins>
  <Plugins><Name>mcctls</Name></Plugins>
  <Plugins><Name>mcchttp</Name></Plugins>
  <Plugins><Name>mccsoap</Name></Plugins>
  <Plugins><Name>arex</Name></Plugins>
  <Plugins><Name>echo</Name></Plugins>
  <Chain>
    <Component name="tcp.service" id="tcp">
      <next id="tls"/> 
      <tcp:Listen><tcp:Port>60000</tcp:Port></tcp:Listen>
    </Component>
    <Component name="tls.service" id="tls">
      <next id="http"/>
      <KeyPath>/etc/grid-security/key.pem</KeyPath>
      <CertificatePath>/etc/grid-security/cert.pem</CertificatePath>
      <CACertificatePath>/etc/grid-security/ca.pem</CACertificatePath>
    </Component>
    <Component name="http.service" id="http">
      <next id="soap">POST</next>
    </Component>
    <Component name="soap.service" id="soap">
      <next id="plexer"/>
    </Component>
    <Plexer name="plexer.service" id="plexer">
      <next id="a-rex">/arex</next>
      <next id="echo">/echo</next>
    </Plexer>
    <Service name="a-rex" id="a-rex">
      <arex:endpoint>https://localhost:60000/arex</arex:endpoint>
      <arex:username>nobody</arex:username>
      <arex:gmconfig>/etc/arc.conf</arex:gmconfig>
    </Service>
    <Service name="echo" id="echo">
      <echo:prefix>[ </echo:prefix>
      <echo:suffix> ]</echo:suffix>
    </Service>
  </Chain>
</ArcConfig>

If you generated your own certificate according to the instructions in
the previous section, remember to update the KeyPath, CertificatePath,
and CACertificatePath elements accordingly.

The echo service is "atomic" and has no additional dependencies other
than what is provided by the Hosting Environment Daemon (HED). If you
do not want to run the echo service, simply remove the lines
'xmlns:echo="urn:echo_config"', '<Plugins><Name>echo</Name></Plugins>',
'<next id="echo">/echo</next>', and '<Service name="echo" id="echo">
[...] </Service>' from the configuration file.

In order to use the A-REX service, however, you need to run a
Grid-Manager as well. There is not yet a Grid-Manager available in the
new generation of ARC, but the Grid-Manager from ARC 0.6.x can be used
in the meantime. How to install and set up that Grid-Manager is
described in detail on
http://www.nordugrid.org/documents/ng-server-install.html and in
NORDUGRID-TECH-14 "The ARC Computational Job Management Module -
A-REX: Description and Administrator's Manual".

Please note, that there is a reference to the configuration file for
the Grid-Manager in the configuration file for the HED:
"<arex:gmconfig>/etc/arc.conf</arex:gmconfig>". If your configuration
file for the Grid-Manager is located somewhere else or has another
name, you must update the configuration file for HED accordingly.

Worth mentioning is also that the user account from which the HED
containing the A-REX service is run, will be the owner of the jobs in
the local batch system, and that this account must have write
permission in the session and control directories of the Grid-Manager.

If you do not want to run the A-REX service, simply remove the lines
'xmlns:arex="http://www.nordugrid.org/schemas/a-rex/Config"'
'<Plugins><Name>arex</Name></Plugins>', '<next id="a-rex">/arex</next>',
and '<Service name="a-rex" id="a-rex"> [...] </Service>' from the
configuration file.


Starting the Server
===================

To start the ARC server, type the following on the command line:

  /usr/local/sbin/arched -c /etc/arcserv.xml &

If the server complains about "libglobus..." and that it cannot open a
shared object file, try to add "/opt/globus/lib" to your
LD_LIBRARY_PATH:

  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/globus/lib

In the current release, the server prints some warnings and messages
that can safely be ignored. Those are:
- Unknown element "Server" - ignoring
- Not a '__arc_***_modules__' type plugin
- Assigned new informational document

Remember to also start the Grid-Manager, as described above, in order
to be able to use the A-REX service.


The A-REX Client
================

The configuration of the ARC A-REX client is specified in an XML
file. The location of the configuration file is specified by the
environment variable ARC_AREX_CONFIG. If there is no such environment
variable, the configuration file is assumed to be arex_client.xml in
the current working directory. An example configuration file is shown
below:

<?xml version="1.0"?>
<ArcConfig
  xmlns="http://www.nordugrid.org/schemas/ArcConfig/2007"
  xmlns:tcp="http://www.nordugrid.org/schemas/ArcMCCTCP/2007">
  <ModuleManager>
    <Path>/usr/local/lib/arc/</Path>
  </ModuleManager>
  <Plugins><Name>mcctcp</Name></Plugins>
  <Plugins><Name>mcctls</Name></Plugins>
  <Plugins><Name>mcchttp</Name></Plugins>
  <Plugins><Name>mccsoap</Name></Plugins>
  <Chain>
    <Component name='tcp.client' id='tcp'>
      <tcp:Connect>
        <tcp:Host>127.0.0.1</tcp:Host>
        <tcp:Port>60000</tcp:Port>
      </tcp:Connect>
    </Component>
    <Component name='tls.client' id='tls'>
      <next id='tcp'/>
      <KeyPath>/etc/grid-security/key.pem</KeyPath>
      <CertificatePath>/etc/grid-security/cert.pem</CertificatePath>
      <CACertificatePath>/etc/grid-security/ca.pem</CACertificatePath>
    </Component>
    <Component name='http.client' id='http'>
      <next id='tls'/>
      <Method>POST</Method>
      <Endpoint>/arex</Endpoint>
    </Component>
    <Component name='soap.client' id='soap' entry='soap'>
      <next id='http'/>
    </Component>
  </Chain>
</ArcConfig>


Using the A-REX Client
======================

To submit a job, type

  <install-prefix>/bin/apsub <JSDL-file> <JobID-file>

where <JSDL-file> is the location of a file that contains the job
specification in JSDL format and <JobID-file> the location of a file
in which the Job ID will be stored.

To query the status of a job, type

  <install-prefix>/bin/apstat <JobID-file>

where <JobID-file> the location of the file in which the Job ID is
stored (the file created when the job was submitted).

To terminate a job, type

  <install-prefix>/bin/apkill <JobID-file>

where <JobID-file> the location of the file in which the Job ID is
stored (the file created when the job was submitted).

More detailed information about how to use the client tools is
available in NORDUGRID-TECH-15 "WS-Based ARC Clients".


The Echo Client
===============

The configuration of the ARC echo client is specified in an XML
file. The location of the configuration file is specified by the
environment variable ARC_ECHO_CONFIG. If there is no such environment
variable, the configuration file is assumed to be echo_client.xml in
the current working directory. An example configuration file is shown
below:

<?xml version="1.0"?>
<ArcConfig
  xmlns="http://www.nordugrid.org/schemas/ArcConfig/2007"
  xmlns:tcp="http://www.nordugrid.org/schemas/ArcMCCTCP/2007">
  <ModuleManager>
    <Path>/usr/local/lib/arc/</Path>
  </ModuleManager>
  <Plugins><Name>mcctcp</Name></Plugins>
  <Plugins><Name>mcctls</Name></Plugins>
  <Plugins><Name>mcchttp</Name></Plugins>
  <Plugins><Name>mccsoap</Name></Plugins>
  <Chain>
    <Component name='tcp.client' id='tcp'>
      <tcp:Connect>
        <tcp:Host>127.0.0.1</tcp:Host>
        <tcp:Port>60000</tcp:Port>
      </tcp:Connect>
    </Component>
    <Component name='tls.client' id='tls'>
      <next id='tcp'/>
      <KeyPath>/etc/grid-security/key.pem</KeyPath>
      <CertificatePath>/etc/grid-security/cert.pem</CertificatePath>
      <CACertificatePath>/etc/grid-security/ca.pem</CACertificatePath>
    </Component>
    <Component name='http.client' id='http'>
      <next id='tls'/><Method>POST</Method>
      <Endpoint>/echo</Endpoint>
    </Component>
    <Component name='soap.client' id='soap' entry='soap'>
      <next id='http'/>
    </Component>
  </Chain>
</ArcConfig>


Using the Echo Client
======================

To use the echo client, type

  <install-prefix>/bin/apecho <message>

where <message> is the message which the echo service will return.


Contributing
============

The open source development of the ARC middleware is coordinated by
the NorduGrid Collaboration. Currently, the main contributor is the
KnowARC project (www.knowarc.eu), but the Collaboration is open to new
members. Contributions from the community to the software and the
documentation is welcomed. Sources can be downloaded from the software
repository at download.nordugrid.org or the Subversion code repository at
svn.nordugrid.org.

The technical coordination group defines outstanding issues that have
to be addressed in the framework of the ARC development. Feature
requests and enhancement proposals are recorded in the Bugzilla bug
tracking system at bugzilla.nordugrid.org. For a more detailed
description, write access to the code repository and further
questions, write to the nordugrid-discuss mailing list (see
www.nordugrid.org for details). Ongoing and completed Grid Research
projects and student assignments related to the middleware are listed
on the NorduGrid Web site as well.


Support, documentation, mailing lists, contact
==============================================

User support and site installation assistance is provided via the
request tracking system available at nordugrid-support@nordugrid.org.
In addition, NorduGrid runs a couple of mailing lists, among which the
nordugrid-discuss mailing list is a general forum for all kind of
issues related to the ARC middleware.

NorduGrid deploys the Bugzilla problem tracking system
(bugzilla.nordugrid.org). Feature and enhancement requests, as well as
discovered problems, should be reported there.

Research papers, overview talks, reference manuals, user guides,
installation instructions, conference presentations, FAQ and even
tutorial materials can be fetched from the documentation section of
www.nordugrid.org

Contact information is kept updated on the www.nordugrid.org web site.