NAME

pts_examine - Displays a Protection Service entry

SYNOPSIS

pts examine -nameorid <user or group name or id>+ [-cell <cell name>] [-noauth] [-localauth] [-force] [-auth] [-help] [-encrypt [<yes|no>]] [-config <configuration file>]

DESCRIPTION

The pts examine command (alias pts check) displays information about user, machine, network or group entries specified by the -nameorid argument.

OPTIONS

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

-auth

Use the calling user's tokens to communicate with the Protection Server. For more details, see pts(1).

-cell <cell name>

Names the cell in which to run the command. For more details, see pts(1).

-config <configuration file>

Sets the location of the configuration file to be used. The default file is /etc/yfs/yfs-client.conf. For more details, see pts(1).

-encrypt [<yes|no>]

Enables or disables encryption for any communication with the Protection Server. For more details, see pts(1).

-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.

-help

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

-localauth

Constructs a server ticket using a key from the local /etc/yfs/server/KeyFileEx file. Do not combine this flag with the -cell or -noauth options. For more details, see pts(1).

-noauth

Assigns the unprivileged identity anonymous to the issuer. For more details, see pts(1).

OUTPUT

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

Name

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

id

A unique number that is used to identify users, machines, networks, and groups. Auristor user, machine and network numbers (AUNs) are positive integers. Auristor Group Numbers (AGNs) are negative integers. The AUNs and AGNs managed by the Protection Service function similarly to the AUNs and AGNs used in local file systems, but apply only to /afs access control list (ACL) processing and other cell operations.

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 Service automatically records the system:administrators group in this field for user, machine and network entries at creation time.

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.

membership

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

flags

A string of six characters, referred to as privacy and authorization flags, which indicate who can display or administer certain aspects of the entry; or whether the entry is a member of the system:authuser group.

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

The six flags are:

(n)

Indicates whether the user, machine or network entry will be included in the system:authuser group. If the value is - then the entry will be included in the system:authuser group. If the value is N then the entry will not be included. Use the pts setfields command to alter the value.

It is best practice for machine and network entries to be excluded from the system:authuser group. Although network entries and the anonymous entry can never authenticate.

(s)

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

(S)

When set to uppercase S the entry can be displayed by anyone that can communicate with the cell's Protection Servers.

(s)

When set to lowercase s a user, machine or network entry can be displayed by the members of the system:administrators group, the authenticated entity the entry represents, and the entry's owner.

When set to lowercase s a group entry can be displayed by the members of the system:administrators group and the members of the group.

(o)

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

(-)

When set to hyphen -, members of the system:administrators group and the authenticated user can list the groups he or she owns.

When set to hyphen -, members of the system:administrators group and a group's owner can list the groups that a group owns.

(O)

When set to O, anyone who can access the cell's Protection Servers can list the groups owned by a network or group entry.

(m)

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

(-)

When set to hyphen -,

  • all members of the system:administrators group and the authenticated entity whose membership is being queried can list the groups the entity belongs to.

  • members of the system:administrators group can list the groups a network belongs to.

  • members of the system:administrators group and a group's owner can list the users, machines, networks and groups that belong to it.

(m)

When set to lowercase m, members of a group can list the other members.

(M)

When set to uppercase M, anyone who can access the cell's Protection Servers can list membership information for a user, machine, network or group.

(a)

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

(-)

When set to hyphen -, members of the system:administrators group and the owner of the group can add members to the group.

(a)

When set to lowercase a, members of a group can add new members to the group.

(A)

When set to uppercase A, anyone who can access the cell's Protection Servers can add new members to the group.

(r)

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

(-)

When set to hypen -, members of the system:administrators group and the owner of the group can remove members from the group.

(r)

When set to lowercase r, members of a group can remove other members from the group.

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.

The default privacy flags for user, machine and network entries are -S----, meaning that anyone can display the entry and that the entry when authenticated will be included in the system:authuser group. The ability to perform any commands other than pts examine is restricted to members of the system:administrators group and the entry's owner (as well as the authenticated user or machine for a user or machine entry).

The default privacy and authorization 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. The defaults for the privacy and authorization flags may be changed by configuring the ptserver default_access option. See ptserver(8) for more discussion of the default_access option.

group quota

The number of additional groups an authenticated user or machine is permitted to create. The pts createuser command sets the initial group quota to 20 for users, machines, and networks but it has no meaningful interpretation for a network because it is not possible to authenticate as a network. Similarly, it has no meaning in group entries that only deal with the local cell. The pts creategroup command sets the initial group quota to 0 (zero); do not change this value.

When federated authentication using Kerberos version 5 cross-realm is configured, a special group of the form system:authuser@foreign.realm can be created by an administrator. This group behaves similarly to the system:authuser group except its membership are only user and machine entities authenticated from the Kerberos version 5 realm FOREIGN.REALM. If the group quota for this special group is greater than zero, then aklog can automatically register users whose Kerberos version 5 client principals were issued by the FOREIGN.REALM KDCs. Users or machines that are registered will be added system:authuser@foreign.realm group and the group's group quota will be decremented by one.

EXAMPLES

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

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

The following example displays the entries for the Auristor groups with AGNs -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.

PRIVILEGE REQUIRED

The required privilege depends on the setting of the (S) privacy flag in the Protection Service entry of each entry specified by the -nameorid argument:

SEE ALSO

aklog(1), pts(1), pts_adduser(1), pts_chown(1), pts_creategroup(1), pts_createuser(1), pts_listowned(1), pts_membership(1), pts_removeuser(1), pts_rename(1), pts_setaccess(1), pts_setfields(1)

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.

ACKNOWLEDGEMENTS

"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)

"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)

The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).

"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).

"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.