LCMAPS_POOLACCOUNT.MOD(8)

💖 lcmaps_poolaccount.mod(8) 💖

okay bestie, sit down, hydrate, because we're reading the manual page for lcmaps_poolaccount.mod — part of Site Access Control — and it's actually kind of a serve. it's a LCMAPS plugin. it switches user identity by pool accounts. iconic behavior honestly. 🎀

---

✨ NAME ✨

lcmaps_poolaccount.mod — an LCMAPS plugin that switches user identity by pool accounts. 💅

---

🌸 SYNOPSIS 🌸

lcmaps_poolaccount.mod [-gridmapfile grid-mapfile] [-gridmapdir
gridmapdir] [-no_wildcard|-disablewildcard] [-override_inconsistency]
[-max_mappings_per_credential maxnrofmappings] [-strict_poolprefix_match
{yes|no}]

---

🦋 DESCRIPTION 🦋

so this plugin is an acquisition plugin, meaning it's the one that goes and gets the goods — specifically, it hands LCMAPS some Pool Account credential information. 🫶

here's the vibe: the plugin tries to find a pool account (and like, more specifically a UserID) based on the Distinguished Name (DN) of the user's end-entity certificate. the account gets acquired from an account pool. and no cap — the accounts in that pool have to actually exist on the system, either locally or through some centralised account database, e.g. LDAP.

first thing it does? it tries to find a DN → pool name mapping in the grid-mapfile. and the pool name starts with a dot . instead of an alphanumeric character. that mapping is what gives it a whole list of local accounts to play with. ✨

the gridmapdir directory is gonna be used as a persistent and open mapping database. a "pool" here means a set of accounts that follow a particular pattern in their naming, like test001. in that directory, the plug-in makes a new filename out of the lowercase URL-encoded Subject-DN of the user. yes it's a lot. it's giving filename-as-identity. 😭

for example — if the DN is mapped to .test in the grid-mapfile, it'll be mapped to the pool accounts test001, test002, etc., and the names of those can be found in the gridmapdir. 🌈

if there's no pool account assigned to the user yet, the plugin will try to find a free pool account (i.e. one for which the link count is 1) and make a new hardlink to it, using the URL-encoded subject DN as the name. 🧚

and when the user comes back to this site? the plugin looks for that user's DN (URL encoded) in this directory. if it's found — boom, the corresponding pool account gets assigned to the user. no cap, it just remembers them. 💜

here's an example showing the output of ls -li:

1836080 -rw-r--r-- 2 root root %2fdc%3dorg%2fdc%3dterena%2fdc%3dtcs%2fc%3dnl%2fo%3dnikhef%2fcn%3doscar%20koeroo%20okoeroo%40nikhef%2enl
1836080 -rw-r--r-- 2 root root test003

see how the filename is hardlinked to the mapped account-name? 👑 creating this hardlink is designed to be an atomic operation, and it's verified to work on large installations serving multiple services from one NFS-share. it's giving scale, it's giving reliability. periodt.

lastly, the plugin will resolve the UID, GID and all the secondary GIDs of the mapped local (system) account username. 🎀

---

💅 OPTIONS 💅

• -gridmapfile grid-mapfile — this file must contain the DN → pool name mappings. and bestie, it is strongly advised to set this option and to set it to an absolute path, so you don't accidentally use 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). when those are unset too, the default depends on whether the plugin runs 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 tries to get the value from the environment variable GRIDMAPDIR (see ENVIRONMENT). in a (setuid-)root application, relative paths are taken with respect to /etc/grid-security/. 🗂️
• -override_inconsistency — okay so, moving a user from one pool to another 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 running this plugin, the plugin would normally fail. this option tells the plugin to just go ahead and remap to the new pool account. it's the "we move" flag. 💅
• -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. this 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 every 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. in the case of mapcounters, the lease name (or poolindex) looks like this:

url_encoded(<DN>):mapcount=<mapnumber>)

• -no_wildcard, -disablewildcard — when this option is set, the plug-in will only match exact DNs. i.e. /DC=org/DC=terena/DC=tcs/C=NL/* will not match. no wildcard privileges today, sorry. 🚫
• -strict_poolprefix_match {yes|no} — if this is set to yes, a line in the grid-mapfile like <DN> .pool will result in mapping pool accounts that match only the regexp pool[0-9]+. otherwise it'll be allowed to match the wider range of pool.* (that's the legacy behaviour). choose your fighter. ⭐

---

🌟 RETURN VALUES 🌟

• LCMAPS_MOD_SUCCESS — success. slay. 🎉
• LCMAPS_MOD_FAIL — failure. 💀

---

🌈 ENVIRONMENT 🌈

• GRIDMAP | GLOBUSMAP | globusmap | GlobusMap — when no grid-mapfile is specified as an option to the plugin, it'll try to obtain the file location from one of these environment variables. (yes, all four spellings. the plugin is thorough like that. 👑)
• GRIDMAPDIR — when no gridmapdir is specified as an option to the plugin, it'll try to obtain the file location from this environment variable. 📁

---

🎀 NOTES 🎀

since version 1.6.0, the poolaccount plugin also takes the requested username (such as forwarded by gsissh) into consideration. when that'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>. they want to know. fr fr. 🙈

---

💜 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>. absolute legends, honestly. 🌸

---

and that's the whole page, bestie!! 💖 big kisses and a cute little sign-off: this beauty comes to you from Stichting FOM/Nikhef, dated February 6, 2015. go forth and map those pool accounts. ✨🎀🦋