Understanding the GUMS configuration file

The gums.config file has three main parts:

persistenceFactories - defines where the local data can be stored. For example, GUMS will keep a local copy of the VO listings; you can decide where to keep them. Each component that needs persistence, that is that needs to store things somewhere, will retrieve it through the factory. This allows to store part of the information in different database and to create a custom persistence layer for the facility that connects to other site components.

groupMappings - defines groups of users and sets how they are mapped. A groupMapping is defined by two things: a set of users (userGroup) and a policy for account mapping (accountMapping). Optionally, the policy can be composed of multiple policies (compositeAccountMapping)

hostGroups - defines which groupMappings are used for the different hosts. GUMS uses the gums.config file in this way.

Let's go through an example. A request comes in to map user DN="/DC=org/DC=doegrids/OU=People/CN=Gabriele Carcassi" FQAN="/atlas/usatlas" coming from gatekeeper "/DC=org/DC=doegrids/OU=Services/CN=mygk.usatlas.bnl.gov". FQAN stands for Fully Qualified Attribute Name.

Gums will first look through the hostGroups section to find a match to the gatekeeper CN. Say we have:

  <hostGroups>
    <!-- RHIC gatekeepers -->
    <hostGroup className="gov.bnl.gums.CertificateHostGroup" cn='star*.*.bnl.gov' ... />
    <hostGroup className="gov.bnl.gums.CertificateHostGroup" cn='phenix*.*.bnl.gov' ... />

    <!-- ATLAS test gatekeeper -->
    <hostGroup className="gov.bnl.gums.CertificateHostGroup" cn='mygk.usatlas.bnl.gov' ... />

    <!-- Rest of ATLAS gatekeepers -->
    <hostGroup className="gov.bnl.gums.CertificateHostGroup" cn='*.usatlas.bnl.gov' ... />
  </hostGroups>

			

GUMS will go through that list in the order specified, and find the first match to the "wildcard" attribute. In this case, we match the third hostGroup specification. Notice that if you put the third hostGroup last, it would never actually be used, because mygk.usatlas.bnl.gov also matches "*.usatlas.bnl.gov", which covers a broader range of hosts. If you have broader match together with more specific cases, the more specific cases must preceed the broader case.

Let's look more closely at the hostGroup entry; there are additional attributes, in particular "groups". This attribute refers to group mappings. In our case it is:

  <hostGroup className="gov.bnl.gums.CertificateHostGroup"
             cn='mygk.usatlas.bnl.gov' 
             groups='atlasProd,usatlasPool,ivdglPool, ...' />

			

GUMS will now go through the list of groups (i.e. group mappings) in the order specified and take the first one that matches the given credentials. GUMS will check whether the credentials are part of atlasProd; if not, then usatlasPool, and so on, until either a match is found or the list ends. The first match will define the map, and the user will get mapped accordingly. As before, if you have both a broad default and a more specific case, the specific case must come first.

In a correct configuration, each group (e.g., atlasProd, usatlasPool,...) must be defined in the groupMappings section in a groupMapping element. GUMS first checks the first one listed, e.g., atlasProd. A groupMapping element contains userGroup elements. Let's look at the atlasProd group mapping:

  <groupMapping name='atlasProd' accountingVo='usatlas' accountingDesc='ATLAS'>
    <userGroup className='gov.bnl.gums.VOMSGroup'
               url='https://vo.racf.bnl.gov:8443/edg-voms-admin/atlas/services/VOMSAdmin'
               persistenceFactory='mysql' name='atlasProd'
               voGroup="/atlas"
               voRole="production"
               sslCertfile='/etc/grid-security/gumscert.pem'
               sslKey='/etc/grid-security/gumskey.pem' />
    <accountMapping className='gov.bnl.gums.GroupAccountMapper'
                    groupName='usatlas1' />
  </groupMapping>

			

The userGroup defines "who is going to be part of this map". In this case, all members of the group "/atlas" with role "production" are included. Also, the FQAN must match '/atlas/Role=production'. Our sample FQAN is different (/atlas/usatlas); It doesn't match. We proceed with the next group, usatlasPool. Its group mapping is as follows:

  <groupMapping name='usatlasPool' accountingVo='usatlas' accountingDesc='ATLAS'>
    <userGroup className='gov.bnl.gums.VOMSGroup'
               url='https://vo.racf.bnl.gov:8443/edg-voms-admin/atlas/services/VOMSAdmin'
               persistenceFactory='mysql' name='osgusatlas'
               voGroup="/atlas/usatlas"
               sslCertfile='/etc/grid-security/gumscert.pem'
               sslKey='/etc/grid-security/gumskey.pem'
               acceptProxiesWithoutFQAN="true"/>
    <compositeAccountMapping>
      <accountMapping className='gov.bnl.gums.AccountPoolMapper'
                      persistenceFactory='mysql' name='bnlPool' />
      <accountMapping className='gov.bnl.gums.GroupAccountMapper' groupName='usatlas1' />
    </compositeAccountMapping>
  </groupMapping>

			

This says all the people in the ATLAS VO server at 'https://vo.racf.bnl.gov:8443/edg-voms-admin/atlas/services/VOMSAdmin', part of /atlas/usatlas, are part of this group. The attribute 'acceptProxiesWithoutFQAN="true"' means standard/non-VOMS proxies are allowed. Our case, DN="/DC=org/DC=doegrids/OU=People/CN=Gabriele Carcassi" FQAN="/atlas/usatlas", is clearly part of /atlas/usatlas. Even if it came in with no FQAN, however, it would still be considered a match, and get mapped. If it came with a different FQAN, though, it wouldn't have matched the FQAN: if present, it needs to match. Once can use matchFQAN to change how the FQAN is matched.

Since there is a match, GUMS will use this groupMapping element to determine the account. It looks at the accountMapping, which happens to be composite (there's a pool of accounts and a group account): GUMS will go through the accountMapping elements in the order listed, until one returns a value.

The first is a pool of accounts; if it has any available accounts left, it will return either an assigned account previously assigned to this user, or it will assign a new account to him. If its pool of accounts is exhausted, it will not return an account. In this case, the next accountMapping element will be used; this one always maps to the same group account, usatlas1.

persistenceFactories

This section just contains a list of persistenceFactory elements.

  <persistenceFactories>
    <persistenceFactory name='mysql' className='gov.bnl.gums.MySQLPersistenceFactory' />
  </persistenceFactories>

persistenceFactory

The type of persitenceFactory is determined by the class which has to implement the PersistenceFactory interface. The basic attributes are:

Other attributes are implementation specific.

All the elements that will be using the database, will need to set the 'persistenceFactory' attribute to the name, and then provide a 'name' attribute that will identify which information to use. What that name means is implementation specific. For a database layer, for example, it could mean a table or a column value within a well known table; for a file layer it could mean the name of the file.

gov.bnl.gums.HibernatePersistenceFactory

Hibernate is the name of a Java library that stores Java object in a relational database. All the attributes are passed as properties to that library, which allows to write on any major relational database. We support MySQL, but with little knowledge of Hibernate you will probably be able to port GUMS to any database (i.e. Postgres, Oracle, ...) just by setting the correct configuration. Here is an example for mysql:

 <persistenceFactory name='mysql'
       className='gov.bnl.gums.hibernate.HibernatePersistenceFactory'
       hibernate.connection.username='gums'
       hibernate.connection.password='mysecret'
       hibernate.connection.url='jdbc:mysql://mydb.mysite.org/GUMS_1_1'
       hibernate.connection.driver_class='com.mysql.jdbc.Driver'
       hibernate.dialect='net.sf.hibernate.dialect.MySQLDialect'
       hibernate.connection.pool_size='3' />

adminUserGroup

This defines the set of users that have admin privileges on GUMS. This entry has the same options as a userGroup entry. Refer to that part of the documentation.

groupMappings

This section will contain a list of groupMapping elements.

groupMapping

A group mapping is composed by two elements: a userGroup and a mapping, which can either be a compositeAccountMapping or an accountMapping.

userGroup

This element defines the list of people that will be part of this groupMapping. A userGroup is typically defined by a group on a VO server or on a database. This element corresponds to the UserGroup interface in the code, meaning you can provide your own logic. The basic attributes are:

gov.bnl.gums.LDAPGroup

This class retrieves the list of members from an LDAP VO, as it is defined within LCG. The attributes available are:

For example:

  <userGroup className='gov.bnl.gums.LDAPGroup'
             server='grid-vo.nikhef.nl'
             query='ou=People,o=atlas,dc=eu-datagrid,dc=org'
             persistanceFactory='mysql' name='atlas' />

Retrieves all the user in the ATLAS VO LDAP server.

gov.bnl.gums.VOMSGroup

This class retrieves the list of members from an VOMS Server. The attributes available are:

For example:

  <userGroup className='gov.bnl.gums.VOMSGroup'
             url='https://vo.racf.bnl.gov:8443/edg-voms-admin/atlas/services/VOMSAdmin'
             persistanceFactory='mysql' name='atlas'
             voGroup="/atlas/test"
             sslCertfile='/etc/grid-security/hostcert.pem'
             sslKey='/etc/grid-security/hostkey.pem'/>

Retrieves all the user in the VOMS server at the specified url from the /atlas/test group. It also specifies which credentials should be used to contact the server.

gov.bnl.gums.ManualGroup

This class manages a group of identities stored in the persistence. Useful to handle special cases, for development testbed or for the list of admins. GUMS The attributes available are:

For example:

  <userGroup className='gov.bnl.gums.ManualUserGroup'
             persistanceFactory='mysql' name='testGroup' />

Selects the users stored manually in the testGroup group.

compositeAccountMapping

A compositeAccountMapping is a mapping policy made up by a list of policies. When a request to map a user comes, the composite mapper will forward the request to the first mapper in the list. If this fails, the request is forwarded to the second, and so on. This allows you to create a policy that has a default (the last element on the list) but allows special cases (the top element in the list).

This element simply contains a list of accountMapping elements.

accountMapping

An account mapping defines the logic with which the user credentials are mapped to the local account. The logic will be provided by a class implementing the goc.bnl.gums.AccountMapping interface.

gov.bnl.gums.GecosNisAccountMapper

This class retrieves the NIS maps and tries to match the name from a certificate. Please, read the full documentation on the javadoc about this class before using it. The attributes available are:

For example:

  <accountMapping className='gov.bnl.gums.GecosNisAccountMapper'
                  jndiNisUrl='nis://nis.mysite.org/domain' />

Uses the NIS map taken from the nis.mysite.org server for domain.

gov.bnl.gums.GecosLdapAccountMapper

This class retrieves the LDAP maps and tries to match the name from a certificate. Please, read the full documentation on the javadoc about this class before using it. The attributes available are:

For example:

  <accountMapping className='gov.bnl.gums.GecosLdapAccountMapper'
                  jndiLdapUrl='ldap://ldap.mysite.org/dc=domain,dc=mysite,dc=gov' />

Uses the LDAP map taken from the ldap.mysite.org server for domain.

gov.bnl.gums.AccountPoolMapper

This class implements account pooling. Please refer to the account pool documentation for the full detailed description. The attributes available are:

For example:

  <accountMapping className='gov.bnl.gums.AccountPoolMapper'
                  persistenceFactory='mysql' name='bnlPool' />

Maps people from the set of accounts defined in mysql in the bnlPool pool. The accounts for the pool should be created and fed to GUMS through the ./gums command.

gov.bnl.gums.GroupAccountMapper

This class maps all users to the same account. The attributes available are:

For example:

  <accountMapping className='gov.bnl.gums.GroupAccountMapper'
                  groupName='atlas' />

Maps everyone to the atlas account.

hostGroups

This section contains a list of host groups. To determine to which group a particular host is part, GUMS start from the first one in the list and stops at the first match.

hostGroup

A hostGroup defines a group of hosts and which groupMappings will be used. This element corresponds to the HostGroup interface. This allows to retrieve hosts lists from other components of the facility, for example an information service.

gov.bnl.gums.WildcardHostGroup (deprecated)

This class represent a set of hosts defined by a hostname wildcard. For example, *.mysite.org would include all the hosts which end in mysite.org. The attributes that can be set for this class are:

The use of WildcardHostGroup is discouraged as it doesn't properly handle certificate identities. In that case the host identity is really the full DN, and the CN is can include the service name. Use it only if you really need to preserve backward compatibility with gums-client 1.0.x. The CertificateHostGroup should be used instead of the WildcardHostGroup.

For example:

  <hostGroup className="gov.bnl.gums.WildcardHostGroup"
             wildcard='*.usatlas.bnl.gov'
             groups='gridex,sdss,uscms,usatlasGroup,btev,ligo,ivdgl' />

Maps the hosts in the usatlas subdomain at BNL to the list of groups, which will have been defined in the groupMappings section.

gov.bnl.gums.CertificateHostGroup

This class represent a set of services defined by a DN or CN wildcard. For example, *.mysite.org would include all the services which DN ends in mysite.org. The attributes that can be set for this class are:

For example:

  <hostGroup className="gov.bnl.gums.CertificateHostGroup"
             cn='*.usatlas.bnl.gov'
             groups='gridex,sdss,uscms,usatlasGroup,btev,ligo,ivdgl' />

Maps the hosts in the usatlas subdomain at BNL to the list of groups, which will have been defined in the groupMappings section.