README

glite-info-service is an information provider for the GlueService and
GlueServiceData objects, producing LDIF output according to the LDAP
representation of version 1.3 of the GLUE schema, see:
http://glueschema.forge.cnaf.infn.it/Spec/V13

The provider takes three arguments: a service-specific configuration file,
the GlueSiteUniqueID, and optionally the GlueServiceUniqueID in case there
is a reason to force a specific value; by default a UniqueID will be
constructed by the provider. The GlueSiteUniqueID may also be omitted if
it is supplied in the configuration file.

It is expected that the provider will be called from a wrapper with one
invocation per service on the node. The distribution includes template
configuration files; for a service svc these are named
glite-info-service-svc.conf.template. The files required on a given node
should be copied and possibly edited to apply any local configuration
required for that service.

The configuration files consist of a series of key=value lines. Blank lines
and lines starting with # are ignored. All keys except get_site_id must be
present in the file even if they represent a null value. Most values are
commands to be executed using the backquote operator in perl; these may
be inline commands or a service-specific script. If this is used it is
named glite-info-service-svc and should be in the PATH seen by the provider.
Using "echo" as the command effectively represents a null value.

The keys are as follows:

get_site_id: A command which returns the site name (GlueSiteUniqueID) as
an alternative to passing it as an argument. Either method is optional,
but the ID must be specified in one way or the other. If both are specified
the argument takes precedence.

init: This allows a setup command which will be executed before anything else.
Environment variables can be set for subsequent commands by writing lines
of the form X=Y to stdout. A non-zero return code from the init command will
abort the provider without producing any output, e.g. if the service is not
installed on the node. This command may be null.

service_type: This is a string rather than a command, and is not optional.
It should be taken from the official list of service types at:
http://glueschema.forge.cnaf.infn.it/V12/ServiceType

get_version: A command to return the service interface version. The
canonical form is x.y.z, but one- or two-component versions will be
padded with .0; four or more components are not allowed. The version
components are not required to be numeric. This may not be null;
"echo 1" can be used as a minimal default.

get_endpoint: A command to return the endpoint of the service, i.e. a
contactable URL. This may be null.

get_status: A command to check the status of the service. The return code
is used to determine the standard GLUE status values:  0 = OK, 1 = Critical,
2 = Warning, 3 = Unknown, other = Other. Any text written to stdout will appear
as the GlueStatusInfo attribute, truncated if necessary and with special
characters removed. The standard list of pids in status strings, e.g.
"(pid 123 456)", is also stripped out. This command may not be null,
a minimal value is "echo OK".

WSDL_URL: This is a string giving the URL of a WSDL document describing
the service, if any. Any string not starting with "http" is treated as null.

semantics_URL: A string giving the URL of a document containing a
human-readable description of the service, e.g. a manual. Any string not
starting with "http" is treated as null.

get_starttime: A command to return the service start time as a Unix
timestamp, e.g. from a stat on a pid file. This is not optional, but
"echo 0" will set the start time to the Unix epoch as a minimal default.

get_owner: A command to return a list of "owners", typically the names of
VOs which are served by the service. These should be written to stdout, one
owner per line. This should be null if the service is a generic one usable
by anyone.

get_acbr: A command to return access-control information, in the standard
GLUE AccessControlBaseRule format, with one entry per line written to stdout.
In the simplest case this will be the same list as the "owners" with
VO names prefixed by "VO:". The interpretation of this information may be
service-specific.

get_data: This is a command which can return arbitrary service information
as key/value pairs, written to stdout as one "key=value" line per entry. This
will often be null. Each key/value pair will be output as a GlueServiceData
object. Note that the LDAP schema structure prevents the inclusion of more
than one entry with the same key, and that only 7-bit ASCII characters are
allowed - any top-bit-set characters in the value are replaced with a "?".

get_services: A command to return a list of related services, writing one
GlueServiceUniqueID per line to stdout. This is highly service-specific and
will usually be null.

General notes:

The GlueServiceUniqueID is constructed using the scheme host_type_check,
where check is the checksum of the configuration file. This should ensure
uniqueness as long as a real FQDN is returned for the hostname. However,
this also means that the UniqueID will change if the configuration changes.
In some cases it may be desirable to enforce a specific persistent UniqueID,
in which case it can be supplied as an argument to the information provider.

The glite-info-service-test script allows the service status to be set
to "Warning", e.g. if the service is being tested and should not be used
for production. This is done by defining a variable
GLITE_INFO_SERVICE_STATUS_SVC where SVC is the name of the service (in
uppercase). The content of the string will be written to the StatusInfo
attribute.

For some services it may be desirable to have the endpoint contain a
DNS alias rather than the real hostname. In this case a service-specfic
variable needs to be defined in the context in which the info provider runs,
usually SVC_HOST.

In general the Owner and ACBR information (i.e. authorised VOs etc) are
difficult to determine dynamically on the node, so these will often need
to be filled in at configuration time, e.g. by YAIM. This can either be
with an inline echo, or for longer lists a cat of a file containing the
data.

It seems that the old and long-deprecated GlueServiceAccessControlRule
attribute is still required at present for backward compatibility. Such
attributes are output only for ACBR entries of the form VO:<vo-name>,
from which the VO: prefix is stripped.

Two standard ServiceData entries are written, with Keys of
glite-info-service_version and glite-info-service_hostname. The Values
are respectively an internal version number of the info provider code,
and the local hostname where the provider is run.

Currently none of the service providers require access to a host
certificate/proxy, but this may be desirable in some cases.

It is assumed that anything written to stderr will not get mixed with
the LDAP output - nothing except valid LDAP should be written to stdout.
Ideally any stderr output should be logged, as it may indicate an error
even if the provider apparently publishes successfully.

In some cases the rpm command is used to extract a version number. This
will need modification for installations using packaging methods other
than rpm.

In many cases the status is determined from "/sbin/service svc status".
However, it may be desirable to move to wrapping this as the return code is
not necessarily correct and the StatusInfo message may not be very useful.

It does not seem to be possible to cleanly extract the start time of a process
as a timestamp value. However, in most cases the timestamp on a pid or lock
file is a suitable alternative.

The support for related services, i.e. adding the UniqueIDs of other
services as ForeignKeys, is rather basic, in that the list of IDs has to
be provided explicitly. Better support for particular services could
probably be managed given a concrete use-case. At the moment this is
only used by the FTS which has its own info provider.

Values are error-checked as far as possible. Errors are indicated with
variants on the well-known "4444" used by the GlueCE information provider.

Service-specific notes:

AMGA:

The protocol version is hardwired to 2.0.0 for now as this is correct for
all current AGMA servers.

The hostname used in the endpoint can be changed, e.g. to an alias, by
setting the AMGA_HOST environment variable before calling the provider.

The port is taken from the config file, or defaults to 8822.

The start time is taken from the lock file, the name of which is hardwired
(/var/lock/subsys/amgad).

BDII:

There are three BDII config templates: one for a generic BDII, and two for
site- and top-level BDIIs. The only real difference is the service type,
although the top-level config also publishes the FCR URL as a ServiceData
entry. 

The bdii.conf file is normally only readable by edguser (the bdii user)
because it contains a password, but in practice this shouldn't be a problem
for the info provider.

The bdii code is currently installed to /opt/bdii and there is no obvious
way to know if it is relocated, so in this case the variable BDII_CONF
should be set to the location of the config file.

To publish a DNS alias in the endpoint, define the BDII_HOST variable
appropriately.

The version is hardwired to 3.0.0 as all LDAP servers currently support
LDAP protocol version 3. It might also be useful to publish the Glue schema
version as ServiceData, but this has not so far been implemented as there
doesn't seem to be an especially easy way to do it.

gsirfio:

This is just a barebones implementation, it's not clear if we will want to
use this.

MyProxy:

Variables MYPROXY_CONF, MYPROXY_HOST and  MYPROXY_PORT can be set to define
non-standard values.

The version is hard-wired to 2.0.0 as it seems that all current MyProxy servers
use protocol version v2. It appears to be possible to get the version
dynamically from a reply to a telnet connection, and this may be implemented
in future. 

The various access control rules (authorized_renewers, default_renewers,
authorized_retrievers, default_retrievers, authorized_key_retrievers,
default_key_retrievers, trusted_retrievers, default_trusted_retrievers) are
published as AccessControlBaseRule entries with the special scheme MYPROXY,
which should be ignored by generic ACBR parsers, e.g.:

GlueServiceAccessControlBaseRule: MYPROXY:authorized_renewers=/DC=ch/DC=cern/OU=computers/CN=abc.example.org
GlueServiceAccessControlBaseRule: MYPROXY:default_renewers=/DC=ch/DC=cern/OU=computers/CN=renewerDEF.example.org
GlueServiceAccessControlBaseRule: MYPROXY:trusted_retrievers=/DC=ch/DC=cern/OU=computers/CN=trusted.example.org

There is no pid file, but there is a lock file so the creation time
is used for the service start time.

CREAM/CEMon:

These two services both run under tomcat, so the configuration is very similar
and they both use the same script (glite-info-service-cream) to set the
environment variables for host, port and pid file.

The Versions are set from the versions of the glite-ce-cream and
glite-ce-monitor rpms. As in other cases it isn't entirely obvious that
this represents the protocol version, and will need modification for
non-rpm-based installations.

The web service endpoints are hard-wired, but they are presumably
unlikely to change.

Possibly CREAM and CEMon should be connected as related services, but this
isn't implemented for now.

VOMS:

A VOMS server has a separate service for each VO served. The usage
is therefore slightly non-standard; there is a script called
glite-info-service-voms-wrapper which should be called instead of
glite-info-service, but with the same arguments. This determines the
list of VOs and calls glite-info-service once for each of them, setting an
environment variable (GLITE_INFO_SERVICE_VO) to pass the VO name. It also
constructs the GlueServiceUniqueID, appending the VO name, since the
standard algorithm would generate the same ID for each instance.

The publisher is almost entirely self-configuring since the VO names
and ports can be extracted from the local configuration files. However,
as usual the published hostname can be set to an alias name by setting
the VOMS_HOST environment variable.

The start time is taken from the lock file (assumed to be in
$GLITE_LOCATION_VAR/lock/subsys/voms.<vo-name>).

The Version is set to the version of the glite-security-voms-server RPM.

voms-admin

voms-admin is a web service running in a tomcat container. It has a generic
endpoint listing all supported VOs, plus an endpoint to manage each VO. This
could be treated in the same way as VOMS as described above, i.e. one
GlueService object per endpoint. However, the present configuration treats
it as a single GlueService, with the Endpoint being the generic endpoint,
and a ServiceData entry for each VO with a Key of "Endpoint-<vo-name>" and
a Value which gives the VO-specific endpoint. These endpoints can
alternatively be obtained from the published Endpoint by substituting
"/voms/<vo-name>" for "/vomses". 

Again this is largely self-configuring. However, the hostname, port and
pid file can be set externally if necessary using the VOMS_ADMIN_HOST,
VOMS_ADMIN_PORT and VOMS_ADMIN_PID_FILE environment variables.

The Version is set to the version of the glite-security-voms-admin-interface
RPM.

RTEPublisher:

This publishes a GridFTP endpoint as used for software installation on a CE.
As usual default values can be overriden by setting RTEPUBLISHER_HOST and
RTEPUBLISHER_PORT environment variables.

The endpoint includes the path to the tag directories, which is currently
hardwired to /opt/glite/var/info. This can be overriden by setting the
RTEPUBLISHER_PATH environment variable.

VO names are extracted from directory names two levels below the
RTEPUBLISHER_PATH, and published both as Owner and in ACBRs assuming
that the VOMS role used for publication is lcgadmin.

The start time is taken from a stat of the /proc directory for the
ftpd process.

The publication includes the suported SubClusters, as ServiceData entries
with a Key of GlueSubClusterUniqueID:<SubClusterID> and no Value. The
IDs are taken from the names of directories under the RTEPUBLISHER_PATH.

The version is set to 1.0.0 as the installation method has never changed.

VOBOX:

This is used to publish the gsissh service endpoint. As usual the hostname
and port can be specified if necessary (the port seems to be hardwired in
the init.d script).

The version number is hardwired to 1.0.0.

The init.d script for gsissh has no status method, so the status is just
based on whether the process is running.

There seems to be no URL for any user documentation for VOBOXes.

SRM-DPM:

There are two configuration files for the v1 and v2 endpoints, as both can
currently exist. The v2 configuration is effectively explicitly for 2.2
due to the way DPM is configured.

The start time is taken from the DPM daemon rather than the SRM itself. The
PID file location is apparently hardwired in the init.d script.

The hostname is taken from the DPM_HOST variable, or failing that from
the shift.conf file, or failing that from "hostname -f". The second
option may be fragile as it depends on the detailed format.

The port is also taken from the shift.conf file or else defaulted.

If the presence of a host certificate/proxy were assumed the version
and status could be obtained with an SRM ping, but this has not so far
been done. The version is hardwired, and the status uses
"service xxx status" on the DPM, DPNS and SRM services.

SRM-dCache:

There are two configuration files for the v1 and v2 endpoints, as both can
currently exist.

dcache is assumed to be installed in /opt/dcache by default, this can be
overridden with the DCACHE_DIR variable.

The hostname is taken from the DCACHE_HOST variable, or failing that from
the node_config or dCacheSetup files, or failing that from "hostname -f".
The second option may be fragile as it depends on the detailed format, and
also the locations and names of the config files.

The port is taken from dCacheSetup or defaults to 8443.

The versions are currently hardwired.

The init.d script does not have a status method, so this is emulated using
the PID file (the location of which is hardwired).