doc/man-pages/pod8/kas.pod

   1 =head1 NAME
   2
   3 kas - Introduction to the kas command suite
   4
   5 =head1 DESCRIPTION
   6
   7 The commands in the B<kas> command suite are the administrative interface
   8 to the Authentication Server, which runs on each database server machine
   9 in a cell, maintains the Authentication Database, and provides the
  10 authentication tickets that client applications must present to AFS
  11 servers in order to obtain access to AFS data and other services.
  12
  13 There are several categories of commands in the B<kas> command suite:
  14
  15 =over 4
  16
  17 =item *
  18
  19 Commands to create, modify, examine and delete entries in the
  20 Authentication Database, including passwords: B<kas create>, B<kas
  21 delete>, B<kas examine>, B<kas list>, B<kas setfields>, B<kas setkey>,
  22 B<kas setpassword>, and B<kas unlock>.
  23
  24 =item *
  25
  26 Commands to create, delete, and examine tokens and server tickets: B<kas
  27 forgetticket>, B<kas listtickets>, B<kas noauthentication>, and B<kas
  28 stringtokey>.
  29
  30 =item *
  31
  32 A command to enter interactive mode: B<kas interactive>.
  33
  34 =item *
  35
  36 A command to trace Authentication Server operations: B<kas statistics>.
  37
  38 =item *
  39
  40 Commands to obtain help: B<kas apropos> and B<kas help>.
  41
  42 =back
  43
  44 Because of the sensitivity of information in the Authentication Database,
  45 the Authentication Server authenticates issuers of B<kas> commands
  46 directly, rather than accepting the standard token generated by the Ticket
  47 Granting Service. Any B<kas> command that requires administrative
  48 privilege prompts the issuer for a password. The resulting ticket is valid
  49 for six hours unless the maximum ticket lifetime for the issuer or the
  50 Authentication Server's Ticket Granting Service is shorter.
  51
  52 To avoid having to provide a password repeatedly when issuing a sequence
  53 of B<kas> commands, enter I<interactive mode> by issuing the B<kas
  54 interactive> command, typing B<kas> without any operation code, or typing
  55 B<kas> followed by a user and cell name, separated by an at-sign (C<@>; an
  56 example is C<kas smith.admin@abc.com>). After prompting once for a
  57 password, the Authentication Server accepts the resulting token for every
  58 command issued during the interactive session. See L<kas_interactive(8)>
  59 for a discussion of when to use each method for entering interactive mode
  60 and of the effects of entering a session.
  61
  62 The Authentication Server maintains two databases on the local disk of the
  63 machine where it runs:
  64
  65 =over 4
  66
  67 =item *
  68
  69 The Authentication Database (F</usr/afs/db/kaserver.DB0>) stores the
  70 information used to provide AFS authentication services to users and
  71 servers, including the password scrambled as an encryption key. The
  72 reference page for the B<kas examine> command describes the information in
  73 a database entry.
  74
  75 =item *
  76
  77 An auxiliary file (F</usr/afs/local/kaauxdb> by default) that tracks how
  78 often the user has provided an incorrect password to the local
  79 Authentication Server. The reference page for the B<kas setfields> command
  80 describes how the Authentication Server uses this file to enforce the
  81 limit on consecutive authentication failures. To designate an alternate
  82 directory for the file, use the B<kaserver> command's B<-localfiles>
  83 argument.
  84
  85 =back
  86
  87 =head1 OPTIONS
  88
  89 The following arguments and flags are available on many commands in the
  90 B<kas> suite. (Some of them are unavailable on commands entered in
  91 interactive mode, because the information they specify is established when
  92 entering interactive mode and cannot be changed except by leaving
  93 interactive mode.) The reference page for each command also lists them,
  94 but they are described here in greater detail.
  95
  96 =over 4
  97
  98 =item B<-admin_username> <I<user name>>
  99
 100 Specifies the user identity under which to authenticate with the
 101 Authentication Server for execution of the command. If this argument is
 102 omitted, the B<kas> command interpreter requests authentication for the
 103 identity under which the issuer is logged onto the local machine.  Do not
 104 combine this argument with the B<-noauth> flag.
 105
 106 =item B<-cell> <I<cell name>>
 107
 108 Names the cell in which to run the command. It is acceptable to abbreviate
 109 the cell name to the shortest form that distinguishes it from the other
 110 entries in the F</usr/vice/etc/CellServDB> file on the local machine. If
 111 the B<-cell> argument is omitted, the command interpreter determines the
 112 name of the local cell by reading the following in order:
 113
 114 =over 4
 115
 116 =item *
 117
 118 The value of the AFSCELL environment variable.
 119
 120 =item *
 121
 122 The local F</usr/vice/etc/ThisCell> file.
 123
 124 =back
 125
 126 The B<-cell> argument is not available on commands issued in interactive
 127 mode. The cell defined when the B<kas> command interpreter enters
 128 interactive mode applies to all commands issued during the interactive
 129 session.
 130
 131 =item B<-help>
 132
 133 Prints a command's online help message on the standard output stream. Do
 134 not combine this flag with any of the command's other options; when it is
 135 provided, the command interpreter ignores all other options, and only
 136 prints the help message.
 137
 138 =item B<-noauth>
 139
 140 Establishes an unauthenticated connection to the Authentication Server, in
 141 which the Authentication Server treats the issuer as the unprivileged user
 142 C<anonymous>. It is useful only when authorization checking is disabled on
 143 the server machine (during the installation of a server machine or when
 144 the B<bos setauth> command has been used during other unusual
 145 circumstances). In normal circumstances, the Authentication Server allows
 146 only privileged users to issue most B<kas> commands, and refuses to
 147 perform such an action even if the B<-noauth> flag is provided. Do not
 148 combine this flag with the B<-admin_username> and B<-password_for_admin>
 149 arguments.
 150
 151 =item B<-password_for_admin> <I<password>>
 152
 153 Specifies the password of the command's issuer. It is best to omit this
 154 argument, which echoes the password visibly in the command shell, instead
 155 enter the password at the prompt. Do not combine this argument with the
 156 B<-noauth> flag.
 157
 158 =item B<-servers> <I<machine name>>+
 159
 160 Establishes a connection with the Authentication Server running on each
 161 specified database server machine, instead of on each machine listed in
 162 the local F</usr/vice/etc/CellServDB> file. In either case, the B<kas>
 163 command interpreter then chooses one of the machines at random to contact
 164 for execution of each subsequent command. The issuer can abbreviate the
 165 machine name to the shortest form that allows the local name service to
 166 identify it uniquely.
 167
 168 =back
 169
 170 =head1 PRIVILEGE REQUIRED
 171
 172 To issue most kas commands, the issuer must have the C<ADMIN> flag set in
 173 his or her Authentication Database entry (use the B<kas setfields> command
 174 to turn the flag on).
 175
 176 =head1 SEE ALSO
 177
 178 L<CellServDB(5)>,
 179 L<kaserver.DB0(5)>,
 180 L<kaserverauxdb(5)>,
 181 L<kas_apropos(8)>,
 182 L<kas_create(8)>,
 183 L<kas_delete(8)>,
 184 L<kas_examine(8)>,
 185 L<kas_forgetticket(8)>,
 186 L<kas_help(8)>,
 187 L<kas_interactive(8)>,
 188 L<kas_list(8)>,
 189 L<kas_listtickets(8)>,
 190 L<kas_noauthentication(8)>,
 191 L<kas_quit(8)>,
 192 L<kas_setfields(8)>,
 193 L<kas_setpassword(8)>,
 194 L<kas_statistics(8)>,
 195 L<kas_stringtokey(8)>,
 196 L<kas_unlock(8)>,
 197 L<kaserver(8)>
 198
 199 =head1 COPYRIGHT
 200
 201 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 202
 203 This documentation is covered by the IBM Public License Version 1.0.  It was
 204 converted from HTML to POD by software written by Chas Williams and Russ
 205 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.