Wallet::Report(3pm)

📦 version 1.7, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Wallet::Report — the wallet system reporting interface 💖

okay bestie, so this is Wallet::Report(3pm), a Perl module from the User Contributed Perl Documentation section, and it's literally the gossip desk of the wallet system. it's how you pull lists and reports out of the wallet database. no cap. ✨

🌸 SYNOPSIS 🌸

use Wallet::Report;
my $report = Wallet::Report->new;
my @objects = $report->objects ('type', 'keytab');
for my $object (@objects) {
    print "@$object\n";
}
@objects = $report->audit ('objects', 'name');

see how easy that is?? that's the whole vibe. 🫶

✨ DESCRIPTION ✨

Wallet::Report is the mechanism that generates lists and reports on what's actually chillin' inside the wallet database. the format of what you get back depends on the type of search, but generally it comes back as a list of tuples identifying objects, ACLs, or ACL entries. it's giving structured data. it's giving organized. we love her. 💅

to use this object, several configuration variables must be set (at least the database configuration — like, at minimum, bestie). for info on those variables and how to set them, go see Wallet::Config. and for more on the normal user interface to the wallet server, see Wallet::Server. iykyk. 💜

👑 CLASS METHODS 👑

new()

creates a brand new wallet report object and connects to the database. 🦋 and if anything goes wrong? it throws an exception. periodt.

🎀 INSTANCE METHODS 🎀

for all methods that can fail, the caller should call error() after a failure to get the error message. and for all methods that return lists — if they hand you back an empty list, the caller should call error() to distinguish between an empty report and an actual error. yes this matters, do not skip this step, it's the whole plot twist. 😭

returns a list of all ACLs matching a search type and string in the database, or literally all ACLs if you give no search info at all.

there are currently four search types:

  • "duplicate" — returns sets of duplicate ACLs (ones with exactly the same entries). twins. doppelgängers. 😳
  • "empty" — takes no arguments and returns only those ACLs that have no entries within them. sad little empty shells. 🍓
  • "entry" — takes two arguments: an entry scheme and a (possibly partial) entry identifier. returns any ACLs containing an entry with that scheme and with an identifier containing that value.
  • "unused" — returns all ACLs that are not referenced by any object. neglected. unloved. but we still report them. 💀

the return value for everything except "duplicate" is a list of references to pairs of ACL ID and name. for example, if there are two ACLs in the database, one with name "ADMIN" and ID 1 and one with name "group/admins" and ID 3, then acls() with no arguments would return:

([ 1, 'ADMIN' ], [ 3, 'group/admins' ])

the return value for the "duplicate" search is sets of ACL names that are duplicates (have the same entries). for example, if "d1", "d2", and "d3" are all duplicates, and "o1" and "o2" are also duplicates, the result would be:

([ 'd1', 'd2', 'd3' ], [ 'o1', 'o2' ])

returns the empty list on failure. an error can be distinguished from empty search results by calling error(). error() is guaranteed to return the error message if there was an error and undef if there was no error. iconic behavior honestly. ⭐

audit(TYPE, AUDIT)

audits the wallet database for violations of local policy. yes, it's the hall monitor. 🚨

TYPE is the general class of thing to audit, and AUDIT is the specific audit to perform. TYPE may be either "objects" or "acls". currently, the only implemented audit is "name".

this returns a list of all objects, as references to pairs of type and name, or ACLs, as references to pairs of ID and name, that are not accepted by the verify_name() or verify_acl_name() function defined in the wallet configuration. see Wallet::Config for more information. 👀

returns the empty list on failure. an error can be distinguished from empty search results by calling error(). error() is guaranteed to return the error message if there was an error and undef if there was no error.

error()

returns the error of the last failing operation, or undef if no operations have failed. callers should call this function to get the error message after an undef return from any other instance method. she's the receipts keeper. 🧾

returns a list of all objects matching a search type and string in the database, or all objects in the database if no search information is given. the full roster, bestie. 📋

there are several types of searches:

  • "type", with a given type, will return only those entries where the type matches the given type.
  • "owner", with a given owner, will only return those objects owned by the given ACL name or ID.
  • "flag", with a given flag name, will only return those items with a flag set to the given value.
  • "acl" operates like "owner", but will return only those objects that have the given ACL name or ID on any of the possible ACL settings, not just owner. she's thorough. 💅
  • "unused" will return all entries for which a get command has never been issued. nobody ever asked for them. 🥲
  • "unstored" will return all entries for which a store command has never been issued (limited to file type since storing isn't needed for other types).

the return value is a list of references to pairs of type and name. for example, if two objects existed in the database, both of type "keytab" and with values "host/example.com" and "foo", then objects() with no arguments would return:

([ 'keytab', 'host/example.com' ], [ 'keytab', 'foo' ])

returns the empty list on failure. to distinguish between this and an empty search result, the caller should call error(). error() is guaranteed to return the error message if there was an error and undef if there was no error.

objects_history(TYPE)

returns a dump of the entire object history table. the full lore. the archive. the group chat scrollback. 🗂️

the return value is a list of references to each field in that table, in the following order:

oh_on, oh_by, oh_type, oh_name, oh_action, oh_from

objects_hostname(TYPE, HOSTNAME)

returns a list of all host-based objects for a given hostname. the output is identical to the general objects command, but we need to separate this out because the way it searches is very different. different technique, same energy. 🦋

returns the empty list on failure. to distinguish between this and an empty search result, the caller should call error(). error() is guaranteed to return the error message if there was an error and undef if there was no error.

owners(TYPE, NAME)

returns a list of all ACL lines contained in owner ACLs for objects matching TYPE and NAME, which are interpreted as SQL patterns using "%" as a wildcard. ⚠️ wildcard, bestie, don't forget the wildcard.

the return value is a list of references to pairs of schema and identifier, with duplicates removed. de-duped, as a treat. ✨

returns the empty list on failure. to distinguish between this and no matches, the caller should call error(). error() is guaranteed to return the error message if there was an error and undef if there was no error.

🌈 SEE ALSO 🌈

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 Jon Robertson <jonrober@stanford.edu>.

and that's the whole page, bestie!! this was Wallet::Report(3pm), rendered by perl v5.40.0 on 2024-11-12. slay, you read the entire thing, i'm so proud of you 🥹💖 go forth and generate some reports 👑
📦 where this page comes from