LCMAPS_VOMS...LACCOUNT.MOD(8)

👑 LCMAPS_VOMS_POOLACCOUNT.MOD(8) — Site Access Control 💅

okay bestie, gather round, because this is the manual page for lcmaps_voms_poolaccount.mod — that's section 8 of the Site Access Control docs, and she is iconic. She's a plugin. She switches your user identity around based on VOMS credentials by way of pool accounts. Let's get into it. 🦋

---

✨ NAME ✨

lcmaps_voms_poolaccount.mod — the LCMAPS plugin that switches user identity based on VOMS credentials, using pool accounts. no cap. 💖

---

✨ SYNOPSIS ✨

lcmaps_voms_poolaccount.mod [-gridmapfile grid-mapfile] [-gridmapdir gridmapdir] [--do-not-add-primary-gid-from-mapped-account] [--add-primary-gid-from-mapped-account] [--add-primary-gid-as-secondary-gid-from-mapped-account] [--do-not-add-secondary-gids-from-mapped-account] [--add-secondary-gids-from-mapped-account] [--use-voms-gid|--use_voms_gid|-use_voms_gid] [--use-account-gid] [--do-not-require-primary-gid] [--require-primary-gid] [--do-not-use-secondary-gids|-do_not_use_secondary_gids] [-override_inconsistency] [-max_mappings_per_credential maxnrofmappings] [-strict_poolprefix_match {yes|no}]

---

✨ DESCRIPTION ✨

So the VOMS poolaccount acquisition plugin is basically a glow-up of lcmaps_poolaccount.mod.8 — a "VOMS-aware" remix, if you will. 🎀

What she does: she tries to find you a local account — more specifically a UserID — based on the VOMS info that LCMAPS has on hand, and especially on the Fully Qualified Attribute Names, aka FQANs. And where does the account come from? From an account pool. And heads up, those accounts in the pool have to actually exist on the system — either locally or through some centralised account database, like LDAP. no vibes-only accounts here bestie. 😭

First thing she does is try to find an FQAN → pool-name mapping in the grid-mapfile. And when I say "pool-name" I mean a name that starts with a dot . instead of an alphanumeric character. That mapping is what hands her a list of local accounts. ✨

Then there's the gridmapdir directory, which gets used as a persistent and open mapping database. Now, a pool is defined as a set of accounts that all follow one particular pattern in their naming — like pool001 or atlas001. In that directory the plug-in makes a brand new filename consisting of the lowercase URL-encoded Subject-DN of the user, followed by the name of the Unix groups that other plug-ins already mapped. 💅

For example — say the FQAN is mapped to .atlas in the grid-mapfile. Then she's gonna map it to the pool accounts atlas001, atlas002, etc., and those names are findable in the gridmapdir. 🦋

Now if there's no pool account assigned to the user yet? She'll go hunting for a free pool account — meaning one where the link count is 1 — and she'll make a new hardlink to it, named with the URL-encoded subject DN plus group names. 👑

And when a user comes back to the site? The plugin goes looking for the DN of the user (URL encoded) in that directory, and if she finds it, the corresponding pool account gets reassigned to that user. She remembers you. 🫶

Example showing the output of ls -li:

1836080 -rw-r--r-- 2 root root %2fo%3ddutchgrid%2fo%3dusers%2fo%3dnikhef%2fcn%3djohn%20doe:pool:group004
1836080 -rw-r--r-- 2 root root pool003

See how the filename is hardlinked to the mapped account name? Creating that hardlink is designed to be an atomic operation, and it's been verified to work on large installations that serve multiple services from a single NFS-share. slay. 🔥

Last thing: the plugin will resolve the UID of the mapped local (system) account username.

---

✨ OPTIONS ✨

• -gridmapfile grid-mapfile — this file has to contain the FQAN → pool name mappings. Strongly advised: set this option, and set it to an absolute path, so you don't end up using the wrong file (or the wrong file*path*). When it's unset, the plugin tries to grab the value from one of the environment variables (peep ENVIRONMENT below). When those are unset too, the default depends on whether the plugin is running inside a (setuid-)root application. In the (setuid-)root case, the default is /etc/grid-security/grid-mapfile. In the non-(setuid-)root case, the default is <homedir>/.gridmap. And in a (setuid-)root application, relative paths are taken with respect to /etc/grid-security/. 💖
• -gridmapdir gridmapdir — a directory used for the mapping database. If this option is unset, the plugin will try to obtain the value from the environment variable GRIDMAPDIR (see ENVIRONMENT). In a (setuid-)root application, relative paths are taken with respect to /etc/grid-security/. 🎀
• --do-not-add-primary-gid-from-mapped-account — after the account is mapped, do NOT add the primary Group ID from the passwd-file/LDAP of the mapped account as a part of the mapping result. Default is NOT to add the primary Group ID, unless --use-account-gid is specified. See also --add-primary-gid-from-mapped-account, --add-primary-gid-as-secondary-gid-from-mapped-account and --use-account-gid. 🙈
• --add-primary-gid-from-mapped-account — after the account is mapped, add the primary Group ID from the passwd-file/LDAP of the mapped account as a part of the mapping result. Default is NOT to add the primary Group ID, unless --use-account-gid is specified. See also --do-not-add-primary-gid-from-mapped-account, --add-primary-gid-as-secondary-gid-from-mapped-account and --use-account-gid. ✨
• --add-primary-gid-as-secondary-gid-from-mapped-account — after the account is mapped, add the primary Group ID from the passwd-file/LDAP of the mapped account as a secondary Group ID as a part of the mapping result (possibly in addition to adding it as a primary Group ID). Default is NOT to add it at all. See also --do-not-add-primary-gid-from-mapped-account, --add-primary-gid-from-mapped-account and --use-account-gid. 💅
• --do-not-add-secondary-gids-from-mapped-account — after the account is mapped, do NOT add the secondary Group ID(s) from the groups-file/LDAP of the mapped account as secondary Group ID(s) as a part of the mapping result. Default is NOT to add the sGIDs, unless --use-account-gid is specified. See also --add-secondary-gids-from-mapped-account --use-account-gid. 🦋
• --add-secondary-gids-from-mapped-account — after the account is mapped, add the secondary Group ID(s) from the groups-file/LDAP of the mapped account as secondary Group ID(s) as a part of the mapping result. Default is NOT to add the secondary Group ID(s), unless --use-account-gid is specified. See also --do-not-add-secondary-gids-from-mapped-account --use-account-gid. 🌸
• --use-voms-gid, --use_voms_gid, -use_voms_gid — this one does the opposite of --use-account-gid, telling the plugin NOT to add the mapped account group information to the mapping result. And ngl, this is currently already the default, so this option has no effect. See also --use-account-gid. 💀
• --use-account-gid — by default this plugin will NOT add the primary and secondary Group ID(s) from the passwd-file/groups-file/LDAP of the mapped account as part of the mapping result. Specifying this option overrides that default. Part or all of the group information can still be added or removed by using the --add-* and --do-not-add-* flags. See also --use-voms-gid. 👑
• --require-primary-gid — the group names already present in the LCMAPS mapping store, prior to this plugin running, get used to create the (URL encoded) lease name in the gridmapdir. This option can be used to enforce the existence of a primary Group ID prior to running this plug-in — which you can do by running other plugins earlier on in the policy. Default is not to require a primary GID. ⭐
• --do-not-require-primary-gid — the opposite effect of --require-primary-gid: it tells the plugin NOT to enforce the presence of a primary GID prior to its running. This is currently already the default, so this option has no effect. See also --require-primary-gid. 😭
• --do-not-use-secondary-gids, -do_not_use_secondary_gids — this option prevents adding mapped secondary group names to the lease name. Default is: add secondary group names to the lease name. 🎀
• -override_inconsistency — moving a user from one pool to another (because of a VO change) should normally only be done by changing the grid-mapfile to indicate the new pool for that user. If the resulting URL-encoded lease (hardlink) already exists but points to a different pool account than what would result from this plugin running, the plugin would normally fail. This option instructs the plugin to remap to the new pool account. 🙏
• -max_mappings_per_credential maximum number of mappings — this feature is deprecated. It was intended to work together with the Globus Dynamic Account Service/Workspace Service. The value indicates the maximum number of accounts a user — or, more specifically, a set of credentials (= DN + FQANS) — can be mapped to. Normally this number is 1. But if each job should run under its own account, the number should be increased. Whether LCMAPS will actually use the mapcounter depends on the LCMAPS interface being used. The lease name (or poolindex), in the case of mapcounters, looks like:

url_encoded(<DN>):gid1[:gid2[:gid3[...]]]:mapcount=<mapnumber>)

• -strict_poolprefix_match {yes|no} — if this is set to 'yes', a line in the grid-mapfile like <FQAN> .pool will result in mapping pool accounts matching only the regexp pool[0-9]+. Otherwise it will be allowed to match the wider range of pool.* (legacy behaviour). 💜

---

✨ RETURN VALUES ✨

• LCMAPS_MOD_SUCCESS — success, we ate. 🔥
• LCMAPS_MOD_FAIL — failure, we did not. 💀

---

✨ ENVIRONMENT ✨

• GRIDMAP | GLOBUSMAP | globusmap | GlobusMap — when no grid-mapfile is specified as an option to the plugin, she'll try to obtain the file location from one of these environment variables. 🦋
• GRIDMAPDIR — when no gridmapdir is specified as an option to the plugin, she'll try to obtain the file location from this environment variable. 🎀

---

✨ NOTES ✨

Since version 1.6.0, the voms_poolaccount plugin also takes the requested username (like the one forwarded by gsissh) into consideration. When it's present, the resulting pool account has to match it in order for the plugin to succeed. And heads up, this requires LCMAPS version 1.6.0 or newer. 👑

---

✨ BUGS ✨

Please report any errors to the Nikhef Grid Middleware Security Team <grid-mw-security-support@nikhef.nl>. 🫶

---

✨ SEE ALSO ✨

lcmaps.db(5), lcmaps(3).

---

✨ AUTHORS ✨

LCMAPS and the LCMAPS plug-ins were written by the Grid Middleware Security Team <grid-mw-security@nikhef.nl>. 🌈

---

and that's the whole page bestie, every last flag, every default, every env var, all of it 💅 — brought to you by Stichting FOM/Nikhef, dated February 6, 2015, from the LCMAPS_VOMS...LACCOUNT.MOD(8) manual. mwah. 🎀✨💖