NAME
Tivoli::AccessManager::Admin::Group
SYNOPSIS
use Tivoli::AccessManager::Admin;
my ($resp, @groups);
my $pd = Tivoli::AccessManager::Admin->new(password => 'N3ew0nk');
# Lets see who is there
$resp = Tivoli::AccessManager::Admin::Group->list($pd, pattern => "lgroup*");
print join("\n", @{$resp->value});
# Alternately, search by DN.
$resp = Tivoli::AccessManager::Admin::Group->list($pd, pattern => "lgroup*", bydn => 1);
print join("\n", @{$resp->value});
# Create a new group the easy way
$resp = Tivoli::AccessManager::Admin::Group->create($pd,
name => 'lgroup',
dn => 'cn=lgroup,ou=groups,o=rox,c=us',
cn => 'lgroup'
);
$groups[0] = $resp->value if $resp->is_ok;
# Create a few more groups in a different way
for my $i (1 .. 3) {
my $name = sprintf "lgroup%02d", $i;
$groups[$i] = Tivoli::AccessManager::Admin::Group->new($pd, name => $name);
# Don't attempt to create something that already exists
next if $groups[$i]->exist;
$resp = $groups[$i]->create(dn => "cn=$name,ou=groups,o=rox,c=us");
}
# Add members to the group, skipping those users already in the group
$resp = $groups[0]->members(add => [qw/luser01 luser02 luser03 luser04 luser05/ ],
force => 1);
# List the members
$resp = $groups[0]->members();
print "\t$_\n" for (@{$resp->value()});
# Remove members
$resp = $groups[0]->members(remove => [qw/luser02 luser03/]);
# Add and remove members at the same time
$resp = $groups[0]->members(remove => [qw/luser01 luser04/],
add => [qw/luser02 luser03/ ]
);
# Delete the group
$resp = $groups[0]->delete();
# We didn't remove it from the registry. Import it and delete it again
$resp = $groups[0]->groupimport();
$resp = $groups[0]->delete(1);
DESCRIPTION
Tivoli::AccessManager::Admin::Group provides the interface to the group portion of the TAM API.
CONSTRUCTOR
new(PDADMIN[, name=> NAME, dn => DN, cn => CN])
Creates a blessed Tivoli::AccessManager::Admin::Group object and returns it.
Parameters
- PDADMIN
-
An initialized Tivoli::AccessManager::Admin::Context object. Please note that, after the Tivoli::AccessManager::Admin::Group object is created, you cannot change the context w/o destroying the object and recreating it.
- name => NAME
-
The name of the group to which the object refers. new will query TAM to determine if the group exists or not, retrieving the other values (cn and dn) if it does.
- dn => DN
-
The group's DN. If this value is provided (but "name" is not), new will look to see if the group is already defined. If the group is, the other fields (name and cn) will be retrieved from TAM.
- cn => CN
-
The group's common name. Nothing special happens if you provide the cn. If this parameter is not provided, I will assume it is the same as the group's name.
Returns
A fully blessed Tivoli::AccessManager::Admin::Group object.
CLASS METHODS
Class methods behave like instance methods -- they return Tivoli::AccessManager::Adming::Response objects.
list(PDADMIN [,maxreturn => N, pattern => STRING, bydn => 1])
Lists some subset of TAM groups.
Parameters
- PDADMIN
-
A fully blessed Tivoli::AccessManager::Admin::Context object. Since this is a class method, and Tivoli::AccessManager::Admin::Context objects are stored in the instances, you must provide it.
- maxreturn => N
-
The number of users to return from the query. This will default to 0, which means all users matching the pattern. Depending on how your LDAP is configured, this may cause issues.
- pattern => STRING
-
The pattern to search on. The standard rules for TAM searches apply -- * and ? are legal wild cards. If not specified, it will default to *, which may cause issues with your LDAP.
- bydn => 1
-
Search by DN instead of group name. This changes the semantics of the search in an interesting fashion. By default, you will only get tamified groups. Searching by dn will return any LDAP object that TAM recognizes as a group, irrespective of the TAMification. This parameters defaults to 0.
Returns
The resulting list of users.
METHODS
This verse is the same as all the rest. Methods called with optional parameters will attempt to set. Methods called with no options will perform a get.
Given that all return values are cleverly hidden in the returned Tivoli::AccessManager::Admin::Response object, I am not going to worry about documenting that part. I will only say what will be in the object.
create(name => NAME, dn => DN, cn => CN, container => 'CONTAINER NAME')
"create" a new group in TAM. At the bare minimum, both the name and the DN must be defined. See "Parameters" below for a full discussion. create can be called instead of new. The new object can be retrieved from the Tivoli::AccessManager::Admin::Response object.
Parameters
- container => 'CONTAINER NAME'
-
The group container, if there is one. This parameter is optional. If you don't understand it, don't provide it.
- name => NAME
- dn => DN
- cn => CN
-
These are the same as defined for "new" and are only required if you either did not provide them when you created the instance or if you are calling "create" to create a new object.
Returns
The success of the ooerstion if new was used, the new Tivoli::AccessManager::Admin::Group object otherwise.
delete([1])
Deletes the group from TAM.
Parameters
If anything is provided that perl will interpret as "true", the group will be deleted from the registry. Defaults to false.
Returns
The success of the operation
description([STRING])
Gets or sets the description of the group.
Parameters
- STRING
-
The new description for the group. This is an optional parameter.
Returns
The description for the group for either the set or the get.
exist
A flag indicating if the group exists or not.
cn
Returns the CN for the group. This is a read-only function. No sets are allowed via the TAM API (go see Net::LDAP if you really want to do this).
dn
Returns the DN for the group. This is a read-only function. No sets are allowed via the TAM API.
name
Returns the name for the group. This is a read-only function. No sets are allowed via the TAM API.
members(add => [qw/list of users/], remove => [qw/list of users/], force => 1)
Adds, removes and retrieves the members of a group. The add and remove option can be used at the same time -- removes are processed first. If the removal fails, no adds will be attempted.
Parameters
- add => [qw/list of users/]
-
An array reference to the list of users to be added to the group.
- remove => [qw/list of users/]
-
An array reference to the list of users to be removed from the group.
- force => 1
-
Under normal circumstances, TAM will get unhappy if you try to either add members that are already in the group or delete members that don't exist. Using the force option will cause members to only add those members that are not in the group or delete those that are.
If no members will be added/deleted, you will get a warning in the response.
Returns
Unless there is an error, you will get the new membership list for the group.
list(maxreturn => NUMBER, pattern => STRING)
Gets a list of groups defined in TAM. If the pattern contains an '=', list will search by DNs. Otherwise, it will search by name. Yes, this is the same as the class method. I like being able to call this way as well, although it rather breaks the metaphor.
Parameters
- maxreturn => NUMBER
-
The maximum number of groups to return. It will default to 0, which means return all matching groups. That could cause problems with the LDAP.
- pattern => STRING
-
The pattern to search for. You can use the * and ? wildcards, but that is about it. This will default to *. It too could cause issues with the LDAP.
Returns
The list of groups that matched the search criteria.
groupimport([name => NAME, dn => DN, container => 'CONTAINER')
Imports an already existing LDAP group into TAM. This can also be used to create a new Tivoli::AccessManager::Admin::Group object.
Parameters
See create for the full explanation. Have I mentioned I am a lazy POD writer yet?
Returns
The success or failure of the import if called as an instance method, the new Tivoli::AccessManager::Admin::Group object otherwise.
ACKNOWLEDGEMENTS
See Tivoli::AccessManager::Admin. I stand upon the shoulders of giants.
BUGS
None known yet.
AUTHOR
Mik Firestone <mikfire@gmail.com>
COPYRIGHT
Copyright (c) 2004-2011 Mik Firestone. All rights reserved. This program is free software; you can redistibute it and/or modify it under the same terms as Perl itself.
Standard IBM copyright, trademark, patent and ownership statement.