2. Installation

Clarens is loosely tied to the Unix/Linux platform, but has only been tested on the Linux on x86 and Solaris on SPARC implementations. This still leaves a wide variety of OS versions to contend with. Instead of relying on versions of the underlying components supplied by the operating system, Clarens is routinely built and distribted in binary form as a set of RPM [12] packages built on top of OpenPKG [7].

The home of the Clarens RPM packages is at http://hepgrid1.caltech.edu/clarens/. In the following paragraphs the installation procedure is described using manual (interactive) and automated methods.

2.1 Installation using clump

The Yellow dog Updater Modified (YUM) [15] is a Python-based automated installer updater that is an easy-to-use automated installation/update tool that is widely supported with numerous package repositories for operating system updates and third-party packages for Linux distributions. This tool has been adapted for use in an OpenPKG environment, and renamed to clump to avoid confusion with the system version of YUM. This is the preferred tool to install and keep a Clarens server updated.

1. To install as the superuser (root) do:
   wget -q -O - http://hepgrid1.caltech.edu/clarens/setup_clump.sh |sh
export opkg_root=/opt/openpkg

2. To install as an ordinary user do:
   wget -q -O - http://hepgrid1.caltech.edu/clarens/setup_user.sh
sh setup_user.sh
   You will be prompted for in installation path. The default is $HOME/openpkg. Then:
   export opkg_root=/my/directory
   

3. If your host already has a certificate/key pair, these can be copied to
   $opkg_root/etc/grid-security
   Make sure that both files are readable by user nobody in the case of a superuser installation.

4. The server can be controlled with
   $opkg_root/etc/rc apache2 start|stop|restart

5. To make sure that the server works, point your web browser at
   https://my.server.name:8443/clarens/clarens_index.html
   using the correct servername or IP address of course.

6. The base address of the server is
   http://my.server.name:8080/clarens/ or
   https://my.server.name:8443/clarens/ for an encrypted connection.

Startup problems are reported on the terminal when the server is started, or recorded in the log file at $opkg_root/apache2/log/error_log.

2.2 Manual OpenPKG installation

Since OpenPKG contains its own RPM database it must be bootstrapped in some way without using the (possibly non-existent or incompatible) system version of RPM. This is done by distributing the base package as a uuencoded shell archive.

The information below describes the procedure carried out by the setup shell scripts for clump, and is provided for completeness. If you are not comfortable with typing in commands in a terminal, please use one the above automated methods instead.

1. Point your browser at
   http://hepgrid1.caltech.edu/clarens/openpkg-binary-redhat-7.3/.
   Fetch the OpenPKG base archive, e.g.
   openpkg-20030813-20030813.ix86-linux2.4-oo.sh
   

2. Install the base package with the following command as root:
   sh openpkg-20030813-20030813.ix86-linux2.4-oo.sh

3. Initialize the OpenPKG runtime environment:
   eval $(/opt/openpkg/etc/rc --eval all env)
   Note that this will only work in a bash, Bourne, or Korn shell environment, not a C-shell.

   It might be useful to add the following to your login scripts to avoid having to type in the above every time the environment is used:

   Shell

   export opkg_root=/opt/openpkg
   alias opkg_init='eval \$(\$opkg_root/etc/rc --eval all env)'
   

   
   
   

4. Download and install all the RPMs from the above location with
   rpm -i *.rpm

5. Start the server with
   /opt/openpkg/etc/rc apache2 start

2.3 Post-Installation Configuration

As with any complex server application, Clarens has many parameters that can be changed to tune its operation to specific task at hand. In the following sections the basic setup parameters of Clarens will be covered.

2.3.1 Apache Web Server

The Apache[1] web server is controlled by one (or a series of) configuration files, starting from the file $opkg_root/etc/apache/httpd.conf. The format and meaning of options in this file is explained in detail at the web pages cited above, but the default configuration used by Clarens deserves some explanation.

• Firstly, the Apache server is run as the user set up by OpenPKG called nuser, short for nobody user. If the server was installed using the superuser installation procedure in 2.1, this would in fact be the nobody user which exists on most systems with extremely limited privileges. By default, this user cannot even log in to the system! The owner (user and groupname) of the server process is set up by the User and Group directives in the httpd.conf file.

  If the user installation procedure was used, the server will run as the same user that did the installation, since normal users are not able to change process ownerships and run applications as other users than themselves. In this case changing the User and Group directives will not have any effect. Except producing an error message in the logs!

• Secondly, the server is set up to listen on two ports, one for unencrypted (plaintext) connections, and one for Secure Sockets Layer (SSL) connections. The plaintext port is set up in the httpd.conf file by the Listen directive while the SSL port is set up by the same directive in the ssl.conf file, which is located in the same directory. These ports are set to values of 8080 and 8443 respectively by default.

  For a superuser installation the port numbers may be lower than 1000, with defaults of 80 and 443 assigned to the HTTP and HTTPS protocols by convention.

• Thirdly, variables controlling the mod_python module's behaviour are stored in a configuration file
  $opkg_root/etc/clarens-config/httpd/clarens-server-default.conf. For more information on the meaning of the options in this file, the mod_python documentation should be consulted. In general it should not be necessary to change this file.

  There may actually be several of these files for different Clarens installations running under the same Apache server.

2.3.2 Server Module Configuration

In the paragraphs all the setup parameters were for the purpose of telling the Apache web server to hand requests off to the mod_python module. Clarens itself also needs some information about where to find some files and store its own databases and so forth.

In order to make changing these parameters easier, the Clarens server package contains an application called clarens-server-config. This application takes care of creating a configuration file. By default the configuration file is stored in $opkg_root/share/apache/clarens/clarens_config.py

Figure 2.1: The clarens-server-config application

Figure 2.3.2 shows a screenshot of clarens-server-config in action. The section labeled Main server configuration shows the configuration parameters and their current values. To change the value of a parameter, use the up and down cursor keys to move the cursor to the chosen value and fill in the required text. Moving the cursor to one of the [Help] buttons and pressing Enter will bring up an explanation of the option in question.

Just as with the main configuration, all add-on modules can have their own sets of parameters. To change a module's parameters, move the cursor until the module name is highligted and press Enter. You will be presented with a list of options and Help values analogous to the main server screen.

After the configuration is changed it can be (and should be!) saved by pressing Enter on the Save Config option. The option values are saved in the directory
$opkg_root/etc/clarens-config/conf/default
The main server options are saved in the file config in that directory, with a subdirectory for each module also containing its config file.

The format of the config files consist of lines, each with comma separated fields for the option internal name, option value, option external name (displayed by the configuration application), help string, and the keyword INTERN or EXTERN. The latter values are written to a final cofiguration file named clarens_config.py that can be accessed by Clarens at runtime. INTERN values are only accessible at install time. Examples of such internal configuration values are the Apache server version and the Apache configuration file location.

2.3.3 Virtual Organization

Each Clarens server instance manages a tree-like VO structure, as shown in Figure 2.2, rooted in a list of administrators. This group, named admins, is populated statically from values provided in the server configuration file on each server restart. The list of group members is cached in a database [2], as is all VO information. The admins group is authorized to create and delete groups at all levels.

Each group consists of two lists of DNs for the group members and administrators respectively. Group administrators are authorized to add and delete group members, as well as groups at lower levels. The group structure is hierarchical because group members of higher level groups are automatically members of lower level groups in the same branch.

The example in Figure 2.2 demonstrates the top-level groups A, B, and C, with second level groups A.1, A.2, and A.3.

Figure 2.2: Clarens virtual organization diagram.

A more concrete example might be to define groups CMS, Atlas, LHCb, and Alice, then for CMS, to define CMS.USA, CMS.CERN, CMS.UK, CMS.Germany. At the third level, one might define CMS.USA.Caltech, CMS.USA.UFL, CMS.USA.FNAL. Management for the latter three groups may then be delegated to the institutes themselves, thereby implementing a distributed trust model that has lower maintenance overhead as well as being more representative of the real organizational structure.

As a further optimization, the hierarchical information in the DNs may also be used to define membership, so that only the initial significant part of the DN need to be specified. DNs are structured to include information on the country (C), state/province (ST), locality/city (L), organization (O), organizational unit (OU), common name (CN), and e-mail address (Email). An example DN issued by the DOE Science Grid CA is
/O=doesciencegrid.org/OU=People/CN=John Smith 12345
for individuals and
/O=doesciencegrid.org/OU=Services/CN=www.mysite.edu
for servers. To add all individuals to a particular group, only
/O=doesciencegrid.org/OU=People
need to be specified as a member DN.

2.3.4 Method Access Control

Since version 0.5.0 the Clarens server enforces access control on methods accessed by clients based on user distinguished names, as well as groups of users.

The access control list (ACL) for the echo module in the above example can be specified using methods in the system module, or bootstrapped using a file in the same directory as the __init__.py file.

2.3.4.1 The .clarens_access file

The file specifying the ACL for a module is a Python script, named .clarens_access placed in the module's subdirectory. It should initialize a list with the name access in the main context. The access control list itself consists of a list of tuples (or lists), one for each ACL. An ACL may be specified for the entire module, or on a method by method basis.

An example to illustrate:

PYTHON

ORDER_ALLOW_DENY=0
access=[("",[ORDER_ALLOW_DENY,   # Order
         ["/"],                  # Allow everybody who can log in
         [],                     # Allow group
         [],                     # Deny indiv default=all
         []  ,                   # Deny default=all
         [None, None, None]])]   # modtime, start_time, end_time

The first tuple in the access list has an empty string as its first member, signifying that this ACL is to be applied to all methods in this module, unless overridden by a specific method ACL later. the second member The second member of the tuple is a list consisting of

• the ACL evaluation order
• a list of allowed distinguished names (empty in this case)
• a list of allowed groups
• a list of denied distinguished names
• a list of denied groups.
• a list with three members set to None. These are used for time values internally, and will be filled in by the Clarens server.

In this case the allowed DNs and groups lists are evaluated first, before the equivalent denied lists. That means that if a group or DN is present in the allowed and denied lists, the allowed list will have preference and the DN or group will be allowed. Groups can be created using the methods in the group module. The way that distinguished names (DNs) ar evaluated in the above lists deserve special mention: If a substring of the DN is found it is considered a match. E.g. the DOEGrids CA issues certificates with DNs of the form
/DC=org/DC=doegrids/OU=People/CN=Joe User 12345

If access needs to be granted to all DNs issued by this CA, simply add the following to the allowed list:
/DC=org/DC=doegrids

Or if all DNs issued to people by this CA needs to access this module, add
/DC=org/DC=doegrids/OU=People

The ACL in the above example might then look like this:

PYTHON

ORDER_ALLOW_DENY=0
access=[("",[ORDER_ALLOW_DENY,   # Order
         ["/DC=org/DC=doegrids/OU=People"], # Allow all People trusted by 
                                 # DOEGrids Certificate Authority
         [],                     # Allow group
         [],                     # Deny indiv default=all
         []  ,                   # Deny default=all
         [None, None, None]])]   # modtime, start_time, end_time

Since the DNs are always evaluated in the format with forward slashes as field separators, an individual DN is always matched by the string "/". Using that as an access specifier is a convenient way to allow or deny access to all users.

2.3.4.2 Individual methods

Some methods may should only be executed by certain users, like methods that perform some administrative function. In that case a tuple may be added for that method. E.g. if the echo module has a method set_string that may only be accessed by the admin group, but the echo method itself should still be executable to all, the ACL might look like this:

PYTHON

ORDER_ALLOW_DENY=0
access=[("",[ORDER_ALLOW_DENY,   # Order
         [],                     # Allow everybody who can log in
         [],                     # Allow group
         [],                     # Deny indiv default=all
         []  ,                   # Deny default=all
         [None, None, None]])    # modtime, start_time, end_time
        ("set_string",[ORDER_ALLOW_DENY,
         [],                     # Allow everybody who can log in
         ["admin"],              # Allow group
         [],                     # Deny indiv default=all
         []  ,                   # Deny default=all
         [None, None, None]])    # modtime, start_time, end_time

2.3.4.3 The system module

In the above ACL specifications, the module name was implicitly added to the method specification, e.g. echo.set_string. For the system module this is not done, implying that ACLs for other modules may be set using the system ACLs.

Since the modification time of the .clarens_access file is used to determine whether it should be parsed, an ACL specification for a module or method in its own directory and the system directory will mean that the most recently modified ACL will be used.

2.3.5 File Access Control

File ACLs are analogous to the method ACLs discussed above, with the addition of fields for write access. The ACL file should also be called .clarens_access, and such a file may be placed in each directory.

For example if the below ACL specification is placed in the Clarens file service virtual root directory, everyone will be given read access to the "/" directory:

PYTHON

ORDER_ALLOW_DENY=0
ORDER_DENY_ALLOW=1
access=[("",                                # File or dir to apply ACL to
         [ORDER_DENY_ALLOW,                 # Order
         ["/"],                             # Allow indiv read
         [],                                # Allow group  read
         [],                                # Deny indiv read
         [],                                # Deny group read

         [],                                # Allow indiv write
         [],                                # Allow group write
         [],                                # Deny indiv write
         []])]                              # Deny group write

As with methods, an empty file or directory name indicates the current directory, while a named file of directory applies to its that entity in the current directory.

Extending this example to give wite access to the rootfiles subdirectory to people with DOEGrids certificates:

PYTHON

ORDER_ALLOW_DENY=0
ORDER_DENY_ALLOW=1
access=[("",                                # File or dir to apply ACL to
         [ORDER_DENY_ALLOW,                 # Order
         ["/"],                             # Allow indiv read
         [],                                # Allow group  read
         [],                                # Deny indiv read
         [],                                # Deny group read

         [],                                # Allow indiv write
         [],                                # Allow group write
         [],                                # Deny indiv write
         []]),                              # Deny group write

         ("rootfiles",                      # File or dir to apply ACL to
         [ORDER_DENY_ALLOW,                 # Order
         ["/"],                             # Allow indiv read
         [],                                # Allow group  read
         [],                                # Deny indiv read
         [],                                # Deny group read

         ["/DC=org/DC=doegrids/"],          # Allow indiv write
         [],                                # Allow group write
         [],                                # Deny indiv write
         []])]                              # Deny group write

2.3.5.1 Avoiding possible conflicts

As the above example illustrates, it is possible to specify an ACL for a subdirectory (e.g. "rootfiles" above ) at a higher level in the directory hierarchy (e.g. "/" above). Since it is also possible to do so in the subdirectory itself, there may be two files specifying the ACL for that entity.

This should be avoided at all costs, since it is impossible to determine which ACL specification will actually be used. I.e. specify the ACL of an entity in only one .clarens_access file!