oracular (3) Wallet::Report.3pm.gz
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.
SEE ALSO
Wallet::Config(3), Wallet::Server(3) 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>.