doc/xml/AdminReference/sect8/kas.xml

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