Configuration examples

This article goes through different scenarios of GUMS configuration. See the gums.config file documentation before reading this.

Mapping people from a VOMS server

Use VOMSGroup. For example, here we get all people from the ATLAS server in the USATLAS (/atlas/usatlas) group, and we map them to a default account 'usatlas'.

<groupMapping name='usatlas' accountingVo='usatlas' accountingDesc='ATLAS'>
    <userGroup className='gov.bnl.gums.VOMSGroup'
        url='https://voms.cern.ch:8443/edg-voms-admin/atlas/services/VOMSAdmin'
        persistenceFactory='mysql' name='usatlas'
        voGroup="/atlas/usatlas" sslCertfile='/etc/grid-security/hostcert.pem'
        sslKey='/etc/grid-security/hostkey.pem'
        matchFQAN="vo" acceptProxyWithoutFQAN='true' />
    <accountMapping className='gov.bnl.gums.GroupAccountMapper'
        groupName='usatlas1' />
</groupMapping>

The userGroup.persistenceFactory and userGroup.name tell us to use mysql to store the information. The VOMS server is contacted only when updateGroup is done. This group will match all users in the VO group coming with a non-VOMS cert (acceptProxyWithoutFQAN='true') or with a VOMS proxy with any role/group from the ATLAS VO (matchFQAN="VO"); it won't match the same user coming with a VOMS proxy from a different VO. We can make all hosts at our site use this mapping by adding in hostGroup.groups the value declared in groupMapping.name, as shown below:

<hostGroup className='gov.bnl.gums.CertificateHostGroup'
    cn='*.mysite.com' groups='...,usatlas,...' />

Allowing ad-hoc list of people

You might need to allow some people without adding a VO, e.g., for testing. You do that by using a ManualGroup. For example:

<groupMapping name='testers'>
    <userGroup className='gov.bnl.gums.ManualUserGroup'
        persistenceFactory='mysql' name='testers' />
    <accountMapping className='gov.bnl.gums.GroupAccountMapper' groupName='test' />
</groupMapping>

The userGroup.persistenceFactory and userGroup.name tells us the list will be stored  in mysql. In this example, we add the group name to the beginning of the hostGroup.groups list, so it will override all the other group, as shown below:.

<hostGroup className='gov.bnl.gums.CertificateHostGroup'
    cn='*.mysite.com' groups='testers,...' />

You can then add and/or remove people using the commands './bin/gums manualGroup-add' and/or './bin/gums manualGroup-remove'.

Using account pools

GUMS does not create accounts. First you'll have to create accounts and make them known to the gatekeeper and worker nodes. Here's an example of configuring a pool of accounts for the ATLAS VO:

<groupMapping name='usatlas' accountingVo='usatlas' accountingDesc='ATLAS'>
    <userGroup className='gov.bnl.gums.VOMSGroup'
    url='https://voms.cern.ch:8443/edg-voms-admin/atlas/services/VOMSAdmin'
    persistenceFactory='mysql' name='usatlas'
    voGroup="/atlas/usatlas" sslCertfile='/etc/grid-security/hostcert.pem'
    sslKey='/etc/grid-security/hostkey.pem'/>
    <accountMapping className='gov.bnl.gums.AccountPoolMapper' persistenceFactory='mysql' name='bnlPool' />
</groupMapping>

This will tell GUMS to look for the list of available accounts in the bnlPool stored in mysql. You can set different pools for different groups, or the same pool for some or all groups. Here we configure the pool to be used by a group of hosts:

<hostGroup className='gov.bnl.gums.CertificateHostGroup'
    cn='*.mysite.com' groups='...,usatlas,...' />

Let's leave the GUMS configuration file for a moment and put some accounts in the pool (the accounts must be known to the gatekeeper and the worker nodes):

> ./bin/gums pool-addRange mysql bnlPool grid0000-199

GUMS will now assign accounts to DNs as requests come in from the gatekeeper. (If you generate a user-to-VO map for accounting, though, all DNs will be assigned an account immediately.)

Composite mapping

It can be useful to assign an account to a DN by hand. For example, we may generally want to assign accounts to usatlas from a pool, but there are a few special cases in which we need more control. We would use <compositeAccountMapping> for these cases, as shown here: 

<groupMapping name='usatlas' accountingVo='usatlas' accountingDesc='ATLAS'>
    <userGroup className='gov.bnl.gums.VOMSGroup'
    url='https://voms.cern.ch:8443/edg-voms-admin/atlas/services/VOMSAdmin'
    persistenceFactory='mysql' name='usatlas'
    voGroup="/atlas/usatlas" sslCertfile='/etc/grid-security/hostcert.pem'
    sslKey='/etc/grid-security/hostkey.pem'/>
    <compositeAccountMapping>
        <accountMapping className='gov.bnl.gums.ManualAccountMapper'
            persistenceFactory='mysql' name='bnlMap' />
        <accountMapping className='gov.bnl.gums.AccountPoolMapper'
            persistenceFactory='mysql' name='bnlPool' />
    </compositeAccountMapping>
</groupMapping>

The compositeAccount allows you specify a list of mappers (e.g., ManualAccountMapper, AccountPoolMapper). If the first doesn't return an account, the second is tried, and so on. In this example, we first use the ManualAccountMapper that takes the bnlMap map from mysql. If the DN in question isn't mapped there, we fall back on the pool.

You can add/remove entries in the map using the commands './bin/gums manualMapping-add' and './bin/gums manualMapping-remove'.

Mapping based on groups/roles

You'll need to create different group mappings for the different roles. This first example maps people with the VOMS attribute voGroup of "/atlas/usatlas" to the account usatlas1. Notice that userGroup.ignoreFQAN is missing; this means that if the VOMS attribute doesn't match, the next group is checked.

<groupMapping name='usatlas' accountingVo='usatlas' accountingDesc='ATLAS'>
    <userGroup className='gov.bnl.gums.VOMSGroup'
    url='https://voms.cern.ch:8443/edg-voms-admin/atlas/services/VOMSAdmin'
    persistenceFactory='mysql' name='usatlas'
    voGroup="/atlas/usatlas" sslCertfile='/etc/grid-security/hostcert.pem'
    sslKey='/etc/grid-security/hostkey.pem'/>
    <accountMapping className='gov.bnl.gums.GroupAccountMapper'
        groupName='usatlas1' />
</groupMapping>

The second maps people with the VOMS attributes voGroup of "/atlas" and voRole "production" to the account usatprod.

<groupMapping name='usatlasProd' accountingVo='usatlas' accountingDesc='ATLAS'>
    <userGroup className='gov.bnl.gums.VOMSGroup'
    url='https://voms.cern.ch:8443/edg-voms-admin/atlas/services/VOMSAdmin'
    persistenceFactory='mysql' name='usatlasProd'
    voGroup="/atlas" voRole="production"
    sslCertfile='/etc/grid-security/hostcert.pem'
    sslKey='/etc/grid-security/hostkey.pem'/>
    <accountMapping className='gov.bnl.gums.GroupAccountMapper'
        groupName='usatprod' />
</groupMapping>

And then we define the hostGroup and include both groups: 

<hostGroup className='gov.bnl.gums.CertificateHostGroup'
    cn='*.mysite.com' groups='usatlasProd,usatlas,...' />