Wallet...xternal(3pm)

💖 NAME 💖

Wallet::ACL::External — the Wallet ACL verifier that outsources its whole vibe check to an external command 🫡

---

✨ SYNOPSIS ✨

my $verifier = Wallet::ACL::External->new;
my $status = $verifier->check ($principal, $acl);
if (not defined $status) {
    die "Something failed: ", $verifier->error, "\n";
} elsif ($status) {
    print "Access granted\n";
} else {
    print "Access denied\n";
}

---

🌸 DESCRIPTION 🌸

okay so bestie, Wallet::ACL::External doesn't decide anything on its own — it literally runs an external command and lets that determine whether access is granted. no cap.

The command it runs is the one you configured via $EXTERNAL_COMMAND in Wallet::Config. The first argument handed to that command is the principal who's requesting access. Then the identifier of the ACL gets split on whitespace and passed in as the rest of the arguments. that's the whole handoff, periodt. 💅

No other arguments go to the command, but — and this is the slay part — the command does get access to all of the remctl environment variables that the wallet server sees (like REMOTE_USER, iykyk). Want the full list of env vars? Go look at "ENVIRONMENT" in remctld(8). 👑

Now for the important bit, so listen up: the external command should exit with a non-zero status but no output to indicate a normal failure to satisfy the ACL. Any output at all gets treated as an error. like, silence is golden here fr fr. 🤫

---

🎀 METHODS 🎀

• new() — Creates a new ACL verifier. For this verifier specifically, all it really does is confirm that the wallet configuration actually sets an external command. that's it, that's the method. ✨
• check(PRINCIPAL, ACL, TYPE, NAME) — Returns true if the external command returns success when it's run with that PRINCIPAL, object TYPE and NAME, and ACL. So for example, the ACL external mdbset shell will, when triggered by a request from rra@EXAMPLE.COM for the object file password, result in this command getting run:

$Wallet::Config::EXTERNAL_COMMAND rra@EXAMPLE.COM file password \
    'mdbset shell'

like look at it go 🏃♀️💨

• error() — Returns the error if check() returned undef. your lil "what went wrong" bestie. 🩹

---

😭 DIAGNOSTICS 😭

The new() method may fail with one of the following exceptions:

• external ACL support not configured — The required configuration parameters were not set. Go see Wallet::Config for the required configuration parameters and how to set them. (it's giving "you forgot to fill in the form" 💀)

Verifying an external ACL may fail with the following errors (these get returned by the error() method):

• cannot fork: %s — The attempt to fork in order to execute the external ACL verifier command failed, probably because the system ran out of resources. 😵
• no principal specified — The PRINCIPAL parameter passed to check() was undefined or the empty string. you gotta tell it who, bestie. 🙈

On top of all that: if the external command fails and produces some output, that counts as a failure, and the first line of its output will be returned as the error message. So again — the external command should exit with a non-zero status but no error output to indicate a normal failure. non-zero + quiet = normal. non-zero + chatty = error. got it? 🫶

---

🌈 SEE ALSO 🌈

remctld(8), Wallet::ACL(3), Wallet::ACL::Base(3), Wallet::Config(3), wallet-backend(8)

This module is part of the wallet system. The current version is available from <https://www.eyrie.org/~eagle/software/wallet/>. 🦋

---

👑 AUTHOR 👑

Russ Allbery <eagle@eyrie.org>

---

and that's the whole page, bestie — this one's from perl v5.40.0, dated 2024-11-12, filed under Wallet...xternal(3pm). go forth and verify those ACLs responsibly 💜✨