CORAL Component documentation: LFCReplicaService

Giacomo Govi

CERN

November 2006


1. Introduction

1.1. Purpose of the component

The LFCReplicaService package is a plugin library allowing to use an LFC server as a database catalogue. Replica information includes authentication credential parameters associated to user-defined roles.

1.2. Repository of the component

:pserver:anonymoys@coral.cvs.cern.ch:/cvs/coral/coral/LFCReplicaService

2. LFCReplicaService Semantics

2.1. Architecture

The LFCReplicaService is a database replica catalogue using an LFC server as a storage backend. The translation of the LFC stored data to the database-related information is implemented in the client-side code, based on the LFC C-API client. Each database replica is stored with its associated information, including the authentication credential (pair username+password), database server host name, status of the server. In order to protect the access to the replica entry for the disclosure of the associated authentication credentials, the LFCReplicaService fully uses the LFC built-in security scheme permission. The LFC uses the Grid (proxy) certificates extended with the VOMS information to establish the identity of the client, and regulates the access to the file entries with a file-system like access permission scheme, which includes ACL's. In order to adopt this security scheme, the LFCReplicaService defines a database catalogue entry (=a logical file name on the LFC side) for each role to be coupled to a credential pair.In such a way the role entry, represented by an entry in the LFC file system, can be protected for the access using the standard LFC security scheme, allowing only the intended grid roles or groups to access the file and disclose the authentication credentials.

2.2. LFC Server Connection

The LFC C-API client does not allow an explicit connection with a given LFC server. The connection is established implicitly, at any function call accessing the LFC name server. The LFC host is specified with the environment variable LFC_HOST. In order to be authenticated into a secure LFC name server, the user needs a valid grid certificate to be available in the execution context. In case of missing valid certificate, the LFC will return the error message: "send2nsd: NS002 - send error : No valid credential found".

2.3. Deployment of CORAL database catalogue into an existing LFC server

In order to use an existing LFC server as a database catalogue, very little deployment operation is required. Since the operation of the database entries involves the management of the database authentication credentials, it is assumed that it will be performed by a super-user, acting as database catalogue administrator. The first action required is the definition of the database catalogue area in the LFC file system. By default, the LFCReplicaService assumes the folder /database as a root base folder for the database entries. Optionally, a user defined folder can be assumed as root, by setting the environment variable CORAL_LFC_BASEDIR. In both cases, the corrisponding folder has to be created and set with the necessary access permission RWX to the db catalogue administrator. In order to add a replica set, the administrator will run the coral_replica_manager -add command, specifying all the required parameters. The entry created will be by default not accessible to the world. In order to let a specific grid identity (role or group) access the database entry, the db administrator has to run the coral_replica_manager -set_perm command for all the group entitled to access the replicas.

Example:

  • logical connection name: /atlas/ecal/calib

  • physical connection string: oracle://ecal_calib/calib_writer

  • username: calib_reader

  • password: xyz2006

  • database server: atlr

  • coral role: writer

  • to be visible for grid role: offline_reader

the commands necessary:

coral_replica_manager -add -l /atlas/ecal/calib -c oracle://ecal_calib/calib_writer 
                           -r writer -u calib_reader -p xyz2006 

coral_replica_manager -set_perm -l /atlas/ecal/calib -r writer -g offline_writer -ro

2.4. Storage of database password in the LFC server

In order to avoid storage of clear text password in the LFC tables, a simple key-based mechansim of encryption has been implemented.

3. Implementation Specifics

The implementation of the package is based on the LFC C-api. All the access to the LFC name server are perfomed within non-named, serialized transactions. The I/O operations are perfomed with calls to the corresponding LFC functions, handling the error condition by translating the LFC error codes in specific run time exceptions. The functionality of the component are provided by a single service, implementing the features of replica lookup and credential store, and the administration commands for the deployment and operation of the database catalogue. The access to the LFC entries for administration and lookup is protected by the LFC built-in file system access permission. In particular, autorization to specific grid-roles or grid-groups is managed with LFC ACL's.

3.1. Mapping of CORAL database catalogue information to LFC tables

The mapping between the database-related information and the LFC data fields is well isolated in a single, specific class, allowing for easy modification of the schema with little impact on the rest of the software architecture. Here follows the table describing the mapping.

4. Related components

  • RelationalAccess, is the package where the CORAL abstract interfaces are defined.

  • CoralCommon, is the package where some developer-level interfaces and some common implementation classes are defined.

  • LFC, is the package where APIs are defined.

5. LFCReplicaService Reference

5.1. class ILookupService

5.1.1. Members
  •   

    IDatabaseServiceSet* lookup( const std::string& logicalName, coral::AccessMode accessMode = coral::Update, std::string authenticationMechanism = "" ) const;

    Parameters:

    •  logicalName 
      : the logical connection string, which can be described by a file absolute or relative path, with an arbitrary complex folder hierarchy. The root base folder in the LFC filesystem is fixed to /database by default, and can be moved to other location using the environment variable CORAL_LFC_BASEDIR.

    •  accessMode 
      : the access mode capability of the connection. Possible values are items of the coral::AccessMode enumeration. Default value is Update, which means that with no parameter specified, only the Update capable connection will be considered.

    •  authenticationMechanism 
      : the authentication mechanism required by the physical connections. Default value is an empty string, which will be interpreted by applying no filter to the available connections (all the mechansim are considered.). In the LFC replica service, only two mechansim can be currently associated to the physical connections: "password", to be used for credential based authentication, and "none", when no authentication is required.

    Effects: Resolves the specified logical connection string, looking up the LFC database catalogue according to the access permission of the underlying grid role or group. In case of successfull access, a data structure is filled with the associated replica information, while in the service memory the are stored the authentication credentials required by all of the physical connections involved in the selection.

    Returns: A user owned pointer to the data structure holding the replica list. The free of this memory allocation does not have any effect on the service.

5.2. class IAuthenticationService

5.2.1. Members
  • IAuthenticationCredential& credentials( const std::string& connectionString ) const;

    Parameters:

    •  connectionString 
      : the physical connection string requiring the authentication parameters.

    Effects: This method call DOES NOT trigger any access to the LFC catalogue. It only delivers a reference to the already existing authentication data for the default role (named coral_default_role), loaded by the previous last lookup call. Any call to this method which is not anticipated by a lookup call, will throw an Authentication exception, because no data will be present in the service credential store.

    Returns: A reference to the current credential store loaded in the service memory. It contains valid data only after a call of the corresponding lookup method. The role looked up for the credential pairs (username+password) is the default role (named coral_default_role).

  • IAuthenticationCredential& credentials( const std::string& connectionString, const std::string& role ) const;

    Parameters:

    •  connectionString 
      : the physical connection string requiring the authentication parameters.

    •  role 
      : the role defining the identity for the authentication.

    Effects:Same effect as for the above method.

    Returns:Same return value as the above method, selecting the credential pair associated to the specified role.

5.3. Command line tools

A set of LFCDbLookupService administrating commands has been provided for the management of mapping information stored in LFC. These command line tools are implemented using LFC APIs for adding, removing, listing the replica entries (with the accociated credential informaton) for specified logical connection string and to export the replica entries of a logical connection string into XML file. All of the available commands are issued with a single executable:

coral_replica_manager

The usage sintax is:

coral_replica_manager [COMMAND] [PARAMETER_0]... [PARAMETER_N]

The available commands:

  • -add ( --add ) : Adds a new replica entry for the specified logical connection string and role Usage:

    -add

    • -l lcs ( the logical connection string to be mapped to the replica )

    • -c pcs ( the physical connection string defining the replica )

    • [-h host] ( the database host of the replica - if not specified is extracted from the physical connection string)

    • [-r role] ( the role associated to the replica credential pairs - default=coral_default_role )

    • [-u username]( the username associated to the replica )

    • [-p password]( the password associated to the replica )

    • [-np]( no authentication credential associated to the replica )

    • [-ro]( read-only capable physical connection )

    • [-rw]( update capable physical connection - default )

    • [-help]( help for the add command )

  • -ls ( --list ) : Lists available replicas mapped to a logical connection string - with optional filters. Usage:

    -ls

    • [-h host] ( select replicas with the specified database host)

    • [-l lcs ] ( select replica of the the specified logical connection string (or path )

    • [-c pcs ] ( select replicas with the sepcified physical connection string )

    • [-r role]( selecting replicas with the credential associated to the specified role )

    • [-np]( select replicas with no authentication required )

    • [-u username]( select replicas with the specified username in the credential pair )

    • [-s ]( scan option - recursively scan inner folders )

    • [-ro]( select replicas with read-only capability )

    • [-rw]( select replicas with update capability )

    • [-on]( select replicas with status on )

    • [-off]( select replicas with status off )

    • [-help]( help for the list command )

  • -set ( --set_param ) : Change the status or the passoword values to the specified replica(s) Usage:

    -set

    • -h host ( select replicas with the specified database host)

    • [-u username]( select replicas with the specified username in the credential pair )

    • [-p password]( the new password associated to the replica, replacing the existing one. )

    • [-on]( the new value for the replica status=on )

    • [-off]( the new value for the replica status=off )

    • [-help]( help for the set command )

  • -del ( --delete ) : Removes the existing replica(s) mapped to a logical connection string. Usage:

    -del

    • -l lcs ( select replica(s) of the the specified logical connection string (or path )

    • [-h host] ( select replicas with the specified database host)

    • [-c pcs ] ( select replicas with the sepcified physical connection string )

    • [-r role]( selecting replicas with the credential associated to the specified role )

    • [-np]( select replicas with no authentication required )

    • [-u username]( select replicas with the specified username in the credential pair )

    • [-s ]( scan option - recursively scan inner folders )

    • [-ro]( select replicas with read-only capability )

    • [-rw]( select replicas with update capability )

    • [-on]( select replicas with status on )

    • [-off]( select replicas with status off )

    • [-help]( help for the del command )

  • -val ( --validate_param ) : Validate the specified passoword against the current value for the specified replica(s) Usage:

    -val

    • -h host ( select replicas with the specified database host)

    • -u username( select replicas with the specified username in the credential pair )

    • -p password( the password associated to the replica, to be validated. )

    • [-help]( help for the val command )

  • -set_perm ( --set_permission) : Set the specified access permission for the specified LFC group entry (mapped to a Grid role or group), to the specified logical connection string and role. Usage:

    -set_perm

    • -g group ( the LFC group entry to be granted )

    • -l lcs ( the logical connection string to access )

    • -r role ( the role associated to the credential pair)

    • [-na] ( grant no access permission )

    • [-rw]( grant read-write access permission )

    • [-ro]( grant read-only access permission )

    • [-wo]( grant write only access permission )

    • [-help]( help for the set_perm command )

  • -exp ( --export ) : Export available replicas and associated credential information into xml files, in the format supported by XMLLookupService and XMLAuthenticationService, with optional filters. Usage:

    -exp

    • [-h host] ( select replicas with the specified database host)

    • [-l lcs ] ( select replica of the the specified logical connection string (or path )

    • [-c pcs ] ( select replicas with the sepcified physical connection string )

    • [-r role]( selecting replicas with the credential associated to the specified role )

    • [-np]( select replicas with no authentication required )

    • [-u username]( select replicas with the specified username in the credential pair )

    • [-s ]( scan option - recursively scan inner folders )

    • [-ro]( select replicas with read-only capability )

    • [-rw]( select replicas with update capability )

    • [-on]( select replicas with status on )

    • [-off]( select replicas with status off )

    • [-af authentication_file]( specify the name of the authentication file - default=authentication.xml )

    • [-lf lookup_file ]( specify the name of the lookup file - default=dblookup.xml )

    • [-help]( help for the exp command )

  • -imp ( --import ) : Import available replicas and associated credential information from xml files, in the format supported by XMLLookupService and XMLAuthenticationService. Usage:

    -imp

    • [-af authentication_file]( specify the name of the authentication file - default=authentication.xml )

    • [-lf lookup_file ]( specify the name of the lookup file - default=dblookup.xml )

    • [-help]( help for the exp command )

  • -help ( --help ) : Displays the general help of the tool Usage:

    -help