NAME

Wallet::Report - Wallet system reporting interface

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');

DESCRIPTION

Wallet::Report provides a mechanism to generate lists and reports on the contents of the wallet database. The format of the results returned depend on the type of search, but will generally be returned as a list of tuples identifying objects, ACLs, or ACL entries.

To use this object, several configuration variables must be set (at least the database configuration). For information on those variables and how to set them, see Wallet::Config. For more information on the normal user interface to the wallet server, see Wallet::Server.

CLASS METHODS

new(): Creates a new wallet report object and connects to the database. On any error, this method throws an exception.

INSTANCE METHODS

For all methods that can fail, the caller should call error() after a failure to get the error message. For all methods that return lists, if they return an empty list, the caller should call error() to distinguish between an empty report and an error.

acls([ TYPE [, SEARCH ... ]])

Returns a list of all ACLs matching a search type and string in the database, or all ACLs if no search information is given. There are currently four search types. "duplicate" returns sets of duplicate ACLs (ones with exactly the same entries). "empty" takes no arguments and will return only those ACLs that have no entries within them. "entry" takes two arguments, an entry scheme and a (possibly partial) entry identifier, and will return 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.

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, 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.

audit(TYPE, AUDIT)

Audits the wallet database for violations of local policy. 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.

objects([ TYPE [, SEARCH ... ]])

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.

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. "unused" will return all entries for which a get command has never been issued. "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", 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 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.

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. The return value is a list of references to pairs of schema and identifier, with duplicates removed.

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.

AUTHOR

Russ Allbery <eagle@eyrie.org> and Jon Robertson <jonrober@stanford.edu>.