Author image Phillip Moore
and 1 contributors

NAME

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

SYNOPSIS

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

DESCRIPTION

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.

METHODS -- Inherited

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

new
errors
supportsOperation
supportsArgument

METHODS (with complex return values)

creategroup

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

createuser

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

examine

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

listentries

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

listmax

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

listowned

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

membership

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

METHODS (with simple return values)

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

adduser

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

chown

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

delete

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

removeuser

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

rename

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

setfields

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

setmax

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

SEE ALSO

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