Incubator/Dynamic Accounts/Documentation/TP5/InstallationGuide

From Globus

Navigation:

Dynamic Accounts - Documentation - TP5 - InstallationGuide

Contents 1 GT4 1.1 Recommended Installation: 1.2 Compatibility 2 Download 2.1 Service code and back-end implementations 2.2 VOMS parsing libraries 3 Deploy 4 Install the System Backend 4.1 database pool accounts (default) 4.1.1 Installation 4.1.2 Configuring the pool mapping 4.1.3 Configuring the service with pool accounts 4.1.4 Expire and Quarantine 4.2 LCMAPS pool accounts 4.2.1 Install LCMAPS 4.2.2 Set up pool 4.2.3 Associations 4.2.4 Install lcmaps_poolindex 4.2.5 Termination 4.3 useradd 5 Authorization Scheme 5.1 General overview 5.2 Creating dynamic accounts: Factory Service Authorization Configurations 5.2.1 DN ACL 5.2.2 DN banlist 5.2.3 Attribute ACL 5.2.4 Attribute banlist 5.2.5 Separate query authorization 6 Using DA with GRAM

GT4

The Dynamic Accounts Service requires the Globus Toolkit 4 (GT4) hosting environment. The GT4 hosting environment can be embedded in applications, deployed in Tomcat (Java only), or run in a standalone container.

Note: all subsequent Globus related directions assume that you are using the standalone container on Linux.

Recommended Installation:

The recommended installation procedure for GT4 can be found here -- the quickstart is helpful.

Only Java WSRF core and a basic Globus security configuration are necessary to install and configure -- see Globus is Modular for more information about minimal installations.

Compatibility

The Dynamic Accounts Service is only compatible with GT4 WSRF based releases, these documents reflect GT version 4.0. Currently, the service is provided in Java and there are only system account implementations available for Unix/Linux systems.

Download

Service code and back-end implementations

These can be downloaded here:

$ wget http://workspace.globus.org/downloads/dynamic_accounts_TP_5.tgz
$ tar xvzf dynamic_accounts_TP_5.tgz
$ cd workspaceService
$ export DA_HOME=pwd`

$DA_HOME has five subdirectories: client - Java source code for the example client command line program. common - WSDL files, Java stubs are generated directly from these. docs - HTML files. local - Programs for implementing dynamic Unix accounts. service - Java source code for the Grid Services. Also, user editable files for deploy-time configurations.

VOMS parsing libraries

The VOMS parsing libraries are from the gLite cvs. A binary can be downloaded directly here if you agree with the licensing terms.

NOTE: You must place this jar file in the $DA_HOME/service/java/source/lib directory in order for the service to compile.

Deploy

Given a working GT4 installation, deploying the service to the container is just a matter of configuring the deployment information and running the ant build process.

1. Set GLOBUS_LOCATION

$ export GLOBUS_LOCATION=/path/to/GL

2. Edit $DA_HOME/service/java/source/deploy-jndi-config.xml

Parameter	Description
WorkspaceFactoryService:defaultTTL	Default account time-to-live (in minutes)
WorkspaceFactoryService:maxWorkspaces	Number of workspaces per unique credential used for the create operation (currently only for LCMAPS and database impls).
WorkspaceService:resourceClass	Configures accounts implementation to use: org.globus.workspace.impl.service.LeasedAccountsResource (default) org.globus.workspace.impl.service.LCMAPSResource org.globus.workspace.impl.service.UnixAccountsResource
WorkspaceService:conffile	Location of lcmaps configuration file
WorkspaceService:sweeperDelay	How often workspaces are checked for reaping (in ms). Default is every second (i.e., workspace TTL is respected to the second).
WorkspaceService:lcmapsMultipleLeases	Set to true if multiple leases are allowed for LCMAPS (this is a bit redundant to factory setting, will fix in future version)

3. Stop service container

4. Deploy services

$ source $GLOBUS_LOCATION/etc/globus-devel-env.sh   (or .csh)
$ cd $DA_HOME
$ ant deploy

5. Install appropriate system program to $GLOBUS_LOCATION/bin (see next section about backend installation)

6. Add logging declaration to $GLOBUS_LOCATION/container-log4j.properties:

log4j.category.org.globus.workpsace=INFO

7. Start service container. The EPRs to use will be advertised:

Starting SOAP server at: https://host.org:8443/wsrf/services/
With the following services:

[1]: https://host.org:8443/wsrf/services/WorkspaceFactoryService
[2]: https://host.org:8443/wsrf/services/WorkspaceService

Install the System Backend

A system administrator may want to configure accounts according to different policies. In order to support a range of possibilities offering different trade-offs in terms of control, flexibility and maintenance we currently provide two back-end implementations.

The "adduser" method calls directly a Unix command creating an account via a setuid process. After termination the account is destroyed such that no other user ever maps to this account. The advantage of this method is flexibility (a new account gets created on the fly) and also the fact that the same account is never "recycled" for another Grid identity which simplifies audit.

Although in principle such accounts could hit the naming limit, in practice this is very unlikely to happen. Also, this method ensures that there are only as many accounts at a given time as necessary. On the other hand, this method is likely to interfere with local account management systems and makes it hard for local administrators to exercise tight control over the account creation, configuration and termination.

For this reason, many site administrators prefer to use a pre-generated pool of accounts. Such accounts are created directly and configured by the site administrator in a site-specific way. The workspace service then creates a binding between a specific Grid entity and a new account taken from the pool. Account termination means that such binding (and all the access policies that it implies) is destroyed. While account termination may mean "clean up" (file deletion, etc.) it does not necessarily mean that an account is deleted. It may be quarantined and then restored to the pool in site-specific way to be used with a different Grid entity.

While this method allows the site administrator to closely control the process of account creation and termination, it has some limitations. The pre-generated account pool is finite. Statically allocating resources to these pre-generated accounts may mean that those resources will get allocated even if they are not immediately needed. And the possibility of mapping multiple identities to the same account complicates audit.

database pool accounts (default)

This pool account implementation uses a database to keep track of the local accounts that are allocated. We used Apache Derby for our implementation, but it can be easily be replaced by any JDBC compliant database. By default everything is deployed and configured to work with Derby. There are however a few more steps an administrator needs to take to configure the service.

Installation

You can deploy the package by running ant deploy in top-level dir. (There are no special deployment instructions for the database as ant deploy will take care of deploying and configuring the database for use).

See

Configuring the pool mapping

The service considers two files when ascertaining which account pool a lease request should map to. These files are:

• grid-mapfile - This is used to do specific caller-DN based mapping. This defaults to the DN authorization file configured under the etc directory.

• attr-autz file under the service etc directory - This is used to perform a more scalable attribute to pool mapping.

Note: the pool accounts are represented with a "." character in front of them.

For example, if accountpool1 is a pool of accounts that you want DN foo to be mapped to, then a entry in the grid-mapfile would look like this:

"foo" .accountpool1

If you want to do attribute based mapping then (assuming you have enabled VOMS processing), the attr-authz file needs to be populated like this:

"foo" .accountpool1

Configuring the service with pool accounts

In this implementation each pool of accounts is represented with a file under $GLOBUS_LOCATION/etc/workspace_service/pools/. Note that the name of the file should be the name of the pool. So if you have, for example, three account pools names accountpool1, accountpool2, accountpool3 then your directory structure under $GLOBUS_LOCATION/etc/workspace_service/pools/ would look similar to this:

$ ls $GLOBUS_LOCATION/etc/workspace_service/pools/
accountpool1
accountpool2
accountpool3

The contents of a typical file under pools dir should be the list of the account names that are under that pool. For example, if you have 4 local accounts under accountpool1, then the contents of a file named "accountpool1" (this file should have the same name as the pool name) would list the system account names, one per line, e.g.:

$ cat $GLOBUS_LOCATION/etc/workspace_service/pools/accountpool1
poolaccount1
poolaccount2
poolaccount3
poolaccount4

Expire and Quarantine

After an account is terminated (either explicity by a WS destroy operation or by the termination time being reached), the service can optionally invoke an expiration script that will clean an account to prepare it for the next leasing. This script should contain site specific logic, an example is included that deletes all user processes, all user files in ~ and /tmp. There are safety mechanisms in place in this script, see the comments in $SRC_DIR/local/leased/sample-expire.sh. The script to use is a configuration entry in the jndi-config.xml file.

If using this script, it is recommended to call the script with root privileges via sudo in order to ensure a complete erasure of the pool account user's activities. A sample is included in $SRC_DIR/local/leased/sample-via-sudo.sh In all cases the expire script should only be writable by root and placed in a directory only writable by root.

Before this script is invoked, the account is quarantined. This means the account cannot be leased but is also not available to the previous authorized clients anymore. The account remains quarantined during the expiration callout. If the expiration callout returns a failure code, the account will not be unquarantinedand will remain unleasable until manual administrator action.

LCMAPS pool accounts

The Dynamic Accounts Service can be configured to use LCMAPS, a local credential mapping service developed by David Groep and Martijn Steenbakkers (NIKHEF Amsterdam, the Netherlands). We employ a subset of LCMAPS's functionality, the pool and VOMS credential mapping plugins.

LCMAPS uses a flexible algorithm configurable with a custom policy definition language to associate credentials with pool leases.

Upon account creation, the Workspace Service calls the 'lcmaps_poolindex' program (that we provide) that calls the LCMAPS poolindex function which associates credential information with a pool lease. LCMAPS leases an acount via hardlink in the gridmapdir - a directory set up explicity to lease pool accounts based on Andrew McNab's gridmapdir patch.

Upon account termination, the Workspace Service calls the 'lcmaps_poolindex' program to remove the lease from the gridmapdir, quarantine accounts (if configured to do so) and callout to a site specific program to clean the user account (we provide an example system script). The termination procedure is documented below.

As of version TP4, the LCMAPS service implementation includes support for persisting WSRF resources. If the container is rebooted, the service maintains continuity and no information is lost.

The directions here are not complete LCMAPS instructions, but instructions for driving LCMAPS with the Dynamic Accounts grid services and system tools. For full documentation, see the LCMAPS page.

Install LCMAPS

The LCMAPS code itself is not included in the Workspace Management Service distribution.

Installation notes for LCMAPS and the Dynamic Accounts service can be found here but we also provide instructions below (use one or the other set of directions). If you have gLite installed, LCMAPS is included as part of the distribution.

The code is also available via anonymous CVS. A script of the checkout/build process is available here. If you run it from $DIR, the build directory is $DIR/egee. The code will be installed to $DIR/egee/stage but the script takes an optional argument to override the install prefix to another location. A typical location is /opt/glite

e.g.,

./lcmaps_cvs.sh /usr/local

Set up pool

Before configuring LCMAPS, set up a pool of users.

1.

# mkdir /path/to/gridmapdir

2. Create Unix accounts. One option is to use a creation script (via Andrew McNab):

• addpoolusers script
• addpoolusers2 script (non redhat, lacks the -n flag to useradd)

Look at the scripts carefully before use. It is especially important to set the first five variables of the script to valid values.

3. If you did not use the creation script, /bin/touch a file in the gridmapdir for each account in the pool. The accounts need to have a common prefix, e.g., 'pool001','pool002',etc., to be considered in the same pool

4. LCMAPS needs to know to use this pool, set the "gridmapdir" paths in lcmaps.db

A sample lcmaps.db file that works well with the workspace service can be viewed here.

lcmaps.db can be stored anywhere on your file system (if readable by the globus user).

Associations

LCMAPS uses two files to associate DNs and attributes to pools and groups.

This sample grid-mapfile associates the attribute "/EGEE/egee" with the 'EGEE' pool (users in gridmapdir with prefix 'EGEE') and another attribute "/EGEE/egee/manager" to a separate pool. Also, here a DN is mapped to directly to a pool.

"/O=dutchgrid/O=users/O=nikhef/CN=UserSmith" .mgmtpool
"/EGEE/egee/manager" .mgmtpool
"/EGEE/egee" .EGEE

This sample groupmapfile associates the attribute "/EGEE/egee" with the Unix group 'egtest' and the attribute "/EGEE/egee/manager" with the Unix group 'egmgr'.

"/EGEE/egee" egtest
"/EGEE/egee/manager" egmgr

LCMAPS needs to know how to find these files. It does by using lcmaps.db. A sample lcmaps.db file can be viewed here.

Configure lcmaps.db to use the appropriate files. Also create a directory "groupmapdir" and configure the -groupmapdir field in lcmaps.db

Install lcmaps_poolindex

To configure the lcmaps_poolindex program, edit $DA_HOME/local/lcmaps/source/lcmaps_poolindex.conf which contains text explaining each option.

One of these settings is a path to an account expiry program (we provide a sample program). For a full termination explanation, see the termination section below.

Edit $DA_HOME/local/lcmaps/source/Makefile: set correct path to 'org.glite.security.lcmaps-interface/interface' for the headers.

Once configured, compile and install lcmaps_poolindex by running:

$ export GLOBUS_LOCATION=/path/to/globus
$ make install

The program "lcmaps_poolindex" is now in $GLOBUS_LOCATION/bin where the service code expects it to be.

NOTE: In order for the service to call the LCMAPS driver correctly, the deploy-jndi-config.xml 'conffile' setting must point to the configuration file you configured above

NOTE: remember for the service code to drive LCMAPS for its backend, the deploy-jndi-config.xml resourceClass has to be set to org.globus.workspace.impl.service.LCMAPSResource

NOTE: if the LCMAPS install is not in the system shared library search path, you must add it before starting the container as it is the container process' environment that will be loading the library

$ cd $GLOBUS_LOCATION
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/lcmaps/install/lib
$ ./bin/globus-start-container 2>&1 | tee globus_log

Termination

Account termination is achieved by either an authorized destroy request, or by allowing the account's time to live (TTL) to expire. An authorized client can prevent automatic termination by extending the termination time.

The setuid program is called with -unlease_poolindex to expire the lease in the gridmapdir and can optionally be configured (in lcmaps_poolindex.conf) to put a quarantine on the account. The quarantine lasts until the quarantine hardlink (e.g., "pool002.quarantined") is removed, either by a script or manually (rm *quarantined). After the lease is expired, the program can optionally be configured (in lcmaps_poolindex.conf) to invoke a site specific script that should deal with cleaning up an expired account. The example script included (expire_pooluser) kills all the user's processes (via kill -9), deletes all the user's files, and reverts the user's group back to the default.

Note

Whether or not quarantine is configured, the account is quarantined during the lease removal process. If any configuration problems or callout script errors occur, the account remains quarantined whether or not DO_QUARANTINE is configured.

expire_pooluser Errors

• The C program expects 0 for success and non-zero for failure. Non zero return values are logged and translated to the EXPIRY_PROG_FAILURE return value (see errors.h). This signals the service that there was an internal failure in the script that was called.
• The C program is currently set up to check several aspects of the program it is configured to run (program path is configured in lcmaps_poolindex.conf). The program must exist as a regular file and be executable by its owner. The program must not be editable by any user other than the effective UID of the program. These situations return the EXPIRY_PROG_CHECK error (see errors.h) from the setuid program to the Java service (triggering an exception) and implies an environment problem.
• Note: at the point either of these types of problems occurs, the lease (the gridmapdir mapping that actually secures the lease) is expired. Also, the account is quarantined and unavailable for new pool leases (a good safety net, an administrator can examine the problem with the expire_pooluser.sh script) no matter if DO_QUARANTINE is configured or not).

In the future a Developer's Guide will explain how to configure a different program entirely to call at resource destruction (i.e., modification of the C call from Java). This 'termination' section refers to modifying the lcmaps_poolindex program's invocation of the expire script, which is different.

useradd

Currently there is no documentation for the useradd implementation.

Authorization Scheme

Dynamic account creation and management is subject to authorization policies. This section explains how those policies are configured.

The service supports both push mode and pull mode authorization. The push mode assumes information carried in the credentials and is currently supported via the VOMS credentials (the support is extensible, see the developers guide). Ordinary X509 credentials are naturallly accepted. The pull mode is configured via policy decision points (PDPs) calling out to access control lists (ACLs) as explained below.

In addition to the above, we allow for authorizing clients against a configured DN and attribure banlist. The deployment has a default implementation which looks up files to get the list of DNs and attributes not allowed to use the service. The implementation can be extended/overridden for other site specific banlist scheme.

General overview

• Step 1: A client call to the factory service is protected by access control lists (DNs and/or attributes). The policy file paths are configured in the factory section of server-config.wsdd.

• Step 2: If pooled accounts are being used, the factory maps the caller to an account pool. The mapping policy file paths are configured in the jndi-config.xml file and these default to be the same as the creation authorization files.

• Step 3: The dynamic account is instantiated and represented by a WSRF resource instance. There are two separate policies associated with this resource instance: who can manage the account and who can access the account on the grid. Both of these default to the DN of the factory-create caller, but they can be altered. (The policy about who can access the account can be passed in as a parameter to the create request)

• Step 4: When a management call is made (e.g. "extend termination time", "add DN to the access policy", or "destroy"), the management policy is consulted.

• Step 5: Remote components may call the query operation to see what accounts are mapped to a DN (or attribute). This query operation itself may be protected by a separate policy (also DNs and/or attributes) than the factory-create call, but it currently defaults to be the same policy. To separate them (e.g. to prevent phishing) and only allow trusted services to make queries, see below.

Creating dynamic accounts: Factory Service Authorization Configurations

Operations on the factory are authorized via the ACL mechanism. Entities can be authorized by DN or by attribute (in which case any DN with a specified attribute gets authorized). Two ACLs are used: one for DNs (consulted first) and one for attributes.

DN ACL

Before service deployment (before you run "ant deploy") the DN ACL file can be found here:

$DA_HOME/service/java/source/etc/dn-authz

After service deployment the file is deployed to:

$GLOBUS_LOCATION/etc/workspace/dn-authz

The policy in this file can be modified after the service is deployed.

Example of a DN ACL, one DN per line, no quotes:

/DC=org/DC=doegrids/OU=People/CN=Timothy Freeman 964650
/DC=org/DC=doegrids/OU=People/CN=Rachana Ananthakrishnan 485437

DN banlist

Before service deployment (before you run "ant deploy") the DN banlist file can be found here:

$DA_HOME/service/java/source/etc/dn-banlist

After service deployment the file is deployed to:

$GLOBUS_LOCATION/etc/workspace/dn-banlist

The policy in this file can be modified after the service is deployed.

Example of a DN banlist:

"/DC=org/DC=doegrids/OU=People/CN=Rachana Ananthakrishnan 485437" .foo

The presence of the pool mapping on the right side is a convenience for the typical scenario where the same file is used for factory authorization and for pool mappings. The file to use for pool mappings is configured in the jndi-config.xml file and it is by default the same as listed in server-config.wsdd for authorization. If this is only being used for authorization the value on the right can be arbitrary but must exist due to an implementation nit.

Attribute ACL

Before service deployment (before you run "ant deploy") the attribute ACL file can be found here:

$DA_HOME/service/java/source/etc/attr-authz

After service deployment the file is deployed to:

$GLOBUS_LOCATION/etc/workspace/attr-authz

As before, policy in this file can be modified after the service is deployed.

Example, one attribute per line, no quotes:

/EGEE/egee/manager
/egtest/mytemp/Role=NULL/Capability=NULL

Attribute banlist

Before service deployment (before you run "ant deploy") the attribute banlist file can be found here:

$DA_HOME/service/java/source/etc/attr-banlist

After service deployment the file is deployed to:

$GLOBUS_LOCATION/etc/workspace/attr-banlist

As before, policy in this file can be modified after the service is deployed.

Example, one attribute per line, no quotes:

/EGEE/egee/manager
/egtest/mytemp/Role=NULL/Capability=NULL

Separate query authorization

NOTE: to enable a different policy between query and creation, configure the service with different authorization files, making sure to change the keyname prefix, e.g. instead of the default "workspaceAuthz-dnAuthzConfigFile" use e.g. "queryAuthz-dnAuthzConfigFile" in the service section of server-config.wsdd and make the value a different path. The prefix is not meaningful, it just needs to be different than the factory. Also, the service will need a separate security descriptor.

• adjust the server-config.wsdd service settings to use different files
• adjust the server-config.wsdd service parameter names to use a different scope prefix (e.g. "workspaceAuthzQuery" instead of "workspaceAuthz")
• copy security-descriptor.xml to security-descriptor-query.xml
• edit security-descriptor-query.xml, replace 'workspaceAuthz' with 'workspaceAuthzQuery' to match above
• adjust the server-config.wsdd service section's 'securityDescriptor' setting to 'security-descriptor-query.xml'

Using DA with GRAM

It is possible to enable GRAM to consult the dynamic accounts service for authorization and mapping policies instead of a grid-mapfile. Thus, a client can lease an account and submit jobs to GRAM to be run in that account.

The following assumes you have a GT4 container with the workspace service and GRAM deployed into it.

• Substitute <authz value="gram:org.globus.workspace.QueryPDP"/> for the pre-existing <authz value="gridmap"/> entry in the following file (relative to $GLOBUS_LOCATION): "etc/gram-service/managed-job-factory-security-config.xml"

• Edit out the references to globus-gridmap-and-execute so that the sudo rules only reference "globus-job-manager-script.pl *" and "globus-gram-local-proxy-tool *" without the preceding globus-gridmap-and-execute -g <file>. Also, each valid pool account will need to be listed as an allowed account for the container user to run those two programs in, just like any mapped username in the normal grid-mapfile (using groups is a good idea).

• Lease a workspace and then submit a job to GRAM, which you should be authorized to do since the default workspace policy is that the workspace creator is in the workspace's access policy (which is what is being consulted by GRAM via the QueryPDP). If multiple workspaces have your DN in their access policies, it is possible to specify which is used for the job by designating the correct username in the RSL's "localUserId" element, documented here