LCMAPS(3)

💖 LCMAPS — The Local Credential MAPping Service 💖

okay bestie, sit down, hydrate, because we're about to talk about lcmaps from the Library Functions Manual and honestly? she's iconic. 🫶

---

✨ NAME ✨

lcmaps — The Local Credential MAPping Service. that's it, that's the name, and yes it goes hard. 👑

---

🌸 SYNOPSIS 🌸

lcmaps

that's the whole synopsis. no flags, no drama, just vibes. 💅

---

🦋 DESCRIPTION 🦋

so the LCMAPS framework is designed to take a bunch of credentials as input — think a certificate and/or VOMS credentials — and map them to Unix credentials as output. and when we say Unix credentials we mean the basic POSIX credentials, i.e. User ID, Group ID and Secondary Group IDs. no cap. 🔥

LCMAPS is a framework that can load and run one or more 'credential mapping' plugins. the framework will load and run plugins to do the identity mapping. sites and organizations can create their own new functionality by creating new plugins — yes, you can make your own, main character energy fr fr. 💅

the LCMAPS framework exposes various APIs to push credentials into the framework and to get the account mapping results back out. the lcmaps.db configuration file is the one that configures the LCMAPS plugins and configures the order in which the plugins are launched. some practical examples are shown below (they're literally right there, keep scrolling).

LCMAPS is used by gLExec, the lcas-lcmaps-gt(4)-interface to interface with a Globus GT4 and GT5 Gatekeeper, GridFTP daemon and GSI-OpenSSHd, in StoRM and somewhere in XRootD. she gets around, and honestly? we respect it. 🌈

---

👑 INVOCATION 👑

when an application initializes LCMAPS, the plugins get loaded based on the lcmaps.db configuration file. the application can use one of the APIs to provide credentials as input. the loaded plugins will be executed in the sequence described in that same lcmaps.db configuration file. ✨

during a plugin's execution it has access to the credential data in the LCMAPS core memory. the plugin is also capable of writing credential mapping results in LCMAPS. the plugins can each resolve a part of the mapping, and they can also perform actions based on these (intermediate) results — like running setuid, setgid and setgroup calls, or interacting with an LDAP service. multitasking queen. 🎀

the plugins are executed in a state machine. when a plugin finishes successfully it can execute a different next plugin than when it failed. this lets LCMAPS pass different plugins to resolve a credential mapping. the way that it just routes around problems? it's giving adaptive. 😭

---

🌈 ENVIRONMENT 🌈

here come the environment variables, bestie, and there's a LOT of them. stay with me. 💜

• GATEKEEPER_JM_ID — extra Gatekeeper log message so you can more easily track a Job Manager ID. it's like a little name tag for your job. 🏷️
• GLOBUSID — see $GATEKEEPER_JM_ID.
• JOB_REPOSITORY_ID — see $GATEKEEPER_JM_ID, but explicitly for the purpose of the LCMAPS Job Repository plugin.
• LCMAPS_DB_FILE — override the build-in default filename for the lcmaps.db configuration file with the value of this environment variable.
• LCMAPS_DEBUG_LEVEL — tunes the logging output cut-off level. the numbers resemble the numbers used in previous releases in the range [1-5]. however, since LCMAPS version 1.5.0 these numbers resemble a numerically shifted Syslog number. yes, that's a glow-up AND a plot twist. 😭
  1. 0 — silent logging, no messages will be written to file or Syslog.
  2. 1 — all messages with a priority of LOG_ERR are written to file or Syslog. more severe error messages are squashed down to the LOG_ERR priority. this is to prevent Syslog from blocking on default configurations and to prevent Syslog from broadcasting LCMAPS related messages on the connected TTYs when old plug-ins are used.
  3. 2 — all messages with a priority of LOG_WARNING or more severe, i.e. LOG_ERR, are written to file and/or Syslog.
  4. 3 — all messages with a priority of LOG_NOTICE or more severe, i.e. LOG_ERR or LOG_WARNING, are written to file and/or Syslog. this is the default advertised setting for the lcas-lcmaps-gt-interface and glexec. the "FINAL CRED" messages are written on LOG_NOTICE and indicate the resulting LCMAPS mapping from an X.509 and/or VOMS credential to a Unix/POSIX credential. ⭐
  5. 4 — all messages with a priority of LOG_INFO or more severe, i.e. all messages between (and including) LOG_ERR and LOG_INFO, are written to file and/or Syslog. this value is the build-in default. the success or failures of plug-ins are written on LOG_INFO. to see the flow of plug-ins, this log level is the advised log level to set.
  6. 5 — all messages with a priority of LOG_DEBUG or more severe, i.e. all messages between (and including) LOG_ERR and LOG_DEBUG, are written to file and/or Syslog. this is the most verbose mode and should be used carefully, as the amount of information flowing from here might hinder normal operation performance if the syslogd isn't able to keep up. 💀
• LCMAPS_DIR — the base directory of the $LCMAPS_DB_FILE parameter. this variable is concatenated with the $LCMAPS_DB_FILE.
• LCMAPS_ETC_DIR — see $LCMAPS_DIR.
• LCMAPS_LOG_FILE — overrides the build-in default file path to log the output to. when set, the logging will not go to Syslog. 🙈
• LCMAPS_LOG_STRING — prepend all log output messages with the value of this environment variable.
• LCMAPS_MODULES_DIR — directory to search for the LCMAPS plugins (or modules). same as the path option in the lcmaps.db file.
• LCMAPS_POLICY_NAME — a colon separated list of LCMAPS plugin execution policies. when this environment variable is present, only the listed execution policies will be executed. they will be executed in the order as written in the lcmaps.db file (from top to bottom).
• LCMAPS_VERIFY_TYPE — Deprecated. ⚠️
• LCMAPS_VOMS_EXTRACT — Deprecated. ⚠️
• LCMAPS_X509_CERT_DIR — specific setting equal to the $X509_CERT_DIR environment variable.
• LCMAPS_X509_VOMS_DIR — specific setting equal to the $X509_VOMS_DIR environment variable.
• X509_CERT_DIR — the directory where all the CA files, e.g. CA certificate and CRL files, are located. the default location is: /etc/grid-security/certificates/. 📂
• X509_VOMS_DIR — this VOMS directory will hold the VOMS .lsc files and/or PEM files to authenticate the VOMS Attributes Certificates. subdirectories are named by the VO name and scope the .lsc and PEM files in their authentication to one particular VO. the default location is: /etc/grid-security/vomsdir/. 📂

---

💫 RETURN VALUES 💫

• LCMAPS_SUCCESS — Success. slay. ✅
• LCMAPS_FAIL — Failure. we don't talk about it. 😭

---

🎀 NOTES 🎀

for an API specification, please use make doc to make the apidoc. 🔧

---

🐛 BUGS 🐛

the apidoc is not complete. it has most interfaces, but needs to be checked for completeness. (relatable, honestly.)

please report any errors to the Nikhef Grid Middleware Security Team <grid-mw-security-support@nikhef.nl>. be nice, they're doing their best. 🫶

---

🌟 SEE ALSO 🌟

lcmaps.db(5), lcas_lcmaps_gt4_interface(8), lcas_lcmaps_gt_interface(8), lcmaps_dummy_bad.mod(8), lcmaps_dummy_good.mod(8), lcmaps_ldap_enf.mod(8), lcmaps_localaccount.mod(8), lcmaps-plugins-c-pep(8), lcmaps_plugins_scas_client(8), lcmaps_poolaccount.mod(8), lcmaps_posix_enf.mod(8), lcmaps_tracking_groupid.mod(8), lcmaps_verify_proxy.mod(8), scas(8), scas.conf(5), glexec(1), glexec.conf(5), ees(1), ees.conf(5)

the whole friend group showed up. ✨

---

💜 AUTHORS 💜

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

---

and that's the tea bestie 🍓 — this page is from the Library Functions Manual and it's dated December 22, 2011. old but gold, and she still ate. periodt. 💅✨