AFS::Command::PTS - OO API to the AFS pts command

    use AFS::Command::PTS;

    my $pts = AFS::Command::PTS->new();

    my $pts = AFS::Command::PTS->new
      (
       command			=> $path_to_your_pts_binary,
      );

    my $pts = AFS::Command::PTS->new
      (
       noauth			=> 1,
       force			=> 1,
      );

This module implements an OO API wrapper around the AFS 'pts' command. The supported methods depend on the version of the pts binary used, and are determined automagically.

All of the following methods are inherited from the AFS::Command::Base class. See that documentation for details.

new

errors

supportsOperation

supportsArgument

Arguments

The pts help string is:

    pts creategroup: create a new group
    Usage: pts creategroup -name <group name>+ [-owner <owner of the group>]
			   [-id <id (negated) for the group>+]
			   [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->creategroup
      (
       # Required arguments
       name			=> $name, # OR [ $name1, $name2, ... ]
       # Optional arguments
       owner			=> $owner,
       id			=> $id, # OR [ $id1, $id2, ... ]
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

Return Values

This method returns an AFS::Object::PTServer object, which contains one AFS::Object::Group for each group created.

    my $result = $pts->creategroup
      (
       name			=> $name,
       owner		=> $owner,
      ) || die $pts->errors();
    foreach my $group ( $result->getGroups() ) {
	my ($grname,$grid) = ($group->name(),$group->id());
	print "New group $grname has id $grid\n";
    }

Each of these objects has the following attributes and methods:

AFS::Object::PTServer

    Methods			Returns
    -------			-------
    getGroupNames()		list of group names
    getGroupIds()		list of group ids
    getGroups()			list of AFS::Object::Group objects
    getGroupByName($name)	the AFS::Object::Group object for group $name
    getGroupById($id)		the AFS::Object::Group object for id $id
    getGroup( name => $name )	the AFS::Object::Group object for group $name
    getGroup( id => $id )	the AFS::Object::Group object for id $id

AFS::Object::Group

    Attributes			Values
    ----------			------
    name			Group name
    id				Group id

Arguments

The pts help string is:

    pts createuser: create a new user
    Usage: pts createuser -name <user name>+ [-id <user id>+]
			  [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->createuser
      (
       # Required arguments
       name			=> $name, # OR [ $name1, $name2, ... ]
       # Optional arguments
       owner			=> $owner,
       id			=> $id, # OR [ $id1, $id2, ... ]
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

Return Values

This method returns an AFS::Object::PTServer object, which contains one AFS::Object::User for each user created.

    my $result = $pts->createuser
      (
       name			=> $name,
       owner		=> $owner,
      ) || die $pts->errors();
    foreach my $user ( $result->getUsers() ) {
	my ($username,$userid) = ($user->name(),$user->id());
	print "New user $username has id $userid\n";
    }

Each of these objects has the following attributes and methods:

AFS::Object::PTServer

    Methods			Returns
    -------			-------
    getUserNames()		list of user names
    getUserIds()		list of user ids
    getUsers()			list of AFS::Object::User objects
    getUserByName($name)	the AFS::Object::User object for user $name
    getUserById($id)		the AFS::Object::User object for id $id
    getUser( name => $name )	the AFS::Object::User object for user $name
    getUser( id => $id )	the AFS::Object::User object for id $id

AFS::Object::User

    Attributes			Values
    ----------			------
    name			User name
    id				User id

Arguments

The pts help string is:

    pts examine: examine an entry
    Usage: pts examine -nameorid <user or group name or id>+
		       [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->examine
      (
       # Required arguments
       nameorid			=> $nameorid, # OR [ $nameorid1, $nameorid2, ... ]
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

Return Values

This method returns an AFS::Object::PTServer object, which contains one AFS::Object::User or AFS::Object::Group object for each user/group examined.

    my $result = $pts->examine
      (
       nameorid			=> [ $name1, $name2 ],
       cell				=> 1,
      ) || die $pts->errors();
    foreach my $userobj ( $result->getUser() ) {
	my ($name,$id) = ($userobj->name(),$userobj->id());
	print "User $name has id $id\n";
    }
    foreach my $groupobj ( $result->getGroups() ) {
	my ($name,$id) = ($groupobj->name(),$groupobj->id());
	print "Group $name has id $id\n";
    }

Each of these objects has the following attributes and methods:

AFS::Object::PTServer

    Methods			Returns
    -------			-------
    getGroupNames()		list of group names
    getGroupIds()		list of group ids
    getGroups()			list of AFS::Object::Group objects
    getGroupByName($name)	the AFS::Object::Group object for group $name
    getGroupById($id)		the AFS::Object::Group object for id $id
    getGroup( name => $name )	the AFS::Object::Group object for group $name
    getGroup( id => $id )	the AFS::Object::Group object for id $id
    getUserNames()		list of user names
    getUserIds()		list of user ids
    getUsers()			list of AFS::Object::User objects
    getUserByName($name)	the AFS::Object::User object for user $name
    getUserById($id)		the AFS::Object::User object for id $id
    getUser( name => $name )	the AFS::Object::User object for user $name
    getUser( id => $id )	the AFS::Object::User object for id $id

AFS::Object::User, AFS::Object::Group

    Attributes			Values
    ----------			------
    name			User or group name
    id				User or group id
    owner			Owner of the entry
    creator			Creator of the entry
    membership			Number of groups the user is a member of, or..
				Number of members of the group
    groupquota			Group creation quota

Arguments

The pts help string is:

    pts listentries: list users/groups in the protection database
    Usage: pts listentries [-users] [-groups] [-cell <cell name>]
			   [-noauth] [-force]
    Where: -users   list user entries
	   -groups  list group entries

The corresponding method invocation looks like:

    my $result = $pts->listentries
      (
       # Optional arguments
       users			=> 1,
       groups			=> 1,
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

Return Values

This method returns an AFS::Object::PTServer object, which contains one AFS::Object::User or AFS::Object::Group object for each user/group listed.

    my $result = $pts->listentries
      (
       users			=> 1,
       groups			=> 1,
       cell				=> $cell,
      ) || die $pts->errors();
    # Starting to see a pattern?  The result is parsed in almost the
    # same way as shown for examine

Each of these objects has the following attributes and methods:

AFS::Object::PTServer

    Methods			Returns
    -------			-------
    getGroupNames()		list of group names
    getGroupIds()		list of group ids
    getGroups()			list of AFS::Object::Group objects
    getGroupByName($name)	the AFS::Object::Group object for group $name
    getGroupById($id)		the AFS::Object::Group object for id $id
    getGroup( name => $name )	the AFS::Object::Group object for group $name
    getGroup( id => $id )	the AFS::Object::Group object for id $id
    getUserNames()		list of user names
    getUserIds()		list of user ids
    getUsers()			list of AFS::Object::User objects
    getUserByName($name)	the AFS::Object::User object for user $name
    getUserById($id)		the AFS::Object::User object for id $id
    getUser( name => $name )	the AFS::Object::User object for user $name
    getUser( id => $id )	the AFS::Object::User object for id $id

AFS::Object::User, AFS::Object::Group

    Attributes			Values
    ----------			------
    name			User or group name
    id				User or group id
    owner			Numeric id of the owner of the entry
    creator			Numeric id of the creator of the entry

Arguments

The pts help string is:

    pts listmax: list max id
    Usage: pts listmax [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->listmax
      (
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

Return Values

This method returns an AFS::Object::PTServer object, which contains two attributes:

    my $result = $pts->listmax
      (
       cell				=> $cell,
      ) || die $pts->errors();
    print "Maximum group ID is " . $result->maxgroupid() . "\n";
    print "Maximum user ID is " . $result->maxuserid() . "\n";

This object has the following attributes, which are always present:

    Attributes			Values
    ----------			------
    maxgroupid			Numeric value of the highest group ID
    maxuserid			Numeric value of the highest user ID

Arguments

The pts help string is:

    pts listowned: list groups owned by an entry or zero id gets orphaned groups
    Usage: pts listowned -nameorid <user or group name or id>+
			 [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->listowned
      (
       # Required arguments
       nameorid			=> $nameorid, # OR [ $nameorid1, $nameorid2, ... ]
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

Return Values

This method returns an AFS::Object::PTServer object, which contains one AFS::Object::User or AFS::Object::Group object for each user/group specified.

    my $result = $pts->listowned
      (
       nameorid			=> $user,
       cell				=> $cell,
      ) || die $pts->errors();
    my $userobj = $result->getUserbyName($user);
    print "User $user owns the following groups:\n";
    foreach my $owned ( $userobj->getOwned() ) {
	print "\t$owned\n";
    }

Each of these objects has the following attributes and methods:

AFS::Object::PTServer

    Methods			Returns
    -------			-------
    getGroupNames()		list of group names
    getGroupIds()		list of group ids
    getGroups()			list of AFS::Object::Group objects
    getGroupByName($name)	the AFS::Object::Group object for group $name
    getGroupById($id)		the AFS::Object::Group object for id $id
    getGroup( name => $name )	the AFS::Object::Group object for group $name
    getGroup( id => $id )	the AFS::Object::Group object for id $id
    getUserNames()		list of user names
    getUserIds()		list of user ids
    getUsers()			list of AFS::Object::User objects
    getUserByName($name)	the AFS::Object::User object for user $name
    getUserById($id)		the AFS::Object::User object for id $id
    getUser( name => $name )	the AFS::Object::User object for user $name
    getUser( id => $id )	the AFS::Object::User object for id $id

AFS::Object::User, AFS::Object::Group

    Attributes			Values
    ----------			------
    name			User or group name
    id				User or group id

    Methods			Returns
    -------			-------
    getOwned()			list of group names owned by the user or group

Arguments

The pts help string is:

    pts membership: list membership of a user or group
    Usage: pts membership -nameorid <user or group name or id>+
			  [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->membership
      (
       # Required arguments
       nameorid			=> $nameorid, # OR [ $nameorid1, $nameorid2, ... ]
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

Return Values

This method returns an AFS::Object::PTServer object, which contains one AFS::Object::User or AFS::Object::Group object for each user/group specified.

    my $result = $pts->membership
      (
       nameorid			=> $user,
       cell			=> $cell,
      ) || die $pts->errors();
    my $userobj = $result->getUserbyName($user);
    print "User $user is a member of these groups:\n";
    foreach my $group ( $userobj->getMembership() ) {
	print "\t$group\n";
    }

Each of these objects has the following attributes and methods:

AFS::Object::PTServer

    Methods			Returns
    -------			-------
    getGroupNames()		list of group names
    getGroupIds()		list of group ids
    getGroups()			list of AFS::Object::Group objects
    getGroupByName($name)	the AFS::Object::Group object for group $name
    getGroupById($id)		the AFS::Object::Group object for id $id
    getGroup( name => $name )	the AFS::Object::Group object for group $name
    getGroup( id => $id )	the AFS::Object::Group object for id $id
    getUserNames()		list of user names
    getUserIds()		list of user ids
    getUsers()			list of AFS::Object::User objects
    getUserByName($name)	the AFS::Object::User object for user $name
    getUserById($id)		the AFS::Object::User object for id $id
    getUser( name => $name )	the AFS::Object::User object for user $name
    getUser( id => $id )	the AFS::Object::User object for id $id

AFS::Object::User, AFS::Object::Group

    Attributes			Values
    ----------			------
    name			User or group name
    id				User or group id

    Methods			Returns
    -------			-------
    getMembership()		For a user, the list of group to which the user belongs,
				for a group, the members of the group

All of the following commands return a simple Boolean (true/false) value, if they succeed or fail.

The pts help string is:

    pts adduser: add a user to a group
    Usage: pts adduser -user <user name>+ -group <group name>+
		       [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->adduser
      (
       # Required arguments
       user			=> $user, # OR [ $user1, $user2, ... ]
       group			=> $group, # OR [ $group1, $group2, ... ]
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

The pts help string is:

    pts chown: change ownership of a group
    Usage: pts chown -name <group name> -owner <new owner>
		     [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->chown
      (
       # Required arguments
       name			=> $name,
       owner			=> $owner,
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

The pts help string is:

    pts delete: delete a user or group from database
    Usage: pts delete -nameorid <user or group name or id>+
		      [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->delete
      (
       # Required arguments
       nameorid			=> $nameorid, # OR [ $nameorid1, $nameorid2, ... ]
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

The pts help string is:

    pts removeuser: remove a user from a group
    Usage: pts removeuser -user <user name>+ -group <group name>+
			  [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->removeuser
      (
       # Required arguments
       user			=> $user, # OR [ $user1, $user2, ... ]
       group			=> $group, # OR [ $group1, $group2, ... ]
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

The pts help string is:

    pts rename: rename user or group
    Usage: pts rename -oldname <old name> -newname <new name>
		      [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->rename
      (
       # Required arguments
       oldname			=> $oldname,
       newname			=> $newname,
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

The pts help string is:

pts setfields: set fields for an entry Usage: pts setfields -nameorid <user or group name or id>+ [-access <set privacy flags>] [-groupquota <set limit on group creation>] [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->setfields
      (
       # Required arguments
       nameorid			=> $nameorid, # OR [ $nameorid1, $nameorid2, ... ]
       # Optional arguments
       access			=> $access,
       groupquota		=> $groupquota,
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

The pts help string is:

    pts setmax: set max id
    Usage: pts setmax [-group <group max>] [-user <user max>]
		      [-cell <cell name>] [-noauth] [-force]

The corresponding method invocation looks like:

    my $result = $pts->setmax
      (
       # Optional arguments
       user			=> $user,
       group			=> $group,
       cell			=> $cell,
       noauth			=> 1,
       force			=> 1,
      );

AFS::Command(1), AFS::Object(1)