6. Service packaging and configuration

This chapter is neccesarily short becuase in versions of the Clarens aserver after 0.7.0 installation of new services became exeedingly simple: install the service files in the reight directory, and install one or more configuration files in the configuration directory.

6.1 Service installation

6.1.1 Service code

In order for a new service to be accessible it should be installed as a Python module under the Clarens toplevel service directory. Usually this means creating a subdirectory under
/opt/openpkg/share/apache/clarens
containing a file called __init__.py and .clarens_access as described in Chapters 5 and 2.

6.1.2 Configuration files

Services needing extra configuration parameters may create a file named config in a directory structure used by the clarens-server-config program.

By convention, each config file should be in a subdirectory with the same name as the service itself, under the toplevel directory. Multiple Clarens server instances can be run under the same Apache server under different virtual server paths, but it is assumed that there will always be one instance named default, with a set of configuration files under the toplevel directory /opt/openpkg/etc/clarens-config/conf/default/.

6.1.3 Minimal example

As an example, we create a service with the name picalc that calculates a large number of digits of the number $\pi$. The service contains one method that takes the number of digits required and returns the appropriate answer.

The service is also smart enough to store the answers in a small database so that it doesn't need to recalculate the answers it already knows. It stores the answers in a database that can be specified by the server administrator.

If the default installation is used, the new service would consist of the following files:

File list

/opt/openpkg/share/apache2/clarens/picalc/__init__.py
/opt/openpkg/share/apache2/clarens/picalc/.clarens_access
/opt/openpkg/etc/clarens-config/conf/default/picalc/config

When the service is packaged, these files should be included in the package so that thay can be installed in the same locations.

6.2 Service configuration

6.2.1 Configuration file format

A short description of the configuration file format was given in section 2.3.2. A more elaborate description and example will be given here.

Each service has it's own configuration file, making it possible to easily distribute services without requiring the user to edit a central configuration file. Configuration files are text files that can be created with a text editor. Each file contains a set of options and their descriptions, one per line, that serves as input to the clarens-server-config utility that in turn will create a single Python configuration file that the Clarens server can use directly.

Each configuration line consist of a comma-separated list of five values as shown in Table 6.1.

Table 6.1: Configuration file description

Name	Description
Variable name	A gloablly unique configuration variable name. Because this is a string, it should be quoted
Value	The value of the variable, also a string
Label	A short human-readable string label of the configuration item. This label will be visible next to the item value in the clarens-server-config display
Help text	A longer description string of the configuration option. This will be displayed as the Help text for the option. Line breaks may be inserted using $\backslash$ n
Status	Either INTERN or EXTERN. The latter will be included in the final configuration made available to the Clarens server

All five configuration items should be on a sigle line, one per variable. The configuration file can also contain comments, denoted by the hash symbol, $\char93$ at the beginning of the line.

Lines not conforming to the above format will simply be ignored by clarens-server-config.

6.2.2 Configuration file example

A short example configuration file might look as follows:

Configuration file

# Auto-generated configuration file created by clarens-server-config
'gridmapfile','/my/gridmap-file','Gridmap','Globus-style gridmap file',EXTERN
'suexec_path','/bin',"Suexec dir','Path to the clarens-suexec file',EXTERN

This file contains three lines, one for an initial comment and two containing definitions for the gridmapfile and suexec-path variables.

6.2.3 Command-line configuration

The configuration utility can also be run in a non-interactive batch-oriented mode which can be useful in scripts and to obtain debugging information printed during execution. In order to activate this batch mode, use the command
clarens-server-config -batch -save.

To print out the debugging information generated as the utility is running add the -debug option to the above. To obtain a full list of options, run the command using the -help option.