Installing and Maintaining the LCMAPS VOMS Plugin¶

Warning

This document is for software that will no longer be supported after the OSG 3.5 retirement (February 2022). See the Release Series Support Policy for details.

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.

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.

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
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 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.

Mapping VOs
Mapping users
Banning VOs
Banning users
Mapping using all FQANs

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.

Note

The openssl version 1.1.x command prints the subject DN in a slightly different format. OpenSSL version 1.1 is present on Enterprise Linux 8 systems. The new format is a comma separated list of attributes. You must convert that back to the older format for our map files. Each attribute must start with a / and there are no spaces around the = and remove the comma between attributes:

DC = org, DC = opensciencegrid, O = Open Science Grid, OU = People, CN = Matyas Selmeci

should be written as:

/DC=org/DC=opensciencegrid/O=Open Science Grid/OU=People/CN=Matyas Selmeci

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, xrootd, etc.) to clear any authentication caches. In the case of XRootD when the service is not restarted the change could take up to 12hrs to take effect. This can be modified by defining the authzto option in the sec.protocol configuration attribute, e.g.:

sec.protocol /usr/lib64 gsi \
    -certdir:/etc/grid-security/certificates \
    -cert:/etc/grid-security/xrd/xrdcert.pem \
    ...
    -authzto:3600

The units of -authzto are in seconds which means that the above will set the LCMAPS cache lifetime to 1hr.

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, xrootd, etc.) to clear any authentication caches. In the case of XRootD when the service is not restarted the change could take up to 12hrs to take effect. This can be modified by defining the authzto option in the sec.protocol configuration attribute, e.g.:

sec.protocol /usr/lib64 gsi \
    -certdir:/etc/grid-security/certificates \
    -cert:/etc/grid-security/xrd/xrdcert.pem \
    ...
    -authzto:3600

The units of -authzto are in seconds which means that the above will set the LCMAPS cache lifetime to 1hr.

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
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 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:lcmapscfg=/etc/xrootd/lcmaps.cfg,loglevel=5,policy=authorize_only \
            -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¶

A user/VO still has access to my XRootD server after adding them to the ban files¶

The best way to ensure that a user/VO is immediately banned is to restart the XRootD server after adding the DN or VOMS attributes to the corresponding ban file. If the above is not possible, the the lifetime of the LCMAPS cache for XRootD can be controlled by setting the parameter authzto within the sec.protocol configuration attribute, e.g.:

sec.protocol /usr/lib64 gsi \
-certdir:/etc/grid-security/certificates \
-cert:/etc/grid-security/xrd/xrdcert.pem \
...
-authzto:3600

The units of -authzto are in seconds which means that the above will set the LCMAPS cache lifetime to 1hr. The default value for this parameter is 12hrs.

Wrong version of GridFTP¶

If you have the EPEL version of the GridFTP server, you may see error messages in journalctl 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`