man-page-pts-updates-20080605
[openafs.git] / doc / man-pages / pod1 / pts_examine.pod
index 9ba521c..7118fa8 100644 (file)
@@ -1,20 +1,27 @@
 =head1 NAME
 
-pts examine - Displays a Protection Database entry
+pts_examine - Displays a Protection Database entry
 
 =head1 SYNOPSIS
 
-B<pts examine> B<-nameorid> <I<user or group name or id>>+
-    [B<-cell> <I<cell name>>] [B<-noauth>] [B<-force>] [B<-help>]
+=for html
+<div class="synopsis">
 
-B<pts e> B<-na> <I<user or group name or id>>+ [B<-c> <I<cell name>>]
-    [B<-no>] [B<-f>] [B<-h>]
+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<pts check> B<-na> <I<user or group name or id>>+ [B<-c> <I<cell name>>]  
-    [B<-no>] [B<-f>] [B<-h>]
-   
-B<pts che> B<-na> <I<user or group name or id>>+ [B<-c> <I<cell name>>]  
-    [B<-no>] [B<-f>] [B<-h>]
+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<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<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>]
+
+=for html
+</div>
 
 =head1 DESCRIPTION
 
@@ -45,11 +52,22 @@ L<pts(1)>.
 Assigns the unprivileged identity anonymous to the issuer. For more
 details, see L<pts(1)>.
 
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+F</usr/afs/etc/KeyFile> file. Do not combine this flag with the 
+B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
+
 =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<-auth>
+
+Run using the user's current authentication. This is the default unless
+the B<-noauth> or B<-localauth> options are used.
+
 =item B<-help>
 
 Prints the online help for this command. All other valid options are
@@ -66,7 +84,7 @@ fields:
 
 =item Name
 
-The contents of this field depend on the type of entry: 
+The contents of this field depend on the type of entry:
 
 =over 4
 
@@ -190,7 +208,9 @@ 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.
+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
 
@@ -198,8 +218,15 @@ 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.
+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
 
@@ -209,18 +236,18 @@ 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, 
+   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, 
+   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, 
+   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, 
+   Name: smith:colleagues, id: -674, owner: smith, creator: smith,
      membership: 14, flags: SOM--, group quota: 0.
 
 =head1 PRIVILEGE REQUIRED