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