Import Upstream version 1.8.5

[hcoop/debian/openafs.git] / doc / man-pages / pod1 / pts_examine.pod.in

=head1 NAME

pts_examine - Displays a Protection Database entry

=head1 SYNOPSIS

=for html
<div class="synopsis">

B<pts examine> S<<< B<-nameorid> <I<user or group name or id>>+ >>>
    S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>] 
    [B<-force>] [B<-auth>] [B<-help>]
    [B<-encrypt>] S<<< [B<-config> <I<config directory>>] >>>

B<pts e> S<<< B<-na> <I<user or group name or id>>+ >>> S<<< [B<-c> <I<cell name>>] >>>
    [B<-no>] [B<-l>] [B<-f>] [B<-a>] [B<-h>]
    [B<-e>] S<<< [B<-co> <I<config directory>>] >>>

B<pts check> S<<< B<-na> <I<user or group name or id>>+ >>> S<<< [B<-c> <I<cell name>>] >>>
    [B<-no>] [B<-l>] [B<-f>] [B<-a>] [B<-h>]
    [B<-e>] S<<< [B<-co> <I<config directory>>] >>>

B<pts che> S<<< B<-na> <I<user or group name or id>>+ >>> S<<< [B<-c> <I<cell name>>] >>>
    [B<-no>] [B<-l>] [B<-f>] [B<-a>] [B<-h>]
    [B<-e>] S<<< [B<-co> <I<config directory>>] >>>

=for html
</div>

=head1 DESCRIPTION

The B<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 -nameorid <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.

=include fragments/pts-common.pod

=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 B<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 B<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 B<pts createuser> or B<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 I<privacy flags>, which
indicate who can display or administer certain aspects of the entry.

=over 4

=item s

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

=item o

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

=item m

Controls who can issue the B<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 B<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 B<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.

=back

For example, the flags C<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.

The default privacy flags for user and machine entries are C<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 C<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. The defaults for the privacy flags may be changed by
running B<ptserver> with the B<-default_access> option. See L<ptserver(8)>
for more discussion of the B<-default_access> option.

=item group quota

The number of additional groups the user is allowed to create. The B<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
that only deal with the local cell and the B<pts creategroup> command sets
it to 0 (zero); do not change this value.

When using cross-realm authentication, a special group of the form
system:authuser@FOREIGN.REALM is created by an administrator and used.  If
the group quota for this special group is greater than zero, then aklog
will automatically register foreign users in the local PTS database, add
the foreign user to the system:authuser@FOREIGN.REALM, and decrement the
group quota by one.

=back

=head1 EXAMPLES

The following example displays the user entry for C<terry> and the machine
entry C<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 C<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 C<S>, anyone who can access the cell's database server
machines can examine the entry.

=back

=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)>

=head1 COPYRIGHT

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

This documentation is covered by the IBM Public License Version 1.0.  It was
converted from HTML to POD by software written by Chas Williams and Russ
Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.