=head1 NAME

kas - Introduction to the C<kas> command suite

=head1 DESCRIPTION

The commands in the C<kas> command suite are the administrative interface
to the Authentication Server, which runs on each database server
machine in a cell, maintains the Authentication Database, and provides
the authentication tickets that client applications must present to
AFS servers in order to obtain access to AFS data and other services.

There are several categories of commands in the C<kas> command suite:

=over

=item *

Commands to create, modify, examine and delete entries in the
Authentication Database, including passwords: C<kas create>, C<kas
delete>, C<kas examine>, C<kas list>, C<kas setfields>, C<kas setkey>, C<kas
setpassword>, and C<kas unlock>

=item *

Commands to create, delete, and examine tokens and server tickets:
C<kas forgetticket>, C<kas listtickets>, C<kas noauthentication>, and C<kas
stringtokey>

=item *

A command to enter interactive mode: C<kas interactive>

=item *

A command to trace Authentication Server operations: C<kas
statistics>

=item *

Commands to obtain help: C<kas apropos> and C<kas help>

=back

Because of the sensitivity of information in the Authentication
Database, the Authentication Server authenticates issuers of C<kas>
commands directly, rather than accepting the standard token generated
by the Ticket Granting Service. Any C<kas> command that requires
administrative privilege prompts the issuer for a password. The
resulting ticket is valid for six hours unless the maximum ticket
lifetime for the issuer or the Authentication Server's Ticket Granting
Service is shorter.

To avoid having to provide a password repeatedly when issuing a
sequence of C<kas> commands, enter I<interactive mode> by issuing the C<kas
interactive> command, typing C<kas> without any operation code, or typing
C<kas> followed by a user and cell name, separated by an at-sign (@; an
example is C<kas smith.admin@abc.com>). After prompting once for a
password, the Authentication Server accepts the resulting token for
every command issued during the interactive session. See the reference
page for the C<kas interactive> command for a discussion of when to use
each method for entering interactive mode and of the effects of
entering a session.

The Authentication Server maintains two databases on the local disk of
the machine where it runs:

=over

=item *

The Authentication Database (B</usr/afs/db/kaserver.DB0>) stores the
information used to provide AFS authentication services to users
and servers, including the password scrambled as an encryption
key. The reference page for the C<kas examine> command describes the
information in a database entry.

=item *

An auxiliary file (B</usr/afs/local/kaauxdb> by default) that tracks
how often the user has provided an incorrect password to the local
Authentication Server. The reference page for the C<kas setfields>
command describes how the Authentication Server uses this file to
enforce the limit on consecutive authentication failures. To
designate an alternate directory for the file, use the C<kaserver>
command's B<-localfiles> argument.

=back

=head1 OPTIONS

The following arguments and flags are available on many commands in
the C<kas> suite. (Some of them are unavailable on commands entered in
interactive mode, because the information they specify is established
when entering interactive mode and cannot be changed except by leaving
interactive mode.) The reference page for each command also lists
them, but they are described here in greater detail.

=over 4

=item B<-admin_username>

Specifies the user identity under which to authenticate with
the Authentication Server for execution of the command. If this
argument is omitted, the C<kas> command interpreter requests
authentication for the identity under which the issuer is
logged onto the local machine. Do not combine this argument
with the B<-noauth> flag.

=item B<-cell> I<cell name>

Names the cell in which to run the command. It is acceptable to
abbreviate the cell name to the shortest form that
distinguishes it from the other entries in the
B</usr/vice/etc/CellServDB> file on the local machine. If the
B<-cell> argument is omitted, the command interpreter determines
the name of the local cell by reading the following in order:

=over

=item 1.

The value of the AFSCELL environment variable

=item 2.

The local B</usr/vice/etc/ThisCell> file

=back

The B<-cell> argument is not available on commands issued in
interactive mode. The cell defined when the C<kas> command
interpreter enters interactive mode applies to all commands
issued during the interactive session.

=item B<-help>

Prints a command's online help message on the standard output
stream. Do not combine this flag with any of the command's
other options; when it is provided, the command interpreter
ignores all other options, and only prints the help message.

=item B<-noauth>

Establishes an unauthenticated connection to the Authentication
Server, in which the Authentication Server treats the issuer as
the unprivileged user B<anonymous>. It is useful only when
authorization checking is disabled on the server machine
(during the installation of a server machine or when the C<bos
setauth> command has been used during other unusual
circumstances). In normal circumstances, the Authentication
Server allows only privileged users to issue most C<kas> commands,
and refuses to perform such an action even if the B<-noauth> flag
is provided. Do not combine this flag with the B<-admin_username>
and B<-password_for_admin> arguments.

=item B<-password_for_admin>

Specifies the password of the command's issuer. It is best to
omit this argument, which echoes the password visibly in the
command shell, instead enter the password at the prompt. Do not
combine this argument with the B<-noauth> flag.

=item B<-servers>

Establishes a connection with the Authentication Server running
on each specified database server machine, instead of on each
machine listed in the local B</usr/vice/etc/CellServDB> file. In
either case, the C<kas> command interpreter then chooses one of
the machines at random to contact for execution of each
subsequent command. The issuer can abbreviate the machine name
to the shortest form that allows the local name service to
identify it uniquely.

=back

=head1 PRIVILEGE REQUIRED

To issue most C<kas> commands, the issuer must have the C<ADMIN> flag set in
his or her Authentication Database entry (use the C<kas setfields>
command to turn the flag on).

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<CellServDB_client_version(1)>,
L<kaserver.DB0(1)> and L<kaserver.DBSYS1(1)>,
L<kaserverauxdb(1)>,
L<kas_apropos(1)>,
L<kas_create(1)>,
L<kas_delete(1)>,
L<kas_examine(1)>,
L<kas_forgetticket(1)>,
L<kas_help(1)>,
L<kas_interactive(1)>,
L<kas_list(1)>,
L<kas_listtickets(1)>,
L<kas_noauthentication(1)>,
L<kas_quit(1)>,
L<kas_setfields(1)>,
L<kas_setpassword(1)>,
L<kas_statistics(1)>,
L<kas_stringtokey(1)>,
L<kas_unlock(1)>,
L<kaserver(1)>

=cut
