AFS::PTS(3pm)

NAME

AFS::PTS - Class to communicate with the AFS Protection Server

SYNOPSIS

use AFS::PTS;

my $num_flg = AFS::PTS->convert_numeric_names;
my $bits  = AFS::PTS->ascii2ptsaccess("S----");
my $flags = AFS::PTS->ptsaccess2ascii($bits);

my $pts = AFS::PTS->new;

my $id    = $pts->createuser('guest');
my $entry = $pts->listentry('guest');
foreach my $key ( sort keys %$entry) {
    printf("%20s =>  %s\n", $key, $$entry{$key});
}
$ok = $pts->delete('guest');
undef $pts;   # destroy server connection

$pts   = AFS::PTS->new;
$entry = $pts->dumpentry(67136, 1, 1);
foreach my $key ( sort keys %$entry) {
    printf("%20s =>  %s\n", $key, $$entry{$key});
}

my $over  = 1;
my @names = $pts->getcps('nog', 1, $over);
print "OVER = $over \n";
print "cps for NOG\n";
foreach my $mem (sort @names) {
    print "  $mem\n";
}

AFS::PTS->convert_numeric_names(1);
my @ids = (28053, 1, 105, 32000, 32766);
@names  = $pts->PR_IDToName(\@ids);
foreach my $name (@names) {
    print "name = $name\n";
}

print "Convert(nog): ", $pts->id('nog'), "\n";

DESCRIPTION

This class is used to communicate with the AFS Protection Server in order to maintain and to administer the Protection Database maintained by the Protection Server. The Protection Database stores information
about AFS users, client machines, and groups which the File Server
process uses to determine whether clients are authorized to access AFS data.

This class provides methods to map back and forth between user account names and their internal numerical AFS identifiers. It also manages the creation, manipulation, and update of user-defined groups suitable for use on ACLs. It has methods to query the information held for any
given AFS user or group and to create, modify, and delete the records
in the PDB where the above information is held.

Before you can access any PDB records you must establish a connection
to the Protection Server. This is done by the constructor method "new" which returns a PTS object. A PTS object is essentially a handle to
talk to the Protection Server in a given cell. Such a PTS object is
required before any of the other PTS instance methods can be called.

All PR_* methods are essentially the same as the low-level AFS PTS APIs and are considered as low-level methods. The other methods (considered as high-level) are more user friendly and perl-like. Whereas the lowlevel (PR_*) methods only accept numerical values for names or groups
the high-level methods accept either numeric IDs or names.

COMPATIBILITY

This release does NOT support any features and interfaces from version 1.

METHODS

CONSTRUCTOR

$pts = AFS::PTS->new(([SEC [, CELL]]);: Creates a new object of the class AFS::PTS. An AFS::PTS object is essentially a handle to talk to the Protection Server in a given
CELL. Internally an AFS::PTS object is a pointer to a ubik_client structure, although this may change and the value returned from
AFS::PTS::new should always be treaded as an opaque handle.; CELL defaults to NULL. The security level SEC (default 1) is a
number from 0 to 2:

0 un-authenticated connection should be made
1 try authenticated first, fall back to un-authenticated
2 fail if an authenticated connection can't be made; DESTRUCTOR; $pts->DESTROY;
Destroys the ubik connection to the Protection Server and frees the ubik connection structure.; CLASS METHODS; $bits = AFS::PTS->ascii2ptsaccess(FLAGS);
Converts the privacy flags FLAGS (a string of five characters) into its corresponding five privacy bits. The privacy flags indicate who can display or administer certain aspects of a PTS entry.; $flags = AFS::PTS->ptsaccess2ascii(BITS);
Converts the five PTS privacy bits BITS into its corresponding
privacy flags (a string of five characters). The privacy flags
indicate who can display or administer certain aspects of a PTS
entry.; $value = AFS::PTS->convert_numeric_names;
AFS::PTS->convert_numeric_names(NEWVAL);
Gets or sets the global flag for converting names into numeric AFS ids. If conversion is 'on' (default) all names NOT looking like a numeric value are converted into its AFS id. If you set NEWVAL to 0 (conversion is 'off'), NO conversion is done. You'll probably want to leave conversion 'on' unless you create PTS names that look
exactly like numbers. (not a good idea to begin with :-); INSTANCE METHODS (high-level)
All high-level methods will accept either numeric AFS ids or AFS
user names.; $ok = $$ppttss->adduser(NAME, GROUP);
Adds the given user NAME to the specified GROUP. It calls the AFS system library function 'PR_AddToGroup'.; $ok = $$ppttss->chid(NAME, NEWID);
Changes the id for the given entry NAME to NEWID. It calls the AFS system library function 'PR_ChangeEntry'.; $ok = $$ppttss->chown(NAME, OWNER);
Changes the owner of the given entry NAME to OWNER. It calls the
AFS system library function 'PR_ChangeEntry'.; $id = $$ppttss->creategroup(NAME [, OWNER [, GID]]);
Creates the new group NAME. You can optionally specify the OWNER
and the id GID of the new group. If successful, the group ID
allocated for this new entry is returned. It calls the AFS system
library function 'PR_INewEntry' or 'PR_NewEntry'.; $id = $$ppttss->createuser(NAME [, UID]);
Creates the new user NAME. You can optionally specify the id UID of the new user. If successful, the user ID allocated for this new
entry is returned. It calls the AFS system library function
'PR_INewEntry' or 'PR_NewEntry'.; $ok = $$ppttss->delete(NAME);
Deletes the entry NAME. It calls the AFS system library function
'PR_Delete'.; $entry = $$ppttss->dumpentry(POS [, LOOKUP_ID [, CONV]]);
Returns a reference to a hash table containing the values from the C structure "prdebugentry". If LOOKUP_ID is 1 (default) then the
AFS ids in the hash table will be converted to names. If CONV is 1 (default) then flags will be converted to its ASCII representation. It calls the AFS system library function 'PR_DumpEntry'.; @members = $$ppttss->getcps(NAME [, LOOKUP_ID [, OVER]]);
Returns the Current Protection Subdomain (CPS) for the given PTS id. The CPS is the closure of all identities that the given NAME
can use. This list includes all the groups NAME belongs to, the
special AFS ids (system:anyuser and system:authuser), as well as
the id itself. If LOOKUP_ID is 1 (default) then names will be
returned. If the size of the list is greater then
&AFS::PR_MAXGROUPS then OVER will be set to a non-zero value and
only &AFS::PR_MAXGROUPS items will be returned. It calls the AFS
system library function 'PR_GetCPS'.; $id = $$ppttss->id($NAME [, ANON]]);
@id = $$ppttss->id(\@NAME [, ANON]]);
$idref = $$ppttss->id(\%NAME [, ANON]]);
Converts the NAME into a AFS id. The first method returns a single id. The second method takes a reference to an array of names and
returns an array of ids. The third method takes a reference to a
hash table, the keys of which are names, and returns a reference to the same hash, with the ids as the value of each key.

If ANON is 1 (default) and a given name does not map into an id
then the value &AFS::ANONYMOUSID will be returned. If ANON is 0
then the id will be set to undef. It calls the AFS system library function 'PR_NameToID'.; $ok = $$ppttss->ismember(NAME, GROUP);
Returns a non-zero value if NAME is a member of GROUP. It calls
the AFS system library function 'PR_IsAMemberOf'.; $entry = $$ppttss->listentry(NAME [, LOOKUP_ID [, CONV]]);
Returns a reference to a hash table containing the values from the C structure "prcheckentry". If LOOKUP_ID is 1 (default) then the
PTS ids in the hash table will be converted to names. If CONV is 1 (default) then flags will be converted to its ASCII representation. It calls the AFS system library function 'PR_ListEntry'.; ($uid, $gid) = $$ppttss->listmax;
Returns the largest allocated user ID and group ID. It calls the
AFS system library function 'PR_ListMax'.; @members = $$ppttss->members(NAME [, LOOKUP_ID [, OVER]]);
Returns the list of groups in which the user NAME is a member. If
NAME is a group, this method returns a list of users which are in
that group. If LOOKUP_ID is 1 (default) then names will be
returned. If the size of the list is greater then
&AFS::PR_MAXGROUPS then OVER will be set to a non-zero value and
only &AFS::PR_MAXGROUPS items will be returned. It calls the AFS
system library function 'PR_ListElements'.; $name = $$ppttss->name(ID [, ANON]]);
@name = $$ppttss->name(ID [, ANON]]);
$nameref = $$ppttss->name(ID [, ANON]]);
Converts AFS ID into a name. The first method returns a single
name. The second method takes a reference to an array of ids and
returns an array of names. The third method takes a reference to a hash table, the keys of which are ids, and returns a reference to
the same hash, with the names as the value of each key. If ANON is 1 (default) and a given id does not map into a name then the id
value will be converted to a string (i.e, 11234 => "11234").

If ANON is 0 then the name will be set to undef. It calls the AFS system library function 'PR_IDToName'.; @members = $$ppttss->owned(NAME [, LOOKUP_ID [, OVER]]);
Returns a list of AFS ids owned by the given user or group NAME.
If NAME is 0, then the PDB orphan list is returned. There is also a global orphan list, which contains entries for all orphans, namely groups belonging to users that have been deleted from the PDB. If
LOOKUP_ID is 1 (default) then names will be returned. If the size of the list is greater then &AFS::PR_MAXGROUPS then OVER will be
set to a non-zero value and only &AFS::PR_MAXGROUPS items will be
returned. It calls the AFS system library function 'PR_ListOwned'.; $ok = $$ppttss->rename(NAME, NEWNAME);
Renames NAME into NEWNAME. It calls the AFS system library
function 'PR_ChangeEntry'.; $ok = $$ppttss->removeuser(NAME, GROUP);
Removes the user NAME from GROUP. It calls the AFS system library function 'PR_RemoveFromGroup'.; $ok = $$ppttss->setaccess(NAME, NEWFLAG);
Sets the privacy flags for the given entry NAME to NEWFLAG. It
calls the AFS system library function 'PR_SetFieldsEntry'.; $ok = $$ppttss->setgroupquota(NAME, NGROUPS);
Sets the group creation quota for NAME to NGROUPS. It calls the
AFS system library function 'PR_SetFieldsEntry'.; $max = $$ppttss->setmax(ID [, ISGROUP]);
If ISGROUP is 0 (default) then the maximum id number for user is
set to ID. Otherwise the maximum id number of groups is set to ID. It calls the AFS system library function 'PR_SetMax'.; $pos = $$ppttss->whereisit(NAME);
Returns the PDB byte offset of NAME. This method is used in
conjunction with the method 'dumpentry'. It calls the AFS system
library function 'PR_WhereIsIt'.; INSTANCE METHODS (low-level)
The following low-level methods deal only with numeric AFS ids.; $ok = $$ppttss->PR_AddToGroup(UID, GID);
Adds the given AFS UID to the group whose numerical identifier is
GID.; $ok = $$ppttss->PR_ChangeEntry(ID, NAME, OID, NEWID);
Allows the caller to change one or more aspects of the user or
group entry in the PDB whose numerical id is ID. An attempt to
change the entry for any of the reserved AFS ids (ANYUSERID,
AUTHUSERID, ANONYMOUSID, or SYSADMINID) will be rejected. The new
name, if any, to assign to the entry is held in NAME. If no name
change is to be made, then the name argument may be set to NULL.
Similarly, the numerical ID of the entry's (possibly new) owner is listed in the OID parameter. If no owner change is desired, OID is set to zero. Finally, a new numerical ID may be specified for the
given entry in NEWID. If this is set to zero, then the entry's ID
will not be altered.; $ok = $$ppttss->PR_Delete(ID);
Deletes the PDB entry for the user or group whose id is ID.; $entry = $$ppttss->PR_DumpEntry(POS);
Returns the contents of the PDB entry located at byte offset POS
within the database, and is intended to be used only for debugging.; @ids = $$ppttss->PR_GetCPS(ID, OVER);
Generate the Current Protection Subdomain, or CPS, for the AFS user with the given numerical ID. Basically, the CPS is the closure of
all identities that the given ID can use. This list of groups and special AFS ids (e.g. ANYUSERID and AUTHUSERID) to which the
specified user belongs is returned. The user's own ID also appears on this list. If the size of the list has overflowed the maximum
list size, PR_MAXGROUPS (5,000), then the OVER argument is set to a nonzero value.; @names = $$ppttss->PR_IDToName(\@IDS);
Converts the array of numerical AFS user IDS into the appropriate
printable AFS user names. Entries in the given list IDS for which
the Protection Server does not have an IDtoname mapping are
translated to the string representation of the numerical ID, in
base 10.; $id = $$ppttss->PR_INewEntry(NAME, ID, OID);
Creates an entry in the PDB for a user or group with the given
NAME, and whose owner's id is OID. The numerical AFS id must be
set to the given value ID. If successful, the given ID allocated
for this new entry is returned.; $ok = $$ppttss->PR_IsAMemberOf(UID, GID);
Returns a non-zero value if user UID is a member of group GID.; @ids = $$ppttss->PR_ListElements(ID, OVER);
For the user ID, this method returns the list of groups in which
the user is a member. For the group ID, this method returns a list of users which are in that group. Note that this function returns
numerical ids, not names. If the size of the generated list has
overflowed the maximum list size, PR_MAXGROUPS (5,000), then the
OVER argument is set to a nonzero value.; $entry = $$ppttss->PR_ListEntry(ID);
Returns a reference to a hash table containing the values from the C structure "prcheckentry" for the PDB entry ID. No conversion is
done on ids or flags.; ($uid, $gid) = $$ppttss->PR_ListMax;
Returns the largest allocated user id and group id.; @members = $$ppttss->PR_ListOwned(ID, OVER);
Returns a list of AFS ids owned by the given user or group ID. If the ID parameter is set to zero, then the PDB orphan list is
returned. If the size of the generated list has overflowed the
maximum list size, PR_MAXGROUPS (5,000), then the OVER argument is set to a nonzero value.; @ids = $$ppttss->PR_NameToID(\@NAMES);
Converts the array of AFS NAMES into the appropriate AFS ids.
Entries in the given list NAMES for which the Protection Server
does not have an IDtoname mapping are set to &AFS::ANONYMOUS.; $id = $$ppttss->PR_NewEntry(NAME, FLAG, OID);
Creates an entry in the PDB for a user or group with the given
NAME, and whose owner's ID is OID. If successful, the user or
group ID allocated for this new entry is returned. The FLAG
argument is used to communicate whether the entry is for a user or group. Legal values are

&AFS::PRGRP create a group
&AFS::PRUSER create a user
$ok = $$ppttss->PR_RemoveFromGroup(UID, GID);: Removes the given AFS id UID from the group identified by GID.
$ok = $$ppttss->PR_SetFieldsEntry(ID, MASK, FLAGS, NGROUPS, NUSERS, S1, S2);: This method allows a caller to change one or more fields within the PDB entry matching the given user ID. The MASK argument is used to select which fields are to be changed. Depending on what has been
selected, the values placed in the argument fLAGS (setting the flag bits), NGROUPS (setting the group creation limit), and/or NUSERS
(setting the foreign user limit) are inserted into the PDB entry.
The remaining two arguments, S1 and S2, are not referenced, and are reserved for future expansion.
$ok = $$ppttss->PR_SetMax(ID, GFLAG);: Sets the value of either the highestallocated AFS user or group to ID. The GFLAG argument is set to a nonzero value if the given ID is for a group, and to zero for an individual user.
$pos = $$ppttss->PR_WhereIsIt(ID);: Returns the PDB byte offset for ID. This method is used in
conjunction with the method 'PR_DumpEntry'.

CURRENT AUTHOR

Norbert E. Gruener <nog@MPA-Garching.MPG.de>..SH "AUTHOR EMERITUS" Roland Schemers <schemers@slapshot.stanford.edu>..SH "COPYRIGHT AND DISCLAIMER": X 2001-2008 Norbert E. Gruener <nog@MPA-Garching.MPG.de>.
All rights reserved.; X 1994 Board of Trustees, Leland Stanford Jr. University.
All rights reserved.; Most of the explanations in this document are taken from the original AFS documentation.; AFS-3 Programmer's Reference:
Protection Server Interface
Edward R. Zayas
X 1991 Transarc Corporation.
All rights reserved.; IBM AFS Administration Reference
X IBM Corporation 2000.
All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The original module is covered by the following copyright:: Copyright (c) 1994 Board of Trustees, Leland Stanford Jr.
University; Redistribution and use in source and binary forms are permitted
provided that the above copyright notice and this paragraph are
duplicated in all such forms and that any documentation,
advertising materials, and other materials related to such
distribution and use acknowledge that the software was developed by Stanford University. The name of the University may not be
used to endorse or promote products derived from this software
without specific prior written permission. THIS SOFTWARE IS
PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

DOCUMENT VERSION

Revision $Rev: 859 $

docs.sk

comprehensive documentation repository

Most Viewed