man-page-pts-updates-20080605
authorJason Edgecombe <jason@rampaginggeek.com>
Thu, 5 Jun 2008 20:31:13 +0000 (20:31 +0000)
committerRuss Allbery <rra@stanford.edu>
Thu, 5 Jun 2008 20:31:13 +0000 (20:31 +0000)
LICENSE BSD

Add documentation of foreign realm user registration and cross-realm PTS
groups.  Add documentation of missing ptserver flags.  Add some additional
to-do entries for the man pages.

doc/man-pages/README
doc/man-pages/pod1/aklog.pod
doc/man-pages/pod1/pts_examine.pod
doc/man-pages/pod8/ptserver.pod

index 33f08ab..d0ba975 100644 (file)
@@ -201,6 +201,7 @@ Known Problems
 
    * The following installed commands have no man pages:
 
+       compile_et.afs
        copyauth
        fs cscpolicy
        fs memdump
@@ -208,13 +209,19 @@ Known Problems
        fs rxstatpeer
        fs rxstatproc
        fs setcbaddr
+       klog.krb
+       krb.conf
+       pagsh.krb
        restorevol
        rmtsysd
+       tokens.krb
        vldb_convert
        vos clone
        vos setfields
        vsys
 
+   * Add -noresolve to the documentation of all the vos commands.
+
    * klog.krb, pagsh.krb, and tokens.krb need to be listed as alternative
      names in the NAME line of the non-.krb man pages, links should be
      installed on man page installation, and the behavior of pagsh.krb
index 5351dd8..3709397 100644 (file)
@@ -20,19 +20,29 @@ B<aklog> [B<-d>] [B<-hosts>] [B<-zsubs>] [B<-noprdb>] [B<-noauth>] [B<-linked>]
 =head1 DESCRIPTION
 
 The B<aklog> program authenticates to a cell in AFS by obtaining AFS
-tokens.  If B<aklog> is invoked with no command-line arguments, it will
-obtain tokens for the workstation's local cell.  It may be invoked with an
-arbitrary number of cells and pathnames to obtain tokens for multiple
-cells.  B<aklog> knows how to expand cell name abbreviations, so cells can
-be referred to by enough letters to make the cell name unique among the
-cells the workstation knows about.
+tokens using a Kerberos 5 ticket. If B<aklog> is invoked with no
+command-line arguments, it will obtain tokens for the workstation's local
+cell.  It may be invoked with an arbitrary number of cells and pathnames
+to obtain tokens for multiple cells.  B<aklog> knows how to expand cell
+name abbreviations, so cells can be referred to by enough letters to make
+the cell name unique among the cells the workstation knows about.
 
 B<aklog> obtains tokens by obtaining a Kerberos service ticket for the AFS
 service and then storing it as a token.  By default, it obtains that
-ticket from the realm corresponding to that cell (the upcase version of
+ticket from the realm corresponding to that cell (the uppercase version of
 the cell name), but a different realm for a particular cell can be
 specified with B<-k>.  B<-k> cannot be used in B<-path> mode (see below).
 
+When a Kerberos 5 cross-realm trust is used, B<aklog> looks up the AFS ID
+corresponding to the name (Kerberos principal) of the person invoking the
+command, and if the user doesn't exist and the
+system:authuser@FOREIGN.REALM PTS group exists, then it attempts automatic
+registration of the user with the foreign cell.  The user is then added to
+the system:authuser@FOREIGN.REALM PTS group if registration is successful.
+Automatic registration in the foreign cell will fail if the group quota
+for the system:authuser@FOREIGN.REALM group is less than one.  Each
+automatic registration decrements the group quota by one.
+
 When using B<aklog>, be aware that AFS uses the Kerberos v4 principal
 naming format, not the Kerberos v5 format, when referring to principals in
 PTS ACLs, F<UserList>, and similar locations.  AFS will internally map
@@ -75,11 +85,11 @@ identical.  If this flag is given, it will skip that check.
 
 =item B<-hosts>
 
-Prints all the server addresses which may act as a single point of
-failure in accessing the specified directory path.  Each element of the
-path is examined, and as new volumes are traversed, if they are not
-replicated, the server's IP address containing the volume will be
-displayed.  The output is of the form:
+Prints all the server addresses which may act as a single point of failure
+in accessing the specified directory path.  Each element of the path is
+examined, and as new volumes are traversed, if they are not replicated,
+the server's IP address containing the volume will be displayed.  The
+output is of the form:
 
     host: <ip-address>
 
@@ -106,11 +116,13 @@ setting tokens.
 =item B<-noprdb>
 
 Ordinarily, B<aklog> looks up the AFS ID corresponding to the name of the
-person invoking the command, and if the user doesn't exist and the cell is
-a foreign one, attempts automatic registration of the user with the remote
-cell.  Specifying this flag turns off this functionality.  This may be
-desirable if the protection database is unavailable for some reason and
-tokens are desired anyway, or if one wants to disable user registration.
+person invoking the command, and if the user doesn't exist, the cell is a
+foreign one, the system:authuser@FOREIGN.REALM PTS group exists, and has a
+positive group quota, then it attempts automatic registration of the user
+with the foreign cell.  Specifying this flag turns off this functionality.
+This may be desirable if the protection database is unavailable for some
+reason and tokens are desired anyway, or if one wants to disable user
+registration.
 
 =item B<-path> <I<pathname>>, B<-p> <I<pathname>>
 
index 6921d97..7118fa8 100644 (file)
@@ -9,16 +9,16 @@ pts_examine - Displays a Protection Database entry
 
 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<-help>]
+    [B<-force>] [B<-auth>] [B<-help>]
 
 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<-h>]
+    [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<-h>]
+    [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<-h>]
+    [B<-no>] [B<-l>] [B<-f>] [B<-a>] [B<-h>]
 
 =for html
 </div>
@@ -63,6 +63,11 @@ B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
 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
@@ -203,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
 
@@ -211,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
 
index 228e58b..454ae92 100644 (file)
@@ -7,9 +7,14 @@ ptserver - Initializes the Protection Server
 =for html
 <div class="synopsis">
 
-B<ptserver> S<<< [B<-database> <I<db path>>] >>> S<<< [B<-p> <I<number of threads>>] >>>
-    [B<-rebuildDB>] [B<-enable_peer_stats>] [B<-enable_process_stats>]
-    [B<-allow-dotted-principal>] [B<-rxbind>] [B<-help>]
+B<ptserver> S<<< [B<-database> | B<-db> <I<db path>>] >>> S<<< [B<-p> <I<number of threads>>] >>>
+    [B<-rebuildDB>] S<<< [B<-groupdepth> <I<# of nested groups>>] >>>
+    S<<< [B<-default_access> <I<user access mask>> <I<group access mask>>] >>>
+    [B<-restricted>] [B<-enable_peer_stats>]
+    [B<-enable_process_stats>] [B<-allow-dotted-principal>]
+    [B<-rxbind>] S<<< [B<-auditlog> <I<file path>>] >>>
+    S<<< [B<-syslog>[=<I<FACILITY>>]] >>> S<<< [B<-rxmaxmtu> <I<bytes>>] >>>
+    [B<-help>]
 
 =for html
 </div>
@@ -48,6 +53,14 @@ request. The CPS lists all groups to which a user or machine belongs.
 
 =back
 
+When using Kerberos 5, cross-realm authentication is possible. If the
+special pts group system:authuser@FOREIGN.REALM exists and its group quota
+is greater than zero, B<aklog> will automatically create an entry for the
+foreign user in the local PTS database and add the foreign user to the
+system:authuser@FOREIGN.REALM PTS group.  Each time a foreign user is
+created in the local PTS database, the group quota for the
+system:authuser@FOREIGN.REALM PTS group is decremented by one.
+
 This command does not use the syntax conventions of the AFS command
 suites. Provide the command name and all option names in full.
 
@@ -55,7 +68,7 @@ suites. Provide the command name and all option names in full.
 
 =over 4
 
-=item B<-database> <I<db path>>
+=item B<-database> <I<db path>>, B<-db> <I<db path>>
 
 Specifies the pathname of an alternate directory in which the Protection
 Database files reside. Provide the complete pathname, ending in the base
@@ -75,6 +88,24 @@ Rebuilds the Protection Database at the beginning of Protection Server
 initialization. Use this argument only in consultation with AFS
 Development or Product Support.
 
+=item B<-groupdepth> <I<# of nested groups>>, B<-depth> <I<# of nested groups>>
+
+Specifies the group depth for nested groups when B<ptserver> is compiled
+with the SUPERGROUPS option enabled.  The default depth for nested groups
+is 5.  This option may be shortened to B<-depth>.
+
+=item B<-default_access> <I<user access>> <I<group access>>
+
+Specifies the default user and group privacy flags to apply to each
+entry. Provide a string of five characters, one for each of the
+permissions. See L<pts_examine(1)> or L<pts_setfields(1)> for more
+information on the flags.
+
+=item B<-restricted>
+
+Run the PT Server in restricted mode. While in restricted mode, only
+members of the system:administrators PTS group may make any PTS changes.
+
 =item B<-enable_peer_stats>
 
 Activates the collection of Rx statistics and allocates memory for their
@@ -94,17 +125,32 @@ Monitoring API.
 =item B<-allow-dotted-principal>
 
 By default, the RXKAD security layer will disallow access by Kerberos
-principals with a dot in the first component of their name. This is to avoid
-the confusion where principals user/admin and user.admin are both mapped to the
-user.admin PTS entry. Sites whose Kerberos realms don't have these collisions 
-between principal names may disable this check by starting the server
-with this option.
+principals with a dot in the first component of their name. This is to
+avoid the confusion where principals user/admin and user.admin are both
+mapped to the user.admin PTS entry. Sites whose Kerberos realms don't have
+these collisions between principal names may disable this check by
+starting the server with this option.
 
 =item B<-rxbind>
 
 Bind the Rx socket to the primary interface only.  (If not specified, the
 Rx socket will listen on all interfaces.)
 
+=item B<-syslog>[=<I<syslog facility>>]
+
+Specifies that logging output should go to syslog instead of the normal
+log file.  B<-syslog>=I<FACILITY> can be used to specify to which facility
+the log message should be sent.  Logging message sent to syslog are tagged
+with the string "ptserver".
+
+=item B<-auditlog> <I<file path>>
+
+Specifies the full pathname for the B<AuditLog> file.
+
+=item B<-rxmaxmtu> <I<bytes>>
+
+Sets the maximum transmission unit for the RX protocol.
+
 =item B<-help>
 
 Prints the online help for this command. All other valid options are