man-page-pts-updates-20080605
[openafs.git] / doc / man-pages / pod1 / aklog.pod
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>>