jimzah/openafs
1
0
Fork 0
mirror of https://git.openafs.org/openafs.git synced 2025-01-19 15:30:14 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
e3dfba8e6c
openafs/doc/man-pages/pod1/pts_examine.pod
Russ Allbery e3dfba8e6c man-page-conversion-20051208 
This is the initial conversion of the AFS Adminstrators Reference into POD
for use as man pages.  The man pages are now generated via pod2man from
regen.sh so that only those working from CVS have to have pod2man
available.  The Makefile only installs.  The pages have also been sorted
out into pod1, pod5, and pod8 directories, making conversion to the right
section of man page easier without maintaining a separate list and allowing
for names to be duplicated between pod5 and pod1 or pod8 (which will likely
be needed in a few cases).

This reconversion is done with a new script based on work by Chas Williams.
In some cases, the output is worse than the previous POD pages, but this is
a more comprehensive conversion.

This is only the first step, and this initial conversion has various
problems.  In addition, the file man pages that didn't have simple names
have not been converted in this pass and will be added later.  Some of the
man pages have syntax problems and all of them have formatting errors.  The
next editing pass, coming shortly, will clean up most of the remaining
mess.
2005-12-08 12:14:33 +00:00

296 lines
7.9 KiB
Plaintext
Raw Blame History

=head1 NAME
pts examine - Displays a Protection Database entry
=head1 SYNOPSIS
B<pts examine -nameorid> <I<user or group name or id>>+ [-cell <I<cell name>>]
[B<-noauth>] [B<-force>] [B<-help>]
B<pts e -na> <I<user or group name or id>>+ [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [-h]
B<pts check -na> <I<user or group name or id>>+ [-c <I<cell name>>]
[B<-no>] [B<-f>] [B<-h>]
B<pts che -na> <I<user or group name or id>>+ [-c <I<cell name>>]
[B<-no>] [B<-f>] [B<-h>]
=head1 DESCRIPTION
The 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
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 -cell
Names the cell in which to run the command. For more details, see
the introductory B<pts> reference page.
=item -noauth
Assigns the unprivileged identity anonymous to the
issuer. For more details, see the introductory B<pts> reference
page.
=item -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 -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 C<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 C<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.
L<(1)>
L<(1)>
=item C<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
B<system:administrators> group in this field for user and
machine entries at creation time.
L<(1)>
=item C<creator
>
The user who issued the B<pts createuser> or pts
creategroup command to create the entry. This field serves as an
audit trail, and cannot be changed.
L<(1)>
=item C<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 C<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 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
B<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
B<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 B<system:administrators>
group can perform other functions.
=item C<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 and the B<pts creategroup> command sets it to 0
(zero); do not change this value.
L<(1)>
L<(1)>
=back
=head1 EXAMPLES
The following example displays the user entry for terry and the
machine entry B<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
B<system:administrators> group and the user associated with a
user entry can examine it, and only members of the
B<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.
Reference in New Issue View Git Blame Copy Permalink