src/kauth/kas.doc

   1 @comment (
   2 /*
   3  * Copyright 2000, International Business Machines Corporation and others.
   4  * All Rights Reserved.
   5  *
   6  * This software has been released under the terms of the IBM Public
   7  * License.  For details, see the LICENSE file in the top-level source
   8  * directory or online at http://www.openafs.org/dl/license10.html
   9  */
  10
  11 )
  12 @comment (
  13 Revision 1.5  89/01/30  09:56:16
  14 Added copyright notice.
  15
  16   Revision 1.2  89/01/30  09:49:04
  17   Added copyright notice
  18   )
  19
  20 This a brief description of the asr command which provides a preliminary
  21 interface to the Authentication Server.
  22         881209
  23 Updated.
  24         890111
  25
  26 The command uses the libcmd.a facilities with a couple of modifications:
  27   1. If the command is given no argument the interactive command is assumed as
  28      a default.
  29   2. If the first command line argument starts with "-c" the interactive
  30      command is invoked.
  31   3. If the first command line argument contains either a '.' or a '@'
  32      character the interactive command is invoked.
  33 These shorthands allow the most common cases to enter interactive mode with a
  34 minimum of hassle.
  35
  36 If one of the above cases is not met the first command line argument is taken
  37 as a command name.  These commands fall into three groups.  The first are those
  38 provided by the libcmd facility such as help and apropos.  The second group
  39 only makes sense within interactive mode.  The last group includes all the
  40 action commands.
  41
  42 The interactive command is only useful from the command line; within command
  43 mode it is a no-op.  The quit command just leaves interactive mode.  Generally
  44 all commands in a single command invocation use a single connection to the
  45 Authentication Server.  The noauth command replaces the current connection with
  46 an unauthenticated one.  This will only be useful if the server is also running
  47 -noauth, but can be simpler than running unlog to remove all your tickets..
  48
  49 Certain optional arguments are common to all the action commands.  These are
  50 important if the command is being run from the command line but they are
  51 ignored once a connection has been established in interactive mode.  These
  52 arguments are as follows:
  53   -username - This allows the specification of the principal name to use for
  54      authentication to the admin server.  The format of the principal is
  55      "name[.instance][@cell]".  If this parameter is not specified the username
  56      defaults to the current Unix user name, the null instance and the local
  57      cell.
  58
  59   -password - This allows the specification of the password associated
  60      with the username.  If not present it is prompted for.
  61
  62   -cell - This specifies the cell containing the Authentication Server
  63      to contact.  A cell name may not be specified in both the username
  64      and with this argument.
  65
  66   -servers - This argument is followed by a list of servers that is
  67      passed to Ubik.  It can be used to override the contents of
  68      CellServDB.  Use with care!
  69
  70 To use of most of this program's commands you must have a ticket for the server
  71 "AuthServer.Admin".  If you don't have one the program will prompt for your
  72 password (unless it is specified with the -password parameter) and try to
  73 obtain one.  If your database entry marks you as an admin user you will be able
  74 to run all these commands (except getpassword).  Otherwise you will only be
  75 able to use getticket or run setpassword on yourself.
  76
  77 Some of the action command accept parameters which are passwords.  If these are
  78 not specified on the command line they are prompted for.  Other arguments are
  79 required unless otherwise specified.
  80
  81 debuginfo - This prints out a lot of debugging information that should be of
  82     little interest to anyone except the program maintainer.
  83 statistics - This returns various statistics about the AuthServer and its
  84     database.
  85 getticket <user> - this gets a ticket for the server <user> and installs the
  86     ticket in the ticket cache.  At present, except for the server named "afs",
  87     this will fail.  This is a debugging entry can won't be useful for most
  88     users.
  89 getpassword <user> - this returns a user's encryption key.  It is used by the
  90     message guardians to allow PC users to authenticate.  It will fail unless
  91     you're running on a file server.
  92 setpassword (sp) <user> <pass> - This is used to set a user's password.  You
  93     must be authenticated as <user> or be an admin user.
  94 setfields (sf) <user> - Set various database entry fields for this user.  This
  95     command takes three optional parameters, at least one of which must be
  96     specified.  They are "-flags", "-expiration" and "-lifetime".
  97       -expiration <date> - this specifies the date after which the user will
  98           not be able to authenticate himself.  The format of the date is
  99           "[[[yy]mm]dd]hhmm[.ss]".
 100       -lifetime <hh:mm | seconds> - this specified the maximum ticket
 101           lifetime.
 102       -flags <flag expression | hex number> - this specifies the value
 103           of the flags field.  A flag expression allows combining the
 104           individual bits by name.  If the expression starts with an '='
 105           then all the desired bits must be set, otherwise the
 106           expression is relative to the current flag value.  Bits may be
 107           added (with '+') or subtracted (with '-' or '_').  The flag
 108           bit names and their values are as follows:
 109             NORMAL  = 0x01; /* set if a regular user */
 110             FREE    = 0x02; /* set if in free list */
 111             ADMIN   = 0x04; /* an administrator */
 112             NOTGS   = 0x08; /* Don't allow to use TGS */
 113             OLDKEYS = 0x10; /* set if entry used to store old keys */
 114             NOSEAL  = 0x20; /* don't use this entry's key to seal tickets */
 115             NOCPW   = 0x40; /* don't let principal to change its own key */
 116           Setting the FREE or OLDKEYS bits will result in an error.
 117           Thus "_ADMIN" removes the admin bit; "+NOCPW-admin" adds the
 118           no cpw bit and removes the admin bit; and "=ADMIN" sets the
 119           admin bit with all the other bits off (except NORMAL).
 120 delete (rm) <user>" - Delete a user.
 121 create <user> <pass> - Create a user with initial password.
 122 examine <user> - Print the database entry for this user.
 123 list (ls) - This lists all the users in the database.
 124