./bin/gums

We describe the ./bin/gums which provides all the administrative functions for GUMS. We'll describe the use of the commands, giving examples, but for the full options please refer to the --help output of the commands themselves.

./bin/gums consists of a set of command line tools which will be run under the user GRID credentials. The user must be part of the GUMS admins.

Authentication and authorization

./bin/gums runs using the user credentials, not the host credentials. This means that the user will need to run grid-proxy-init, or voms-proxy-init, to generate a valid proxy certificate. The certificate will also need to be in the admin group, or you will get an authorization denied. To add a person in the admin group, refer to the GUMS Service documentation.

./bin/gums commands

The script provides many commands, which you can list just by running the script with no arguments:

[carcassi@atestgk01 ~]$ /opt/gums/bin/gums
usage: gums command [command-options]
Commands:
  generateGrid3UserVoMap - Generate grid3-user-vo-map.txt for a given service/host.
  generateGridMapfile - Generate grid-mapfile for a given service/host.
  manualGroup-add - Includes a DN in a group.
  manualGroup-remove - Removes a DN from a group.
  manualMapping-add - Adds a DN-to-username in a mapping.
  manualMapping-remove - Removes a DN from a mapping.
  mapUser - Local credential used for a particular user.
  mapfileCache-refresh - Regerates mapfiles in the cache.
  pool-addRange - Adds accounts to an account pool.
  updateGroups - Contact VO servers and retrieve user lists.
  version - Retrieve GUMS client version.
For help on any command:
  gums command --help

You can then retrieve the full syntax of each command by calling it with the --help options. For example:

[carcassi@atestgk01 ~]$ /opt/gums/bin/gums mapUser --help
usage: gums mapUser [-s SERVICEDN] [-n TIMES] [-t NREQUESTS] [-b] [-f
            FQAN] [-i FQANISSUER] USERDN1 [USERDN2] ...
Maps the grid identity to the local user.
Options:
 -s,--service <arg>   DN of the service. When using gums-host, it defaults
                      to the host credential DN.
 -f,--fqan <arg>      Fully Qualified Attribute Name, as it would be
                      selected using voms-proxy-init; no extended information by default
 -t,--timing <arg>    enables timing, grouping the requests. For example,
                      "-t 100" will give you timing information on 100 requests at a time
 -b,--bypassCallout   connects directly to GUMS instead of using the
                      callout
 -i,--issuer <arg>    Fully Qualified Attribute Name Issuer, that is the
                      DN of the VOMS service that issued the attribute certificate
 -n,--ntimes <arg>    number of times the request will be repeated
    --help            print this message

Please, refer to the help on the command line for the full syntax of the commands.

Service mapping generation commands

This set of commands can be used by the admin to check how the mapping across the services is maintained. One can look how the maps generated by GUMS look like, and check to which local user any Grid identity is mapped. These are the same as the ./bin/gums-host commands, but, since they run with admin credential, they can access mapping to all hosts.

gums mapUser

With this command an admin can check the mapping of a specific identity, including the VOMS extended proxy FQAN. This allows to check if the user is mapped to the correct account when using different VO roles. It issues a mapping request as the callout to the gatekeeper does, which is very helpful to diagnose problems.

Here are a couple of examples:

[carcassi@atestgk01 ~]$ /opt/gums/bin/gums mapUser \
  -s  "/DC=org/DC=doegrids/OU=Service/CN=mygk.mysite.com" \
  "/DC=org/DC=doegrids/OU=People/CN=Gabriele Carcassi 12345"
LocalId[userName: grid12345]

This examples asks the GUMS server what account would the certificate be mapped on the mygk.mysite.com gatekeeper.

One can also ask what account would be used if the user would come in with a particular role.

[carcassi@atestgk01 ~]$ /opt/gums/bin/gums mapUser \
  -s  "/DC=org/DC=doegrids/OU=Service/CN=mygk.mysite.com" \
  -f  "/myvo/Role=role1" \
  -i  "/DC=org/DC=doegrids/OU=Service/CN=voms.mysite.com" \
  "/DC=org/DC=doegrids/OU=People/CN=Gabriele Carcassi 12345"
LocalId[userName: special1]

Here we see the same user being assigned a different account.

gums generateGridMapfile

This commands allows to retrieve a grid-mapfile for a specific service. Be careful: generating a map will force all the policy to be explored, and it might have undesired side effects. For example, when using the pool account mapping, this will force assigning an account to each user, even if they are never going to come on site. For example:

[carcassi@atestgk01 ~]$ /opt/gums/bin/gums generateGridMapfile /DC=org/DC=doegrids/OU=Services/CN=gatekeeper.mysite.com
#---- members of vo: usatlas ----#
"/C=CH/O=CERN/OU=GRID/CN=Frederik Orellana 5894" usatlas1
"/C=CH/O=CERN/OU=GRID/CN=Michela Biglietti 4798" usatlas1
"/C=CH/O=CERN/OU=GRID/CN=Miguel De Oliveira Branco 2423" usatlas1
"/C=CH/O=CERN/OU=GRID/CN=Shulamit Moed 9840" usatlas1
"/DC=org/DC=doegrids/OU=People/CN=Alden Stradling 409738" usatlas1
"/DC=org/DC=doegrids/OU=People/CN=Aldo Saavedra 942457" usatlas1
"/DC=org/DC=doegrids/OU=People/CN=Alexandre V Vaniachine 778117" usatlas1
...

As an admin, you can generate the map for any service.

gums generateGrid3UserVoMap

This command allows to retrieve the inverse map used by Grid3/OSG accounting. Be careful: generating a map will force all the policy to be explored, and it might have undesired side effects. For example, when using the pool account mapping, this will force assigning an account to each user, even if they are never going to come on site. For example:

[carcassi@atestgk01 ~]$ /opt/gums/bin/gums generateGrid3UserVoMap /DC=org/DC=doegrids/OU=Services/CN=test.mysite.com
#User-VO map
# #comment line, format of each regular line line: account VO
# Next 2 lines with VO names, same order, all lowercase, with case (lines starting wi
th #voi, #VOc)
#voi usatlas ivdgl ligo btev uscms sdss gridex grase
#VOc ATLAS iVDgL LIGO BTeV CMS SDSS GRIDEX GRASE
#---- accounts for vo: usatlas ----#
usatlas1 usatlas
#---- accounts for vo: ivdgl ----#
ivdgl ivdgl
...

As an admin, you can generate the map for any service

Manual groups and mappings managements commands

This set of commands allows the admin to add and remove entries from a manual group or mapping. These are resident in your database, and are managed "by hand" by the admin to handle special cases or customizations. To have any effect, these groups/mappings must be set in the configuration file. For example, the following uses a manually define set of users to be mapped to the account "myacc".

    <groupMapping name='example1' accountingVo='myvo' accountingDesc='myVo'>
      <userGroup className='gov.bnl.gums.ManualUserGroup' persistenceFactory='mysql'
                 name='group1' />
      <accountMapping className='gov.bnl.gums.GroupAccountMapper' groupName='myacc' />
    </groupMapping>

The manual user group is identified by the persistence (mysql) and the name of the group (group1). These are the parameter that will also be used for the command line.

For a manual mapping, the following defines a manual mapping for the users taken from a VOMS server.

    <groupMapping name='example2' accountingVo='myvo' accountingDesc='myVo'>
      <userGroup className='gov.bnl.gums.VOMSGroup'
         url='https://voms.mysite.com:8443/edg-voms-admin-myvo/services/VOMSAdmin'
         persistenceFactory='mysql' name='myvo'
         voGroup="/myvo"
         sslCertfile='/etc/grid-security/hostcert.pem'
         sslKey='/etc/grid-security/hostkey.pem' />
      <accountMapping className='gov.bnl.gums.ManualAccountMapper' persistenceFactory='mysql' name='map1'/>
    </groupMapping>

Also there, the manual map is defined by the persistence (mysql) and a name (map1).

gums manualGroup-add

To add a member in a manual group:

[carcassi@atestgk01 ~]$ /opt/gums/bin/gums manualGroup-add mysql group1 "/DC=org/DC=doegrids/OU=People/CN=Gabriele Carcassi 12345"

gums manualGroup-remove

To remove a member from a manual group:

[carcassi@atestgk01 ~]$ /opt/gums/bin/gums manualGroup-remove mysql group1 "/DC=org/DC=doegrids/OU=People/CN=Gabriele Carcassi 12345"

gums manualMapping-add

To add an entry in a map:

[carcassi@atestgk01 ~]$ /opt/gums/bin/gums manualMapping-add mysql map1 "/DC=org/DC=doegrids/OU=People/CN=Gabriele Carcassi 12345" carcassi

gums manualMapping-remove

To remove an entry from a map:

[carcassi@atestgk01 ~]$ /opt/gums/bin/gums manualMapping-remove mysql map1 "/DC=org/DC=doegrids/OU=People/CN=Gabriele Carcassi 12345"

Other commands

gums updateGroups

This command will force GUMS to recontact all the VO servers and retrieve a new list of people.

[carcassi@atestgk01 ~]$ /opt/gums/bin/gums updateGroups

gums pool-addRange

This is a utility to add a range of accounts to a pool. This won't actually create accounts, which must be already created; it just makes GUMS aware that they exist and can be used. It assumes that accounts are something like grid0002, grid0003, ... That is with a fixed part at the beginning and an increasing number at the end.

This command will add the accounts grid0020, grid0021, ... until grid0040 to the pool

[carcassi@atestgk01 ~]$ /opt/gums/bin/gums pool-addRange mysql pool1 grid0020-40