=head1 NAME

pts examine - Displays a Protection Database entry

=head1 SYNOPSIS

pts examine B<-nameorid> I<user or group name or id>
[I<user or group name or id> ...]
[B<-cell> I<cell name>]
[B<-noauth>]  [B<-force>]  [B<-help>]

pts e B<-na> I<user or group name or id>
[I<user or group name or id> ...]
[B<-c> I<cell name>]  [B<-no>]  [B<-f>]  [B<-h>]

pts check B<-na> I<user or group name or id>
[I<user or group name or id> ...]
[B<-c> I<cell name>]
[B<-no>]  [B<-f>]  [B<-h>]

pts che B<-na> I<user or group name or id>
[I<user or group name or id> ...]
[B<-c> I<cell name>]
[B<-no>]  [B<-f>]  [B<-h>]

=head1 DESCRIPTION

The C<pts examine> command displays information from the Protection
Database entry of each user, machine or group specified by the
B<-nameorid> argument.

=head1 OPTIONS

=over 4

=item B<-nameorid> I<user or group name or id> [I<user or group name or id> ...]

Specifies the name or AFS UID of each user, the name or AFS GID
of each group, or the IP address (complete or wildcard-style)
or AFS UID of each machine for which to display the Protection
Database entry. It is acceptable to mix users, machines, and
groups on the same command line, as well as names (IP addresses
for machines) and IDs. Precede the GID of each group with a
hyphen to indicate that it is negative.

=item B<-cell> I<cell name>

Names the cell in which to run the command. For more details,
see the introductory L<pts(1)> reference page.

=item B<-noauth>

Assigns the unprivileged identity anonymous to the issuer. For
more details, see the introductory L<pts(1)> reference page.

=item B<-force>

Enables the command to continue executing as far as possible
when errors or other problems occur, rather than halting
execution at the first error.

=item B<-help>

Prints the online help for this command. All other valid
options are ignored.

=back

=head1 OUTPUT

The output for each entry consists of two lines that include the
following fields:

=over 4

=item Name 

The contents of this field depend on the type of entry:

=over 4

=item *

For a user entry, it is the username that the user types when
authenticating with AFS.

=item *

For a machine entry, it is either the IP address of a single
machine in dotted decimal format, or a wildcard notation that
represents a group of machines on the same network. See the
C<pts createuser> reference page for an explanation of the
wildcard notation.

=item *

For a group entry, it is one of two types of group name. If
the name has a colon between the two parts, it represents a
regular group and the part before the prefix reflects the
group's owner. A prefix-less group does not have the owner
field or the colon. For more details on group names, see the
C<pts creategroup> reference page.

=back

=item id

A unique number that the AFS server processes use to identify
AFS users, machines and groups. AFS UIDs for user and machine
entries are positive integers, and AFS GIDs for group entries
are negative integers. AFS UIDs and GIDs are similar in
function to the UIDs and GIDs used in local file systems such
as UFS, but apply only to AFS operations.

=item owner

The user or group that owns the entry and thus can administer
it (change the values in most of the fields displayed in the
output of this command), or delete it entirely. The Protection
Server automatically records the system:administrators group in
this field for user and machine entries at creation time.

=item creator

The user who issued the pts createuser or pts creategroup
command to create the entry. This field serves as an audit
trail, and cannot be changed.

=item membership

An integer that for users and machines represents the number of
groups to which the user or machine belongs. For groups, it
represents the number of group members.

=item flags

A string of five characters, referred to as privacy flags,
which indicate who can display or administer certain aspects of
the entry.

=over 4

=item s

Controls who can issue the pts examine command to display
the entry.

=item o

Controls who can issue the pts listowned command to
display the groups that a user or group owns.

=item m

Controls who can issue the pts membership command to
display the groups a user or machine belongs to, or which
users or machines belong to a group.

=item a

Controls who can issue the pts adduser command to add a
user or machine to a group. It is meaningful only for
groups, but a value must always be set for it even on
user and machine entries.

=item r

Controls who can issue the pts removeuser command to
remove a user or machine from a group. It is meaningful
only for groups, but a value must always be set for it
even on user and machine entries.

=back

Each flag can take three possible types of values to enable a
different set of users to issue the corresponding command:

=over 4

=item *

A hyphen (-) designates the members of the
system:administrators group and the entry's owner. For user
entries, it designates the user in addition.

=item *

The lowercase version of the letter applies meaningfully to
groups only, and designates members of the group in addition
to the individuals designated by the hyphen.

=item *

The uppercase version of the letter designates everyone.
For example, the flags SOmar on a group entry indicate that
anyone can examine the group's entry and display the groups
that it owns, and that only the group's members can display,
add, or remove its members.

=back

The default privacy flags for user and machine entries are
S----, meaning that anyone can display the entry. The ability
to perform any other functions is restricted to members of the
system:administrators group and the entry's owner (as well as
the user for a user entry).
The default privacy flags for group entries are S-M--, meaning
that all users can display the entry and the members of the
group, but only the entry owner and members of the
system:administrators group can perform other functions.

=item group quota

The number of additional groups the user is allowed to create.
The pts createuser command sets it to 20 for both users and
machines, but it has no meaningful interpretation for a
machine, because it is not possible to authenticate as a
machine. Similarly, it has no meaning in group entries and the
pts creategroup command sets it to 0 (zero); do not change this
value.

=back

=head1 EXAMPLES

The following example displays the user entry for terry and the
machine entry 158.12.105.44.

    pts examine terry 158.12.105.44

    Name: terry, id: 1045, owner: system:administrators, creator: admin,
    membership: 9, flags: S----, group quota: 15.
    Name: 158.12.105.44, id: 5151, owner: system:administrators,
    creator: byu, membership: 1, flags: S----, group quota: 20.

The following example displays the entries for the AFS groups with
GIDs -673 and -674.

    pts examine -673 -674

    Name: terry:friends, id: -673, owner: terry, creator: terry,
    membership: 5, flags: S-M--, group quota: 0.
    Name: smith:colleagues, id: -674, owner: smith, creator: smith,
    membership: 14, flags: SOM--, group quota: 0.

=head1 PRIVILEGE REQUIRED

The required privilege depends on the setting of the first privacy
flag in the Protection Database entry of each entry specified by the
B<-nameorid> argument:

=over 4

=item *

If it is lowercase s, members of the system:administrators group
and the user associated with a user entry can examine it, and only
members of the system:administrators group can examine a machine
or group entry.

=item *

If it is uppercase S, anyone who can access the cell's database
server machines can examine the entry.

=back

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<pts(1)>,
L<pts_adduser(1)>,
L<pts_chown(1)>,
L<pts_creategroup(1)>,
L<pts_createuser(1)>,
L<pts_listowned(1)>,
L<pts_membership(1)>,
L<pts_removeuser(1)>,
L<pts_rename(1)>,
L<pts_setfields(1)>

=cut
