

Installing and Maintaining the LCMAPS VOMS Plugin¶

LCMAPS is a software library used on HTCondor-CE, GridFTP, and XRootD hosts for mapping grid certificates of incoming connections to specific Unix accounts. The LCMAPS VOMS plugin enables LCMAPS to make mapping decisions based on the VOMS attributes of grid certificates, e.g. /cms/Role=production/Capability=NULL. In OSG 3.4, the LCMAPS VOMS plugin replaced GUMS and edg-mkgridmap as the authentication method at OSG sites.

The OSG provides a default set of mappings from VOMS attributes to Unix accounts. By configuring LCMAPS, you can override these mappings, including changing the Unix account that a VO is mapped to; adding custom mappings for specific users and VOMS attributes; and/or banning specific users and VOMS attributes.

Use this page to learn how to install and configure the LCMAPS VOMS plugin to authenticate users to access your resources on a per-VO basis.

Installing the LCMAPS VOMS Plugin¶

To install the LCMAPS VOMS plugin, make sure that your host is up to date before installing the required packages:

Clean yum cache:

[email protected] # yum clean all --enablerepo=*

Update software:
```
[email protected] # yum update
```
This command will update all packages

Install lcmaps, the default mapfile, and the configuration tools:

[email protected] # yum install lcmaps vo-client-lcmaps-voms osg-configure-misc

Configuring the LCMAPS VOMS Plugin¶

The following section describes the steps required to configure the LCMAPS VOMS plugin for authentication. Additionally, there are optional configuration instructions if you need to make changes to the default mappings, or migrate from edg-mkgridmap or GUMS.

Enabling the LCMAPS VOMS plugin¶

To configure your host to use LCMAPS VOMS plugin authentication, edit /etc/osg/config.d/10-misc.ini and set the following options:

edit_lcmaps_db = True
authorization_method = vomsmap

If the glexec_location option is present, you must comment it out or set it to UNAVAILABLE. The LCMAPS VOMS plugin does not work with gLExec.

Supporting mapped VOs and users¶

Ensure Unix accounts exist for each VO, VO role, VO group, or user you choose to support in the mapfiles:

Consult the default VO mappings in /usr/share/osg/voms-mapfile-default to determine the mapped Unix account names. Each of the mapfiles has the following format:
```
"<VO, VO role, VO group or user>" <Unix account>
```
Create Unix accounts for each VO, VO role, VO group, and user that you wish to support. The full list of VOs is located in the OSG topology. You are not expected to support all the VOs. If you would like to support opportunistic usage, we recommend creating the following Unix accounts:

VO name Unix account(s)

GLOW glow

OSG osg

ATLAS usatlas3

CMS cmsuser

Fermilab fnalgrid

HCC hcc

Gluex gluex

Additionally, it is also recommended to create the mis Unix account, which is used by OSG staff to assist with troubleshooting.
Edit /etc/osg/config.d/30-gip.ini and specify the supported VOs per Subcluster or ResourceEntry section:
```
allowed_vos="VO1,VO2..."
```

Applying configuration settings¶

Making changes to the OSG configuration files in the /etc/osg/config.d directory does not apply those settings to software automatically. For the OSG settings, use the osg-configure tool to validate (to a limited extent) and apply the settings to the relevant software components. If instead you wish to manage the LCMAPS VOMS plugin configuration yourself, skip to the manual configuration section.

Make all changes to .ini files in the /etc/osg/config.d directory.

Note

This document only describes the critical settings for the LCMAPS VOMS plugin and related software. You may need to configure other software that is installed on your host, too.
Validate the configuration settings:
```
[email protected] # osg-configure -v
```
Once the validation command succeeds without errors, apply the configuration settings:
```
[email protected] # osg-configure -c
```

Optional configuration¶

The following subsections contain information on migration from edg-mkgridmap, mapping or banning users by their certificates' Distinguished Names (DNs) or by their proxies' VOMS attributes. Any optional configuration is to be performed after the installation and configuration sections above.

For a table of the configuration files and their order of evaluation, consult the reference section.

Migrating from edg-mkgridmap
Migrating from GUMS
Mapping VOs
Mapping users
Banning VOs
Banning users
Mapping using all FQANs

Migrating from edg-mkgridmap¶

The program edg-mkgridmap (found in the package edg-mkgridmap), used for authentication on HTCondor-CE, GridFTP, and XRootD hosts, is no longer supported by the OSG. The LCMAPS VOMS plugin (package lcmaps-plugins-voms) now provides the same functionality. To migrate from edg-mkgridmap to the LCMAPS VOMS plugin, perform the following procedure:

Configure user DN mappings:
1. Remove /etc/grid-security/grid-mapfile
2. Check if you have a local grid mapfile:
```
[email protected] # grep gmf_local /etc/edg-mkgridmap.conf
```
3. If the above command returns a file that exists and has contents, move it to /etc/grid-security/grid-mapfile.
If you are converting an HTCondor-CE host, remove the HTCondor-CE GRIDMAP configuration. Otherwise, skip to the next step.
1. Find where GRIDMAP is set:
```
[email protected] # condor_ce_config_val -v GRIDMAP
```
2. If the above command returns a file, remove the GRIDMAP configuration from that file. Repeat this until the command returns Not defined: GRIDMAP.
3. Reconfigure HTCondor-CE:
```
[email protected] # condor_ce_reconfig
```
Remove edg-mkgridmap and related packages:
```
[email protected] # yum erase edg-mkgridmap
```
Warning

In the output from this command, yum should not list other packages than the one. If it lists other packages, cancel the erase operation, make sure the other packages are updated to their latest OSG 3.4 versions (they should have ".osg34" in their versions), and try again.

Migrating from GUMS¶

GUMS is no longer supported by the OSG and has been replaced by the LCMAPS VOMS plugin. Note that unlike GUMS, which runs on a central host, the LCMAPS VOMS plugin will run on your GUMS clients (e.g. HTCondor-CE, GridFTP, and XRootD). To migrate any custom authentication configuration from GUMS to the LCMAPS VOMS plugin, perform the following procedure:

On your GUMS host, retrieve the conversion helper script and run it:

[email protected] # wget https://raw.githubusercontent.com/opensciencegrid/osg-vo-config/mapfile-generator-0.2/bin/manual-mapfile-from-gumsdb.py
[email protected] # python manual-mapfile-from-gumsdb.py

Verify that the contents of ban-mapfile.additions, grid-mapfile.additions, and voms-mapfile.additions include any custom banned users, user mappings, and VO mappings, respectively.

Note

The above files will not include all VO mappings; the OSG provides default VO mappings in /usr/share/osg/voms-mapfile-default
On each of your client hosts (e.g. HTCondor-CE, GridFTP, XRootD), perform the following:
1. If you have not done so already, install and configure the LCMAPS VOMS plugin
2. Append each .additions file to its corresponding file in /etc/grid-security/ (creating those files if they do not exist)

Mapping VOs¶

To map VOs, VO roles, or VO groups to Unix accounts based on their VOMS attributes, create /etc/grid-security/voms-mapfile. An example of the format of a voms-mapfile follows:

# map GLOW jobs in the chtc group to the 'glow1' Unix account.
"/GLOW/chtc/*" glow1
# map GLOW jobs with the htpc role to the 'glow2' Unix account.
"/GLOW/Role=htpc/*" glow2
# map other GLOW jobs to the 'glow' Unix account.
"/GLOW/*" glow

Each non-commented line is a shell-style pattern which is compared against the user's VOMS attributes, and a Unix account that the user will be mapped to if the pattern matches. The patterns are compared in the order they are listed in. Therefore, more general patterns should be placed later in the file.

Note

The Unix account must exist for the user to be mapped. If a VO's Unix account is missing, that VO will not be able to access your resources.

Additionally, if you map VOMS attributes to a non-existent user in /etc/grid-security/voms-mapfile, /usr/share/osg/voms-mapfile-default will be considered next to find a mapping. The best way to ban a VO is edit /etc/grid-security/ban-voms-mapfile as described in Banning VOs below. Do not edit voms-mapfile-default as your changes will be overwritten upon updates.

Mapping users¶

To map specific users to Unix accounts based on their certificates' DNs, create /etc/grid-security/grid-mapfile. An example of the format of a grid-mapfile follows:

# map Matyas's FNAL DN to the 'matyas' Unix account
"/DC=gov/DC=fnal/O=Fermilab/OU=People/CN=Matyas Selmeci/CN=UID:matyas" matyas

Note

The Unix account must exist for the user to be mapped. If a user's Unix account is missing, that user will not be able to access your resources.

Banning VOs¶

/etc/grid-security/ban-voms-mapfile is used to ban an entire VO or a role withing a VO from accessing resources on your machine. An example of the format of a ban-voms-mapfile follows:

# ban CMS production jobs
"/cms/Role=production/*"

Each non-commented line is a shell-style pattern which is compared against a user's VOMS attributes. If the pattern matches, that user will be unable to access your resources.

Danger

When banning VOs, you must restart the services using LCMAPS VOMS authentication (e.g. condor-ce, globus-gridftp-server, etc.) to clear any authentication caches.

Warning

/etc/grid-security/ban-voms-mapfile must exist, even if you are not banning any VOs. In that case, the file should not contain any entries. If the file does not exist, LCMAPS will ban every user.

Banning users¶

/etc/grid-security/ban-mapfile is used to ban specific users from accessing your resources based on their certificates' DNs. An example of the format of a ban-mapfile follows:

# ban Matyas's FNAL DN
"/DC=gov/DC=fnal/O=Fermilab/OU=People/CN=Matyas Selmeci/CN=UID:matyas"

Danger

When banning users, you must restart the services using LCMAPS VOMS authentication (e.g. condor-ce, globus-gridftp-server, etc.) to clear any authentication caches.

Warning

/etc/grid-security/ban-mapfile must exist, even if you are not banning any users. In that case, the file should be blank. If the file does not exist, LCMAPS will ban every user.

Mapping using all FQANs¶

By default, the LCMAPS VOMS plugin only considers the first FQAN of a VOMS proxy for mapping. If you want to consider all FQANs, you must set the appropriate option.

If you are using osg-configure, set all_fqans = True in 10-misc.ini, then run osg-configure -c

Note

If you are using OSG 3.4, osg-configure should be at least version 2.2.2.
If you are configuring lcmaps.db manually (see manual configuration below), add "-all-fqans" to the module definitions for vomsmapfile and defaultmapfile

Using the LCMAPS VOMS Plugin¶

LCMAPS is a software library that is called for authentication; therefore, there are no running services and it does not have to be invoked manually.

Validating the LCMAPS VOMS Plugin VO Mappings¶

To validate the LCMAPS VOMS plugin by itself, use the following procedure to test mapping your own cert to a user:

Verify your DN is not in /etc/grid-security/grid-mapfile, or else it will generate a false positive
Verify your DN is not in /etc/grid-security/ban-mapfile, or else it will generate a false negative

Install the llrun and voms-clients packages:

[email protected] # yum install llrun voms-clients

As an unprivileged user, create a VOMS proxy (filling in <YOUR_VO> with a VO you are a member of):
```
[email protected] $ voms-proxy-init -voms <YOUR_VO>
```

Verify that your credentials are mapped as expected:

[email protected] $ llrun -s -l mode=pem,policy=authorize_only,db=/etc/lcmaps.db \
    -p/tmp/x509up_u`id -u`

If you did not get correctly mapped, check your proxy's FQAN by running:

[email protected] $ voms-proxy-info -fqan

and make sure it matches one of the patterns in /etc/grid-security/voms-mapfile or /usr/share/osg/voms-mapfile-default, and does not match any patterns in /etc/grid-security/ban-voms-mapfile.

Troubleshooting the LCMAPS VOMS Plugin¶

LCMAPS logs to journalctl (EL7) or /var/log/messages (EL6) and the verbosity of the logging can be increased by modifying the appropriate configuration and restarting the relevant service. This section outlines the configuration necessary to raise the debug level for the different hosts that can use LCMAPS VOMS authentication as well as common LCMAPS VOMS authentication issues.

HTCondor-CE hosts¶

If you are troubleshooting an HTCondor-CE host, follow these instructions to raise the LCMAPS debug level:

Add the following text to /etc/sysconfig/condor-ce:

export LCMAPS_DEBUG_LEVEL=5
# optional (uncomment the following line to output log messages to a file):
# export LCMAPS_LOG_FILE=/tmp/lcmaps.log

Disable HTCondor-CE authentication caches by creating /etc/condor-ce/config.d/99-disablegsicache.conf with the following contents:
```
GSS_ASSIST_GRIDMAP_CACHE_EXPIRATION = 0
```
Restart the condor-ce service

Tip

After you've completed troubleshooting, remember to revert the changes above and restart services!

XRootD hosts¶

If you are troubleshooting an XRootD host, follow these instructions to raise the LCMAPS debug level:

Choose the configuration file to edit based on the following table:

If you are running XRootD in... Then modify the following file...

Standalone mode /etc/xrootd/xrootd-standalone.cfg

Clustered mode /etc/xrootd/xrootd-clustered.cfg

Set --loglevel,5 under the -authzfunparms of the sec.protocol /usr/lib64 gsi line. For example:

sec.protocol /usr/lib64 gsi -certdir:/etc/grid-security/certificates \
            -cert:/etc/grid-security/xrootd/xrootdcert.pem \
            -key:/etc/grid-security/xrootd/xrootdkey.pem -crl:1 \
            -authzfun:libXrdLcmaps.so -authzfunparms:--loglevel,5 \
            -gmapopt:10 -gmapto:0

Restart the xrootd service

Tip

After you've completed troubleshooting, remember to revert the changes above and restart services!

GridFTP hosts¶

If you are troubleshooting a GridFTP host, follow these instructions to raise the LCMAPS debug level:

Add the following text to /etc/sysconfig/globus-gridftp-server:

export LCMAPS_DEBUG_LEVEL=5
# optional (uncomment the following line to output log messages to a file):
# export LCMAPS_LOG_FILE=/tmp/lcmaps.log

Restart the globus-gridftp-server service.

Tip

After you've completed troubleshooting, remember to revert the changes above and restart services!

Common issues¶

Wrong version of GridFTP¶

If you have the EPEL version of the GridFTP server, you may see error messages in journalctl (EL7), var/log/messages (EL6), or the location specified by LCMAPS_LOG_FILE.

Symptoms

Apr 11 13:51:41 atlas-hub globus-gridftp-server: You are still root after the LCMAPS execution. The implicit root-mapping safety is enabled. See documentation for details

Next actions

If the versions of the globus-gridftp-server-* packages do not end in osgXX.elY, continue with these instructions. To check the version of your globus-gridftp-server-*, run the following command:
```
[email protected] $ rpm -qa 'globus-gridftp*'
```
Verify that the priority of the OSG repositories are set properly

Clean your yum cache

[email protected] # yum clean all --enablerepo=*

Reinstall globus-gridftp-server:

[email protected] # yum update globus-gridftp-server

Getting Help¶

To get assistance, please use the this page.

Reference¶

Configuration Files¶

The files are evaluated in the following order, with earlier files taking precedence over later ones:

File	Provider	Purpose
`/etc/grid-security/ban-mapfile`	Admin	Ban DNs
`/etc/grid-security/ban-voms-mapfile`	Admin	Ban VOs
`/etc/grid-security/grid-mapfile`	Admin	Map DNs
`/etc/grid-security/voms-mapfile`	Admin	Map VOs
`/usr/share/osg/voms-mapfile-default`	OSG	Map VOs (default)

Warning

/usr/share/osg/voms-mapfile-default is not meant to be edited and will be overwritten on upgrades. All VO mappings can be overridden by editing the above files in /etc/grid-security.

Manual Configuration¶

This section is intended for use as reference if you choose to forego configuring the LCMAPS VOMS plugin via osg-configure (i.e., if you prefer a configuration management system like Ansible or Puppet). Therefore, the following instructions serve as a replacement for this section above.

LCMAPS is configured in /etc/lcmaps.db and since the VOMS plugin is a newer component, configuration for it may not be present in your existing /etc/lcmaps.db file.

Ensure the following lines are present in the "Module definitions" section (the top section, before authorize_only) of /etc/lcmaps.db:

gridmapfile = "lcmaps_localaccount.mod"
              "-gridmap /etc/grid-security/grid-mapfile"
banfile = "lcmaps_ban_dn.mod"
          "-banmapfile /etc/grid-security/ban-mapfile"
banvomsfile = "lcmaps_ban_fqan.mod"
              "-banmapfile /etc/grid-security/ban-voms-mapfile"
vomsmapfile = "lcmaps_voms_localaccount.mod"
              "-gridmap /etc/grid-security/voms-mapfile"
defaultmapfile = "lcmaps_voms_localaccount2.mod"
                 "-gridmap /usr/share/osg/voms-mapfile-default"

verifyproxynokey = "lcmaps_verify_proxy2.mod"
          "--allow-limited-proxy"
          "--discard_private_key_absence"
          " -certdir /etc/grid-security/certificates"

Edit the authorize_only section so that it contains only the following uncommented lines:

verifyproxynokey -> banfile
banfile -> banvomsfile | bad
banvomsfile -> gridmapfile | bad
gridmapfile -> good | vomsmapfile
vomsmapfile -> good | defaultmapfile
defaultmapfile -> good | bad

Edit /etc/grid-security/gsi-authz.conf and ensure that it contains the following line with a newline at the end:
```
globus_mapping liblcas_lcmaps_gt4_mapping.so lcmaps_callout
```

VO name	Unix account(s)
GLOW	`glow`
OSG	`osg`
ATLAS	`usatlas3`
CMS	`cmsuser`
Fermilab	`fnalgrid`
HCC	`hcc`
Gluex	`gluex`

If you are running XRootD in...	Then modify the following file...
Standalone mode	`/etc/xrootd/xrootd-standalone.cfg`
Clustered mode	`/etc/xrootd/xrootd-clustered.cfg`